@wardby/cli 0.8.0 → 0.9.0

package/help/admin-viewer.md

@@ -27,6 +27,7 @@ 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/claude-code-run-pane.md

@@ -3,8 +3,8 @@ 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: [claude code, plugin, wardby-runs, pane, claude-plugin, runs, desktop, auto mode, permissions]
-appliesTo: ">=0.8.0"
+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
@@ -25,8 +25,10 @@ server named `wardby` yet. Or install it yourself with
 `/wardby-runs`.
 
 If the pane says auto mode refused a call, allow `mcp__wardby__list_runs`,
-`mcp__wardby__list_agents`, `mcp__wardby__get_run` and
-`mcp__wardby__get_run_transcript` in `/permissions`.
+`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
@@ -37,4 +39,25 @@ keys it shows. The desktop app needs no setting.
 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.

package/help/errors/coding-mcp-gateway-unavailable.md

@@ -0,0 +1,46 @@
+---
+id: errors/coding-mcp-gateway-unavailable
+title: A coding run failed before launch because the native gateway did not wake
+summary: In low-power mode, the run failed with coding_failure_mcp_gateway_unavailable because the native gateway that serves its MCP tools did not wake in time.
+audience: operator
+tags: [error, mcp, coding-agents, low-power, coding_failure_mcp_gateway_unavailable, coding_mcp_gateway_unavailable]
+appliesTo: ">=0.8.0"
+---
+
+# A coding run failed before launch because the native gateway did not wake
+
+## What happened
+
+The run's error starts with `coding_failure_mcp_gateway_unavailable`, followed
+by a diagnostic id. It happens only in [low-power mode](../low-power-mode.md).
+
+A coding run with MCP tools sends every MCP call through the coding proxy to
+the native gateway (`wardby-native-gateway`). In low-power mode the gateway
+may be scaled to zero, so before such a run launches, wardby wakes the gateway
+together with the proxy and waits for a ready endpoint. The gateway did not
+become ready in time, so wardby failed the run rather than start it without
+its MCP tools. Nothing was launched, so the run made no changes.
+
+The run's error contains only the code and the diagnostic id. The control
+plane log has the cause at `warn`, under the same diagnostic id, with the
+internal code `coding_mcp_gateway_unavailable` and the underlying wake error,
+usually [`low_power_wake_timeout`](low-power-wake-timeout.md) or
+[`low_power_scale_forbidden`](low-power-scale-forbidden.md).
+
+## What to do
+
+1. Search the control plane log for the diagnostic id and read the wake error.
+2. For `low_power_wake_timeout`, check why the gateway pod did not become
+   ready: `kubectl -n <namespace> describe deployment wardby-native-gateway`
+   and the events of its pod. A cold Autopilot node can take a few minutes.
+   The wait is at least 5 minutes; for coding runs a
+   `KUBERNETES_READY_TIMEOUT_MS` above that, set on the control-plane
+   Deployment, raises it.
+3. For `low_power_scale_forbidden`, re-run `up.sh` with `WARDBY_LOW_POWER=1` to
+   apply the `wardby-power` Role.
+4. Trigger the agent again once the gateway is ready.
+
+Runs without MCP tools do not wake the gateway and never fail this way.
+
+See [Remote MCP servers for coding agents](../../docs/mcp-servers.md#coding-agents)
+and [Low-power mode](../low-power-mode.md).

package/help/low-power-mode.md

@@ -3,7 +3,7 @@ id: low-power-mode
 title: Low power mode on GKE
 summary: Low power mode: scale the coding proxy and native gateway to zero when idle to cut the cost of a lightly used GKE deployment, and what changes when they wake.
 audience: operator
-tags: [gke, cost, low-power, scale-to-zero, kubernetes, autoscaling, idle, power_sleep, power_status, sleep now, power:manage]
+tags: [gke, cost, low-power, scale-to-zero, kubernetes, autoscaling, idle, power_sleep, power_status, sleep now, power:manage, mcp, coding-agents]
 appliesTo: ">=0.6.0"
 ---
 
@@ -38,14 +38,20 @@ only when `WARDBY_LOW_POWER=1`.
 - **Sleep.** Every minute the scheduler leader scales the coding proxy
   (`wardby-coding-proxy`) or native gateway (`wardby-native-gateway`) to 0 when
   nothing is pending or running for it and nothing finished within the idle
-  window. The gateway also needs no active session. Either target sleeps only
+  window. For the gateway that means sandbox runs and coding runs with MCP
+  tools, and it also needs no active session. Either target sleeps only
   once at least one idle window has passed since it was last woken (annotation
   `wardby.io/power-woke-at`) and since the control plane started, whichever is
   later. The check repeats just before scaling. Log: `power: proxy slept (idle 30m)`.
 - **Wake.** A coding run scales the proxy to 1 and waits for a ready endpoint;
-  a sandbox run does the same for the gateway. The wait is at least 5 minutes.
-  A `KUBERNETES_READY_TIMEOUT_MS` (proxy) or `NATIVE_SANDBOX_READY_TIMEOUT_MS`
-  (gateway) above that, set on the control-plane Deployment, raises it. Expect
+  a sandbox run does the same for the gateway. A coding run with MCP tools
+  wakes both at once, because its MCP calls go through the gateway; if the
+  gateway does not wake it fails before launch with
+  [`coding_failure_mcp_gateway_unavailable`](errors/coding-mcp-gateway-unavailable.md).
+  The wait is at least 5 minutes.
+  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 that, set on the control-plane Deployment, raises it. Expect
   about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`. A
   sandbox run woken this way may then wait for a gVisor node for its worker
   pod, so its first model call can come several minutes after it started. From
