# Sessions

A session is one implementation attempt run by something other than June's own model loop: a coding agent such as headless Claude Code, given a workspace and a task and left to change files. `june/session` is the contract between such a session and whatever hosts it, such as the Ship Agent.

```ts
import type { ImplementationSession, SessionOutcome } from "june/session";

declare const session: ImplementationSession;

const outcome: SessionOutcome = await session.run({
  workspace: "/path/to/checkout",
  task: { id: "t1", revision: 1, attempt: 1 },
  prompt: "Keep the selected station when switching views.",
  limits: { timeoutMs: 20 * 60_000, maxTurns: 40 },
  signal: new AbortController().signal,
});
```

## What a session returns is a claim

`SessionOutcome.status` says how the session ended (`completed`, `failed`, `limit`, `canceled` or `interrupted`), not whether the work is right, and `summary` and `claim` are the session's own account of what it did. A host decides what happened by reading the workspace: the Ship Agent captures the working tree as a candidate and runs its own checks and review on it, whatever the session said.

## Capabilities, limits and usage

A session declares what it can do in `capabilities`:

- **`limits`**: which of `timeoutMs`, `maxTurns`, `maxModelCalls` and `maxCostUsd` it enforces itself. A request may ask for more; the outcome lists what it couldn't enforce in `unsupportedLimits`, and `unsupportedLimits(capabilities, limits)` works that out ahead of time, so a host can refuse to start instead.
- **`resume`**: `none`, or `same-workspace` when a session can be continued by its `reference` in the workspace it started in.
- **`usage`**: `exact` when the session counts its own model calls, `reported` when it passes on what the provider said, `none` when it can't say. An outcome's `usage` is absent rather than guessed.

## References

`SessionReference` is a `JobRef` from [`june/train`](https://june.dev/docs/training/jobs.md): `{ id, kind, data: { workspace } }`, plain JSON to save with the attempt. It names an external session. It is not proof that a process is alive, or that anything the session did was kept: a host reconciles the workspace, not the reference.

## Cancellation and events

Aborting `signal` stops the session and everything it started. `onEvent` receives bounded progress (`started`, `progress`, `tool`, `diagnostic`) for a log or a trace.

## Claude Code

`claudeCode()` runs the locally installed Claude Code CLI as a session:

```ts
import { claudeCode } from "june/session";

const session = claudeCode({ model: "claude-sonnet-5-5" });
```

- **How it runs.** `claude -p <prompt>` by argv, in the workspace as its working directory, with `--output-format stream-json`, `--permission-mode acceptEdits` and `--allowedTools` set to reading, editing and running commands (`allowedTools` and `permissionMode` change them). It never skips permissions, and on a CLI that supports it, `--permission-prompts none` denies what nobody is there to approve, which then shows in the outcome. The request's `instructions` go in with `--append-system-prompt`. The session's environment is a minimal one (PATH, HOME, the locale, proxies, and the CLI's and its backends' own settings: `CLAUDE_CODE_*`, `ANTHROPIC_*`, `AWS_*`, `CLAUDE_CONFIG_DIR` and Vertex's) with the request's `env` over it, so the host's other credentials aren't passed on; leave publishing credentials out of `env` too, as the Ship Agent does. The environment isn't a sandbox: a session with Bash and your HOME can still use credentials kept on disk, such as a `gh` login or a git credential helper. Run it as a user, or in a checkout, that can't publish when that matters.
- **Limits.** `maxTurns` and `maxCostUsd` are passed to the CLI, and `timeoutMs` is enforced here. It can't count model calls, so `maxModelCalls` is reported unsupported.
- **Supervision.** The CLI runs in its own process group: a cancellation or a time limit sends it `SIGTERM`, then `SIGKILL` after `killGraceMs`, and whatever it started goes with it. Output is bounded (`maxOutputBytes`), and unreadable lines are reported as diagnostics rather than failing the run.
- **Outcome.** The final result record becomes the outcome: `completed`, `failed` (an error result or exit), `limit` (turns, spend or time), `canceled`, or `interrupted` when the process ended without a result. Permission denials are reported, usage is passed on as `reported` when the CLI gives it, and a JSON object the session ends its answer with is its `claim`.
- **Resume.** A reference resumes its session with `--resume` only in the workspace it was made in; otherwise a new session starts, with a diagnostic saying so.
- **Version.** `claudeCodeVersion()` reads the CLI's version; an unavailable CLI is a `failed` outcome, not an exception.

To try it against the real CLI, logged in and on the `PATH`:

```sh
JUNE_CLAUDE_SMOKE=1 make test path=packages/june/src/session
```

That makes one small model call in a temporary directory; without the variable it is skipped.
