@wardby/cli 0.6.0 → 0.8.0

package/dist/viewer/api-schema.js

@@ -6,6 +6,7 @@
  * `npm run build:viewer-schemas`, and commit the regenerated files.
  */
 import { z } from "zod";
+import { legacyJsonSchema } from "../core/zod-json-schema.js";
 export const RunStatusSchema = z.enum([
     "pending",
     "running",
@@ -210,3 +211,9 @@ export const VIEWER_SCHEMAS = {
     "viewer-event": ViewerEventSchema,
     "infra-info": InfraInfoSchema,
 };
+/** A viewer schema's JSON Schema (draft-07 keywords, no `$schema`), as the published files spell it. */
+export function viewerJsonSchema(schema) {
+    const json = legacyJsonSchema(z.toJSONSchema(schema, { target: "draft-07", io: "output" }));
+    delete json.$schema;
+    return json;
+}

package/dist/viewer/build-schemas.js

@@ -2,14 +2,18 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import { VIEWER_SCHEMAS } from "./api-schema.js";
+import { viewerJsonSchema } from "./api-schema.js";
 import { OPENAPI_PATH, renderViewerOpenApi } from "./openapi.js";
 export const SCHEMA_DIR = join(dirname(fileURLToPath(import.meta.url)), "schemas");
 export function renderSchemas() {
     return Object.fromEntries(Object.entries(VIEWER_SCHEMAS).map(([name, schema]) => [
         `${name}.schema.json`,
-        `${JSON.stringify(zodToJsonSchema(schema, { name, $refStrategy: "none" }), null, 2)}\n`,
+        `${JSON.stringify({
+            $ref: `#/definitions/${name}`,
+            definitions: { [name]: viewerJsonSchema(schema) },
+            $schema: "http://json-schema.org/draft-07/schema#",
+        }, null, 2)}\n`,
     ]));
 }
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/dist/viewer/graph.js

@@ -1,4 +1,5 @@
 import { periodStart } from "../core/budget-groups.js";
+import { codeProviderOf } from "../coding/code-host.js";
 import { publicCodingRunResult } from "../coding/protocol.js";
 const DEFAULT_SINCE_MS = 60 * 60 * 1000;
 const RELATIVE_SINCE_MS = {
@@ -102,7 +103,7 @@ function outcomesFor(row, pullRequests, sites) {
         !pullRequests.some((pr) => pr.url === result.pullRequestUrl)) {
         outcomes.push({
             kind: "pull_request",
-            provider: "github",
+            provider: codeProviderOf(result.repository),
             repository: result.repository,
             number: result.pullRequestNumber,
             url: result.pullRequestUrl,

package/dist/viewer/openapi.js

@@ -6,8 +6,8 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { stringify } from "yaml";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import { VIEWER_SCHEMAS } from "./api-schema.js";
+import { viewerJsonSchema } from "./api-schema.js";
 import { DEFAULT_GRAPH_LIMIT, MAX_GRAPH_LIMIT, SSE_HEARTBEAT_MS } from "./limits.js";
 export const OPENAPI_PATH = join(dirname(fileURLToPath(import.meta.url)), "../../docs/viewer-api.openapi.yml");
 const AUTH_NOTE = "Requires a bearer token with the `admin:view` scope, held by a caller with the admin role.";
@@ -103,9 +103,7 @@ export const VIEWER_ROUTES = [
 function componentSchemas() {
     const schemas = {};
     for (const [name, schema] of Object.entries(VIEWER_SCHEMAS)) {
-        const json = zodToJsonSchema(schema, { target: "jsonSchema2019-09", $refStrategy: "none" });
-        delete json.$schema;
-        schemas[name] = json;
+        schemas[name] = viewerJsonSchema(schema);
     }
     schemas.ViewerError = {
         type: "object",

package/dist/wardby-bin.js

@@ -42,6 +42,21 @@ async function main() {
         const { helpCommand } = await import("./help/cli.js");
         await helpCommand(process.argv.slice(3));
     }
+    else if (command === "resume") {
+        // Runs on a developer's machine: no environment, database, or server runtime.
+        const { resumeCommand } = await import("./coding/transcript/resume/command.js");
+        process.exitCode = await resumeCommand(process.argv.slice(3));
+    }
+    else if (command === "resume-tools") {
+        // Hidden: the stand-in tool server `wardby resume` configures Claude Code to start.
+        const { resumeToolsCommand } = await import("./coding/transcript/resume/stand-in.js");
+        await resumeToolsCommand(process.argv.slice(3));
+    }
+    else if (command === "claude-plugin") {
+        // Sets up the Claude Code plugin on this machine: no environment, database, or server runtime.
+        const { claudePluginCommand } = await import("./claude-plugin/command.js");
+        process.exitCode = await claudePluginCommand(process.argv.slice(3));
+    }
     else if (command === "knowledge") {
         // Offline bundle validation: no environment, database, or HTTP runtime.
         const { knowledgeCommand } = await import("./knowledge/cli.js");

package/docs/README.md

@@ -13,16 +13,26 @@
   runs are billed.
 - [Agent recipes](agent-recipes.md) gives two copyable setups, an architecture
   keeper and a per-language builder, with the prerequisites each needs.
+- [Debugging an agent run](debugging-agent-runs.md) triages a run that failed,
+  opened no pull request, or missed what you expected.
 - [Coding-agent setup](coding-agent-setup.md) configures the local trusted proxy
   and isolated Codex or Claude Code workers.
+- [Claude Code plugin](claude-code-plugin.md) (0.8.0+) installs the `wardby-runs`
+  pane: your runs beside the chat, grouped by pull request, with run details and
+  Continue locally.
 - [Architecture knowledge bundles](knowledge.md) covers `docs/knowledge/`: the
   concept format, how coding runs and reviewers use it, `wardby knowledge check`,
   and the scheduled architecture agent.
-- [Native sandbox](native-sandbox.md) (0.5.4+) runs a native agent's turn loop and user
+- [Native sandbox](native-sandbox.md) (0.6.0+) runs a native agent's turn loop and user
   tools in a single-use, credential-free container behind a native gateway.
 - [Secrets and tools](tool-secrets.md) covers readable and brokered secrets
   (brokered secrets require 0.6.0+):
   attaching secrets to tools, `set_secret_broker`, placements, and errors.
+- [Remote MCP servers](mcp-servers.md) (0.8.0+) registers a remote MCP server and
+  attaches an allowlist of its tools to a native agent.
+- [Host providers](host-providers.md) (0.8.0+) covers adding a code host with
+  your own custom tools: registering, approving, testing and removing a
+  provider.
 - [Coding-worker isolation](coding-worker-isolation.md) documents the threat
   model and enforced worker boundary.
 - [Bring-your-own worker images](coding-worker-byo-images.md) explains how to

package/docs/agent-recipes.md

@@ -231,22 +231,32 @@ to include secrets or internal details. See
 <details>
 <summary>Builder (coding agent) fields that matter</summary>
 
-| Field (`codingProfile`) | What to set                                                                                                                                                  |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `model` (agent field)   | A capable coding model the chosen provider supports, for example `gpt-5.6-terra` with `codex` or `claude-sonnet-5` with `claude-code`; a mismatch is refused |
-| `provider`              | `codex` or `claude-code`; the agent's `model` must be one that provider supports                                                                             |
-| `repository`            | `your-org/your-repo`; your linked GitHub account needs write access                                                                                          |
-| `baseRef`               | The branch runs start from, usually your default branch                                                                                                      |
-| `toolchain`             | `node` or `node-python` (per language below)                                                                                                                 |
-| `toolchainVersion`      | `"3.12"` for `node-python`; omit for `node`                                                                                                                  |
-| `packageAllowlist`      | Top-level packages per ecosystem (`npm`, `pypi`). Needs `packages:approve` or `agents:admin`                                                                 |
-| `packagePolicy`         | Optional `minReleaseAgeDays` (0 to 30)                                                                                                                       |
-| `services`              | Catalog service names the agent may start, for example `["postgres"]`; see [Services](coding-services.md)                                                    |
-| `protectedPaths`        | Globs a run may not change, for example `[".github/**", "CODEOWNERS"]`. `.wardby/**` is always protected except `.wardby/services.yaml`                      |
-| `timeoutSec`            | 60 to 7200; for example `1800`                                                                                                                               |
-| `workerImageRef`        | Digest-pinned custom image; needs `agents:admin` (see "Other languages")                                                                                     |
-| `defaultTask`           | Needed only to schedule the agent                                                                                                                            |
-| Agent `budgetUsd`       | Per-run budget, reserved at dispatch, for example `5`                                                                                                        |
+| Field (`codingProfile`)       | What to set                                                                                                                                                                                                                                                                                                                                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model` (agent field)         | A capable coding model the chosen provider supports, for example `gpt-5.6-terra` with `codex` or `claude-sonnet-5` with `claude-code`; a mismatch is refused                                                                                                                                                                                                                                      |
+| `provider`                    | `codex` or `claude-code`; the agent's `model` must be one that provider supports                                                                                                                                                                                                                                                                                                                  |
+| `repository`                  | `your-org/your-repo`; your linked GitHub account needs write access                                                                                                                                                                                                                                                                                                                               |
+| `baseRef`                     | The branch runs start from, usually your default branch                                                                                                                                                                                                                                                                                                                                           |
+| `toolchain`                   | `node` or `node-python` (per language below)                                                                                                                                                                                                                                                                                                                                                      |
+| `toolchainVersion`            | `"3.12"` for `node-python`; omit for `node`                                                                                                                                                                                                                                                                                                                                                       |
+| `packageAllowlist`            | Top-level packages per ecosystem (`npm`, `pypi`). Needs `packages:approve` or `agents:admin`                                                                                                                                                                                                                                                                                                      |
+| `packagePolicy`               | Optional `minReleaseAgeDays` (0 to 30)                                                                                                                                                                                                                                                                                                                                                            |
+| `services`                    | Catalog service names the agent may start, for example `["postgres"]`; see [Services](coding-services.md)                                                                                                                                                                                                                                                                                         |
+| `protectedPaths`              | Globs a run may not change, for example `[".github/**", "CODEOWNERS"]`. `.wardby/**` is always protected except `.wardby/services.yaml`                                                                                                                                                                                                                                                           |
+| `timeoutSec`                  | 60 to 7200; for example `1800`                                                                                                                                                                                                                                                                                                                                                                    |
+| `workerImageRef`              | Digest-pinned custom image; needs `agents:admin` (see "Other languages")                                                                                                                                                                                                                                                                                                                          |
+| `defaultTask`                 | Needed only to schedule the agent                                                                                                                                                                                                                                                                                                                                                                 |
+| Agent `budgetUsd`             | Per-run budget, reserved at dispatch, for example `5`                                                                                                                                                                                                                                                                                                                                             |
+| Agent `allowedOverrunPercent` | Optional whole percent (0 to 100, default 0) beyond `budgetUsd`, for example `10`. On a coding agent it raises each run's limit; on a lead agent that delegates, it raises its run tree's ceiling for coding sub-agents. It is never reserved: a run is topped up past its base only from room its budget group and run tree have when it needs it. Native runs' own model calls are not affected |
+
+To allow a small overrun on an existing coding agent, call `update_agent`
+(it needs the same permission as changing `budgetUsd`):
+
+```json
+{ "id": "<coding agent id>", "allowedOverrunPercent": 10 }
+```
+
+See [Budgets](coding-agent-setup.md#budgets).
 
 The agent's `systemPrompt` is placed ahead of each request as standing
 instructions. The template below is generic.
@@ -373,8 +383,9 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
 { "id": "<lead agent id>", "maxDelegationsPerRun": 6 }
 ```
 
-- Each `delegate_to_<name>` call still goes to a different sub-agent; a second
-  call to the same one in the same run is refused with `already_dispatched`.
+- A run delegates to each sub-agent and repository at most once: a second call
+  to the same sub-agent in the same run (for a coding sub-agent with a list of
+  repositories, in the same repository) is refused with `already_dispatched`.
   A delegation waiting for budget (see below) also holds its place against
   `maxDelegationsPerRun`: a call beyond the limit is refused with
   `already_dispatched` and a message naming both counts, e.g. "This run
@@ -407,8 +418,10 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
 - Each coding sub-agent's result tells the lead its `status`, its summary
   (`finalText`), cost and tokens, and, when it opened or pushed to a pull
   request, `pullRequest` (`outcome` `opened` or `updated`, `repository`,
-  `number`, `url`) taken from Wardby's own record of the run. A lead prompt can
-  ask the agent to report those links.
+  `number`, `url`) taken from Wardby's own record of the run. A failed builder's
+  result also carries `errorCode`, the leading code of its error (such as
+  `coding_queue_timeout`); the full error stays on the run (`get_run`). A lead
+  prompt can ask the agent to report those links and codes.
 - The whole run tree shares one budget: give the lead a `budgetUsd` that
   covers every builder it may start, plus its own planning. Builders started
   together each reserve their own `budgetUsd` up front, so the ones admitted
@@ -424,8 +437,8 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
   boundary (routes, field names and types, error codes), word for word the same.
 - Wardby adds a **Related pull requests** section to each pull request the
   builders open, listing the others with links, states (open, draft, merged,
-  closed) and the originating issue. With a Jira issue, the list covers every
-  pull request recorded for that issue in any run. When no pull request in the
+  closed) and the originating issue. With a Jira or GitHub issue, the list
+  covers every pull request recorded for that issue in any run. When no pull request in the
   set carries a `mergeOrder` (see below), open ones are numbered as a
   **Suggested merge order** — the order the lead delegated in, not a
   guarantee. When any pull request in the set carries one (open, merged or
@@ -480,6 +493,14 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
   blocks a merge by itself: add `wardby merge order` as a required status
   check in branch protection to gate on it. See
   [The wardby merge order check](../help/merge-order-check.md).
+- With Wardby 0.7.0 or later, set `markReadyWhenPassing: true` on the
+  lead's write link (`link_repository`) to have Wardby mark the draft pull
+  requests its builders open ready for review once they pass, instead of
+  leaving that to a person; the coding builders need no link of their own.
+  With a `mergeOrder` set, a later step only becomes ready this way once the
+  `wardby merge order` check above reports `success` on it — that is, once
+  the steps it depends on have merged. See [Mark ready
+  when passing](code-review-agents.md#mark-ready-when-passing-markreadywhenpassing).
 - The section, and the follow-up hints below, list every pull request in the
   set by repository name and number. A request that spans repositories of
   different visibility can therefore show a private repository's name in a
@@ -487,6 +508,37 @@ the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
   repositories, keep that work in separate requests (separate Jira issues, or
   separate lead agents).
 
+#### One coding agent, several repositories
+
+Instead of one builder per repository, give one coding builder a list: its default in
+`codingProfile.repository`, and each other repository with `link_repository`
+(`access: "write"`, no triggers). The lead then names the repository on each
+call, and may delegate to the same builder once per repository:
+
+```json
+{ "task": "Add the /quotes endpoint the client will call.", "repository": "your-org/api", "mergeOrder": 1 }
+```
+
+```json
+{ "task": "Add the quotes page that calls /quotes.", "repository": "your-org/web", "mergeOrder": 2 }
+```
+
+Set `maxDelegationsPerRun` (up to 20) for the number of calls, and use
+`mergeOrder` where the pull requests must land in order. A call without
+`repository` is refused with `repository_required` when the builder has extra
+repositories (unless it continues a prior run with `continuePriorRun`), and a
+repository not on the list with `repository_not_listed`. A native sub-agent
+refuses `repository` with `repository_requires_coding_agent`. The lead sees the
+list in the tool definition only when it has the same owner as the builder, or
+another owner with execute access to a builder that sets
+`allowWebhookTaskOverride`. All repositories share the builder's toolchain,
+budget and prompt.
+
+Being on the list lets a run work in a repository; it starts nothing there. Link
+the lead and the reviewer on each listed GitHub repository with the triggers
+they need, or a pull request opened there gets no review, mention follow-up, fix
+round or mark-ready.
+
 #### Follow-ups across the set
 
 A human-triggered follow-up task (an `@<app-slug>` mention, or a Jira issue
@@ -500,8 +552,9 @@ too:
     repository that already has an open sibling for this request.
 
 The usual delegation rails still apply on top of this: `maxDelegationsPerRun`
-caps calls per run; a second `delegate_to_<name>` call to the same sub-agent
-in one run is refused with `already_dispatched`; dispatch re-checks every
+caps calls per run; a run delegates to each sub-agent and repository at most
+once, and a second such call is refused with `already_dispatched`; dispatch
+re-checks every
 `continuePriorRun` id (refusing with `continuation_refused` when this
 deployment can't continue the run it names — for example it belongs to a
 different owner's agent); every push to a sibling pull request still gets its
@@ -512,6 +565,11 @@ fails with category `continuation_closed` and pushes nothing — see
 
 #### Limits
 
+- If two executions of one delegation step overlap (for example a stalled
+  process and the process that took the run over) and the call id is already
+  held by a run of a different sub-agent, the call returns
+  `delegation_conflict` to the lead without starting a run or failing it; see
+  [Delegation conflict](../help/errors/delegation-conflict.md).
 - Cancelling the lead run does not stop a native sub-agent that is already
   running; it keeps running to completion. A coding sub-agent is stopped.
 - If Wardby restarts mid-batch, the batch's delegation calls replay and each
@@ -546,6 +604,19 @@ the run; the pull request description says which. A person
 reviews and merges; Wardby never merges for you. A later mention on that pull
 request continues the same branch.
 
+When a mention run finishes without opening a pull request or failing a
+sub-run and its reply is longer than about 2,000 characters (for example a
+plan), the status comment does not cut the reply short. It says "✅ Finished
+without opening a pull request. The full reply follows in the next
+comment(s)." (in a review thread: "...follows in this pull request's
+conversation."), and the reply is posted in up to four numbered comments
+("Reply, part i of n") of about 60,000 characters each, split at headings,
+paragraphs or lines. Anything beyond four parts is cut with a note; the full
+text stays on the run (`get_run`, `finalText`). `@`-mentions in the reply are
+defused. Each part is posted once; if one cannot be posted, the rest are
+skipped. Shorter replies, and runs that opened a pull request or had a failed
+sub-run, keep the status comment that quotes up to 2,000 characters.
+
 ## Next steps
 
 - [Architecture knowledge bundles](knowledge.md)

package/docs/architecture-runtime.md

@@ -95,7 +95,7 @@ and GKE Autopilot overlays.
 
 ### Native agents in a sandbox
 
-Native sandbox requires Wardby 0.5.4 or later.
+Native sandbox requires Wardby 0.6.0 or later.
 
 Native agents run in the server process by default. A native agent set to
 `nativeExecutionMode=sandbox` instead runs its turn loop and user tools in a

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.