@wardby/cli 0.7.0 → 0.8.0

package/docs/claude-code-plugin.md

@@ -0,0 +1,164 @@
+# Claude Code plugin: the wardby runs pane
+
+From Wardby 0.8.0, the `wardby-runs` Claude Code plugin shows your wardby agent
+runs in a pane beside the chat. It lists runs grouped by pull request, shows a
+run's request, outcomes, services, errors and final answer, and can continue a
+finished Claude Code run in your own terminal.
+
+The plugin lives in this repository under `plugins/claude-code/`, and the
+repository is its marketplace (`.claude-plugin/marketplace.json`). It talks only
+to the wardby MCP server your Claude Code session already has, through
+`list_runs`, `list_agents`, `get_run` and `get_run_transcript`, so it shows
+exactly what those tools show you and needs no token of its own.
+
+## Install
+
+### With the wardby CLI
+
+```sh
+npx @wardby/cli@latest claude-plugin install
+```
+
+This installs the plugin from `wardby/wardby` and offers to allow the pane's
+read-only tools for auto mode (see [Permissions](#permissions)). Options:
+
+| Option                 | What it does                                                                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--server-url <url>`   | Registers the wardby MCP server at this `https` URL (for example `https://wardby.example.com/mcp`) when Claude Code has none named `wardby`             |
+| `--server-name <name>` | The MCP server the pane uses, as `/mcp` lists it (default `wardby`); the allow rules it adds follow the name, for example `mcp__wardby-prod__list_runs` |
+| `--marketplace <src>`  | Installs from another marketplace: an operator's own repository (`your-org/claude-plugins`) or a local folder                                           |
+| `--allow-tools`        | Allows the pane's read-only tools without asking; `--no-allow-tools` leaves permission rules alone                                                      |
+| `--fullscreen`         | Also switches Claude Code's terminal to its fullscreen view (see [Terminal](#in-the-terminal)); it applies to every session                             |
+| `--yes`                | Answers yes to every question                                                                                                                           |
+
+`wardby quickstart` offers the same install once it has connected Claude Code
+(`--claude-plugin` installs it without asking, `--no-claude-plugin` skips it),
+and `wardby doctor` lists the plugin, the MCP server and the allow rules
+alongside its other checks, without failing when the optional pane is missing.
+
+`wardby claude-plugin status` reports whether the plugin, the MCP server and
+the allow rules are in place. `wardby claude-plugin uninstall` removes the
+plugin and only the settings install added: the rules it added and the
+fullscreen view if it switched it on. It leaves the MCP server in place.
+
+The CLI writes to the settings file of the Claude Code it finds:
+`$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json`. It refuses a
+settings file that isn't valid JSON instead of overwriting it.
+
+### In Claude Code
+
+At the prompt of a terminal session:
+
+```
+/plugin install wardby-runs --marketplace wardby/wardby
+```
+
+In the desktop app, where `/plugin` doesn't run: click **+** next to the prompt
+box, then **Plugins**, **Add marketplace** with `wardby/wardby`, then **Add
+plugin**. A plugin installed from a terminal at user scope also loads in the
+desktop app's local Code sessions that read the same Claude Code configuration.
+
+Open the pane with `/wardby-runs`; `/wardby-runs close` closes it and
+`/wardby-runs clear` clears its filters.
+
+### The MCP server
+
+The pane needs an MCP server named `wardby` in Claude Code. `wardby quickstart`
+registers one; for a deployed instance, add it with `--server-url` above or:
+
+```sh
+claude mcp add --transport http --scope user wardby https://wardby.example.com/mcp
+```
+
+then sign in with `/mcp`. Another name works too: set the plugin's **wardby MCP
+server** option to it. A server added through the Claude apps' **Connectors**
+settings is not a Claude Code MCP server and the pane doesn't use it. With another
+name, install with `--server-name <name>` so the allow rules match it, and the
+pane's own hints name it too.
+
+## Permissions
+
+The pane reads only, with the caller's own access:
+
+| Pane feature         | MCP tool             | Scope         | What you see                                                                   |
+| -------------------- | -------------------- | ------------- | ------------------------------------------------------------------------------ |
+| Run list             | `list_runs`          | `agents:read` | All runs of agents you own, and the runs you started on agents shared with you |
+| Agent names, budgets | `list_agents`        | `agents:read` | Agents you can see (the pane asks for `summary: true`)                         |
+| Run detail           | `get_run`            | `agents:read` | Runs you started, or of agents you own                                         |
+| Continue locally     | `get_run_transcript` | `agents:read` | Same as `get_run`                                                              |
+
+Under Claude Code's auto mode, a plugin's MCP calls go through the same safety
+check as any other, and calls the pane makes on its own timer are refused
+unless allowed. Allow these in `/permissions` (or let `wardby claude-plugin
+install` add them): `mcp__wardby__list_runs`, `mcp__wardby__list_agents`,
+`mcp__wardby__get_run` and `mcp__wardby__get_run_transcript`. The pane never
+calls `stop_run` or any other tool that changes something. When a call is
+refused, the pane says which rules to add.
+
+Plugins are not sandboxed: they run as you. **Continue locally** runs
+`npx @wardby/cli@latest resume - --print` in the folder you give it, passing the
+transcript's download link on standard input; the link is never drawn, stored
+or logged. The import writes only under `~/.wardby/` and the new worktree.
+
+## Using the pane
+
+- **Ledger** (desktop): runs grouped by pull request (or Jira issue), each group
+  one row with its state and total cost, folded once every run in it finished.
+  A pull request with one run is one line. Runs that touch no pull request are
+  under **Other**. Each line names its step (opened, review, fix 1, …), with
+  sub-agent runs under their lead.
+- **Strips** (desktop): one card per pull request, its steps drawn as a row of
+  dots; click a step's name to see it.
+- **Filters**: show all, active, failed or finished runs, or type to match an
+  agent, status, trigger or task.
+- **Run detail**: what started the run and what it produced, its request and
+  final answer (as markdown; **Show full text** for all of it), services,
+  errors, the run tree, and **Continue locally** for finished Claude Code runs
+  with `sessionResume` on (see [Resume Claude Code runs locally](coding-agent-setup.md#resume-a-run-locally)).
+
+The pane refreshes every 10 seconds while a run is active and every 60 seconds
+otherwise (the plugin's **pollSeconds** and **idleSeconds** options), asks only
+for what changed since its last refresh, backs off when the server fails, and
+polls only while it is open.
+
+### In the terminal
+
+Claude Code's classic terminal view draws a plugin pane as a band above the
+prompt and doesn't pass mouse clicks to plugins: use the keyboard (ctrl+x tab
+focuses the pane, then `1`–`9` open a run, `r` refreshes, `b` goes back, `x` or
+Escape closes). In the fullscreen view the pane is a side bar beside the chat
+and takes clicks. Turn it on with `"tui": "fullscreen"` in your Claude Code
+settings (or `--fullscreen` above, or `CLAUDE_CODE_NO_FLICKER=1`), then restart
+Claude Code. The desktop app needs none of this.
+
+## Add it to your own marketplace
+
+The plugin keeps everything it needs in `plugins/claude-code/` and has no
+instance-specific values, so an operator can list it in their organization's
+marketplace. Point an entry at this repository's subfolder, pinned to a
+release:
+
+```json
+{
+  "name": "wardby-runs",
+  "source": {
+    "source": "git-subdir",
+    "url": "wardby/wardby",
+    "path": "plugins/claude-code",
+    "ref": "v0.8.0"
+  }
+}
+```
+
+Preset its options for your users in managed settings under
+`pluginConfigs["wardby-runs@<your marketplace>"].options` (for example the MCP
+server's name), and ship the allow rules above in the same managed settings.
+When managed settings set `allowManagedHooksOnly`, a plugin a user installs
+loads no hooks: install it through managed settings instead.
+
+## Limits
+
+- Plugins draw in the Claude Code terminal, the desktop app's Code tab and VS
+  Code; not in claude.ai/code, `claude -p`, the Agent SDK or WSL.
+- The pane polls; there is no push.
+- A run's live steps and a readable transcript are not shown yet.

package/docs/code-review-agents.md

@@ -574,6 +574,12 @@ requires more than owning the agent:
 - **A repository is the owner's binding.** Principals the agent is shared
   with (`grant_access`) can't link, unlink or change its repository, even at
   `write`.
+- **A coding agent's extra repositories follow the same rules.** A
+  `link_repository` call with `access: "write"` and no triggers on a coding
+  agent adds a repository its runs may work in; it needs the same GitHub write
+  access or admin approval as the default repository. Unlinking it
+  refuses queued runs for that repository when they start, and a run already under way is refused at
+  its final push check (`repo_access`), so nothing is pushed.
 
 The authorization is stamped on the link (`authorizedVia`: `host_permission`,
 `admin`, or `grandfathered`) and **checked again every time it is used**: on

package/docs/coding-agent-setup.md

@@ -69,6 +69,81 @@ request currently targets, and the agent resolves any conflicts — see
 Over stdio, the local operator holds every role, so `repositoryAdminOverride`
 is the way to approve a repository there.
 
+## A coding agent's repositories
+
+A coding agent works in one repository per run, chosen from its list:
+
+- `codingProfile.repository` is the **default** repository.
+- `link_repository` adds more. A link on a coding agent takes
+  `access: "write"`, no triggers, no `checkName` and an optional `baseRef`
+  (the base branch for runs in that repository; default: the profile's
+  `baseRef`). The repository must be on GitHub or a `local:` path. Linking the
+  default repository again is refused.
+- `unlink_repository` removes one.
+
+```json
+{ "agentId": "<agent id>", "repository": "your-org/other-repo", "access": "write", "baseRef": "main" }
+```
+
+Only the agent's owner (or an admin approving explicitly with `adminOverride`)
+can add a repository, and the same authorization applies as for the default;
+see [Repository authorization](#repository-authorization).
+
+The repository is chosen when the run starts and never changes during it:
+
+- `trigger_agent` takes an optional `repository`. Leave it out and the run uses
+  the default repository. Name one that is not on the list and the call is
+  refused with `repository_not_listed`. Only the agent's owner can pass
+  `repository`, unless `codingProfile.allowWebhookTaskOverride` is on; anyone
+  else is refused with a 403.
+- A webhook body can carry `wardbyRepository` the same way (not `repository`,
+  which forwarded payloads already use). A refused value is a 400
+  `{ "error": "invalid_repository" }`. A webhook can carry `wardbyRepository`
+  only when `codingProfile.allowWebhookTaskOverride` is on, whoever created
+  the webhook. With the flag off a well-formed value is refused with 403
+  `{ "error": "disabled" }`, before it is compared with the list; a malformed
+  one (not a string, empty, or over 300 characters) is a 400 either way.
+- A lead's `delegate_to_<name>` call takes `repository`. When the sub-agent has
+  more than its default repository the call must name one, unless
+  `continuePriorRun` is given: a follow-up works in the repository of the run
+  it continues. Without a choice the call is refused with
+  `repository_required`.
+
+Everything else about the agent is shared across its repositories: toolchain,
+worker image, services, system prompt, budget, protected paths and the package
+allowlist. If two repositories need different ones, use two agents.
+
+Being on the list lets a run work in a repository; it starts nothing there.
+Reviews, mention follow-ups, fix rounds and mark-ready route by repository and
+trigger, so a pull request opened in a linked repository gets none of them by
+itself. For follow-ups, link the lead and the reviewer on each listed GitHub
+repository with the triggers they need.
+
+An agent with no repository links works only in its default repository.
+Changing an agent's `kind` is refused while it has write links without
+triggers; unlink them first.
+
+Every write link without triggers on a coding agent is on its list, whenever it
+was made. An agent converted from native to coding can hold such links from its
+native configuration: run `list_repositories` on converted agents and unlink any
+repository their runs should not work in.
+
+For the refusals, see [Repository required](../help/errors/repository-required.md)
+and [Repository not on the agent's list](../help/errors/repository-not-listed.md).
+
+## See what a run was asked to do
+
+`get_run` returns a coding run's `request`: the task it received from
+`trigger_agent`, a webhook or a lead, or the agent's default task. It leaves out
+the agent's standing instructions. On a delegated run, this shows what the lead
+told the coding agent, so you can tell a vague task from a run that missed a
+clear one.
+
+The value is masked when it's read: the values of the agent's attached secrets
+and token-shaped values are replaced. If the agent's secrets can't be read,
+`get_run` returns `requestUnavailable: true` instead of the text. Runs from
+before this field have no `request`.
+
 ## Local repositories
 
 A coding agent (or a review agent) can work on a git repository on the same
@@ -313,7 +388,8 @@ agents.
 - **`false`.** Bare mode is off. Claude Code loads `CLAUDE.md` and skills
   itself, through its native Skill tool, instead of reading them from the
   system prompt. Repository settings, hooks, MCP configuration, agents, and
-  commands are still never loaded in either mode; native loading also locks
+  commands are still never loaded in either mode (the only MCP tools a coding
+  run has are those of [attached MCP servers](mcp-servers.md#coding-agents)); native loading also locks
   Claude Code's own hooks to wardby's managed set.
 
 If the worker can't write the native-mode context to disk for a run, that

package/docs/coding-worker-byo-images.md

@@ -95,8 +95,10 @@ the exact command.
 On a local quickstart install with the Docker launcher, `workerImageRef` can be
 the local image ID (`docker image inspect --format '{{.Id}}' <your-tag>`).
 Otherwise, build it, push it to your own registry, and note the resulting digest —
-`docker inspect --format '{{index .RepoDigests 0}}' <your-tag>` after a push,
-or read it straight from `docker buildx build --push`'s output.
+`docker inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' <your-tag>`
+after a push lists one digest per registry the image is in: take the one in
+the registry your cluster pulls from, not simply the first. Or read it straight
+from `docker buildx build --push`'s output.
 
 ## Pointing an agent at it
 

package/docs/coding-worker-isolation.md

@@ -143,7 +143,8 @@ deeply to process is refused with `request_nesting_too_deep`.
 
 - **Anthropic Messages** (`parseAnthropicRequest`): a fixed set of keys,
   text/`tool_use`/`tool_result`/thinking blocks, exactly the two Wardby tool
-  names, the reviewed beta values, the thinking mode the run's model catalog
+  names plus the run's own MCP tool names (see
+  [Remote MCP tools](#remote-mcp-tools)), the reviewed beta values, the thinking mode the run's model catalog
   entry names, and only effort levels that entry lists in `efforts` (top-level,
   or on an effort-only system message for models that change effort per turn).
 - **OpenAI Responses** (`parseOpenAiRequest`), built from what the pinned
@@ -157,8 +158,15 @@ deeply to process is refused with `request_nesting_too_deep`.
     `previous_response_id`, `conversation` and `metadata`, is refused with
     `openai_request_key_not_allowed:<key>`.
   - Tools: `function` and `custom` definitions, and `namespace` groups of
-    them, either in `tools` or in Codex's `additional_tools` input item. Every
-    other tool type, including all hosted tools (`web_search`, `mcp`,
+    them, either in `tools` or in Codex's `additional_tools` input item. A
+    `tool_search` tool is accepted only in the top-level `tools`, only with
+    `execution: "client"` (Codex runs the search over its own tools) and only
+    with `type`, `execution`, `description` and `parameters`; a
+    server-executed search is refused with
+    `openai_tool_not_allowed:tool_search`. Each tool list holds at most 512
+    tools, and a request at most 512 distinct tools in all; a definition
+    repeated in replayed tool search results counts once. Every other tool
+    type, including all hosted tools (`web_search`, `mcp`,
     `code_interpreter`, `image_generation`, `file_search`, `local_shell`, and
     so on), is refused with `openai_tool_not_allowed:<type>`. Tool names are
     checked for shape (`[A-Za-z0-9_-]{1,128}`) but not against a fixed list:
@@ -169,10 +177,17 @@ deeply to process is refused with `request_nesting_too_deep`.
   - Input items: `message` (`input_text`/`input_image` for user, developer
     and system; `output_text` for assistant), `reasoning`, `function_call`,
     `function_call_output`, `custom_tool_call`, `custom_tool_call_output`,
-    `agent_message` and `additional_tools`, each with only the keys Codex
-    sends. Anything else (`input_file`, `input_audio`, `item_reference`,
-    replayed hosted-tool calls, `compaction`, `local_shell_call`) is refused
-    with `openai_input_not_allowed:<type>`. An `input_image` must be an inline
+    `agent_message`, `additional_tools`, `tool_search_call` and
+    `tool_search_output`, each with only the keys Codex sends. The two tool
+    search items must say `execution: "client"`. A `tool_search_call` may
+    carry only a string `query` and a positive integer `limit` as its
+    arguments. Every tool a `tool_search_output` brings into the conversation
+    passes the same checks as a top-level tool, except another `tool_search`;
+    a `function` there may also carry `defer_loading: true`, which Codex sets
+    on the tools it loads through tool search, and nowhere else. Anything
+    else (`input_file`, `input_audio`, `item_reference`, replayed hosted-tool
+    calls, `compaction`, `local_shell_call`) is refused with
+    `openai_input_not_allowed:<type>`. An `input_image` must be an inline
     `data:image/{png,jpeg,gif,webp};base64,` URL, as Codex's `view_image`
     produces; a remote URL or a `file_id` is refused with
     `openai_remote_input_not_allowed`.
@@ -218,6 +233,62 @@ rather than silently widening what reaches OpenAI. Upgrading the pinned
    then widen `parseOpenAiRequest` only for what that review accepts, and
    document it in the list above.
 
+### Remote MCP tools
+
+A coding agent can have [remote MCP server](mcp-servers.md#coding-agents) tools
+attached. The worker still reaches only the proxy:
+
+1. When a run has MCP tools, the control plane mints a per-run MCP token
+   (`rmt_` plus 32 random bytes, base64url). Only its SHA-256 hash is stored
+   with the run's proxy session; the token reaches the worker only as
+   `WARDBY_MCP_TOKEN`, and is never logged. It is valid only on the proxy's
+   `/mcp` route, and only while the session is active and before its deadline.
+   It is not the run capability, and it is not accepted by the model routes.
+2. The worker (Claude Code or Codex, over HTTP) calls `POST /mcp` on the proxy
+   with `Authorization: Bearer <token>`. The proxy checks the token and
+   forwards the request to the native gateway's `/coding-mcp` route
+   (`WARDBY_MCP_GATEWAY_URL`). The proxy never sees an MCP server's URL or
+   secrets. Without `WARDBY_MCP_GATEWAY_URL`, `/mcp` answers `503`
+   `mcp_unavailable`. A bad or expired token gets a `401` without a
+   `WWW-Authenticate` header, so a client doesn't start OAuth discovery.
+3. The gateway checks the token again (the proxy is not trusted), checks the
+   live attachment on every call, counts the call against the run's limit
+   (`WARDBY_MCP_MAX_CALLS_PER_RUN`, default 100; failed calls count), runs it,
+   and removes the server's secret values from the result before it leaves.
+   Logs for the route carry the method, status and session id, never bodies,
+   arguments, results or the token.
+
+The proxy can reach the gateway's HTTP port. It holds no gateway credentials,
+and each route authenticates separately. The Anthropic allowlist accepts the
+run's own MCP tools as plain client tools named
+`mcp__wardby_mcp__<server>__<tool>`, and only those the run pinned.
+
+Where the token is exposed:
+
+- **Claude Code.** The agent container receives the MCP configuration, its
+  bearer header included, on Claude Code's command line. That container runs no
+  model commands and shares no PID namespace with the tool runner, so commands
+  the model runs can't read it.
+- **Codex.** Shell commands run in the same container as Codex, and can read
+  the token through `/proc`. For that reason a Codex agent may use only tools
+  the server marks `readOnlyHint: true`: Wardby refuses any other tool when you
+  attach, when a run loads its tools, and on every call. `readOnlyHint` is the
+  server's own claim, which Wardby can't verify, so the allowlist remains the
+  owner's control. A leaked token is limited to this run's allowed tools, the
+  call limit and the run's deadline.
+
+A repository's own MCP configuration is never loaded. MCP tools need this
+release's Claude worker image and a new Codex driver image; an older image
+ignores the token and gets no MCP tools, and the run does not fail. Codex
+models that use tool search get their MCP tools through `tool_search_output`
+items; the proxy checks every tool in them like a top-level tool (see
+[Model request allowlist](#model-request-allowlist)).
+
+The read-only rule follows the provider a run was started with
+(`CodingRun.provider`), at pin time and on every call, not the agent's current
+profile. At attach, a coding agent counts as Codex unless its provider is
+exactly `claude-code`, so an agent without a profile is held to the rule too.
+
 The proxy also binds a second listener, the **deny port** (`8788`,
 `CODING_PROXY_DENY_PORT`), which serves nothing: it accepts a connection,
 sends no bytes and closes it immediately

package/docs/debugging-agent-runs.md

@@ -0,0 +1,242 @@
+# Debugging an agent run
+
+You can triage most agent problems yourself with the Wardby MCP and GitHub. Only
+some failures need someone with server logs.
+
+## Start here
+
+Find the run with `list_runs`, then read it with `get_run`. Then go to the section
+for what you see.
+
+```mermaid
+flowchart TD
+    start["Find the run: list_runs, then get_run"]
+    start --> none["No run started<br/>Check the repo links and triggers"]
+    start --> failed["Failed or refused<br/>Read failureCategory and the final text"]
+    start --> nopr["Succeeded, no PR<br/>Read outcome in codingResult"]
+    start --> missed["PR, but it missed<br/>Read the diff and the review"]
+    none --> nopull["See: No pull request appeared"]
+    nopr --> nopull
+    failed --> runfailed["See: The run failed"]
+    missed --> didntfix["See: The agent didn't fix what you expected"]
+    runfailed -- still unexplained --> operator["See: When you need an operator"]
+    nopr -- why it decided that --> transcript["See: Run transcripts"]
+    missed -- why it decided that --> transcript
+```
+
+## What you can use without server access
+
+These all work through the Wardby MCP or GitHub, and you only see runs you have
+access to.
+
+| Tool                                                                                                            | What it tells you                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_runs` (agent id, optional `status`)                                                                       | An agent's recent runs: status, trigger, cost, turns, final text, and which run started it                                                                                                                                                                                                                                                                                               |
+| `list_runs` without an agent id (from 0.8.0)                                                                    | Your runs across every agent, each with `agentName`; no final text. `active: true` or `since` (ISO time) narrow it                                                                                                                                                                                                                                                                       |
+| `get_run` (run id)                                                                                              | One run in full, adding `failureCategory`, `diagnosticId`, `codingResult.outcome`, `request`, budget events and package refusals                                                                                                                                                                                                                                                         |
+| `triggerInfo`, `outcomes`, `serviceReadiness` (from 0.8.0, on `get_run` and on `list_runs` without an agent id) | What started the run (the pull request and whether it was a review or a mention, the issue, the schedule or the lead), what it produced (pull requests opened, comments, checks) and each service's state, in the admin viewer API's shapes. Follow a pull request from the run that opened it through its review and fix rounds by matching one run's outcome to the next run's trigger |
+| `get_agent`, `list_repositories`, `list_subagents`                                                              | How the agent is set up: prompt, model, budget, repo links and triggers, sub-agents                                                                                                                                                                                                                                                                                                      |
+| `search_help`, `get_help_article`                                                                               | Help for an error code or failure category                                                                                                                                                                                                                                                                                                                                               |
+| `cost_report`                                                                                                   | What runs cost, when spend is the question                                                                                                                                                                                                                                                                                                                                               |
+| `get_run_transcript`                                                                                            | The run's conversation, for Claude Code runs with `sessionResume` on                                                                                                                                                                                                                                                                                                                     |
+| `stop_run`                                                                                                      | Stops a run that's stuck                                                                                                                                                                                                                                                                                                                                                                 |
+| The PR, issue or Jira ticket                                                                                    | The diff, CI, the review, and the comment the run posted                                                                                                                                                                                                                                                                                                                                 |
+
+From Wardby 0.8.0, `list_agents` with `summary: true` returns each agent's id,
+name, kind, model, coding provider, budget, owner and your access, without the
+prompt and coding profile. Admins (the `admin` role, `admin:view` scope) can add
+`all: true` to `list_agents` or `list_runs` to see every agent or run in the
+deployment.
+
+Admins can also use the [Wardby Viewer](viewer-api.md), a desktop app showing runs,
+sub-agent trees, triggers and outcomes for every owner.
+
+## The run failed
+
+Call `get_run` and read `status`, `error`, `failureCategory` and the final text. A
+failed coding run's `error` looks like
+`coding_failure_repo_access:coding_diag_…`: the middle part is the stage that
+failed, and the ID is what an operator searches for.
+
+| What you see                    | Likely cause                                              | What to do                                                           |
+| ------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------- |
+| `repo_access`                   | The agent's owner lost access, or a repo link was removed | Check `list_repositories` and the owner's GitHub access              |
+| `repo_access_unavailable`       | GitHub couldn't be reached reliably                       | Try again later                                                      |
+| `workspace`                     | Often a workspace disk size above the server's limit      | Lower `workspaceDiskMb`, or ask an operator to raise the limit       |
+| `executor` while running checks | The run may have run out of memory, among other causes    | Reduce what the checks run; send the ID to an operator if it repeats |
+| `merge_conflict`                | The branch conflicts with its target                      | Read the `merge-conflict` help article                               |
+| `service_unready`               | A service the run needs, such as Postgres, didn't start   | Check `.wardby/services.yaml` and the agent's `services`             |
+| `coding_turn_limit`             | The run used all its turns                                | Raise `maxTurns` or narrow the task                                  |
+| `budgetEvents`, or `refused`    | The run, run tree or budget group ran out of money        | Raise the budget or check spend with `cost_report`                   |
+| `packageRefusals`               | A package isn't allowed or is too new                     | Add it to `packageAllowlist`, or wait out the release age limit      |
+
+For anything else, call `search_help` with the code or category. If that doesn't
+explain it, see [When you need an operator](#when-you-need-an-operator).
+
+**Prompt for Claude Code:**
+
+```
+Wardby run <run id> failed. Why, and what can I do about it?
+If it needs server logs, give me the diagnosticId.
+```
+
+## No pull request appeared
+
+First find out whether a run started, using `list_runs` on the lead or router,
+then on the coding agent.
+
+| What `list_runs` shows           | What it means                                                                                              | What to do                                                                                      |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| No new run                       | The request never started anything: nothing is linked with that trigger, or the person doesn't have access | Check `list_repositories` on the router. Only one agent per repo can hold the `mention` trigger |
+| Lead ran, no coding run under it | The lead chose not to delegate                                                                             | Read the lead's final text, which should say why                                                |
+| Coding run failed or was refused | See [The run failed](#the-run-failed)                                                                      |                                                                                                 |
+| Coding run succeeded, with no PR | Check `codingResult.outcome` in `get_run`                                                                  | See below                                                                                       |
+
+| `outcome`          | Meaning                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `no_changes`       | The agent changed nothing. Its final text should say why: the request may be vague or already done. On Claude Code, the transcript shows how it decided |
+| `budget_exhausted` | It ran out of money before finishing. Raise the budget or narrow the task                                                                               |
+| `branch_pushed`    | A local repo: there's a branch, and no PR by design                                                                                                     |
+
+A mention can also get no reply at all. If a server sets
+`WARDBY_MENTION_EXPLANATIONS=false`, a mention that starts nothing stays silent. An
+operator can look for `mention ignored` or `mention declined` in the server log.
+
+**Prompt for Claude Code:**
+
+```
+I asked Wardby agent <agent name> to <request> in <your-org/your-repo>,
+and no pull request appeared. Why?
+```
+
+## The agent didn't fix what you expected
+
+The run succeeded, so most of what you need is on the PR and the run, with no
+server logs involved. Check these in order:
+
+1. **The diff:** what actually changed.
+2. **The PR description:** the run's final text, including what it says it tested.
+   If it says the tests weren't run, trust CI.
+3. **The review:** whether your review check caught the miss.
+4. **The request:** whether the issue or mention said what you meant.
+5. **The task the agent received:** `request` in `get_run` (from Wardby 0.8.0). On a
+   delegated run, this shows what the lead told the coding agent.
+6. **The transcript:** why it decided that. This is only for Claude Code runs with
+   `sessionResume` on.
+
+The usual causes are a vague request, a lead that dropped something when it rewrote
+the request, a repo rule missing from `AGENTS.md`, or a fix aimed at the symptom it
+was told about.
+
+**To fix it,** comment on the PR, mentioning the App, with what's wrong. The
+follow-up pushes to the same branch and PR, so you don't start again. If the same
+miss keeps happening, add the rule to `AGENTS.md` so future runs follow it.
+
+**Prompt for Claude Code:**
+
+```
+PR <PR URL> from Wardby didn't do what I expected: <what you expected>.
+Where did it go wrong? Draft a follow-up comment, but don't post it.
+```
+
+## Run transcripts
+
+A transcript is the run's conversation: the messages, the tool calls and their
+results, and the files and skills the agent loaded. You can get it yourself,
+without server access, on Claude Code agents.
+
+**To turn it on,** set `codingProfile.sessionResume` to `true` with `update_agent`.
+It's off by default and has to be turned on for each agent. It only applies to runs
+started afterward, so an earlier failure has no transcript. The server also needs a
+blob store, set in the environment of the process that launches coding runs:
+`BLOB_STORE` set to `local`, `gcs` or `s3`, plus `BLOB_STORE_LOCAL_DIR`,
+`BLOB_STORE_GCS_BUCKET`, or `BLOB_STORE_S3_BUCKET` and `BLOB_STORE_S3_REGION`.
+Without `BLOB_STORE`, no transcript is stored.
+
+**To read one,** call `get_run_transcript` with the run ID. It returns a download
+link that works for 10 minutes and a command. Run `npx @wardby/cli@latest resume -`
+in a clone of the repo and paste the link, which also lets you continue the session
+on your machine.
+
+| Transcripts        |                                                                                |
+| ------------------ | ------------------------------------------------------------------------------ |
+| **Who can read**   | Anyone who can read the run: the person who triggered it and the agent's owner |
+| **Stored for**     | Runs that finish, fail, or stop at their budget                                |
+| **Not stored for** | Runs stopped with `stop_run` or ended by their timeout                         |
+| **Removed**        | Thinking blocks, the system prompt, the worker's environment, account details  |
+| **Redacted**       | The agent's attached secrets and the run's own tokens                          |
+| **Not available**  | On Codex agents                                                                |
+
+Redaction removes secret values, not other sensitive text, so a transcript includes
+what the agent saw in the repo and in command output. Turn this on only for agents
+whose runs you're comfortable sharing with everyone who can read them.
+
+**Prompts for Claude Code:**
+
+To turn it on:
+
+```
+Turn on transcripts for Wardby agent <agent name>.
+```
+
+To get one:
+
+```
+Get me the transcript for Wardby run <run id>.
+```
+
+See [Resume Claude Code runs locally](../help/resume-runs-locally.md) for more.
+
+## When you need an operator
+
+Ask someone with server access when `get_run` and help don't explain a failure. The
+specific reason for a failed coding run is written only to the server log, under
+its `diagnosticId`.
+
+**Send them:** the run ID, the `diagnosticId`, the repo, and what you expected to
+happen.
+
+**What the operator can do:**
+
+1. Search the control-plane log for the `diagnosticId`, which holds the real reason.
+2. If that isn't enough, turn on the
+   [debug trace](coding-worker-isolation.md#debug-trace) with `debugTraceMinutes`
+   and reproduce the failure.
+
+The debug trace won't help you directly. Only admins can turn it on, it only covers
+runs started afterward, and its output goes to the run's worker log, which you can't
+read. It can include prompts and repo content, so it isn't exposed through MCP.
+
+**What the trace holds:** the agent's whole stream, the commands it ran with their
+output (Claude Code), final usage and duration, and stream failures in full.
+Token-shaped values are redacted. It stops at 2 MiB per run by default.
+
+**What MCP gives you:** the trace itself isn't available through MCP. You can only
+turn it on or off with `update_agent` (admin role), see when it expires with
+`get_agent` (`debugTraceUntil`), and see whether a run was traced with `get_run`
+(`debugTrace: true`).
+
+**Prompt to try first.** Paste this into any client connected to the Wardby MCP:
+
+```
+Wardby run <run id> didn't do what I expected. What happened, and what can I do?
+If it needs server logs, give me the diagnosticId.
+```
+
+## Known gaps
+
+Two things can't be answered without server access yet.
+
+| Gap                                     | Why it matters                                                       | What you can do                                                     |
+| --------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| The specific reason a coding run failed | You get the stage, such as `executor`, but not why                   | Send the `diagnosticId` to an operator                              |
+| Why a mention got no reply              | With explanations off, a declined mention leaves no reply and no run | Turn explanations on where that's acceptable: `true` is the default |
+
+**To turn explanations on,** an operator removes
+`WARDBY_MENTION_EXPLANATIONS=false` from the server's settings, or sets it to
+`true`, then redeploys. Once on, the GitHub App replies to say why a mention started
+nothing. On a public repo, anyone who can read that comment can see what is or isn't
+linked there.
+
+Run transcripts are limited to Claude Code runs with `sessionResume` on, so they
+don't help on Codex agents.