@wardby/cli 0.7.0 → 0.9.0

package/docs/security-deployment.md

@@ -79,15 +79,16 @@ Scopes and roles do different jobs:
 - **Roles authorize.** A user has a set of roles. With no roles, the user is a
   member:
 
-| Role               | Grants                                                                                                 |
-| ------------------ | ------------------------------------------------------------------------------------------------------ |
-| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage` |
-| `package-approver` | `packages:approve`                                                                                     |
-| `service-manager`  | `services:manage`                                                                                      |
-| `model-manager`    | `models:admin`                                                                                         |
-| (none)             | nothing privileged; every other scope works as the token allows                                        |
+| Role               | Grants                                                                                                                |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `admin`            | `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin`, `power:manage` and `hosts:admin` |
+| `package-approver` | `packages:approve`                                                                                                    |
+| `service-manager`  | `services:manage`                                                                                                     |
+| `model-manager`    | `models:admin`                                                                                                        |
+| `host-manager`     | `hosts:admin`                                                                                                         |
+| (none)             | nothing privileged; every other scope works as the token allows                                                       |
 
-Eight operations are privileged:
+Nine kinds of operation are privileged:
 
 - `make_owner`, which reassigns any agent's owner, including another
   principal's private agent (see [Sharing agents](#sharing-agents) for what
@@ -107,7 +108,15 @@ Eight operations are privileged:
   [viewer-api.md](viewer-api.md));
 - reading low-power state and scaling the coding proxy and native gateway to
   zero now (`power_status`, `power_sleep`; see
-  [Low-power mode](getting-started-gke.md#low-power-mode)).
+  [Low-power mode](getting-started-gke.md#low-power-mode));
+- registering, approving, testing and deleting host providers
+  (`register_host_provider`, `approve_host_provider_tools`,
+  `test_host_provider`, `delete_host_provider`; reading one with
+  `get_host_provider` needs the same permission). Approved tools run on the
+  control plane with the provider's credentials, so grant `hosts:admin` like
+  `agents:admin`. Any host manager can read and re-register any provider,
+  including its tool code, whoever owns the tools; see
+  [host-providers.md](host-providers.md).
 
 Each needs **both** its scope on the token **and** a role that grants that
 permission:
@@ -119,13 +128,16 @@ permission:
 - The admin viewer API needs `admin:view`, which only the `admin` role grants.
 - `power_status` and `power_sleep` need `power:manage`, which only the `admin`
   role grants.
+- Host provider tools need `hosts:admin`, which the `admin` and `host-manager`
+  roles grant.
 
 In practice:
 
-- an `admin` can do all eight;
+- an `admin` can do all of them;
 - a `package-approver` can approve packages only;
 - a `service-manager` can change the service catalog only;
 - a `model-manager` can change the model catalog only;
+- a `host-manager` can manage host providers only;
 - a member can do none of them.
 
 Callers who fail the check get `403`:
@@ -312,7 +324,7 @@ someone else's agent (it can adopt the agent first). An HTTP user whose
 subject equals `LOCAL_PRINCIPAL` is not the operator. **Admins** get no
 implicit access to others' agents: they can `list_access` any agent (incident
 response) and reassign one with `make_owner`, which removes bindings the new
-owner doesn't own, suspends tool capabilities the new owner never granted,
+owner doesn't own (secrets, datastores and MCP server attachments), suspends tool capabilities the new owner never granted,
 cuts sub-agent edges the new owner can't delegate, and, between two owners,
 resets every grant. Adopting an owner-less agent keeps its grants but lowers
 an everyone grant to `read` unless `keepEveryoneExecute` is set.
@@ -347,7 +359,7 @@ without their tools' capabilities. Operator runbook:
    printed for review, with the `attach_tool` call that re-grants any
    capabilities it had. The subject must already exist.
 4. `wardby grants prune-bindings` removes, and prints, every remaining
-   binding of one owner's secret or datastore to another owner's agent
+   binding of one owner's secret, datastore or MCP server to another owner's agent
    (already inert).
 5. `wardby grants migration-report > after.txt`.
 
@@ -380,6 +392,15 @@ Trust assumptions:
   owner enabled `allowWebhookTaskOverride`; the owner controls the tools,
   secrets and repository. A repository is a binding: only the owner (or an
   admin's explicit approval) sets it, never a `write`-grantee.
+- **A task can steer a coding agent to any repository on its list.** A caller
+  who may pass `repository` (for `trigger_agent`, the owner, or anyone when
+  `allowWebhookTaskOverride` is on; for a webhook, whoever created it, and only
+  when `allowWebhookTaskOverride` is on), and a lead that delegates to the
+  agent, can pick any listed repository, and the agent's one toolchain,
+  services and package allowlist apply to all of them. Keep the list small, and keep
+  repositories with different trust levels on separate agents. Refusals never
+  repeat the requested value, and a lead sees a sub-agent's list only when it
+  has the same owner or may choose (execute access and the opt-in).
 - **Owner-less agents never hold a repository**, even admin-approved: there is
   no owner whose GitHub access can be checked. Assign an owner first.
 - **Checked where it's used.** Every coding run (before its workspace is
@@ -522,22 +543,22 @@ records. Delete them (see pruning above) if you want the rollback to be final.
 
 ## Resource and networking limits
 
-| Surface                        | Limit                                             |
-| ------------------------------ | ------------------------------------------------- |
-| MCP/webhook bodies             | 1 MiB raw bytes                                   |
-| MCP tool-call arguments        | 100,000 array elements and object members         |
-| Auth bodies                    | 64 KiB raw bytes                                  |
-| Request completion / headers   | 15 seconds / 10 seconds                           |
-| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds              |
-| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects, 8 seconds |
-| Bridge input / output          | 1 MiB / 12 MiB                                    |
-| Parser input / console payload | 256 KiB / 16 KiB                                  |
-| HTML links extracted           | 1000, with incremental result-byte accounting     |
-| Random bytes                   | 65,536 bytes                                      |
-| Host calls                     | 256 per invocation, at most 8 pending             |
-| Datastore value / keys listed  | 1 MiB / 1000                                      |
-| Datastore key / secret name    | 1024 bytes                                        |
-| New secret plaintext           | 64 KiB                                            |
+| Surface                        | Limit                                            |
+| ------------------------------ | ------------------------------------------------ |
+| MCP/webhook bodies             | 1 MiB raw bytes                                  |
+| MCP tool-call arguments        | 100,000 array elements and object members        |
+| Auth bodies                    | 64 KiB raw bytes                                 |
+| Request completion / headers   | 15 seconds / 10 seconds                          |
+| Sandbox invocation             | 32 MiB heap, 1 MiB stack, 10 seconds (see below) |
+| Sandbox fetch                  | 8 MiB encoded and decoded, 5 redirects           |
+| Bridge input / output          | 1 MiB / 12 MiB                                   |
+| Parser input / console payload | 256 KiB / 16 KiB                                 |
+| HTML links extracted           | 1000, with incremental result-byte accounting    |
+| Random bytes                   | 65,536 bytes                                     |
+| Host calls                     | 256 per invocation, at most 8 pending            |
+| Datastore value / keys listed  | 1 MiB / 1000                                     |
+| Datastore key / secret name    | 1024 bytes                                       |
+| New secret plaintext           | 64 KiB                                           |
 
 Oversized or malformed input fails explicitly. Existing oversized datastore
 values/keys and secret ciphertext fail instead of entering Node allocations.
@@ -551,8 +572,9 @@ call arguments against its `paramsZod`, runs in a fresh QuickJS runtime with the
 heap, stack, and time limits above. One that hits a limit fails that tool call
 only: the model receives a `validation_failed` or sandbox error result and the
 run continues. The invocation runs on the thread of the process that hosts the
-run (the server, or the run's worker with the native sandbox), so a call that
-runs to the time limit holds that thread for up to 10 seconds.
+run (the server, or the run's worker with the native sandbox). Code that keeps
+the thread busy is also stopped by the instruction budget, so a long time limit
+mostly lets a call wait on slow requests.
 
 For this release only, a custom tool's `paramsZod` is compiled with Zod 4's
 built-in Zod 3 API (`zod/v3`) so that existing tools keep working; see
@@ -578,7 +600,7 @@ The network layer cannot back this up for the control plane on GKE, because
 Workload Identity needs the metadata server.
 Sandbox code can explicitly log secrets it has been given; log size limits do
 not provide automatic redaction. Keep tool-authoring privileges restricted.
-Public/non-owner tool listings expose only id/name/description; owners retain
+Public/non-owner tool listings expose only id/name/description/timeoutMs; owners retain
 their source and schema. Private agents are indistinguishable from missing IDs.
 
 Cancellation stops bridge delivery, sleep timers, and in-flight network work.
@@ -591,6 +613,108 @@ bound connection pools and concurrent invocations, and review a cancellable
 database adapter or isolated worker if strict immediate termination is required.
 Do not claim these per-invocation caps establish a whole-process memory ceiling.
 
+### Tool time limits
+
+A tool call has 10 seconds unless the tool sets its own `timeoutMs`
+(`create_tool`, `update_tool`, `dry_run_tool`, `wardby tool create|update
+--timeout-ms`, or `timeoutMs` in a bundle's `config/tools.json`). The limit
+covers the whole call: each `fetch` may run until it, and a timer can't be set
+for longer. A call never outlasts its run: stopping the run aborts it, and a
+sandboxed run's deadline cuts it off.
+
+| Variable                     | Default  | Meaning                                                                                                                                                                                                                                 |
+| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_TOOL_MAX_TIMEOUT_MS` | `300000` | The longest `timeoutMs` a tool may set, in milliseconds (at least `10000`). A larger value is refused when the tool is saved. A run uses the lower of the tool's `timeoutMs` and this value, so lowering it also covers existing tools. |
+
+Set it on every process that runs tools or serves the native sandbox gateway:
+`wardby serve`, `wardby scheduler` and the gateway. An invalid value stops
+start-up. On the native sandbox the gateway gives each of a tool's host calls
+its limit plus 20 seconds, never past the run's deadline. A long limit lets one
+call hold its run (and a sandboxed run's worker) for longer, so raise the
+ceiling only as far as your tools need.
+
+**Upgrading:** the release adds the nullable `Tool.timeoutMs` and
+`HostProviderOperation.timeoutMs` columns; apply the migration with
+`prisma migrate deploy` as with any upgrade. A sandboxed run passes a tool's
+`timeoutMs` to its worker, so update the native worker image together with the
+server: an older image refuses the run of an agent that has a tool with
+`timeoutMs`. Tools without `timeoutMs` run on either image.
+
+### Run steps
+
+Runs record their steps (tool calls with a status, and what the model said, each
+cut to one short line) for `get_run_steps`; see
+[Run steps](debugging-agent-runs.md#run-steps). Only the control plane and the
+native gateway write them, and only after removing every secret value of the
+run's agent and every token-shaped value; a step whose agent secrets can't be
+read is not stored. At `summary` tool output is never recorded. At `detail` (the instance and the
+agent's owner must both choose it) the end of each tool's output is stored,
+redacted as above; a secret that only exists in a file the run read, and that
+matches no known shape, can remain. Detail is returned only to the agent's owner,
+the run's starter and the stdio operator, never to the admin viewer. Set `WARDBY_RUN_STEPS=off` to
+record nothing.
+
+**Claude Code and Codex runs.** The coding proxy holds no secret values, so it
+sends step text to the control plane's run-steps listener
+(`WARDBY_RUN_STEPS_LISTEN` on `wardby serve`, `POST /internal/run-steps`)
+unmasked. Neither side logs, stores or echoes that text or a request body; the
+control plane redacts it by exact value (the same path as native runs) before
+writing. The proxy sends nothing unless `WARDBY_RUN_STEPS_URL` is set and
+`WARDBY_RUN_STEPS` is not `off`. It sends tool output (its last 4 KB) only for a
+run at `detail`, and only when its own `WARDBY_RUN_STEPS` is `detail`; the same
+listener conditions apply.
+
+The listener is authenticated by the run's capability. The run's worker holds
+that capability too (it is the worker's model API key), so it limits a caller to
+its own run; it cannot tell the proxy from the worker. The network boundary keeps
+workers off the port:
+
+- **Kubernetes:** a NetworkPolicy admits ingress to port 8792 only from the
+  proxy's pods, and the listener has its own ClusterIP Service, off any load
+  balancer. Admit no worker pod to that port.
+- **Docker backend:** the run's isolated network keeps run containers from
+  reaching the listener. A proxy container reaches a server on the host at
+  `host.docker.internal` (Docker Desktop). On Linux, add
+  `extra_hosts: ["host.docker.internal:host-gateway"]` to the proxy's service. A
+  `127.0.0.1` bind is unreachable from containers on Linux, and a `0.0.0.0` bind
+  exposes the listener to your LAN: bind to the Docker bridge address, or
+  firewall the port.
+
+The proxy-to-listener hop is plain `http` on the cluster or host network by default; use `https`, or keep the listener on a trusted network, wherever the path leaves one.
+
+Limits: a run's MCP token is masked only by its token shape. A write that times
+out can still land, so a step's status can arrive before or after its step. A
+cancelled run can post its last steps until its deadline.
+
+| Variable                  | Read by          | Default | Meaning                                                                                                                    |
+| ------------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_RUN_STEPS_LISTEN` | `wardby serve`   | unset   | `host:port` or `:port` of the run-steps listener. Unset: none. `wardby serve` is the only process that runs it.            |
+| `WARDBY_RUN_STEPS_URL`    | the coding proxy | unset   | The listener's `http(s)` origin, without credentials or path. Unset: coding runs record no steps. Invalid: start-up stops. |
+
+### Remote MCP servers
+
+Owners can register a remote MCP server (Streamable HTTP, HTTPS only) and attach
+an allowlisted subset of its tools to a native agent, which then calls them
+through Wardby's control plane. `WARDBY_MCP_SERVERS` decides who may register
+servers: `owners` (the default), `admins` (only `hosts:admin` holders), or `off`
+to disable the feature. An agent can use a server only while its owner owns it or
+holds `use` on it through a grant; revoking or lowering that grant detaches it. Secret values for a server are never sent to the model,
+stored in run records, or returned by Wardby's MCP tools. See [Remote MCP servers](mcp-servers.md) for the
+full guide.
+
+Claude Code and Codex agents can use attached servers too. Their workers reach
+the tools only through the coding proxy's `/mcp` route, which forwards to the
+native sandbox gateway's `/coding-mcp` route; the proxy never sees a server's URL
+or secrets. Codex agents get only tools the server marks `readOnlyHint: true`
+(see [Coding worker isolation](coding-worker-isolation.md#remote-mcp-tools)).
+
+| Variable                       | Read by                                                                                                  | Default       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_MCP_SERVERS`           | the server processes and the gateway                                                                     | `owners`      | Who may register remote MCP servers: `owners` (the default: owners may register servers), `admins` (registering, updating and refreshing a server needs `hosts:admin`), or `off` (every MCP-server tool except `detach_mcp_server` and `delete_mcp_server` is refused with a 403 that names this variable, and attached servers' tools are left out of runs). Any other value stops start-up.                                                                                                                 |
+| `WARDBY_MCP_MAX_CALLS_PER_RUN` | the native gateway, which counts calls; also checked at start-up by the server processes and the gateway | `100`         | The most remote MCP tool calls one coding run (Claude Code or Codex) may make. Every call to one of the run's MCP tools counts, whatever its outcome; a call past the limit is refused with the [`mcp_call_limit`](../help/errors/mcp-call-limit.md) error, which the agent sees as the tool's result. A positive whole number; any other value stops start-up.                                                                                                                                               |
+| `WARDBY_MCP_GATEWAY_URL`       | the coding proxy                                                                                         | unset         | The native sandbox gateway's base URL, for example `http://<gateway host>:<port>`. The proxy's `/mcp` route, which a coding run's worker uses as its MCP server, forwards each request to the gateway's `/coding-mcp` route; the proxy never sees an MCP server's URL or credentials. Unset, coding runs get no MCP tools: `/mcp` answers `503` with [`mcp_unavailable`](../help/errors/mcp-unavailable.md). An `http` or `https` URL without credentials, query or fragment; any other value stops start-up. |
+| `WARDBY_MCP_TOKEN`             | the coding worker                                                                                        | set by Wardby | Don't set it. Wardby gives each coding run whose agent has MCP tools its own MCP token in this worker variable. It is valid only for the proxy's `/mcp` route, and only while the run is active and before its deadline; only its hash is stored, and it is never logged.                                                                                                                                                                                                                                     |
+
 ## Slack workflow notifications
 
 This integration requires Wardby 0.6.0 or later.
@@ -779,6 +903,12 @@ packages, both forced to patched versions by `overrides` in `package.json`:
   re-run `prisma generate`, `prisma validate`, the `migrate diff` drift check,
   and the migration image's `migrate deploy`.
 
+ESLint and `typescript-eslint` still ask for `minimatch` 10, which is flagged
+(GHSA-g3hv-75wg-m249, moderate, fixed in 11.0.1), so `overrides` also forces
+`minimatch` to 11.0.3. It is development-only and never reaches a production
+image. After changing it, confirm `npm run lint` checks the same files and
+still reports problems.
+
 `scripts/security-audit.mjs` carries no exceptions: with the overrides the full
 and production audits are clean, and if a lockfile change ever dropped one, the
 advisory would reappear and the security job would fail.

package/docs/tool-secrets.md

@@ -157,6 +157,9 @@ or that the tool is not granted, fails with
 [`secret_brokered`](../help/errors/secret-brokered.md), so update tools that read
 the value to use `fetch` instead.
 
+A host provider's credentials must be brokered secrets, placed in a header or
+query parameter. See [host-providers.md](host-providers.md).
+
 ## What the host enforces
 
 - **https only**, to the default port. Any other scheme or port is refused with

package/docs/viewer-api.md

@@ -13,6 +13,12 @@ the `admin` role.
 
 ## Access
 
+From an MCP client, an admin gets a deployment-wide listing without this API:
+`list_agents` and `list_runs` with `all: true` (Wardby 0.8.0 and later) need the
+same `admin:view` scope and `admin` role, and are refused otherwise. Their
+`triggerInfo` and `outcomes` fields have the same shapes as a graph run's
+`trigger` and `outcomes` here; `serviceReadiness` is `services` without `reason`.
+
 A caller needs an access token for the Wardby MCP resource that carries the
 `admin:view` scope, and the Wardby `admin` role. Send it as
 `Authorization: Bearer <token>`.
@@ -97,9 +103,14 @@ check is still pending).
 
 ### `GET /admin/api/runs/<id>`
 
-One run in full: the graph fields plus the run's final text and error. For
-coding runs, services report the **names** of their environment variables
-only, never values. An unknown id returns `404`.
+One run in full: the graph fields plus the run's final text and error, and its
+newest steps (Wardby 0.9.0 and later). `steps` lists at most the newest 200, oldest first, each with
+`seq`, `at`, `kind` (`tool` or `said`), `tool`, `summary` and `status`;
+`stepsOmitted` counts earlier steps not listed and `stepsDropped` counts steps
+past the per-run limit that were never recorded. A step's summary is redacted
+when it is recorded; tool output is never included. For coding runs, services
+report the **names** of their environment variables only, never values. An
+unknown id returns `404`.
 
 ### `GET /admin/api/infra`
 
@@ -125,21 +136,25 @@ run claims them.
 
 A Server-Sent Events stream (`text/event-stream`) of live changes. Frames:
 
-| Frame                                            | Meaning                                                                                        |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `retry: 3000`                                    | Suggested client reconnect delay in milliseconds.                                              |
-| `event: hello`                                   | Sent first. Data is `{"connected": <bool>}`: whether the server's live-event connection is up. |
-| `event: run`, `event: service`, `event: outcome` | A run, coding-run service, or outcome changed. Each carries an `id:` line.                     |
-| `event: status`                                  | The server's live-event connection changed. Data is `{"connected": <bool>}`.                   |
-| `event: resync`                                  | The live-event connection is up (again). Events may have been missed: refetch the graph.       |
-| `: ping`                                         | Comment sent every 15 seconds to keep the connection open.                                     |
+| Frame                                                           | Meaning                                                                                        |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `retry: 3000`                                                   | Suggested client reconnect delay in milliseconds.                                              |
+| `event: hello`                                                  | Sent first. Data is `{"connected": <bool>}`: whether the server's live-event connection is up. |
+| `event: run`, `event: service`, `event: outcome`, `event: step` | A run, coding-run service, outcome or run step changed. Each carries an `id:` line.            |
+| `event: status`                                                 | The server's live-event connection changed. Data is `{"connected": <bool>}`.                   |
+| `event: resync`                                                 | The live-event connection is up (again). Events may have been missed: refetch the graph.       |
+| `: ping`                                                        | Comment sent every 15 seconds to keep the connection open.                                     |
 
-Event payloads are small and never include final text; fetch
+Event payloads are small and never include final text or tool output; fetch
 `/admin/api/runs/<id>` for detail. A `run` event carries the run's status,
 turn and token counts, cost and finish time. A `service` event carries the
 service name, its state and the attempt count. An `outcome` event carries only
 the run id and the outcome source (`pull_request`, `host_status`,
 `issue_status` or `host_check`), so refetch the run to see what changed.
+From Wardby 0.9.0, a `step` event carries the run id and the step's `seq`, `stepKind` (`tool` or
+`said`), `tool`, `summary`, `status` and `at`. It is sent when a step is
+recorded and again when its status arrives, so apply it by `seq`. Steps are
+not in the graph: fetch the run to list them.
 
 **There is no replay.** Open the event stream first, then load
 `/admin/api/graph` and apply events on top of it. Refetch `/admin/api/graph` on

package/docs/viewer-api.openapi.yml

@@ -2,7 +2,7 @@
 openapi: 3.1.0
 info:
   title: wardby admin viewer API
-  version: 0.7.0
+  version: 0.9.0
   description: "Read-only admin API behind the wardby viewer: graph, run detail, infrastructure info and a live event stream. Response objects may gain new fields in later releases; clients should ignore unknown fields. See docs/viewer-api.md for the prose contract."
 servers:
   - url: https://{host}
@@ -122,7 +122,7 @@ paths:
       operationId: getRun
       summary: Run detail
       description: |-
-        Full detail for one run, including final text.
+        Full detail for one run, including final text and its newest steps.
 
         Requires a bearer token with the `admin:view` scope, held by a caller with the admin role.
       security:
@@ -297,6 +297,7 @@ paths:
         - `retry: 3000`: suggested client reconnect delay in milliseconds.
         - `event: hello`: sent first. Data is `{"connected": <bool>}`, whether the server's live-event connection is up.
         - `event: run`, `event: service`, `event: outcome`: a run, coding-run service, or outcome changed. Each carries an `id:` line. Payloads match the `viewer-event` schema (see `x-event-schema`).
+        - `event: step`: a run recorded a step, or a step's status arrived. Carries an `id:` line. Data: the step's `seq`, `stepKind` (`tool` or `said`), `tool`, `summary` (redacted when it was recorded), `status` and `at`, never tool output.
         - `event: status`: the server's live-event connection changed. Data is `{"connected": <bool>}`.
         - `event: resync`: the live-event connection is up (again). Events may have been missed: refetch the graph.
         - `: ping`: comment sent every 15 seconds to keep the connection open.
@@ -1107,6 +1108,42 @@ components:
           type: array
           items:
             type: string
+        steps:
+          type: array
+          items:
+            type: object
+            properties:
+              seq:
+                type: integer
+              at:
+                type: string
+              kind:
+                type: string
+                enum:
+                  - tool
+                  - said
+              tool:
+                type:
+                  - string
+                  - "null"
+              summary:
+                type: string
+              status:
+                type:
+                  - string
+                  - "null"
+            required:
+              - seq
+              - at
+              - kind
+              - tool
+              - summary
+              - status
+            additionalProperties: false
+        stepsOmitted:
+          type: integer
+        stepsDropped:
+          type: integer
         coding:
           anyOf:
             - type: object
@@ -1184,6 +1221,9 @@ components:
         - error
         - finalText
         - childRunIds
+        - steps
+        - stepsOmitted
+        - stepsDropped
         - coding
       additionalProperties: false
     viewer-event:
@@ -1282,6 +1322,42 @@ components:
             - runId
             - source
           additionalProperties: false
+        - type: object
+          properties:
+            kind:
+              type: string
+              const: step
+            runId:
+              type: string
+            seq:
+              type: integer
+            stepKind:
+              type: string
+              enum:
+                - tool
+                - said
+            tool:
+              type:
+                - string
+                - "null"
+            summary:
+              type: string
+            status:
+              type:
+                - string
+                - "null"
+            at:
+              type: string
+          required:
+            - kind
+            - runId
+            - seq
+            - stepKind
+            - tool
+            - summary
+            - status
+            - at
+          additionalProperties: false
     infra-info:
       type: object
       properties:

package/help/admin-viewer.md

@@ -19,10 +19,15 @@ It requires the Wardby `admin` role and the `admin:view` scope, which only the
 provider and map it like `agents:admin`. See
 [Configure identity and privileged access](identity-and-access.md).
 
+From an MCP client, an admin gets the same deployment-wide listing with
+`list_agents` and `list_runs` and `all: true` (Wardby 0.8.0 and later; also
+`admin:view`). Without the role the call is refused.
+
 Endpoints, all `GET`:
 
 - `/admin/api/graph?since=1h&limit=500`: a snapshot of runs in a time window.
 - `/admin/api/runs/<id>`: one run in full, including its final text and error.
+  From Wardby 0.9.0 it also lists the run's newest 200 steps (see `run-steps`).
 - `/admin/api/infra`: how this deployment runs coding jobs (launcher, Kubernetes namespace, platform, run labels).
 - `/admin/api/events`: a Server-Sent Events stream of live changes.
 

package/help/agent-recipes.md

@@ -162,8 +162,8 @@ yourself.`
 A router delegates once per run by default. For one native agent that splits a
 request across several repositories, attach one builder per repository and set
 the lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or
-`update_agent`. Each `delegate_to_<name>` call must go to a different
-sub-agent; the calls run one after another unless you also set
+`update_agent`. A run delegates to each sub-agent and repository at most
+once; the calls run one after another unless you also set
 `parallelDelegations: true`, which starts only the **consecutive**
 `delegate_to_*` calls of one turn together — a non-delegation call between
 two delegations splits them, nothing is reordered, and results return to the
@@ -208,6 +208,37 @@ pull request in it also gets a `wardby merge order` check run showing
 whether its earlier steps have merged yet; search help for "merge order
 check" for its states and for requiring it in branch protection.
 
+**One coding agent across 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` (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.
+
+Search help for `repository_required` or `repository_not_listed` for what to do about those refusals.
+
 ## Step 3: confirm
 
 Summarize what you created: each agent's name and id, the sub-agent bindings,

package/help/brokered-secrets.md

@@ -67,6 +67,9 @@ alone never removes it. Every change is audited.
 
 ## Related
 
+- [Host providers](../docs/host-providers.md): a provider's credentials must be brokered
+  secrets
+- [Remote MCP servers](../docs/mcp-servers.md) (0.8.0+): a server's credentials are brokered secrets
 - Full guide: [`docs/tool-secrets.md`](../docs/tool-secrets.md)
 - [Use native agents, tools, and data](native-capabilities.md)
 - Errors: [`secret_brokered`](errors/secret-brokered.md),

package/help/build-claude-code-image.md

@@ -4,7 +4,7 @@ title: Build a tool runner image for a Claude Code agent
 summary: A procedure an MCP assistant follows to build a custom image for a Claude Code coding agent (Ruby, Go, Java or another language) FROM the release's tool runner image, check it, and set it with workerImageRef.
 audience: operator
 tags: [claude-code, custom-image, workerImageRef, tool-runner, worker-image, other-language, ruby, toolchain]
-appliesTo: ">=0.5.4"
+appliesTo: ">=0.6.0"
 ---
 
 # Build a tool runner image for a Claude Code agent

package/help/claude-code-run-pane.md

@@ -0,0 +1,63 @@
+---
+id: claude-code-run-pane
+title: See your runs in Claude Code (the wardby-runs plugin)
+summary: Install the wardby-runs Claude Code plugin to see your runs beside the chat, grouped by pull request, with run details and Continue locally.
+audience: operator
+tags: [run steps, get_run_steps, claude code, plugin, wardby-runs, pane, claude-plugin, runs, auto mode, permissions]
+appliesTo: >=0.8.0
+---
+
+# See your runs in Claude Code
+
+The `wardby-runs` plugin opens a pane in Claude Code that lists your wardby
+runs, grouped by pull request, and shows each run's details. It uses the
+`wardby` MCP server your session already has and only reads.
+
+Install it, and allow its read-only tools for auto mode, with:
+
+```sh
+npx @wardby/cli@latest claude-plugin install
+```
+
+Add `--server-url https://<your wardby host>/mcp` if Claude Code has no MCP
+server named `wardby` yet. Or install it yourself with
+`/plugin install wardby-runs --marketplace wardby/wardby`. Then run
+`/wardby-runs`.
+
+If the pane says auto mode refused a call, allow `mcp__wardby__list_runs`,
+`mcp__wardby__list_agents`, `mcp__wardby__get_run`,
+`mcp__wardby__get_run_transcript` and `mcp__wardby__get_run_steps` in
+`/permissions`. Run `wardby claude-plugin install` again to add a rule a newer
+pane needs.
+
+In the terminal, the pane takes clicks and sits beside the chat only in Claude
+Code's fullscreen view (`"tui": "fullscreen"`); otherwise use ctrl+x tab and the
+keys it shows. The desktop app needs no setting.
+
+`wardby quickstart` offers the pane when it connects Claude Code, and
+`wardby doctor` and `wardby claude-plugin status` check the setup; `wardby claude-plugin
+uninstall` removes the plugin and the rules install added. To continue a run
+from the pane, see `resume-runs-locally`.
+
+A running run's detail shows its **Recent steps** (the last 8 tool calls and
+messages: a ✓ or the exit code of a failed command, then the tool and its
+command; what the model said wraps to about two lines); a finished run's shows all its
+**Steps**, 200 at a time. In the list, a running or failed run shows its newest
+step under its name. Against a server without `get_run_steps` the pane shows no
+steps and checks again every few refreshes; with run steps off it says "Steps
+are off on this server." See `run-steps`. Steps need Wardby 0.9.0 or later
+on the server. From 0.9.0, a step with detail, or a longer message, has a ▸ at
+its right that opens it; in the terminal, `j`/`k` also move between such steps
+and `e` shows or hides one. An open command shows "$ command", its exit status
+and its output, without Codex's framing lines. Detail appears only for the
+agent's owner and the run's starter (and the stdio operator), on a server at
+the detail level. An open detail shows its last 40 lines, with a count of the
+lines above them.
+
+Each section of a run's detail is a card, coloured by its kind (a bar on the
+desktop, the border in the terminal). On the desktop each card, an error and an
+open step's detail have a **Copy** button that copies the full text as the
+server sent it, an open step's detail included in full; in the terminal, **Copy section** (`y`) copies the open
+step's detail.
+
+The full guide is [Claude Code plugin](../docs/claude-code-plugin.md).

package/help/deploy-gke.md

@@ -49,6 +49,11 @@ grants fail, `up.sh` stops before the rollout with a non-zero exit;
 without changing anything. See
 [Upgrading an existing deployment](../docs/getting-started-gke.md#upgrading-an-existing-deployment).
 
+`up.sh` works from its own one-cluster copy of the cluster's
+kubeconfig context, so switching contexts in another terminal mid-deploy can't
+send a step to another cluster. Run one deploy of a cluster at a time: a second
+stops with `another operation (install/upgrade/rollback) is in progress`.
+
 The Kubernetes launcher runs Codex and Claude Code coding workers; a Claude
 Code pod adds a tool-runner sidecar with its own image. Configure an identity
 provider and GitHub App before allowing people to use the public endpoint.