@@ -71,15 +77,17 @@ Pass `target: "proxy"` or `target: "gateway"` to sleep one; omit it for both.
 
 - It scales the target to 0 at once, ignoring the idle window and the woke-at
   grace.
-- It never stops a run. A target with a pending or running run, or for the
-  gateway an active gateway session, stays up, and its run ids are returned:
+- It never stops 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, stays up, and its run ids are returned:
   `{ "slept": ["proxy"], "blocked": [{ "target": "gateway", "runIds": ["..."] }] }`.
   Recently finished runs do not block it.
 - The next run wakes the target as usual.
 - Each call is logged with `event: "power.sleep"` and the caller's principal.
 
 `power_status` returns, for each target, `replicas`, `ready`, `wokeAt` and
-`blockers` (the run ids keeping it busy).
+`blockers` (the run ids keeping it busy; for the gateway these include
+pending or running coding runs with MCP tools).
 
 Both tools need the `power:manage` scope, which only the `admin` role grants
 (see [Identity and access](identity-and-access.md)). With the mode off,
@@ -111,6 +119,9 @@ full table.
 
 - [`low_power_wake_timeout`](errors/low-power-wake-timeout.md): the target did
   not become ready in time, or its Deployment does not exist.
+- [`coding_failure_mcp_gateway_unavailable`](errors/coding-mcp-gateway-unavailable.md):
+  a coding run with MCP tools failed before launch because the gateway did not
+  wake.
 - `native_sandbox_launch_abandoned` (0.7.0 and later): a sandbox run was
   stopped while the gateway woke, so no worker pod was made.
 - [`low_power_disabled`](errors/low-power-disabled.md): `power_sleep` was

package/help/mcp.md

@@ -33,3 +33,5 @@ From Wardby 0.8.0, Claude Code can show your runs in a pane beside the chat
 through the `wardby-runs` plugin: run `wardby claude-plugin install`, then
 `/wardby-runs`. Search help for "claude code plugin" (article
 `claude-code-run-pane`, Wardby 0.8.0 and later).
+
+To follow what a run is doing, call `get_run_steps` (article `run-steps`).

package/help/resume-runs-locally.md

