@wardby/cli 0.8.0 → 0.9.0

package/docs/claude-code-plugin.md

@@ -8,8 +8,8 @@ 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.
+`list_runs`, `list_agents`, `get_run`, `get_run_steps` and `get_run_transcript`,
+so it shows exactly what those tools show you and needs no token of its own.
 
 ## Install
 
@@ -85,15 +85,17 @@ The pane reads only, with the caller's own access:
 | 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                                         |
+| Recent steps, Steps  | `get_run_steps`      | `agents:read` | Same as `get_run`                                                              |
 | 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.
+`mcp__wardby__get_run`, `mcp__wardby__get_run_transcript` and
+`mcp__wardby__get_run_steps`. 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
@@ -105,16 +107,58 @@ or logged. The import writes only under `~/.wardby/` and the new worktree.
 - **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.
+  under **Other**. The newest run comes first: groups (Other too) are ordered by
+  their newest run, and so are the runs in a group. Each line names its step (opened, review, fix 1, …), with
+  sub-agent runs under their lead, and shows the run's status as a coloured
+  pill, its spend as "$x of $y", what started it, its task and how long it
+  ran, over a thin budget bar.
 - **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)).
+- **Run detail**: a header with the run's status, short id, repository, model,
+  duration and budget bar, then a card each for what started the run (with its
+  request), what it produced, the run tree, services (ready, starting or
+  failed), steps, the final answer 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)).
+  Each kind of card has its own colour, the same on every run: a thin bar
+  along its top on the desktop, its rounded border in the terminal.
+  The request and final answer show about three lines, as markdown, then how
+  many more; **Show full text** shows all of it. The pull request link and the
+  other actions sit at the bottom.
+- **Copy**: on the desktop, each card (and an error, and an open step's detail)
+  has a **Copy** button that copies its full text as the server sent it. In the
+  terminal, **Copy section** (`y`) copies the open step's detail; **Copy run
+  id** is on both.
+- **Recent steps** (a running run's detail): its last 8 steps, refreshed with
+  the run. A tool step is one row: its result at the left (✓ when it passed,
+  the exit code of a failed command, or ! for an error), then the tool and its
+  command or file; on the desktop a long command is cut with "…". What the
+  model said wraps to about two lines.
+- **Steps** (a finished run's detail): every recorded step, 200 at a time;
+  **More steps** loads the next 200.
+- **Step detail**: From 0.9.0, a step with detail, or a longer message, has a
+  ▸ at its right that opens it (▾ closes it); in the terminal, `j`/`k` also
+  move between such steps and `e` shows or hides one. One step is open at a
+  time. An open command shows "$ command", its exit status and its output;
+  Codex's framing lines (chunk id, wall time, token count) are left out, and
+  **Copy** still copies the detail exactly as stored. 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.
+- **Last step**: in the list, a running or failed run shows its newest step
+  under the agent's name.
+
+Steps come from the server's run steps (see
+[Run steps](debugging-agent-runs.md#run-steps)): they need a server that has
+`get_run_steps` and records steps (Wardby 0.9.0 or later). Against an older
+server the pane shows no steps and checks again every few refreshes. When the
+server has steps off (`WARDBY_RUN_STEPS=off`) the detail says "Steps are off on
+this server." A run with no recorded steps shows none. If you installed the pane
+before run steps, run `wardby claude-plugin install` again (or allow
+`mcp__wardby__get_run_steps` in `/permissions`): under auto mode the pane
+otherwise shows which rule to add in place of the steps. `wardby claude-plugin
+status` and `wardby doctor` name the missing rule.
 
 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
@@ -125,8 +169,8 @@ polls only while it is open.
 
 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
+focuses the pane, then `1`–`9` open a run, `r` refreshes, `b` goes back, `m`
+shows full text, `y` copies an open step's detail, `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.

package/docs/coding-agent-setup.md

@@ -987,6 +987,23 @@ run's repository and refs, as base64url JSON). A refused download returns
 JSON `{ "error": "<code>" }`; `wardby resume` explains each code (see the
 `errors/run-transcript-download` help article).
 
+## Run steps
+
+Claude Code and Codex runs record their steps (each command with its status, and
+what the model said, one short line each) when the server's run-steps listener is
+set up: `WARDBY_RUN_STEPS_LISTEN` on `wardby serve` and `WARDBY_RUN_STEPS_URL` on
+the coding proxy. Without them, coding runs record no steps. Read the steps with
+`get_run_steps`. The Docker quickstart registers the stdio `wardby mcp` server,
+which never runs the listener, so setting `WARDBY_RUN_STEPS_URL` on its proxy
+alone does nothing: coding runs' steps need a `wardby serve` with
+`WARDBY_RUN_STEPS_LISTEN`. The proxy takes `WARDBY_RUN_STEPS_URL` from the
+environment (for example `http://host.docker.internal:8792`); see
+[Run steps](debugging-agent-runs.md#run-steps) and, for binding the listener
+safely, [Run steps in Security deployment](security-deployment.md#run-steps).
+For a coding agent whose owner sets `runSteps` to `detail`, also set
+`WARDBY_RUN_STEPS=detail` on the proxy, or no tool output is sent; see
+[Run steps](debugging-agent-runs.md#run-steps).
+
 ## Stop the setup
 
 ```sh

package/docs/coding-worker-isolation.md

@@ -304,6 +304,22 @@ port-level policy — that is harmless, because the listener accepts the
 connection, sends nothing and closes it. It is not a leak; it is a fact about
 reachability that the Kubernetes launcher turns into evidence.
 
+### Run steps
+
+The worker is not involved: after relaying each model reply unchanged, the proxy
+reads it (and the newest tool results of the request) and makes one short line
+per tool call or model message. It posts the lines to the control plane's
+run-steps listener (`WARDBY_RUN_STEPS_URL`), authenticated by the run capability;
+the control plane removes the agent's secret values before storing them. Reading
+a reply for steps never delays or fails the relay: a frame the proxy can't read
+gives no step, and a full queue or an unreachable server drops steps.
+
+The worker holds the same capability, so the network keeps it off the listener:
+on Kubernetes, ingress to port 8792 only from proxy pods; on Docker, the run's
+isolated network. The worker's own egress is unchanged: it reaches only the
+proxy. See [Run steps](security-deployment.md#run-steps) and
+[Run steps](debugging-agent-runs.md#run-steps).
+
 ## Debug trace
 
 When a fixed code is not enough to tell why a coding agent's runs fail, an

package/docs/debugging-agent-runs.md

@@ -38,6 +38,7 @@ access to.
 | `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_steps` (from 0.9.0)                                                                                    | The run's steps, one line per tool call or model message, live while it runs; see [Run steps](#run-steps)                                                                                                                                                                                                                                                                                |
 | `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                                                                                                                                                                                                                                                                                                                                 |
@@ -139,6 +140,117 @@ 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 steps
+
+While a run runs, Wardby records its steps: one line for each tool call (the
+tool, and its command, file or first argument, cut to about 100 characters) with
+its status once the result is back (`ok`, `error`, or `exit N`), and one line for
+what the model said (cut to about 120 characters). At the default level, tool
+output and full text are never recorded; see Levels below. Steps are recorded
+for native runs (in the control plane and on the native sandbox) and for Claude Code and Codex runs. Every agent's
+shell command shows as `Bash` (a native `run_command`, Claude Code's command tool,
+Codex's `exec_command`, `shell`, `local_shell` and `shell_command`), another tool
+under its own name (for example `apply_patch`), and a remote MCP tool as
+`mcp:<tool>`. A Claude Code or Codex run's final answer is one `said` step: the
+start of the summary it returned, or `Finished` with the outcome (for example
+`Finished: changes ready`) when it returned none.
+
+For Claude Code and Codex, the coding proxy reads the steps from the model's
+replies after relaying them and posts them to the server's run-steps listener
+(`POST /internal/run-steps`). A slow or unreachable listener loses steps, never
+slows the run. Without the two settings in the table below, coding runs record no
+steps; native runs are unaffected. Steps for a Claude Code or Codex run need the
+listener, which only `wardby serve` runs.
+
+**Levels.**
+
+| Level     | Tool input           | Tool result                             | Model text           |
+| --------- | -------------------- | --------------------------------------- | -------------------- |
+| `off`     | -                    | -                                       | -                    |
+| `summary` | about 100 characters | status only (`ok`, `error`, `exit N`)   | about 120 characters |
+| `detail`  | up to about 4 KB     | status and the last ~2 KB of its output | up to about 8 KB     |
+
+At `summary`, the default, tool output is never recorded. At `detail` each step
+also keeps a **detail** text, at most 16 KB. When the output is cut at the
+start, the partial first line is dropped if it ends within 256 characters;
+otherwise only the first 256 characters are dropped, so a long single-line
+output, such as a JSON result, keeps about its last 1.8 KB. At every level,
+terminal escape sequences (colour codes, links, clipboard writes, title changes)
+and every other control character except line breaks and tabs are removed from
+step text before it is stored.
+
+A run's level is the lower of two settings, fixed when the run is dispatched (a
+change reaches later runs only; lowering the ceiling also stops detail for runs
+already in flight):
+
+- the instance's ceiling, `WARDBY_RUN_STEPS` (default `summary`);
+- the agent's `runSteps` (`off`, `summary` or `detail`), set by the agent's
+  owner with `create_agent` or `update_agent`. Unset counts as `summary`. Set
+  `null` to clear it.
+
+So `detail` needs both the operator and the agent's owner. If `runSteps` asks
+for more than the instance allows, the value is stored, `update_agent` and
+`get_agent` say so in `warnings`, and runs record at the ceiling.
+
+> **Warning: `detail` stores tool output.** Before a step is stored, every
+> secret value the run was given is removed and anything shaped like a token or
+> key is masked. A secret that exists only inside a repository file, or another
+> source the run read, and that matches no known shape, is not known to Wardby
+> and can remain in the detail text. That is why detail is off unless both the
+> operator and the agent's owner ask for it. Turn it on only for agents whose
+> tool output you are prepared to keep for the retention period.
+
+**Reading them.** `get_run_steps` (`runId`, optional `after` and `limit`) lists
+them oldest first, 50 at a time and at most 200; pass the last `seq` you have as
+`after` to get only newer ones. `get_run` and `list_runs` without `agentId`
+include `lastStep`, the newest step as one line. Access is the same as
+`get_run`'s. At `detail`, `get_run_steps` also returns each step's `detail` to the agent's
+owner and to the person who started the run (and to the stdio operator); anyone
+else, including an admin who does not own the agent, gets the lines only.
+`lastStep`, the admin viewer API and its `step` events never include detail.
+The `wardby-runs` Claude Code pane shows them (see
+[Claude Code plugin](claude-code-plugin.md#using-the-pane)); the admin viewer API
+sends a `step` event for each one and lists a run's newest 200 in its detail
+(see [Viewer API](viewer-api.md)), and the Wardby Viewer app shows them in a
+**Steps** section.
+
+**Limits.** A run records at most 2,000 steps; `dropped` in `get_run_steps`
+counts the rest.
+
+**Secrets.** Every step is redacted before it is stored: every secret value of
+the run's agent (attached secrets, readable or brokered, and its MCP servers'
+secrets), the run's own capability and its registry token are replaced with
+`[REDACTED]`, then anything shaped like a token or key.
+If the agent's secrets can't be read at that moment, the step is not stored.
+
+**Retention.** Steps are deleted `RUN_STEP_RETENTION_DAYS` after they are
+recorded. The scheduler leader deletes expired steps at most every ten minutes. `get_run_steps` reports
+`expired` when a run finished more than `RUN_STEP_RETENTION_DAYS` ago and has no
+steps left.
+
+| Variable                  | Read by                                                                                                   | Default   | Meaning                                                                                                                                                                                          |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WARDBY_RUN_STEPS`        | `wardby serve`, `wardby scheduler`, `wardby run`, `wardby mcp`, `wardby native-gateway`, the coding proxy | `summary` | `off` records nothing; `summary` records the lines above; `detail` allows agents whose `runSteps` is `detail` to record detail. The ceiling for every run. Any other value stops start-up.       |
+| `RUN_STEP_RETENTION_DAYS` | `wardby serve`, `wardby scheduler`, `wardby run`, `wardby mcp`, `wardby native-gateway`                   | `30`      | Days to keep a step, a whole number from 1 to 3650. A change applies to steps recorded after it. Any other value stops start-up.                                                                 |
+| `WARDBY_RUN_STEPS_LISTEN` | `wardby serve`                                                                                            | unset     | `host:port` or `:port` of the run-steps listener the coding proxy posts coding runs' steps to. Unset: no listener. An invalid value stops start-up.                                              |
+| `WARDBY_RUN_STEPS_URL`    | the coding proxy                                                                                          | unset     | The listener's origin, for example `http://<server host>:8792`: `http` or `https`, no credentials, path, query or fragment. Unset: coding runs record no steps. An invalid value stops start-up. |
+
+The coding proxy also reads `WARDBY_RUN_STEPS`: with `off`, or with
+`WARDBY_RUN_STEPS_URL` unset, no step text leaves the proxy. For coding runs at
+`detail`, set `WARDBY_RUN_STEPS=detail` on the proxy too: below `detail`, the
+proxy never sends any tool output to the server. Set `WARDBY_RUN_STEPS=detail`
+on every process that writes steps (`wardby serve`, the scheduler, the native
+gateway and `wardby run`). The listener is a
+second network path into the server; see
+[Run steps in Security deployment](security-deployment.md#run-steps) for how to
+restrict it.
+
+**Upgrading.** The release adds the `RunStep` table, the `Run.stepsDropped`
+column, `Agent.runSteps`, `Run.runStepsLevel` and
+`CodingProxySession.runStepsLevel`; apply the migrations with
+`prisma migrate deploy` as with any upgrade. Runs started before the upgrade
+record at most `summary`.
+
 ## Run transcripts
 
 A transcript is the run's conversation: the messages, the tool calls and their

package/docs/getting-started-gke.md

@@ -218,6 +218,13 @@ App replying to say why a mention started nothing; pass it to `up.sh` on every
 run, the same way. See
 [What a linked review agent does](code-review-agents.md#what-a-linked-review-agent-does).
 
+`WARDBY_RUN_STEPS` (`off`, `summary` or `detail`) and `RUN_STEP_RETENTION_DAYS`
+(1 to 3650) are optional, not secrets. Pass them to `up.sh` on every run, the
+same way; unset keeps the server defaults (`summary`, 30 days). `up.sh` adds the
+ceiling to the control plane, the coding proxy and the native gateway, and the
+retention to the control plane and the native gateway. See
+[Run steps](debugging-agent-runs.md#run-steps).
+
 Generate `SECRET_APP_KEY` with:
 
 ```sh
@@ -455,6 +462,14 @@ Desktop includes it). The images build concurrently, and the stages that only
 compile JavaScript run on your machine's own architecture, so building the
 `linux/amd64` images from an arm64 machine emulates only what actually ships.
 
+`up.sh` adds the cluster to your kubeconfig and makes it the current context, as
+`gcloud container clusters get-credentials` does. From then on it works from its
+own one-cluster copy of that context, so switching contexts in another terminal
+while a deploy runs doesn't send its later steps to a different cluster. The
+copy is readable only by you and is removed when `up.sh` exits. Don't run two
+deploys of the same cluster at once: the second stops at its first Helm step
+with `another operation (install/upgrade/rollback) is in progress`.
+
 A control-plane restart is designed not to drop requests, at the cost of a
 slower rollout. A new pod must stay Ready for three minutes before the old one
 is retired, because the load balancer can take well over a minute to start
@@ -656,8 +671,9 @@ control plane 1.
 **Sleeping.** Every minute the scheduler leader scales the coding proxy
 (`wardby-coding-proxy`) to 0 when no coding run is pending or running and none
 finished within the idle window. It scales the native gateway
-(`wardby-native-gateway`) to 0 when no sandbox native run is pending, running or
-recently finished and the gateway has no active session. Either target sleeps
+(`wardby-native-gateway`) to 0 when no sandbox native run and no coding run with
+MCP tools is pending, running or recently finished, and the gateway has no
+active session. Either target sleeps
 only once at least one idle window has passed since it was last woken (recorded
 in its `wardby.io/power-woke-at` annotation) and since the control plane
 started, whichever is later. The condition is checked again immediately before
@@ -665,10 +681,14 @@ scaling. The control plane
 logs `power: proxy slept (idle 30m)`.
 
 **Waking.** Starting a coding run scales the proxy to 1 and waits for a ready
-endpoint. Starting a sandbox run does the same for the gateway. The wait is at
+endpoint. Starting a sandbox run does the same for the gateway, and so does starting a
+coding run with MCP tools, whose MCP calls go through the gateway (0.9.0 and later): it wakes the
+proxy and gateway at once and fails before launch with
+[`coding_failure_mcp_gateway_unavailable`](../help/errors/coding-mcp-gateway-unavailable.md)
+if the gateway does not wake. The wait is at
 least 5 minutes, because a cold Autopilot node can add 1 to 2 minutes of
-start-up; a `KUBERNETES_READY_TIMEOUT_MS` (proxy) or
-`NATIVE_SANDBOX_READY_TIMEOUT_MS` (gateway) above 5 minutes, set on the
+start-up; a `KUBERNETES_READY_TIMEOUT_MS` (the proxy, and the gateway wake of a coding run) or
+`NATIVE_SANDBOX_READY_TIMEOUT_MS` (the gateway wake of a sandbox run) above 5 minutes, set on the
 control-plane Deployment, raises it to that value. The first coding run after a
 control-plane restart also runs the cluster preflight canary, because start-up
 preflight is deferred while the proxy sleeps (`kubernetes_preflight_deferred`).
@@ -690,8 +710,9 @@ the Viewer shows any such leftover as an old replica rather than a failure.
 **Sleeping now.** To skip the idle window (for example right after a test), an
 admin calls the MCP tool `power_sleep`, optionally with `target` set to `proxy`
 or `gateway` (default both). It scales the target to 0 at once, but never stops
-a run: a target with a pending or running run, or for the gateway an active
-gateway session, is left up and its run ids are returned under `blocked`.
+a run: a target with a pending or running run (for the gateway, a sandbox run
+or a coding run with MCP tools), or for the gateway an active gateway session,
+is left up and its run ids are returned under `blocked`.
 Recently finished runs do not block it. The next run wakes the target as usual.
 `power_status` shows each target's replicas, readiness, last wake time and
 blocking run ids. Both tools need the `power:manage` scope, which only the

package/docs/mcp-servers.md

@@ -113,6 +113,15 @@ deadline, and only its hash is stored.
   (the kind and GKE manifests set it). Without it `/mcp` answers `503` with
   [`mcp_unavailable`](../help/errors/mcp-unavailable.md) and coding agents get no MCP tools. See
   [Remote MCP servers](security-deployment.md#remote-mcp-servers) for the variables.
+- **Low-power mode (0.9.0 and later).** With `WARDBY_LOW_POWER=1`, a coding run with MCP tools wakes the native
+  gateway as well as the coding proxy before its worker launches (both at once), and the gateway
+  stays awake while any such run is pending or running, or finished within the idle window. Those
+  runs appear in the gateway's `blockers` in `power_status`, and `power_sleep` refuses to sleep the
+  gateway while they are pending or running. If the gateway doesn't wake in time the run fails before
+  launch with
+  [`coding_failure_mcp_gateway_unavailable`](../help/errors/coding-mcp-gateway-unavailable.md),
+  rather than start without its MCP tools. Runs without MCP tools don't wake the gateway. See
+  [Low-power mode](getting-started-gke.md#low-power-mode).
 - **Worker images.** MCP for coding agents needs this release's Claude worker image and a new Codex
   driver image. An older image ignores the token and the agent gets no MCP tools; the run does not
   fail. Update the images together with the server.

package/docs/native-sandbox.md

@@ -145,6 +145,7 @@ integration settings, and **no Docker access**.
 | LLM provider keys              | The same provider settings as the server (for example `OPENAI_API_KEY`).                                                                                                                                                                                   |
 | `SECRET_APP_KEY`               | Same value as the server, so tools can read their bound secrets or send brokered ones ([details](tool-secrets.md)).                                                                                                                                        |
 | Integration settings           | The same repository-host and issue-tracker settings as the server.                                                                                                                                                                                         |
+| `WARDBY_RUN_STEPS`             | Same value as the server, if you set it: the ceiling for run steps. The gateway records at each run's own level, so set `detail` here too if agents use it ([details](debugging-agent-runs.md#run-steps)).                                                 |
 | `WARDBY_TOOL_MAX_TIMEOUT_MS`   | Same value as the server, if you set it: the longest time limit a tool may use ([details](security-deployment.md#tool-time-limits)).                                                                                                                       |
 | `WARDBY_MCP_MAX_CALLS_PER_RUN` | Same value as the server, if you set it: the most remote MCP tool calls one coding run may make (default `100`; [details](security-deployment.md#remote-mcp-servers)).                                                                                     |
 
@@ -550,6 +551,11 @@ or the server running upkeep is not up.
 Gateway-side variables (`NATIVE_GATEWAY_LISTEN`, `NATIVE_GATEWAY_DENY_PORT`) are
 set on the gateway, not the server.
 
+The gateway also records sandbox runs' steps (see
+[Run steps](debugging-agent-runs.md#run-steps)), so when you change
+`WARDBY_RUN_STEPS` (including `detail`) or `RUN_STEP_RETENTION_DAYS`, set them on
+the gateway as well as the server.
+
 ## Limits and deadline
 
 - Each worker is limited by `NATIVE_SANDBOX_CPUS`, `NATIVE_SANDBOX_MEMORY_MB`,

package/docs/security-deployment.md

@@ -640,6 +640,57 @@ ceiling only as far as your tools need.
 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

package/docs/viewer-api.md

@@ -103,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`
 
@@ -131,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.8.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: