@wardby/cli 0.6.0 → 0.7.0

package/docs/coding-agent-setup.md

@@ -15,6 +15,8 @@ registry) but never holds the run capability.
   for each enabled coding provider: `OPENAI_API_KEY` and/or
   `ANTHROPIC_API_KEY`.
 - The local database has the current Prisma migrations applied.
+- git 2.38 or newer on any machine that runs the wardby server outside the
+  shipped image (follow-up runs merge the pull request's target branch with it).
 - A GitHub App is installed on only the repository to be exercised. (Not needed
   for a repository on this machine; see
   [Local repositories](#local-repositories).) Grant it
@@ -61,6 +63,9 @@ A continuation (`continuePriorRun`) checks separately that the pull request
 it is asked to continue is still open on GitHub; one already merged or closed
 fails with category `continuation_closed` and nothing pushed — see
 [Continuation's pull request is no longer open](../help/errors/continuation-closed.md).
+Before its agent starts, a continuation also merges the branch the pull
+request currently targets, and the agent resolves any conflicts — see
+[Follow-ups bring the pull request up to date](code-review-agents.md#follow-ups-bring-the-pull-request-up-to-date).
 Over stdio, the local operator holds every role, so `repositoryAdminOverride`
 is the way to approve a repository there.
 
@@ -101,7 +106,7 @@ JOB_LAUNCHER=docker
   directly, so the control plane must not run in a container, a pod or on
   another machine. A trusted folder the server cannot see is ignored, so its
   repositories fail with `local_repo_not_allowed`, and `doctor` reports the
-  folder as missing. The machine needs git 2.24 or newer.
+  folder as missing. The machine needs git 2.38 or newer.
 - **Worker images.** Use worker images from the same release as the control
   plane. An older worker image rejects `local:` repositories (the run fails with
   `worker_input_failed`), including a Codex agent's bring-your-own
@@ -128,7 +133,8 @@ JOB_LAUNCHER=docker
 To build on an earlier result, trigger with `baseRef: "wardby/run-<run id>"`. A
 continuation of a run (a lead agent revising its earlier work) fast-forwards the
 same branch; if the branch has moved, or is checked out, the run fails with
-`local_branch_conflict` and nothing is pushed.
+`local_branch_conflict` and nothing is pushed. A local repository has no pull
+requests, so a continuation there does not merge any other branch first.
 
 Result branches accumulate, and wardby does not delete them. Clean up with
 `git branch -D wardby/run-<run id>`.
@@ -374,17 +380,61 @@ the agent's commands); Claude Code itself always runs on
 
 A coding run's budget is reserved when it is dispatched: the agent's own
 `budgetUsd`, tightened to whatever its budget group has left for each
-configured period and, for a sub-agent, whatever its run tree has left. The
-worker can never spend more than that reservation. When a group or run tree
+configured period and, for a sub-agent, whatever its run tree has left. Each
+model request holds part of the reservation before it is sent, and a request
+that would not fit is refused. A reply can still cost more than its hold, up to
+that request's worst case, so a run can end a little over its reservation;
+finished work is still delivered. When a group or run tree
 has nothing left, the run is recorded as `refused` with the error
 `budget_group_exhausted:<day|week|month>` or `run_tree_exhausted`, and no
 container starts (`trigger_agent` returns that status and error directly).
 
+### Allowing a small overrun
+
+A coding agent's `allowedOverrunPercent` (an integer from 0 to 100, default 0,
+set with `create_agent` or `update_agent`, and shown by `get_agent`) lets a run
+spend a little beyond `budgetUsd` instead of stopping at it. It takes the same
+permission as changing `budgetUsd`. On a coding agent it raises the limit of
+each of its runs; on a lead agent that delegates, it raises its run tree's
+ceiling for coding sub-agents. Native runs' own model calls are not affected.
+
+The overrun is permission to spend more, not a reservation. At dispatch a
+coding run reserves only its base budget: the smallest of the agent's
+`budgetUsd`, what its budget group has left and what its run tree has left.
+Its limit is `budgetUsd` raised by the percent, and nothing is held for it up
+front. While the run works, wardby tops up what it may spend, in steps of 10%
+of its base (or the largest model request it has made, if that is more), each
+time it gets within its headroom of what it has been granted: two of its
+largest requests, or 20% of its base if that is more. A run whose base is
+smaller than its first request cannot use its overrun, since that request is
+refused before any top-up. A step is granted
+only out of room its budget group and run tree have left at that moment, and
+never past the limit. The coding proxy enforces what has been granted so far,
+and the Claude Code worker's own budget stop is set to the limit. `get_run`
+shows `budgetBaseUsd`, `budgetLimitUsd` (the limit) and `budgetReservedUsd`
+(what has been granted so far, which the group and run tree hold).
+
+Budget group caps and run-tree ceilings stay hard. A top-up takes whatever room
+is left, so if the group or run tree fills up while a run needs more, the run
+stops at what it has been granted, with its work kept as below, and its budget
+sentence says why, for example "Only $0.40 of its 10% allowed overrun was
+available because the "team" group had no more left of its daily cap." (or
+"Its 10% allowed overrun wasn't available because the "team" group had nothing
+left of its daily cap." when it got none). `get_run` then lists an `overrun_unavailable` event. A run that
+was refused a top-up does not ask again, even if the group frees up later. The
+overrun a run actually got can therefore be lower than the agent's setting, or
+none. For a delegated run tree, the raised ceiling uses the lead (root) agent's
+percent, so set it on the lead agent to let its coding sub-agents go beyond
+the lead's `budgetUsd`. Runs dispatched before this behaviour have no
+`budgetLimitUsd`: their reservation already includes the overrun, and they
+finish as before.
+
 Every live run still pending or running holds its unspent reservation
 (reservation minus cost so far) against its group; a native run holds its
 agent's per-run `budgetUsd`. So overlapping scheduled, webhook and manual runs
 share one cap rather than each seeing the full remainder, and
-`get_budget_group` reports those holds as `reservedUsd` next to `spentUsd`.
+`get_budget_group` reports those holds as `reservedUsd` next to `spentUsd`, and
+each `spend[]` entry's `heldRuns` counts the runs holding budget in that period.
 Native runs are served first come, first served: a native run only counts the
 holds of runs that started before it, so members dispatched on the same tick
 don't starve each other.
@@ -408,8 +458,176 @@ all beat every 10 seconds. A coding run also holds until its
 `CODING_QUEUE_TIMEOUT_SEC` + its `timeoutSec` + 60 seconds have passed since
 dispatch, because it does not beat while it waits in the coding queue. Its
 recorded cost always counts. `wardby run` records the run as `cancelled` on
-Ctrl-C or SIGTERM. If a row is still stuck in `running` for another reason,
-only its real cost counts once its hold lapses.
+Ctrl-C or SIGTERM, and the MCP tool `stop_run` records any pending, queued,
+or running run as `cancelled` (see [Stop or cancel a run](../help/stop-run.md)),
+which ends its hold at once. If a row is still stuck in `running` for another
+reason, only its real cost counts once its hold lapses.
+
+### How a request's hold is estimated
+
+Before each model request the proxy holds an amount against the run's budget.
+A request whose hold does not fit in what is left is refused. The hold is not
+a charge: the run pays the reply's real cost.
+
+The first request of a conversation, and every fallback below, holds the worst
+case: the whole request body as new input written to the cache (one token per
+byte) plus `maxOutputTokens` at the output rate.
+
+After a reply in the same conversation that read from or wrote to the prompt
+cache at least half of its prompt (on OpenAI models only cache reads count),
+the next request holds that cached part at the cache-read rate,
+and the rest (including whatever the body has grown by) at the input and
+cache-write rates, plus the output allowance. It never holds more than the
+worst case. A conversation is the main agent or one of its sub-agents.
+
+The hold falls back to the worst case when:
+
+- there is no previous reply in the conversation;
+- the model changed;
+- the previous reply was interrupted (settled at an estimate) or did not
+  complete;
+- less than half of the previous reply's prompt was read from or written to
+  the cache;
+- the request body got smaller; or
+- the previous request in the conversation was sent more than 5 minutes
+  earlier, the lifetime of the prompt cache.
+
+If the cache misses, a reply can cost more than its hold. It is still settled
+when it costs no more than the worst case, so a run can exceed its budget by at
+most the difference between a request's worst case and its hold, for each
+request in flight. A reply that
+costs more than the worst case cancels the run's model access
+(`reservation_invariant_violated`).
+
+When a request is refused, `budgetEvents` in `get_run` shows the basis of the
+refused hold (`refusedHoldBasis`: `cached` or `full`) and the worst case for
+that request (`refusedHoldCeilingUsd`); see
+[Why a run stopped](#why-a-run-stopped).
+
+### Interrupted replies
+
+When a model reply breaks off before its final usage arrives (a dropped
+connection, a worker that is stopped mid-reply), the proxy settles the request
+at an estimate instead of leaving its whole hold in place. The estimate is the
+input usage the proxy already read; failing that, the input of the previous
+completed reply in the same conversation (the main conversation and each
+sub-agent are tracked apart) on the same model, plus the request body's growth
+since then. That reply is used only if it started within the 5-minute prompt
+cache window before the request and the body has not shrunk since (as after a
+compaction). Failing that, the whole request body counts as new input. New input
+is counted at one token per 3 bytes, a deliberately high count, and priced at
+the higher of the model's input and cache-write rates. It adds the output
+relayed so far (text, tool-call input, and thinking or reasoning text), counted
+high. With nothing relayed, the run's median completed reply on that model is
+used, or no output if there is none yet. A streaming request that failed before
+the provider's response started adds no output, because nothing was generated.
+A provider's placeholder output count at the start of a reply is used only as a
+minimum. The estimate is never more than the request's worst
+case. An estimated request is flagged `costEstimated`, counts in the
+run's cost at the estimate, and is recorded as `uncertain` in the proxy's
+request ledger. If the estimate cannot be computed or recorded, the request
+keeps its full hold. A run can therefore exceed
+its budget by at most the difference between an estimate and the real cost of
+the interrupted request.
+
+### Delegated runs in a budget group
+
+A lead and the sub-agents it starts in the same budget group hold the lead's
+budget once, at the lead: the lead's reservation minus what the whole run tree
+has spent. Each sub-agent reserves its own base out of what the lead's budget
+has left. When the lead has an `allowedOverrunPercent`, its coding sub-agents
+can be topped up past the lead's budget, up to its raised ceiling; the lead
+then holds at least the unspent holds of every live sub-agent run in its tree
+(top-ups included), so the overrun still fits inside the group's cap. This is decided per period: a sub-agent run holds nothing in a
+period only when its lead started in that same period. So a delegating lead
+does not count against its group several times over.
+
+### Why a run stopped
+
+`get_run` returns `budgetEvents` for a run that was refused for budget,
+including a run whose model request was refused but that still finished,
+failed for another reason, or was stopped. The event is recorded when the run
+ends. Each event has `kind` (`refused`, or `overrun_unavailable` for a top-up
+the group or run tree had no room for), `limit`, `at` and `details`. `limit` says which
+cap bound the run: `run` (the agent's own `budgetUsd`), `run-tree` (what the
+lead had left), or `day`, `week` or `month` (the budget group's cap for that
+period). For a refused model request, `details` holds the budget, the amount
+spent, the holds of requests in flight, the refused hold, the model and the
+turn, plus the basis of the refused hold (`refusedHoldBasis`) and its worst case
+(`refusedHoldCeilingUsd`). For a refusal at dispatch it holds the cap, the amount spent, the amount
+held and the number of holding runs (`heldRuns`). Both also name the agent's
+budget group (`groupName`) when it has one, and the lead agent
+(`leadAgentName`) for a `run-tree` limit; a refused model request also gives
+the agent's own `budgetUsd` (`agentBudgetUsd`). An `overrun_unavailable` event
+holds the full cap or tree's numbers (`capUsd`, `spentUsd`, `heldUsd`,
+`leftUsd`), the run's `baseBudgetUsd`, `grantedUsd` and `limitUsd`, and the
+name of the group whose cap was full (`groupName`), which can be the lead's.
+
+The run's error carries the same facts in one sentence after the code, for
+example `coding_budget_exhausted: <sentence>`. A lead's sub-agent result
+carries the sentence in a `budget` field. Pull request and issue comments and
+check summaries show the amounts and the budget group's name only. See
+[Run stopped out of budget](../help/errors/budget-exhausted.md).
+
+Budget sentences name both parts when the run had an overrun, for example
+"this run's $1.00 budget and its 10% allowed overrun ($1.10 in all)", or
+"$1.00 budget and $0.05 of its 10% allowed overrun ($1.05 in all)" when only
+part of it was available.
+
+#### Finished work is delivered
+
+A worker that finishes is pushed, and its pull request opened, even if its
+cost ended over the limit (one reply can cost more than the hold placed for
+it). The run's status is `succeeded`, and its status comment states the
+overrun, for example "Spent $1.04, $0.04 (4%) over its $1.00 budget, within
+its allowed overrun." (without the "within" part when it went past the limit).
+
+#### Stopped for budget: the work so far is kept
+
+When a run is stopped for budget and its worker ended cleanly, its changes so
+far are pushed as the usual draft pull request, or added to the pull request it
+was continuing. A new pull request's description starts "Stopped at its budget
+before finishing; the changes so far are in this draft." A continuation leaves
+the existing description as it is; its status comment says the run stopped.
+The run's status stays
+`budget_exhausted` and its `budgetEvents` are kept. The status comment points
+at the pull request and says that mentioning the agent on it, or on the issue
+the run came from, continues the work with a fresh budget: a comment
+mentioning the App on GitHub, or the service account on a Jira issue.
+
+- A new pull request's description and the run's summary then carry a
+  `### Task` section: the request that started the run, quoted, with mentions
+  defused and wrapper tags neutralised, and cut at 4 KiB with a
+  `[task truncated]` marker. The agent's standing instructions are never
+  included. The worker's own summary follows it, unless it is only the fixed
+  budget sentence. A continuation reads the task from there, so it knows what
+  the draft was for. The request text is shown in the draft, so anyone who can
+  read the pull request can read it.
+- While the draft's latest commit is the one the stopped run pushed, the
+  automatic review is skipped: its check completes as neutral, titled
+  "Skipped: stopped at its budget", and no [fix round](code-review-agents.md#automatic-review-fix-rounds)
+  follows. A review that would start while that run is still finishing waits
+  for its result. Marking the pull request ready for review, or pushing a new
+  commit, gets a normal review; so does an explicit request (re-running the
+  check, or a comment mentioning the App asking for a review). The skip
+  applies to drafts only, because a neutral check counts as passing for branch
+  protection.
+- The status comment says the draft can be continued from the pull request, or
+  from the issue it came from. See
+  [Follow-ups on an issue](code-review-agents.md#follow-ups-on-an-issue).
+- Such a pull request is not marked ready automatically. Marking ready looks at
+  the last run that pushed to the pull request, so a later continuation that
+  finishes makes it eligible again; a continuation that ends with no changes
+  does not.
+- The usual push checks still apply (protected paths, diff limits, access). If
+  one refuses, or there are no changes, the run ends as `budget_exhausted`
+  with nothing pushed.
+- Unfinished work is never pushed onto a pull request that is no longer a
+  draft (marked ready for review by wardby or a person). A continuation of
+  such a pull request that stops for budget ends as `budget_exhausted` with
+  nothing pushed. The draft state is read from the host; when the host cannot
+  be asked, a pull request wardby marked ready counts as not a draft.
+- Nothing is kept from a worker that crashed, timed out or was stopped.
 
 ## Turn limit (Claude Code)
 
@@ -429,6 +647,270 @@ failure. The run's `budgetUsd` and `timeoutSec` still apply and are usually the
 better limits. Codex runs have no turn limit, so `maxTurns` does not affect
 them.
 
+## Output tokens per reply (Claude Code)
+
+A Claude Code run caps each model reply at 32000 output tokens by default.
+Thinking counts toward that cap, so a model with adaptive or extended thinking
+can reach it on a long reply; Claude Code then ends with an error that the
+response exceeded the output token maximum, and the run fails as a stream
+failure. Raise the cap per agent:
+
+```json
+{ "id": "<coding agent id>", "codingProfile": { "maxOutputTokens": 64000 } }
+```
+
+`maxOutputTokens` is 1024 to 128000; `null` restores the default. Pick a value
+the agent's model supports. It is fixed on each run when the run is
+dispatched. The coding proxy reserves `maxOutputTokens` × the model's output
+price (plus the request's input, see
+[How a request's hold is estimated](#how-a-requests-hold-is-estimated)) against the run's budget for every
+model request, so a higher cap needs a larger `budgetUsd`: at a $25/MTok output
+price, 32000 tokens reserve $0.80 per request and 128000 reserve $3.20. A
+request whose reservation does not fit in what is left of the budget is
+refused and the run ends as `budget_exhausted` (see
+[Why a run stopped](#why-a-run-stopped)), so a higher value makes a run
+with a small budget end sooner. Only Claude Code agents take
+`maxOutputTokens`; `create_agent` and `update_agent` refuse it on a Codex
+agent, and changing an agent's provider to `codex` needs it set to `null` in
+the same `update_agent` call (or before).
+
+The 32000 default and `maxOutputTokens` need a Claude Code worker image from a
+release that supports them (Wardby 0.7.0 or later). An older pinned image still
+caps each reply at 4096 tokens, and rejects the input of a run whose agent sets
+`maxOutputTokens` as invalid.
+
+## Resume a run locally
+
+A Claude Code agent can keep a copy of each run's conversation so a developer
+can later continue that session in their own Claude Code. Keeping it is off by
+default. Turn it on per agent:
+
+```json
+{ "id": "<coding agent id>", "codingProfile": { "sessionResume": true } }
+```
+
+`sessionResume` applies to Claude Code agents only; `create_agent` and
+`update_agent` refuse it on a Codex agent. Wardby keeps each run's session,
+and `get_run_transcript` plus `npx @wardby/cli@latest resume` continue it on a
+developer's machine (see [Continue a run on your machine](#continue-a-run-on-your-machine)).
+This section covers what is stored, how to set it up, and how to resume.
+
+Session resume needs Claude Code worker images from a release that supports
+it (Wardby 0.7.0 or later). An older pinned image rejects the input of a run
+whose agent sets `sessionResume` as invalid (`worker_input_failed`).
+
+**What is kept.** The conversation as Claude Code recorded it: the user and
+assistant messages, tool calls and their results, compaction summaries (so a
+long run resumes from its last summary, as it would have in the worker), the
+files and skills the agent loaded, and a session title. When Claude Code made
+no title, the title is `wardby run <id>: ` and the first line of the task.
+Records are kept whole. Removed: thinking blocks (they are tied to the account
+and conversation that produced them and would not replay), the system prompt,
+the worker's environment, date and budget reminders, account and
+organisation details, billing records, and any record kind the pinned Claude
+Code version is not known to write. The content is then redacted against the
+values of the secrets attached to the agent, and the run's capability and
+registry token are redacted by their token shape. If the agent's secrets
+cannot be loaded, nothing is stored.
+
+**Which runs.** Claude Code runs that finish, stop at their budget, or fail.
+A run stopped with `stop_run` or ended by its timeout is not captured, because
+its worker is removed before the transcript can be collected.
+
+**Who can read it.** Transcripts are stored from the first run
+with `sessionResume` on. Anyone who can read a run (its triggerer and the
+agent's owner, as for `get_run`) can download its transcript, and so everything the agent saw and wrote, including file
+contents and command output from the repository. Redaction covers secret
+values, not other sensitive text. Enable `sessionResume` only for agents whose
+runs you are comfortable sharing with everyone who can read them.
+
+**Where it is stored.** In the server's blob store, as a gzip-compressed
+object under the `run-transcripts/` prefix. When a run's context was
+compacted, only what a resume loads is kept: the last compaction's summary,
+the messages that compaction kept, and everything after it. Earlier history
+is never loaded on resume, so it is not stored.
+
+**Size limits.** `RUN_TRANSCRIPT_MAX_BYTES` caps the stored transcript,
+measured before compression (default 10 MiB, at most 64 MiB). A larger
+transcript is not stored. While the run works, its worker keeps the raw
+session in its own in-memory scratch of up to 80 MiB, which counts toward the
+run's memory, and reads at most 64 MiB of it when the run ends. Each run
+records a status of `stored`, `too_large`, `not_captured` or `failed`, with a
+short reason code and no content.
+
+The blob store settings must be present on the **server process** (the
+control plane that launches coding runs), not only on the coding proxy. The
+server also needs its secret cipher, which it has in a normal setup.
+
+| Variable                                       | Default | Purpose                                                                           |
+| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
+| `BLOB_STORE`                                   |         | `local`, `gcs` or `s3`. Without it no transcript is stored.                       |
+| `BLOB_STORE_LOCAL_DIR`                         |         | Directory for `BLOB_STORE=local`.                                                 |
+| `BLOB_STORE_GCS_BUCKET`                        |         | Bucket for `BLOB_STORE=gcs`.                                                      |
+| `BLOB_STORE_S3_BUCKET`, `BLOB_STORE_S3_REGION` |         | Bucket and region for `BLOB_STORE=s3`.                                            |
+| `BLOB_STORE_S3_ENDPOINT`                       |         | Optional: an S3-compatible endpoint for `BLOB_STORE=s3`.                          |
+| `RUN_TRANSCRIPT_RETENTION_DAYS`                | `30`    | Days to keep a transcript, a whole number from 1 to 3650.                         |
+| `RUN_TRANSCRIPT_MAX_BYTES`                     | 10 MiB  | Largest transcript stored, in bytes before compression, from 1048576 to 67108864. |
+
+**Retention.** Expired transcripts are pruned whenever a new one is stored.
+For GCS and S3, also add a bucket lifecycle rule that deletes objects under
+the `run-transcripts/` prefix after the same number of days, so objects are
+removed even when no new run is stored. The reference GKE and AWS modules
+create that rule for you (below).
+
+**Set it up per deployment.** Use a bucket of its own for transcripts, not the
+dependency cache bucket, and give access to the control plane only: a
+transcript holds everything the run saw, and the coding proxy and workers have
+no need for it.
+
+- **GKE**: set `session_transcripts_enabled = true` and a unique
+  `session_transcripts_bucket_name` (optionally
+  `session_transcripts_retention_days`, default 30) in `terraform.tfvars`, and
+  deploy with `WARDBY_SESSION_TRANSCRIPTS=true deploy/gke/up.sh`. Terraform
+  creates the bucket and its lifecycle rule and grants the control plane's
+  service account alone; `up.sh` gives the control plane `BLOB_STORE=gcs`, the
+  bucket and the matching `RUN_TRANSCRIPT_RETENTION_DAYS`. See
+  [`deploy/gke/README.md`](../deploy/gke/README.md#session-transcripts).
+- **AWS (EKS)**: set the Terraform variables of the same names, then give the
+  control plane container `BLOB_STORE=s3`, `BLOB_STORE_S3_BUCKET` (the
+  `session_transcripts_bucket` output), `BLOB_STORE_S3_REGION` and
+  `RUN_TRANSCRIPT_RETENTION_DAYS` (the `session_transcripts_retention_days`
+  output). See
+  [`deploy/aws/README.md`](../deploy/aws/README.md#session-transcripts).
+- **kind harness**: the control plane runs on your host, so set
+  `BLOB_STORE=local` and `BLOB_STORE_LOCAL_DIR` (a directory on your host) in
+  the environment you start it with. Nothing changes in the cluster.
+- **Docker quickstart**: the server runs on your host. Add `BLOB_STORE=local`
+  and `BLOB_STORE_LOCAL_DIR` (an absolute directory on your host) to
+  `.wardby/.env` and restart. The coding proxy container keeps its own
+  dependency cache store and is not affected. A local directory has no
+  lifecycle rule, so expired transcripts are removed only when new ones are
+  stored.
+
+**Startup checks.** With `JOB_LAUNCHER` set to `docker` or `kubernetes`, a
+half-set `BLOB_STORE` (the kind set but its bucket or directory missing), or an
+invalid `RUN_TRANSCRIPT_RETENTION_DAYS` or `RUN_TRANSCRIPT_MAX_BYTES`, stops the server at startup with a
+message naming the variable.
+
+**Custom worker images.** An agent that sets `workerImageRef` must rebuild its
+image from a release that includes session resume. Until then its runs fail at
+input (`worker_input_failed`). `update_agent` warns about this when you turn
+`sessionResume` on, and also warns when the server has no blob store.
+
+### Continue a run on your machine
+
+Ask your MCP client to call `get_run_transcript` with the run's id. It takes
+the same access as `get_run` (the run's triggerer or the agent's owner) and
+returns:
+
+- `status`: `stored` when the transcript can be resumed. Otherwise the status
+  (`none`, `too_large`, `not_captured`, `failed`, `expired`, `unavailable` or
+  `unsupported`), its `reason`, and what it means; no link.
+- `sessionId`, `repository`, `branch` (the branch the run pushed, or its head
+  branch), `baseSha`, `sizeBytes` and `expiresAt` (when the transcript is
+  deleted).
+- `download.url` and `download.expiresAt`: a signed download link that works
+  for 10 minutes.
+- `command`: `npx @wardby/cli@latest resume -`. It asks for the link; paste
+  `download.url`.
+
+The transcript itself never enters your MCP client's conversation, only the
+link. Run the command in a terminal. You can also pass the link as an
+argument (`npx @wardby/cli@latest resume '<link>'`) or pipe it in, but an argument stays
+in your shell history and in the process list while Claude Code runs, so
+pasting it at the prompt is the safer default.
+
+- For a GitHub repository, run it inside a clone of that repository. It
+  fetches the run's branch from the remote that points at the repository and
+  adds a detached git worktree next to the clone, named
+  `<clone>-run-<last 8 characters of the run id>`.
+- For a `local:` repository, run it anywhere on the server's machine. The
+  worktree is added from that repository, next to it. A `local:` path names
+  a folder on the server's machine, so it is used only when the link comes
+  from this machine (`127.0.0.1`, `localhost` or `[::1]`, as with a stdio MCP
+  server). For a link from any other server the command stops with
+  `local_repository_refused` unless you pass `--here`, or `--dir <path>` to
+  check the run out from that folder anyway.
+- A detached worktree works even while the branch is checked out somewhere
+  else. When the branch no longer exists (for example a failed run that
+  pushed nothing), the run's base commit is checked out instead, with a
+  warning that the run's changes are not in it.
+
+```text
+npx @wardby/cli@latest resume - [--dir <path> | --here] [--force] [--print]
+```
+
+| Option         | Effect                                                                             |
+| -------------- | ---------------------------------------------------------------------------------- |
+| `--dir <path>` | Put the worktree at `<path>` instead of the default.                               |
+| `--here`       | Skip the checkout and continue in the current directory as it is.                  |
+| `--force`      | Replace a different session file already imported for this run.                    |
+| `--print`      | Print the `claude` command instead of starting it (also when `claude` is missing). |
+
+The command downloads the transcript and checks its SHA-256 against the
+server's before writing anything. It writes two files, both readable only by
+you, under `~/.wardby/sessions/<run id>/`: the session as
+`<session id>.jsonl`, and `mcp-config.json`. It never writes to Claude Code's
+own configuration directory. It then starts Claude Code in the worktree:
+
+```text
+claude --resume ~/.wardby/sessions/<run id>/<session id>.jsonl \
+  --mcp-config ~/.wardby/sessions/<run id>/mcp-config.json \
+  --system-prompt-snapshot off --append-system-prompt '<move note>'
+```
+
+- **The move note** tells the model the session moved from the worker:
+  `/workspace` (where the run's commands ran) is now the worktree, and the
+  worker's tool is gone. `--system-prompt-snapshot off` makes Claude Code
+  apply the note to a resumed conversation. It needs Claude Code 2.1.257 or
+  later; for an older version that `claude --version` reports, it is left
+  out. When the version cannot be read (for example `claude` is not on
+  `PATH`), the printed command includes it and says so: remove it if your
+  Claude Code is older than 2.1.257.
+- **The stand-in tool server.** Every command in a run went through the
+  worker's `run_command` tool (`wardby_tools`). The MCP config starts a
+  stand-in with the same name and input schema from the same wardby install,
+  so the resumed session shows the run's calls and their output. Under `npx`,
+  `mcp-config.json` points into the npx cache; if that cache has been
+  cleaned, run `wardby resume` again to rewrite it. The stand-in
+  runs nothing: any call answers that the session moved and to use the local
+  Bash, Read and Edit tools in the worktree.
+- **Importing again.** An identical session file is reused. A file that has
+  grown because you continued the session locally is kept, so running the
+  command again picks up where you left off. Any other different file is
+  refused unless you pass `--force`. An existing worktree of the same
+  repository at the target path is reused as it is, with a warning when it
+  is at a different commit from the run's.
+- **Removing an import.** Delete `~/.wardby/sessions/<run id>/` and remove
+  the worktree with `git worktree remove <path>`. The command prints both.
+- Only Claude Code runs can be resumed; for other runs the tool returns
+  `unsupported`.
+
+**The link is a credential.** Anyone who has it can download the transcript
+until it expires, without signing in. Do not paste it into chats, issues or
+logs. It works only for the run and person it was made for, and only while
+that person can still read the run. Over the HTTP transport it points at the
+server's own address (`MCP_CANONICAL_URI`'s origin). Over stdio it points at a
+local port the MCP server opens on `127.0.0.1` while links are in use, so
+your MCP client must stay connected until the download finishes. On a
+multi-instance HTTP deployment a link made on one instance works on every
+other: each instance derives the key that signs links from `SECRET_APP_KEY`,
+which they already share (set `REQUEST_STATE_KEY`, 32 bytes of hex, the same
+on every instance, to use a key of your own instead). A link made by a stdio
+server is never accepted by the HTTP route. `wardby resume` sends the link only over HTTPS, or over plain
+HTTP to this machine.
+
+The token is in the link's query string (as with the secret-entry form's
+links). Exclude `/run-transcripts/download` (and `/elicit/secret`) from
+load-balancer, ingress and proxy access logs, or log those paths without
+their query string.
+
+The download responds with the gzip-compressed transcript and the headers
+`x-wardby-sha256`, `x-wardby-session-id` and `x-wardby-transcript-meta` (the
+run's repository and refs, as base64url JSON). A refused download returns
+JSON `{ "error": "<code>" }`; `wardby resume` explains each code (see the
+`errors/run-transcript-download` help article).
+
 ## Stop the setup
 
 ```sh