@@ -49,6 +49,10 @@ blob store nothing is stored, and `update_agent` warns you.
   (default 10 MiB, at most 64 MiB). Each run records a status (`stored`,
   `too_large`, `not_captured` or `failed`) with a reason code.
 
+For a short line-per-step record of any run, without a blob store and without
+continuing it, see `run-steps`; from 0.9.0 its `detail` level is a lighter way to
+see tool output without a transcript.
+
 ## Who can read it
 
 Transcripts are stored from the first run with `sessionResume` on. Anyone

package/help/run-steps.md

@@ -0,0 +1,140 @@
+---
+id: run-steps
+title: See what a run is doing (run steps)
+summary: Wardby records each run's steps, one line per tool call or model message, so you can follow a running run and read what a finished one did with get_run_steps. Run steps detail adds tool output.
+audience: operator
+tags: [run steps, claude code run steps, get_run_steps, what is my run doing, WARDBY_RUN_STEPS, viewer step event]
+appliesTo: >=0.9.0
+---
+
+# See what a run is doing
+
+Wardby records the steps of a run while it runs:
+
+- 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` for a command that exited with code N);
+- one line for what the **model said**, cut to about 120 characters.
+
+## 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.
+
+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 agent's `run_command`, Claude Code's command tool, and
+Codex's `exec_command`, `shell`, `local_shell` and `shell_command`. Another tool
+shows 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 (the pull request description), or `Finished` with the
+outcome (for example `Finished: changes ready`) when it returned none.
+
+For Claude Code and Codex runs, the coding proxy reads the steps from the
+model's replies after relaying them and posts them to the server, which needs a
+listener for them: `WARDBY_RUN_STEPS_LISTEN` on `wardby serve` and
+`WARDBY_RUN_STEPS_URL` on the proxy. The reference GKE manifests set both; the
+kind overlay sets only `WARDBY_RUN_STEPS_URL`, so set
+`WARDBY_RUN_STEPS_LISTEN` on the host's `wardby serve`. Without either, coding
+runs record no steps; native runs are not affected. A slow or unreachable listener loses steps; it never slows the run.
+
+## Read the steps
+
+- `get_run_steps` with `runId` lists a run's steps, oldest first, 50 at a time
+  (`limit`, at most 200). `next` is what to pass as `after` for the next page.
+  To follow a running run, call it again every few seconds with `after` set to
+  the last `seq` you have.
+- `get_run` and `list_runs` (without `agentId`) include `lastStep`, the run's
+  newest step as one line, for example `Bash: npm test (exit 1)`.
+- The `wardby-runs` Claude Code pane shows a running run's last steps and a
+  finished run's steps; see `claude-code-run-pane`.
+- The admin viewer API sends a `step` event on `/admin/api/events` for each
+  step and status, and `GET /admin/api/runs/<id>` lists the run's newest 200
+  steps (see `admin-viewer`). The Wardby Viewer app shows them in a **Steps**
+  section of a run's detail.
+
+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.
+
+You can read a run's steps when you can read the run with `get_run`.
+
+A run records at most 2,000 steps. Later steps are not recorded; `dropped`
+counts them.
+
+## Secrets
+
+Before a step is stored, Wardby removes every secret value the run's agent has
+(its attached secrets, readable or brokered, and its MCP servers' secrets), the
+run's own capability and registry token, and
+anything shaped like a token or key. A command that echoes a secret shows
+`[REDACTED]` in its place.
+
+## Retention
+
+Steps, and their detail, are deleted `RUN_STEP_RETENTION_DAYS` after they are
+recorded (default 30). A change applies to steps recorded after it. `get_run_steps` reports `expired` when a run finished more than
+`RUN_STEP_RETENTION_DAYS` ago and has no steps left.
+
+## Settings
+
+| Variable                  | Default   | What it does                                                                                                                                                                        |
+| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_RUN_STEPS`        | `summary` | `off` records no steps; `summary` 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` | `30`      | Days to keep a step, a whole number from 1 to 3650. Any other value stops start-up.                                                                                                 |
+| `WARDBY_RUN_STEPS_LISTEN` | unset     | On `wardby serve` only: `host:port` (or `:port`) of the listener the coding proxy posts coding runs' steps to. Unset: no listener.                                                  |
+| `WARDBY_RUN_STEPS_URL`    | unset     | On the coding proxy: the listener's origin, for example `http://<server host>:8792`, with no credentials or path. Unset: coding runs record no steps.                               |
+
+Set `WARDBY_RUN_STEPS` (including `detail`) and `RUN_STEP_RETENTION_DAYS` on
+every process that writes steps: `wardby serve`,
+`wardby scheduler`, `wardby run`, `wardby mcp` and `wardby native-gateway`. The
+coding proxy reads `WARDBY_RUN_STEPS` too: with `off`, or with
+`WARDBY_RUN_STEPS_URL` unset, no step text leaves the proxy. For a coding
+run's steps use `wardby serve` (the only process that runs the listener), not
+the stdio `wardby mcp`.
+
+For coding runs at `detail`, set `WARDBY_RUN_STEPS=detail` on the coding proxy
+too: below `detail`, the proxy never sends any tool output to the server.
+
+The listener is a second network path into the server, from the coding proxy
+only; keep it off any load balancer. See
+[Run steps](../docs/security-deployment.md#run-steps) for how to restrict it.
+
+The full guide is
+[Debugging agent runs](../docs/debugging-agent-runs.md#run-steps).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardby/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Self-hosted control plane for budget-guarded AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/wardby/wardby#readme",

package/prisma/migrations/20261110000000_run_steps/migration.sql

@@ -0,0 +1,26 @@
+-- Run steps: one line per tool call or model message, and the count of steps past the per-run cap.
+ALTER TABLE "Run" ADD COLUMN "stepsDropped" INTEGER NOT NULL DEFAULT 0;
+
+CREATE TABLE "RunStep" (
+    "id" TEXT NOT NULL,
+    "runId" TEXT NOT NULL,
+    "seq" INTEGER NOT NULL,
+    "at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "kind" TEXT NOT NULL,
+    "tool" TEXT,
+    "callId" TEXT,
+    "summary" TEXT NOT NULL,
+    "status" TEXT,
+    "detail" TEXT,
+    "expiresAt" TIMESTAMP(3) NOT NULL,
+    CONSTRAINT "RunStep_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "RunStep_runId_seq_key" ON "RunStep"("runId", "seq");
+
+CREATE INDEX "RunStep_runId_callId_idx" ON "RunStep"("runId", "callId");
+
+CREATE INDEX "RunStep_expiresAt_idx" ON "RunStep"("expiresAt");
+
+ALTER TABLE "RunStep" ADD CONSTRAINT "RunStep_runId_fkey"
+    FOREIGN KEY ("runId") REFERENCES "Run"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261111000000_run_steps_viewer_notify/migration.sql

@@ -0,0 +1,59 @@
+-- Live run steps for the admin viewer (docs/viewer-api.md): a `step` event when a
+-- step is recorded and when its status arrives. Only stored columns are sent:
+-- the summary is already redacted when the row is written; the call id and the
+-- detail text are never sent. Every other branch is unchanged.
+CREATE OR REPLACE FUNCTION wardby_viewer_notify() RETURNS trigger LANGUAGE plpgsql AS $$
+DECLARE
+  payload jsonb;
+BEGIN
+  IF TG_TABLE_NAME = 'Run' THEN
+    IF TG_OP = 'UPDATE'
+       AND NEW."status" IS NOT DISTINCT FROM OLD."status"
+       AND NEW."turns" IS NOT DISTINCT FROM OLD."turns"
+       AND NEW."costUsd" IS NOT DISTINCT FROM OLD."costUsd"
+       AND NEW."tokensIn" IS NOT DISTINCT FROM OLD."tokensIn"
+       AND NEW."tokensOut" IS NOT DISTINCT FROM OLD."tokensOut"
+       AND NEW."finishedAt" IS NOT DISTINCT FROM OLD."finishedAt"
+       AND NEW."parentRunId" IS NOT DISTINCT FROM OLD."parentRunId" THEN
+      RETURN NULL; -- heartbeat-only and other invisible updates
+    END IF;
+    payload := jsonb_build_object(
+      'kind', 'run', 'runId', NEW."id", 'parentRunId', NEW."parentRunId", 'agentId', NEW."agentId",
+      'status', NEW."status", 'turns', NEW."turns", 'tokensIn', NEW."tokensIn", 'tokensOut', NEW."tokensOut",
+      'costUsd', NEW."costUsd"::float8,
+      'finishedAt', to_char(NEW."finishedAt", 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'));
+  ELSIF TG_TABLE_NAME = 'CodingRunServiceStatus' THEN
+    payload := jsonb_build_object(
+      'kind', 'service', 'runId', NEW."runId", 'name', NEW."name", 'state', NEW."state", 'attempts', NEW."attempts");
+  ELSIF TG_TABLE_NAME = 'IssuePullRequest' THEN
+    payload := jsonb_build_object('kind', 'outcome', 'runId', NEW."openedByRunId", 'source', 'pull_request');
+  ELSIF TG_TABLE_NAME = 'RunHostStatus' THEN
+    payload := jsonb_build_object('kind', 'outcome', 'runId', NEW."runId", 'source', 'host_status');
+  ELSIF TG_TABLE_NAME = 'RunIssueStatus' THEN
+    payload := jsonb_build_object('kind', 'outcome', 'runId', NEW."runId", 'source', 'issue_status');
+  ELSIF TG_TABLE_NAME = 'RunHostCheck' THEN
+    payload := jsonb_build_object('kind', 'outcome', 'runId', NEW."runId", 'source', 'host_check');
+  ELSIF TG_TABLE_NAME = 'RunStep' THEN
+    IF TG_OP = 'UPDATE' AND NEW."status" IS NOT DISTINCT FROM OLD."status" THEN
+      RETURN NULL; -- only a step's status is shown as it changes
+    END IF;
+    payload := jsonb_build_object(
+      'kind', 'step', 'runId', NEW."runId", 'seq', NEW."seq", 'stepKind', NEW."kind", 'tool', NEW."tool",
+      'summary', NEW."summary", 'status', NEW."status",
+      'at', to_char(NEW."at", 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'));
+  ELSE
+    RETURN NULL;
+  END IF;
+  -- A viewer event must never fail the write that caused it (e.g. a payload
+  -- over NOTIFY's 8000-byte limit).
+  BEGIN
+    PERFORM pg_notify('wardby_viewer', payload::text);
+  EXCEPTION WHEN OTHERS THEN
+    NULL;
+  END;
+  RETURN NULL;
+END;
+$$;
+
+CREATE TRIGGER "RunStep_viewer_notify" AFTER INSERT OR UPDATE ON "RunStep"
+  FOR EACH ROW EXECUTE FUNCTION wardby_viewer_notify();

package/prisma/migrations/20261112000000_run_steps_detail/migration.sql

@@ -0,0 +1,9 @@
+-- Run steps detail level: the owner's per-agent setting, the level fixed on each run at
+-- dispatch, and the proxy session's copy of it. Additive, nullable: existing rows mean "unset".
+CREATE TYPE "RunStepsLevel" AS ENUM ('off', 'summary', 'detail');
+
+ALTER TABLE "Agent" ADD COLUMN "runSteps" "RunStepsLevel";
+
+ALTER TABLE "Run" ADD COLUMN "runStepsLevel" "RunStepsLevel";
+
+ALTER TABLE "CodingProxySession" ADD COLUMN "runStepsLevel" "RunStepsLevel";

package/prisma/schema.prisma

@@ -87,6 +87,9 @@ model Agent {
   /// single-use worker container/pod. Each Run snapshots this at creation
   /// (Run.nativeExecutionMode), so a change reaches only later runs.
   nativeExecutionMode NativeExecutionMode @default(control_plane)
+  /// The owner's run steps level for this agent's runs; null = unset (summary). A run records
+  /// min(WARDBY_RUN_STEPS, this), fixed at dispatch (Run.runStepsLevel). Owner-only.
+  runSteps RunStepsLevel?
 
   /// Un-phased: sub-agent composition edges (see AgentSubAgent below). An
   /// agent can be a parent (has children it can delegate to) and/or a
@@ -144,6 +147,15 @@ enum AgentKind {
   coding
 }
 
+/// Run steps level (docs/debugging-agent-runs.md#run-steps): off records nothing, summary one
+/// redacted line per step, detail also a redacted detail text (tool input, the tail of tool
+/// output, model text).
+enum RunStepsLevel {
+  off
+  summary
+  detail
+}
+
 /// Where a native agent's runs execute (Agent.nativeExecutionMode).
 enum NativeExecutionMode {
   control_plane @map("control-plane")
@@ -400,6 +412,12 @@ model Run {
   /// run through the server's executor and clears this.
   stopRequestedAt      DateTime?
   stopRequestReason    String?
+  /// Run steps (RunStep) not recorded because the run already had MAX_RUN_STEPS (2,000).
+  stepsDropped         Int                      @default(0)
+  /// The run steps level this run records, fixed at dispatch: min(WARDBY_RUN_STEPS, Agent.runSteps
+  /// or summary). Null on runs from before the field (they record at most summary).
+  runStepsLevel        RunStepsLevel?
+  steps                RunStep[]
 
   /// Un-phased: sub-agent dispatch (see AgentSubAgent). Null for a
   /// top-level run; set when this run was created by a parent run's
@@ -652,6 +670,37 @@ model RunTranscript {
   @@index([expiresAt])
 }
 
+/// One line of what a run did: a tool call (with its status once the result is back) or what the
+/// model said. Derived by trusted code from model traffic and written only by the control plane's
+/// RunStepWriter, after exact-value redaction against the run's secret values
+/// (docs/debugging-agent-runs.md#run-steps). Never tool output at the summary level.
+model RunStep {
+  id        String   @id @default(cuid())
+  runId     String
+  run       Run      @relation(fields: [runId], references: [id], onDelete: Cascade)
+  /// Order within the run, from 1.
+  seq       Int
+  at        DateTime @default(now())
+  /// "tool" | "said"
+  kind      String
+  /// The tool's display name (Bash for every agent's shell tool, mcp:<name>, Edit, ...); null for "said".
+  tool      String?
+  /// The provider's call id (to attach the result), or a said:<key> id; never returned by MCP.
+  callId    String?
+  /// Redacted, at most 300 characters.
+  summary   String
+  /// ok | error | exit N, set when the result arrives.
+  status    String?
+  /// The detail level's text: redacted tool input (~4 KB), then the last ~2 KB of its output once
+  /// the result is back, or the model's text (~8 KB). At most 16,384 characters. Null below detail.
+  detail    String?
+  expiresAt DateTime
+
+  @@unique([runId, seq])
+  @@index([runId, callId])
+  @@index([expiresAt])
+}
+
 /// Coding-run services (docs/coding-services.md): the catalog a repository's
 /// .wardby/services.yaml names entries from. Admin-managed over MCP
 /// (list/get_service: agents:read; create/update/delete_service:
@@ -909,6 +958,9 @@ model CodingProxySession {
   mcpTools                  Json?
   /// SHA-256 (base64url) of the run's MCP token; null when the run has no MCP tools.
   mcpTokenHash              String?                  @unique
+  /// The run's Run.runStepsLevel, copied at session creation: the proxy sends a tool result's
+  /// output tail to the run-steps listener only at detail. Null on older sessions (= summary).
+  runStepsLevel             RunStepsLevel?
   /// MCP tools/call count for this run (capped by WARDBY_MCP_MAX_CALLS_PER_RUN).
   mcpCallCount              Int                      @default(0)