@wardby/cli 0.6.0 → 0.8.0

package/help/native-sandbox.md

@@ -4,7 +4,7 @@ title: Run native agents in a sandbox
 summary: Turn on sandbox mode so a native agent's turn loop and tools run in a single-use, credential-free Docker container or Kubernetes pod behind a native gateway.
 audience: operator
 tags: [native-agents, sandbox, isolation, docker, kubernetes, native-gateway, security, warm-pool]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Run native agents in a sandbox
@@ -102,8 +102,21 @@ are in [Native sandbox](../docs/native-sandbox.md#warm-pool).
   run `budget_exhausted`.
 - Sub-agents of a sandboxed run are managed runs started by the scheduler
   leader on its next tick (about every 10 seconds), so the server or scheduler
-  must be running.
+  must be running. A coding agent child is resolved by the server when it
+  starts (worker image, services, knowledge), so the gateway needs no `CODING_*`
+  settings; a problem there (such as a `workerImageRef` that is not pinned by digest)
+  shows as the child run `failed` or `refused`; the parent's `delegate_to_*`
+  call receives `status: "failed"` with the `errorCode`, or for a refused child
+  the refusal sentence, and the full error is on the child run (`get_run`).
+  Upgrade `wardby serve` and `wardby scheduler` before or together with the
+  gateway: an older server starts the child unresolved (a Codex child on the
+  default image without its instructions, a Claude Code child failing with
+  `coding_provider_not_configured:claude-code`).
 - A sandbox run has a 60-minute maximum lifetime.
+- `stop_run` stops a sandbox run: its gateway session ends so the worker exits
+  at its next call, and a worker still running after 5 seconds is killed and
+  removed (a warm pool worker is discarded, never reused). Search help for
+  "stop run" (article `stop-run`, Wardby 0.7.0 and later).
 
 ## Roll back
 
@@ -120,6 +133,7 @@ codes:
 
 - [native_sandbox_unavailable](errors/native-sandbox-unavailable.md)
 - [native_sandbox_worker_exited](errors/native-sandbox-worker-exited.md)
+- [native_sandbox_gateway_error](errors/native-sandbox-gateway-error.md)
 - [native_sandbox_deadline_exceeded](errors/native-sandbox-deadline-exceeded.md)
 - [native_sandbox_worker_lost](errors/native-sandbox-worker-lost.md)
 - [native_sandbox_image_not_pinned](errors/native-sandbox-image-not-pinned.md)

package/help/operating-agents.md

@@ -32,5 +32,26 @@ A running run's cost, token counts, and turn count update after each model
 call, so `get_run` and `list_runs` show spend so far rather than zero until the
 run finishes.
 
+To see your runs across every agent, call `list_runs` without an `agentId`
+(Wardby 0.8.0 and later). Each row names its agent and leaves out the final
+text; `active: true` keeps pending and running runs, and `since` (an ISO time)
+keeps runs that started or finished since then plus any still active. You see
+every run of the agents you own and only the runs you started on the others.
+`list_agents` with `summary: true` returns just each agent's id, name, kind,
+model, coding provider, budget, owner and your access, without the full
+configuration.
+
+From Wardby 0.8.0, `get_run` and `list_runs` without an `agentId` also return
+`triggerInfo` (the pull request or issue that started the run, and whether it
+was a review or a mention), `outcomes` (pull requests opened, comments, checks)
+and `serviceReadiness` (each coding-run service's state). They use the admin
+viewer API's shapes. Match one run's pull-request outcome to another run's
+trigger to follow a pull request through its review and fix rounds.
+
+To stop a run that is pending, queued, or running (for example one a schedule
+started that you did not want), call `stop_run` with its id. It ends as
+`cancelled`, along with the sub-agent runs it still has in flight. Search help
+for "stop run" (article `stop-run`, Wardby 0.7.0 and later).
+
 For the full lifecycle and the controls applied to every managed run, read
 [`README.md`](../README.md).

package/help/package-audit-mode.md

@@ -0,0 +1,91 @@
+---
+id: package-audit-mode
+title: Package audit mode
+summary: Let a coding agent install packages outside its allowlist for a limited time, recorded for approval afterwards; full mode also installs versions with high-severity advisories. Malware and the release-age limit are always enforced.
+audience: operator
+tags: [coding-agents, packages, allowlist, package audit, package audit mode, audit mode, packageAuditMode, packageAuditMinutes, approve_audited_packages, packages_audited, npm, pypi, supply-chain]
+appliesTo: >=0.7.0
+---
+
+# Package audit mode
+
+From Wardby 0.7.0, a coding agent's registry can run in package audit mode for
+a limited time. Instead of refusing a package that is not on the agent's
+allowlist, the registry installs it and records it. Use it to find out which
+packages a task needs, then approve them and turn the mode off.
+
+## Modes
+
+| Mode    | Packages outside the allowlist | High or critical advisories | Malware | Release age |
+| ------- | ------------------------------ | --------------------------- | ------- | ----------- |
+| off     | refused                        | withheld unless accepted    | refused | enforced    |
+| `audit` | installed and recorded         | withheld unless accepted    | refused | enforced    |
+| `full`  | installed and recorded         | installed and recorded      | refused | enforced    |
+
+Everything else still applies in every mode: integrity checks, source
+distributions, size and file limits, and a version outside an allowlist
+entry's own range (`foo@^1` never serves `foo@2`).
+
+## Turn it on and off
+
+The agent's owner sets it with `update_agent` (needs `packages:approve` or
+`agents:admin`):
+
+```json
+{ "id": "<agent id>", "codingProfile": { "packageAuditMode": "audit", "packageAuditMinutes": 1440 } }
+```
+
+- `packageAuditMinutes` defaults to 1440 (24 hours); the most is 10080 (7 days).
+- `packageAuditMinutes` alone re-arms the stored mode for that long.
+- `"packageAuditMode": null` turns it off.
+- `create_agent` does not accept it.
+
+`get_agent` shows `packageAuditActive` and a warning while the window is
+open. Each coding run takes the mode when it is dispatched and keeps it for
+its whole life, so a run that starts just before the window ends still runs
+with it.
+
+## Where audited packages show up
+
+- `get_run`: `packageAuditMode` and `packageAudit`, one entry per version
+  with its `relation` (`top-level`, `transitive` with `via`, `unknown`, or
+  `allowed`) and, in `full` mode, its `advisories` (the high and critical ones it was served despite).
+- The pull request body: a caution banner, **Packages outside the
+  allowlist**, and in `full` mode **Served despite advisories**.
+- The run's status comment on GitHub or Jira, and a `packages_audited` Slack
+  message on linked channels (see [Slack notifications](slack-notifications.md)).
+- The proxy log: one `registry.audited` line per version.
+
+A lockfile plan in audit mode approves what passes every other check, and the
+dependency cache never restores or saves a lockfile whose plan audited
+anything.
+
+## Keep the packages
+
+Approve the names a run recorded with `approve_audited_packages`
+(`{ "runId": "<run id>" }`), or add them to `codingProfile.packageAllowlist`
+with `update_agent`. Then turn the mode off.
+
+Without `names`, the tool adds only `top-level` packages. A package recorded
+as `unknown` (installed with no metadata or plan to show its parent) may be a
+dependency of an allowlisted package, so every report lists it apart as
+"Relation unknown — may be a dependency; approve only if needed directly".
+Add one only if the project uses it directly, by listing it in `names`.
+
+## Risks
+
+Audit mode weakens the supply-chain guard while it is on. `audit` keeps the
+malware, advisory and release-age checks; `full` keeps only malware and
+release age. A confused or prompt-injected agent could install a lookalike
+package that has no advisory yet. Install scripts stay off, but tests and
+builds still run what was installed. Keep the window short, review the
+caution banner on every affected pull request, and never leave it on.
+
+## Related
+
+- [Coding packages](coding-packages.md)
+- [Not allowed: `wardby_package_not_allowed`](errors/package-not-allowed.md)
+- [Package not reached: `wardby_package_not_allowed_pending`](errors/package-not-allowed-pending.md)
+- [Graph limit: `wardby_graph_limit`](errors/graph-limit.md)
+- [Still being checked: `wardby_graph_incomplete`](errors/graph-incomplete.md)
+- [Package audit mode guide](../docs/coding-packages.md#package-audit-mode)

package/help/related-pull-requests.md

@@ -11,16 +11,19 @@ appliesTo: ">=0.4.2"
 
 When one request produces pull requests in several repositories — a lead
 agent that delegates to one coding agent per repository, or several runs for
-the same Jira issue — Wardby adds a **Related pull requests** section to each
+the same Jira or GitHub issue — Wardby adds a **Related pull requests** section to each
 of those pull requests' descriptions. It lists the others with links and
 their state, names the originating issue when there is one, and gives a
 merge order: the one the delegating agent set, or else a suggested one.
 
-Without a tracked Jira issue, the list covers the pull requests opened by
-runs in the same delegation tree (the same lead run and everything it
-started). With a tracked issue, the list covers every pull request Wardby
-has recorded for that issue across every run, merged and closed ones
-included, plus that run tree's own siblings.
+Without a tracked issue, the list covers the pull requests opened by runs in
+the same delegation tree (the same lead run and everything it started). With
+a tracked issue (a Jira issue, or a GitHub issue whose `@<app-slug>` mention
+started the request), the list covers every pull request Wardby has recorded
+for that issue across every run, merged and closed ones included, plus that
+run tree's own siblings. The section names the issue the same way for both,
+for example "for Jira issue PROJ-123" or "for GitHub issue owner/repo#7",
+linked to the issue.
 
 - **Written by Wardby, not the model.** The list comes from Wardby's own run
   records, never from the agent's text. Edits you make inside the section
@@ -65,7 +68,7 @@ included, plus that run tree's own siblings.
   name and number, so a request that spans repositories of different
   visibility can show a private repository's name in a public repository's
   pull request. If you mix public and private repositories, keep such work in
-  separate requests: separate Jira issues, or separate lead agents.
+  separate requests: separate issues, or separate lead agents.
 
 Reviewers see the section in the pull request description, so a reviewer
 agent can tell that a field, route, or schema a change relies on is added by
@@ -125,15 +128,19 @@ such hints: a fix round's task names only its own pull request. Merged and
 closed pull requests are never listed as continuable: a change there needs a
 new pull request, which joins the set once it is recorded.
 
+When the sub-agent is a coding agent with a list of repositories, a
+follow-up delegation passes `continuePriorRun` and takes its repository from
+that run, so it needs no `repository` of its own.
+
 Give your own delivery or router agent's system prompt a line such as:
 
     Continue the pull request you were asked about, and any listed open
     sibling the change requires; never open a new pull request in a
     repository that already has an open sibling for this request.
 
-The usual limits still apply: `maxDelegationsPerRun` and never delegating to
-the same sub-agent twice in one run; every push to a sibling pull request
-gets its own review; fix rounds are capped per pull request and only one
+The usual limits still apply: `maxDelegationsPerRun` and delegating to each
+sub-agent and repository at most once per run; every push to a sibling pull
+request gets its own review; fix rounds are capped per pull request and only one
 runs at a time on a pull request; and a continuation only ever reaches a
 sub-agent that shares the same owner as the one asked to continue it.
 

package/help/repo-instructions-and-skills.md

@@ -4,7 +4,7 @@ title: Repository instructions and skills in coding runs
 summary: What AGENTS.md, CLAUDE.md, and repo skills a coding run loads, and how to turn repo skills off per agent with codingProfile.repoSkills.
 audience: all
 tags: [coding, skills, repoSkills, claudeBareMode, CLAUDE.md, AGENTS.md, SKILL.md, codex, claude-code]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Repository instructions and skills in coding runs
@@ -81,6 +81,8 @@ never loaded in either mode.
 
 ## See also
 
+- [Remote MCP servers](../docs/mcp-servers.md) (0.8.0+) are for native agents only; a coding run loads no
+  MCP configuration.
 - [Choose a native or coding agent](creating-agents.md) for `codingProfile`
   basics and the other fields it accepts.
 - [Bring-Your-Own Coding-Worker Images](../docs/coding-worker-byo-images.md)

package/help/resume-runs-locally.md

@@ -0,0 +1,134 @@
+---
+id: resume-runs-locally
+title: Resume Claude Code runs locally (sessionResume, get_run_transcript, wardby resume)
+summary: Keep each Claude Code run's redacted conversation with sessionResume, then continue it on your machine with get_run_transcript and npx @wardby/cli@latest resume.
+audience: operator
+tags: [sessionResume, wardby resume, get_run_transcript, transcript, blob-store, WARDBY_SESSION_TRANSCRIPTS]
+appliesTo: ">=0.7.0"
+---
+
+# Resume Claude Code runs locally
+
+`sessionResume` makes a Claude Code agent keep a redacted copy of each run's
+conversation, so the session can be continued locally in Claude Code with
+`get_run_transcript` and `npx @wardby/cli@latest resume`. It is off by default and is not
+available for Codex agents. It needs Claude Code worker images from Wardby
+0.7.0 or later.
+
+## Turn it on
+
+```json
+{ "id": "<coding agent id>", "codingProfile": { "sessionResume": true } }
+```
+
+Use `update_agent` or `create_agent`. The server needs a blob store
+(`BLOB_STORE`, with `BLOB_STORE_LOCAL_DIR`, `BLOB_STORE_GCS_BUCKET`, or
+`BLOB_STORE_S3_BUCKET` and `BLOB_STORE_S3_REGION`, plus the optional
+`BLOB_STORE_S3_ENDPOINT` for an S3-compatible store) set on the **server
+process** that launches coding runs, not only on the coding proxy. Without a
+blob store nothing is stored, and `update_agent` warns you.
+
+## What is stored
+
+- The conversation as Claude Code recorded it: user and assistant messages,
+  tool calls and their results, compaction summaries, files and skills the
+  agent loaded, and a session title (`wardby run <id>: <task>` when Claude
+  Code made none).
+- Removed: thinking blocks, the system prompt, the worker's environment, date
+  and budget reminders, account and organisation details, and billing
+  records.
+- Redacted: the values of the agent's attached secrets, plus the run's
+  capability and registry token by their token shape. If the agent's secrets
+  cannot be loaded, nothing is stored.
+- Stored for runs that finish, stop at their budget, or fail. Not stored for
+  runs stopped with `stop_run` or ended by their timeout.
+- Stored gzip-compressed under the `run-transcripts/` prefix. When the run's
+  context was compacted, only what a resume loads is kept: the last
+  compaction's summary, the messages it kept, and everything after it.
+- At most `RUN_TRANSCRIPT_MAX_BYTES` per run, measured before compression
+  (default 10 MiB, at most 64 MiB). Each run records a status (`stored`,
+  `too_large`, `not_captured` or `failed`) with a reason code.
+
+## 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, which includes
+what the agent saw in the repository and in command output. Redaction removes secret
+values, not other sensitive text. Turn this on only for agents whose runs you
+are comfortable sharing with everyone who can read them.
+
+## Continue a run on your machine
+
+1. Ask your MCP client to call `get_run_transcript` with the run id (same
+   access as `get_run`). For a stored transcript it returns a download link
+   that works for 10 minutes and the command to run; otherwise the status
+   (`none`, `too_large`, `not_captured`, `failed`, `expired`, `unavailable`,
+   `unsupported`) and what it means.
+2. Run the command in a terminal, `npx @wardby/cli@latest resume -`, and paste the link
+   when it asks. (A link given as an argument stays in shell history and the
+   process list.) For a GitHub repository, run it inside a clone of that
+   repository. A `local:` repository is used only when the link comes from
+   this machine (a stdio MCP server); otherwise pass `--here` or `--dir`.
+
+It verifies the download's SHA-256, writes the session to
+`~/.wardby/sessions/<run id>/<session id>.jsonl` (mode 0600, never into
+Claude Code's own config directory), adds a detached git worktree of the
+run's branch next to the repository (the base commit, with a warning, when
+the branch is gone), and starts `claude --resume` there. A stand-in
+`wardby_tools` server shows the run's `run_command` calls but runs nothing,
+and a note tells the model `/workspace` is now the worktree.
+
+Options: `--dir <path>` (worktree location), `--here` (no checkout),
+`--force` (replace a different imported session file), `--print` (print the
+`claude` command instead of starting it). The command passes
+`--system-prompt-snapshot off` so the move note applies; remove it for a
+Claude Code older than 2.1.257 when the version could not be read. Under
+`npx`, the MCP config points into the npx cache: run `wardby resume` again if
+the cache was cleaned.
+
+The link is a credential until it expires: do not share it. Over stdio it
+points at a local port the MCP server opens, so keep your MCP client
+connected until the download finishes. The token is in the link's query
+string: keep `/run-transcripts/download` out of load-balancer and ingress
+access logs. Refusals:
+[Run transcript download refused](errors/run-transcript-download.md).
+
+## Retention
+
+`RUN_TRANSCRIPT_RETENTION_DAYS` is a whole number from 1 to 3650 (default 30).
+Expired transcripts are pruned when new ones are stored. On GCS or S3 also add
+a bucket lifecycle rule on the `run-transcripts/` prefix.
+
+## Set it up per deployment
+
+Give transcripts a bucket of their own, not the dependency cache bucket, that
+only the control plane can use.
+
+- GKE: `session_transcripts_enabled` and `session_transcripts_bucket_name` in
+  Terraform (optionally `session_transcripts_retention_days`), then
+  `WARDBY_SESSION_TRANSCRIPTS=true deploy/gke/up.sh`. Terraform adds the
+  lifecycle rule; `up.sh` passes the same retention to the control plane.
+- AWS: the same Terraform variables, then give the control plane `BLOB_STORE=s3`,
+  the `session_transcripts_bucket` output as `BLOB_STORE_S3_BUCKET`,
+  `BLOB_STORE_S3_REGION`, and the `session_transcripts_retention_days` output as
+  `RUN_TRANSCRIPT_RETENTION_DAYS`.
+- kind harness and Docker quickstart: the server runs on your host. Set
+  `BLOB_STORE=local` and `BLOB_STORE_LOCAL_DIR` in its environment (for the
+  quickstart, in `.wardby/.env`).
+
+## Startup and custom images
+
+With `JOB_LAUNCHER` set to `docker` or `kubernetes`, a half-set `BLOB_STORE`
+or an invalid `RUN_TRANSCRIPT_RETENTION_DAYS` or `RUN_TRANSCRIPT_MAX_BYTES` stops
+the server at startup,
+naming the variable. An agent with its own `workerImageRef` image must rebuild
+it from a release that includes session resume (see
+[Build a tool runner image for a Claude Code agent](help://build-claude-code-image)),
+or its runs fail at input with `worker_input_failed`.
+
+Full setup: [Resume a run locally](../docs/coding-agent-setup.md#resume-a-run-locally).
+See also [Choose a native or coding agent](help://creating-agents).
+
+The `wardby-runs` Claude Code plugin can start the import from a run's detail
+(**Continue locally**); see `claude-code-run-pane` (Wardby 0.8.0 and later).

package/help/review-fix-rounds.md

@@ -3,7 +3,7 @@ id: review-fix-rounds
 title: Automatic review fix rounds
 summary: Let wardby fix its own review's findings on pull requests its coding runs opened, with a round cap.
 audience: operator
-tags: [github, code-review, review_fix, autofix, fix-round, pull-requests]
+tags: [github, code-review, review_fix, autofix, fix-round, pull-requests, pr-description, description, linked-issue]
 appliesTo: ">=0.4.2"
 ---
 
@@ -69,6 +69,38 @@ open right before it pushes; one merged or closed in the time the round was
 working fails with no push made — see
 [Continuation's pull request is no longer open](errors/continuation-closed.md).
 
+## Description updates
+
+Every run's final message is the full pull request description, fix rounds
+included, so a round that changes no code can still correct it: add a missing
+`Resolves #N`, the issue's acceptance checklist, or stale test results.
+
+- **The original issue.** A fix round gets the issue the pull request was
+  opened for in its task, as the first run did: the Jira issue, the GitHub
+  issue whose `@wardby` mention started the work, or the issue the description
+  closes. It is reference material: the round's final message should carry
+  its acceptance checklist and the closing line, and no instruction in the
+  issue is followed. If the issue can't be read, the round goes ahead without
+  it.
+- **Packages.** The description's Packages section lists every package
+  installed by the runs on the pull request; refusals cover the latest run.
+- **Descriptions wardby can't confirm as its own.** If a person edited the
+  description, wardby doesn't overwrite it. It keeps one comment with the
+  description proposed by its latest run, stamped with the commit it
+  describes and written before a push, edited in place by later rounds. A
+  review uses that proposal only for the head it reviews: a requirement is met
+  if either the live description or the proposal meets it. If the author
+  copies the proposal in, wardby takes the description back and keeps it up
+  to date again.
+- **Older pull requests.** For a pull request opened by an earlier wardby
+  version, wardby rebuilds the description its first run wrote from stored
+  records. If the live description still matches, wardby updates it;
+  otherwise it gets the comment.
+
+A description update doesn't trigger an extra review. `get_run` shows what
+happened as `prDescriptionOutcome`. See
+[`docs/code-review-agents.md`](../docs/code-review-agents.md#how-the-pull-request-description-is-kept-current).
+
 If a repository already forwards reviews to a webhook through a
 hand-written CI workflow to fix them automatically, turn on `review_fix` and
 then remove that workflow and its webhook, so a review doesn't trigger two

package/help/sharing-agents.md

@@ -0,0 +1,59 @@
+---
+id: sharing-agents
+title: Share an agent, or make it public
+summary: Grant one person or everyone signed in access to an agent, including a public agent anyone can edit.
+audience: operator
+tags: [sharing, grant_access, public, access-control, agents]
+appliesTo: ">=0.7.0"
+---
+
+# Share an agent, or make it public
+
+An agent's owner controls who else can reach it with `grant_access`,
+`revoke_access` and `list_access`. Levels, lowest first:
+
+- `read`: see the agent in `list_agents` and `get_agent`.
+- `execute`: also run it (`trigger_agent`).
+- `write`: also change it (`update_agent`, schedule, webhooks, tools).
+
+The grantee is one person, `{"subject": "..."}` or `{"principalId": "..."}`,
+who must have signed in once, or `"everyone"`: any principal signed in to the
+MCP server.
+
+## Public agents
+
+Grant `everyone` at `read` or `execute` for an agent anyone can see or run.
+Grant `everyone` at `write` for an agent anyone can also edit.
+
+Everyone-`write` is refused while the agent holds any of its owner's bindings:
+secrets, datastores, repositories, sub-agents, tool capabilities, or a coding
+repository, so a coding agent can't be public-write. Otherwise anyone could
+rewrite its prompt and use them. Detach them first, or grant `execute` instead.
+The reverse holds too: `attach_secret`, `attach_datastore`, `link_repository`,
+`attach_subagent`, `attach_tool` with capabilities, and `update_agent` making
+it a coding agent are refused on an agent everyone can write. Revoke or lower
+the everyone grant first.
+
+### Cap what a public-write agent can spend
+
+Runs of a shared agent are charged to its owner. With `write`, anyone signed in
+can change the agent's model, per-run budget, turns and schedule, and create
+webhooks that trigger it. Before granting everyone `write`, put the agent in a
+budget group (`create_budget_group`, then `update_agent` with `budgetGroupId`).
+Only the owner can change
+budget-group membership, so the group's limit caps total spend whatever anyone
+else changes.
+
+### After you revoke or lower the grant
+
+- **Webhooks:** a webhook fires only while its creator can still run the
+  agent. Revoking the everyone grant stops webhooks other people created;
+  lowering it to `execute` keeps them firing. Use `list_webhooks` and
+  `delete_webhook` to remove them; the owner can delete any webhook on the
+  agent.
+- **Schedule:** a schedule someone else set stays on the agent. Check it with
+  `get_agent` and remove it with `disable_schedule`.
+- **Prompt and settings:** edits stay. Check the prompt, model and budget with
+  `get_agent`.
+
+See [Identity and access](identity-and-access.md) for sign-in and scopes.

package/help/slack-notifications.md

@@ -28,11 +28,25 @@ per card. This is outbound only: nothing in Slack starts or affects a run.
 
 ## Events
 
-`issue_picked_up`, `run_failed` (top-level runs only), `pr_opened`,
-`review_posted` (approve / changes requested / comment), `review_fix` (round
-started, or stopped at the cap), and `pr_closed` (merged or closed, with any
-Jira status move). `events` on a link narrows which of these post; omitted
-means all six. `includeCost` appends the run's spend line.
+`issue_picked_up`, `run_failed` and `run_blocked` (top-level runs only),
+`pr_opened`, `review_posted` (approve / changes requested / comment),
+`review_fix` (round started, or stopped at the cap), `pr_closed` (merged or
+closed, with any Jira status move), and `packages_audited` (from Wardby 0.7.0,
+top-level runs only: what its coding runs installed under package audit mode,
+described in the `package-audit-mode` help article; it doesn't change the
+thread's status). `events` on a link narrows which of these post; omitted
+means all eight. `includeCost` appends the run's spend line.
+
+A pull request opened from a GitHub issue mention posts `pr_opened` and
+`pr_closed` too, the same as one opened for a Jira issue. Its thread is the
+issue's, one per GitHub issue, not one per pull request; once the pull request
+is recorded for the issue, its `review_posted` and `review_fix` events reply
+there as well. The run events of a run a GitHub issue mention started keep a
+thread of their own.
+
+A `run_blocked` event uses the same ⛔ package registry wording and fixes as
+[Run status comments](status-comments.md). See [Package refusal errors](errors/package-refusals.md)
+for allowlist, release-age, advisory, and malware guidance.
 
 wardby never posts code, diffs, review text, or run output to Slack.
 

package/help/status-comments.md

@@ -0,0 +1,31 @@
+---
+id: status-comments
+title: Run status comments
+summary: Read GitHub and Jira run outcomes, package registry blocked statuses, and Slack notifications.
+audience: operator
+tags: [status, comments, github, jira, slack, blocked, packages, mentions]
+appliesTo: >=0.2.1
+---
+
+# Run status comments
+
+Mentioning the GitHub App starts a run and posts a working status comment.
+The comment is updated when the run finishes, with pull request links, an
+answer, or a failure. This includes a run that a deploy moved to a new
+control-plane process. Jira requests also report their outcome in a status
+comment.
+
+When coding sub-runs record package refusals and no pull request or pushed
+changes result, the comment shows ⛔ **Blocked by the package registry: no
+changes were made.** It lists refused packages, registry codes, and fixes.
+Slack notifications use the same blocked wording. Lists are limited to ten
+distinct entries with a count of remaining refusals; use `get_run` for all.
+When changes were pushed despite refusals, the pull request link stays and
+there is a ⚠️ dependency install warning. Without refusals, the usual ✅
+success or ❌ failure wording remains.
+
+An approver can update the coding agent's package allowlist or policy with
+`update_agent` (requires `packages:approve` or `agents:admin`), then mention
+`@wardby` again. See [Package refusal errors](errors/package-refusals.md) for
+code-specific fixes and [Approve packages for coding agents](coding-packages.md)
+for policy details. Malware checks cannot be bypassed.

package/help/stop-run.md

@@ -0,0 +1,58 @@
+---
+id: stop-run
+title: Stop or cancel a run
+summary: Use stop_run to stop a pending, queued, or running run and its in-flight sub-agent runs; it ends as cancelled.
+audience: operator
+tags: [runs, stop run, cancel run, stop_run, cancelled, schedules, coding-agents, native-agents, sandbox]
+appliesTo: ">=0.7.0"
+---
+
+# Stop or cancel a run
+
+Call the MCP tool `stop_run` with the run's id to stop a run that has not
+finished. Add an optional `reason`; it is recorded on the run.
+
+```text
+stop_run {"runId": "<run id>", "reason": "unwanted scheduled run"}
+```
+
+Find the id with `list_runs` (filter with `"status": "pending"` or
+`"running"`). To stop a schedule from creating more runs, disable it with
+`disable_schedule` as well; `stop_run` stops one run, not the schedule.
+
+## What happens
+
+The run ends as `cancelled`, with `Stopped by <your id> with stop_run: <reason>`
+in its `stopRequestReason` (and, for a native run, in its `error`).
+
+| The run is                                 | `stop_run`                                                                                                                                                                                                     |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pending, or a coding run queued for a slot | Ends it now. It never starts.                                                                                                                                                                                  |
+| A running native run in the control plane  | Ends it now; the run stops at its next step. A model turn already under way finishes first; a tool call already under way is aborted within a few seconds.                                                     |
+| A running native run in the sandbox        | Ends it now and ends its gateway session, so the worker's next call is refused and it exits. A worker still running after a short grace (5 seconds) is killed and removed; a warm pool worker is never reused. |
+| A running coding run                       | Ends it, cancels its model proxy session, and stops and removes its worker. It opens or updates no pull request afterwards.                                                                                    |
+| Already finished (any other status)        | Changes nothing and returns its status. Calling `stop_run` again is safe.                                                                                                                                      |
+
+Sub-agent runs the stopped run delegated, and that are still pending or running,
+are stopped too (their ids are in `stoppedChildRunIds`).
+
+Spend already recorded stays counted against the budget. A stopped run is not a
+failure: Slack notifications say it was cancelled, and no defect is filed.
+
+If the result still shows `pending` or `running`, the stop has been recorded
+but has not landed yet; check again with `get_run`.
+
+## Who can stop a run
+
+You need the `runs:trigger` scope and `execute` access to the run's agent, the
+same as `trigger_agent`. The agent's owner can stop any of its runs, including
+scheduled ones; anyone else can stop only runs they triggered. A run you cannot
+see returns `Run "<id>" not found.`, exactly like a missing one; a run you
+triggered but whose agent you can no longer execute returns a 403.
+
+## Related
+
+- [Operate managed agents](operating-agents.md)
+- [Run native agents in a sandbox](native-sandbox.md)
+- [Slack notifications](slack-notifications.md)
+- [Run lost](errors/run-lost.md), for runs a deploy interrupted

package/help/troubleshooting/budgets.md

@@ -41,3 +41,31 @@ with `already_dispatched` and a message naming how many delegations were
 made and how many are waiting for budget.
 
 For a shared-group refusal, read [Budget group exhausted](../errors/budget-group-exhausted.md).
+
+To see exactly which limit stopped a run and with what numbers, read
+`budgetEvents` in `get_run`; see the help article `errors/budget-exhausted`.
+A lead and the sub-agents it starts in the same budget group hold the lead's
+budget once (or its live sub-agent runs' unspent holds, if the lead's overrun
+let them be topped up past it), and `get_budget_group` reports `heldRuns` for
+each period.
+
+A coding run's per-request holds price the cached part of the input at the
+cache-read rate after the first reply of a conversation; see the help article
+`errors/budget-exhausted`.
+
+## Allowing a small overrun
+
+If coding runs stop just short of finishing, set `allowedOverrunPercent` (0 to
+100, default 0) on the coding agent so a run may spend that percent beyond
+`budgetUsd`. Set it on a lead agent that delegates to raise its run tree's
+ceiling for coding sub-agents; native runs' own model calls are not affected.
+
+The overrun is not reserved. A run reserves its base budget, and is topped up
+toward its limit while it works, only from room its budget group and run tree
+have at that moment. Budget group and run-tree caps stay hard: in a full group
+the run stops at what it was granted, and its budget sentence says so ("Only
+$0.40 of its 10% allowed overrun was available because the "team" group had no
+more left of its daily cap."). `get_run` shows `budgetBaseUsd`, the limit in `budgetLimitUsd`, and what
+has been granted so far in `budgetReservedUsd`. A run still stopped for budget
+keeps its work as a draft pull request you can continue. See
+`errors/budget-exhausted`.