@cat-factory/executor-harness 1.88.0 → 1.92.0

package/README.md

@@ -4,7 +4,7 @@ The payload that runs **inside** a per-run Cloudflare Container (or a
 [self-hosted runner](../../docs/runner-pool-integration.md)) to perform real
 repo work with the [Pi coding agent](https://github.com/earendil-works/pi).
 
-It is a thin TypeScript wrapper — a `node:http` server on `:8080` — that the
+It is a thin TypeScript wrapper (a `node:http` server on `:8080`) that the
 Worker drives over a small **job protocol**. Jobs run **asynchronously**: a `POST`
 accepts the job and returns immediately with a `jobId`; the driver then polls
 `GET /jobs/{id}` for live progress and the terminal result.
@@ -22,7 +22,7 @@ accepts the job and returns immediately with a `jobId`; the driver then polls
 
 | Method & path     | Purpose                                                                                                                |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `GET /health`     | Liveness — `{ "status": "ok" }`.                                                                                       |
+| `GET /health`     | Liveness: `{ "status": "ok" }`.                                                                                       |
 | `POST /run`       | Start (or re-attach to) an **implementation** job (`coder` / `mocker` / `playwright`). Returns `202 { jobId, state }`. |
 | `POST /bootstrap` | Start a **repo-bootstrap** job (adapt a reference architecture → force-push a new repo).                               |
 | `POST /blueprint` | Start a **blueprint** job (decompose a repo → write the in-repo `blueprints/` map, commit on a branch).                |
@@ -36,7 +36,7 @@ cat-factory sends are documented in
 [`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md).
 
 `GET /jobs/{id}` is also the harness's observability channel: `spans`, `followUps`
-and `callMetrics` are **drain-on-read** — each poll returns what accumulated since
+and `callMetrics` are **drain-on-read**; each poll returns what accumulated since
 the previous one and clears the buffer. That is deliberate. A job that dies before
 it can return a terminal result (an evicted container, an OOM-killed process) has
 still reported the tool spans it ran and the model calls it paid for. Each drained
@@ -44,8 +44,8 @@ still reported the tool spans it ran and the model calls it paid for. Each drain
 complete list, so the backend can take both channels without double-counting a call.
 
 Because the backend records a call as soon as it drains it (and ignores the terminal
-repeat), a drained call is FINAL. A call whose tokens are still open — a CLI that reports
-only a cumulative total, costed at the end — is withheld from the drain until it is
+repeat), a drained call is FINAL. A call whose tokens are still open (a CLI that reports
+only a cumulative total, costed at the end) is withheld from the drain until it is
 complete; see `createCallMetricPublisher` in `src/pi.ts`.
 
 ## What a job does
@@ -55,54 +55,54 @@ The implementation job (`POST /run`) is the canonical sequence:
 1. **clone** the target repo (shallow) with a short-lived GitHub installation token,
 2. write the composed system prompt (role + the block's best-practice fragments)
    to Pi's **global** context file `~/.pi/agent/AGENTS.md` (outside the checkout,
-   so it never lands in a commit and never clobbers a repo's own `AGENTS.md` —
+   so it never lands in a commit and never clobbers a repo's own `AGENTS.md`:
    Pi reads and concatenates both), and point Pi at the Worker's LLM proxy via
-   `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`) — at the
+   `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`): at the
    phase-tagged completions path for the pass about to run (`.../phase/<phase>`) when the job
    body's `proxyPhasePath` says the backend serves it, which is how a repair round's model spend
    stays distinguishable from the first pass's in telemetry; without that flag the plain path is
    used and the calls are recorded as unattributed
    (see [token-burn instrumentation](../../../docs/initiatives/token-burn-instrumentation.md)),
-3. **prepopulate dependencies**, when the job body carries `dependencyInstall` — the
+3. **prepopulate dependencies**, when the job body carries `dependencyInstall`: the
    service's install command is run with `sh -c` in the checkout BEFORE the agent starts, so
    it reads real installed packages instead of inferring a library's capabilities from a
    manifest entry. Best-effort and never a gate: the outcome (success or the captured
-   failure) is folded into the agent's prompt — on EVERY pass, including the repair passes of
-   steps 6 and 7, which start a fresh agent — and the run continues either way. Whatever the
+   failure) is folded into the agent's prompt (on EVERY pass, including the repair passes of
+   steps 6 and 7, which start a fresh agent) and the run continues either way. Whatever the
    install materialises is excluded from git first, so no later `git add -A` can sweep a
    dependency tree into the pull request (see
    [dependency prepopulation](../../../docs/initiatives/agent-dependency-prepopulation.md)),
-4. **resolve the repo's pull-request template**, when this dispatch opens a PR (`src/pr-template.ts`)
-   — `.github/PULL_REQUEST_TEMPLATE.md` and its root/`docs/`/multi-template-directory variants, or
+4. **resolve the repo's pull-request template**, when this dispatch opens a PR (`src/pr-template.ts`):
+  `.github/PULL_REQUEST_TEMPLATE.md` and its root/`docs/`/multi-template-directory variants, or
    GitLab's `.gitlab/merge_request_templates/`, read straight off the checkout (a symlinked template
-   is followed only while it resolves INSIDE the checkout — this is the one repo-chosen path the
+   is followed only while it resolves INSIDE the checkout: this is the one repo-chosen path the
    harness reads unprompted). Found, it is folded into the agent's prompt (on EVERY pass, as with
    the install above) asking it to write its briefing AS that template, filled in. This exists
    because neither host applies a template to an API-created pull request, so nothing else would:
    the template only reaches the web form a human opens. A directory of several templates with no
-   `default` is left alone deliberately — it exists so a human can choose per pull request,
+   `default` is left alone deliberately: it exists so a human can choose per pull request,
 5. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
-6. **validate** the checkout, when the job body carries `validationChecks` — the service's
+6. **validate** the checkout, when the job body carries `validationChecks`: the service's
    configured check commands (install/lint/test/build) run with `sh -c` in the checkout, and
    while they fail and the attempt budget remains the agent is re-run with the captured output
    as its instruction (see [pre-PR validation](../../../docs/initiatives/pre-pr-validation.md)),
-7. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
+7. **prove the reproduction**, when the job body carries `reproduction`: the declared check is
    run against the pre-fix tree and the tree the PR will open from, in two freshly-created
    symmetric `git worktree` checkouts, and only red-then-green is reported as proof (see
-   [bugfix reproduction proof](../../../docs/initiatives/bugfix-reproduction-proof.md)). Unlike
+   [bugfix reproduction proof](../../docs/adr/0033-bugfix-reproduction-proof.md)). Unlike
    step 6 this NEVER gates the PR: a failed verification is fed back to the agent while budget
    remains, then recorded as `inconclusive`. It runs BEFORE step 6 so validation stays the last
    thing to touch the tree,
-8. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
+8. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }`, but
    ONLY if step 6 ended green. A spent budget returns an error result with the validation report
    and opens no PR. Absent `validationChecks` / `reproduction`, steps 6 and 7 do not happen at
    all. The PR's description prefers the agent-authored reviewer briefing over the generic
    dispatch-time text the job body carries: a PR-opening agent is prompted to write one to the
    `.cat-pr-description.md` sentinel at the checkout root (one per sibling repo in a multi-repo
    run; an optional leading `# <title>` line, when it is the file's only `#` heading, sets the PR
-   title), and `src/pr-description.ts` lifts it — secret-scrubbed, size-capped with a visible
+   title), and `src/pr-description.ts` lifts it; secret-scrubbed, size-capped with a visible
    note, made inert for the host by `src/host-markdown.ts`, kept out of the commit like the
-   effort/follow-ups sentinels — onto `openPullRequest`. Absent or unusable ⇒ the fallback text,
+   effort/follow-ups sentinels; onto `openPullRequest`. Absent or unusable ⇒ the fallback text,
    unchanged. When the repo ships a template (step 4) that briefing IS the filled template: it
    crosses the same scrub/cap/inert boundary on the way out, but the leading-`#` title rule is
    switched OFF for it (`titleFromHeading: false`), because those headings are the repo's and
@@ -111,47 +111,60 @@ The implementation job (`POST /run`) is the canonical sequence:
    title/description in place (carrying the engine's managed report region across); the generic
    fallback never does, so a human's edit is safe.
 
-Bootstrap differs at the ends — it may start from an empty dir, and **resets
+Bootstrap differs at the ends: it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
 ### Skills and tool servers
 
-A job body may carry `skills[]` (procedural playbooks) and `mcpServers[]` (MCP tool servers) — the
+A job body may carry `skills[]` (procedural playbooks) and `mcpServers[]` (MCP tool servers): the
 harness MATERIALISES both and decides nothing about them; the backend has already resolved which
 apply and dropped what this harness cannot serve (see
 [`backend/docs/adr/0029-agent-kind-capabilities.md`](../../docs/adr/0029-agent-kind-capabilities.md)).
 
 - **Skills** install natively under `CLAUDE_CONFIG_DIR/skills/<name>/` for a leased-credential
   claude-code run (the CLI discovers and invokes them), and under
-  `.cat-context/skill/<name>/` in the checkout for Pi, Codex, and an AMBIENT claude-code run —
+  `.cat-context/skill/<name>/` in the checkout for Pi, Codex, and an AMBIENT claude-code run:
   whose prompt carries the instructions instead, because there is no isolated config home to
   install into and the runner refuses to write into the developer's own `~/.claude`.
 - **Tool servers** become a per-run `--mcp-config` file plus `--strict-mcp-config` for claude-code
   (so an ambient run never picks up the developer's personal servers), and `[mcp_servers.*]` blocks
-  in the per-run `CODEX_HOME/config.toml` for Codex — stdio only, and skipped entirely under
-  ambient auth, which has no per-run home to write into. `--allowedTools` is passed ONLY when a
+  in the per-run `CODEX_HOME/config.toml` for Codex: stdio only, and skipped entirely under
+  ambient auth, which has no per-run home to write into. Both stdio-only skips are now BACKSTOPS
+  rather than decisions: the backend knows which transports each harness reaches and drops an
+  `http` server from a Codex dispatch with a stated reason, so the prompt names the gap instead of
+  advertising a tool this side then silently omitted. `--allowedTools` is passed ONLY when a
   server actually narrows its tools, and then carries the CLI's built-in tool names alongside the
-  `mcp__*` patterns — an allow-list is whole-session, not MCP-scoped, so a bare list of MCP
+  `mcp__*` patterns: an allow-list is whole-session, not MCP-scoped, so a bare list of MCP
   patterns would leave the agent unable to read, edit or build anything. Whether the CLI gates on
   that list at all is permission-mode dependent, so treat the narrowing as scoping rather than
-  enforcement; the prompt states it either way.
+  enforcement; the prompt states it either way. An `allowedTools` entry that is not a single tool
+  name is DROPPED at the boundary, the comma above all: the list is joined into one argument with
+  commas, so `search_issues,get_issue` in one entry would become a pattern matching nothing.
+- **An `mcp__*` call is exempt from the no-edit progress bound**, like a read or a subagent
+  dispatch: reaching a wired tool server is what the prompt tells the agent to do, so counting it
+  would abort an edits-expected run for following its own instructions. It is neutral rather than
+  edit-satisfying, and bounded by its own consecutive-call cap
+  (`JOB_MAX_CONSECUTIVE_MCP_CALLS`) for the same reason the web cap exists. Every exempt family
+  ALSO shares one backstop (`JOB_MAX_CONSECUTIVE_NON_ACTION_CALLS`), because each per-family cap
+  resets on any call outside its own family: a run alternating a web search with a tool-server
+  lookup trips neither, and having made no action call it never reaches the no-edit bound either.
 - **An `http` tool server must be `https`, or loopback.** Its headers carry a resolved credential,
   so the job boundary refuses a cleartext off-box URL (the backend refuses the same at
   registration). `secretKeys` names which `env`/`headers` entries are credentials, so exactly those
-  values are registered for redaction — scrubbing the whole map would turn ordinary config strings
+  values are registered for redaction: scrubbing the whole map would turn ordinary config strings
   into `***` in every later log line.
 
 Both config files carry this job's resolved credentials, so they are written to a per-job directory
-(mode `0600`) and never into the checkout or a HOME-global path — see the next section.
+(mode `0600`) and never into the checkout or a HOME-global path: see the next section.
 
 ## Per-job state: never a process- or HOME-global
 
 A job's staging state (the tester's secrets, private-registry auth, a repo-sourced Claude
 Skill) must be scoped to that job, not written into `process.env` or the home directory.
 
-In a container those two ARE per-job — one job per process, and `HOME` belongs to that
-container — so a global was a safe place to stage. The **local native transport** breaks both
+In a container those two ARE per-job (one job per process, and `HOME` belongs to that
+container) so a global was a safe place to stage. The **local native transport** breaks both
 assumptions: one long-lived host process serves every concurrent `ambientAuth` job, on the
 **developer's own home**. A global there is shared mutable state across siblings, and writing
 (or clearing) a dotfile destroys a file the developer owns.
@@ -162,16 +175,16 @@ under a per-job directory:
 
 | State                | Container                                    | Native (`ambientAuth`)                                                    |
 | -------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
-| Tester secrets       | child env                                    | child env (same path — the old `process.env` set/restore is gone)         |
+| Tester secrets       | child env                                    | child env (same path: the old `process.env` set/restore is gone)         |
 | Private-registry auth | `~/.npmrc`; cleared when a job has no entries | per-job `.npmrc` + `npm_config_userconfig`, seeded from the developer's; theirs is never written or removed |
-| Repo-sourced Claude Skill | installed into the isolated `CLAUDE_CONFIG_DIR` | not installed — read from the checkout's `.cat-context/skill/`, like codex |
+| Repo-sourced Claude Skill | installed into the isolated `CLAUDE_CONFIG_DIR` | not installed: read from the checkout's `.cat-context/skill/`, like codex |
 
 Two consequences worth knowing:
 
 - **The skill's PROMPT follows the same split.** A native install gets a short pointer; every
   checkout-reading case (Pi, codex, ambient claude-code) gets the instructions folded in plus a
   pointer to `.cat-context/skill/`. That decision is the backend's `renderSkillForHarness`, which
-  keys off `ambientAuth` as well as the harness — rendering an ambient run as an install would
+  keys off `ambientAuth` as well as the harness: rendering an ambient run as an install would
   point the agent at a skill that is nowhere on disk.
 - **`npm_config_userconfig` reaches less than `~/.npmrc` did.** npm and pnpm honour it; yarn does
   not. And it only reaches processes that are handed the job env, so anything the HARNESS itself
@@ -180,13 +193,13 @@ Two consequences worth knowing:
 
 When you add per-job state, put it in one of those two places. `~/.pi/*` and
 `~/.config/rpiv-web-tools` remain HOME-global, which is fine only because the Pi harness never
-runs natively (the native router sends `ambientAuth` jobs — Claude/Codex only — to the host
+runs natively (the native router sends `ambientAuth` jobs (Claude/Codex only) to the host
 process and everything else to a container).
 
 ## No secrets in the image
 
 The image (built from the `Dockerfile`, base `node:26-trixie-slim`) contains
-only `git` + the Pi CLI + this compiled wrapper — **no API keys, no GitHub
+only `git` + the Pi CLI + this compiled wrapper: **no API keys, no GitHub
 credentials**. Per job, the Worker passes a short-lived GitHub token and a
 signed, model-locked LLM-proxy **session token** in the request body. Pi reaches
 models only through the Worker proxy, which injects the real provider key (qwen /
@@ -197,22 +210,22 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | File               | Responsibility                                                                                          |
 | ------------------ | ------------------------------------------------------------------------------------------------------- |
 | `src/server.ts`    | HTTP entry point; routes `/health`, `/run`, `/bootstrap`, `/blueprint`, `/jobs/{id}`.                   |
-| `src/runner.ts`    | `JobRegistry` — async job lifecycle, idempotent on `jobId`, progress tracking.                          |
+| `src/runner.ts`    | `JobRegistry`: async job lifecycle, idempotent on `jobId`, progress tracking.                          |
 | `src/job.ts`       | Request types + validators for the job specs.                                                           |
 | `src/pi.ts`        | Pi provider config, non-interactive run, JSON-line event + todo-progress parsing, global `AGENTS.md` guidance. |
 | `src/git.ts`       | clone / branch / commit / push + GitHub PR creation; bootstrap history reset + force-push.              |
 | `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
 | `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
-| `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc — the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
-| `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`) — talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
-| `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation — the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations — and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
+| `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc; the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
+| `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`): talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
+| `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation: the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations, and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
-| `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls — it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort — every failure shape becomes a note, never a failed job. Generic — keyed off the job body, never the agent kind. |
-| `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic — keyed off the job body, never the agent kind. |
-| `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic — keyed off the job body, never the agent kind. |
-| `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries — the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers) — with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
+| `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls; it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort: every failure shape becomes a note, never a failed job. Generic: keyed off the job body, never the agent kind. |
+| `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic: keyed off the job body, never the agent kind. |
+| `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic: keyed off the job body, never the agent kind. |
+| `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries: the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers): with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
@@ -227,15 +240,17 @@ runner):
 | `PORT`                | `8080`          | HTTP port the harness listens on.                           |
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
-| `JOB_COLD_START_MS`   | `120000` (2m)   | First-output window (ADR 0026 D4). A job that has produced nothing this long records a cold-start diagnostic — a likely onboarding/auth wedge — WITHOUT being killed: logged, exposed on `GET /jobs/{id}`, and folded into the failure `detail` if the job goes on to fail. `0` disables it. |
-| `DEPENDENCY_INSTALL_TIMEOUT_MS` | a third of `JOB_MAX_DURATION_MS` (20m at its default) | Watchdog for the pre-agent dependency install; a timeout is reported as a failed install (exit 124), never a failed job. Derived from the job ceiling rather than fixed, and an explicit value is clamped by the same share — the agent is what waits on this, so setup can never consume the run it is preparing for. |
+| `JOB_MAX_CONSECUTIVE_MCP_CALLS` | `40` | Consecutive tool-server (`mcp__*`) calls with no other tool call between before the run counts as a lookup loop. The counter-bound the no-edit exemption above owes; a per-kind `tuning.guardLimits` entry can only RAISE it. |
+| `JOB_MAX_CONSECUTIVE_NON_ACTION_CALLS` | `200` | Consecutive calls of ANY no-edit-exempt family (reads, searches, web, tool servers, subagent dispatches) with no action call between them. The backstop above the per-family caps, since each of those resets on a call outside its own family; sized as a backstop rather than a research judgement, and reset by any `bash`/edit. |
+| `JOB_COLD_START_MS`   | `120000` (2m)   | First-output window (ADR 0026 D4). A job that has produced nothing this long records a cold-start diagnostic (a likely onboarding/auth wedge) WITHOUT being killed: logged, exposed on `GET /jobs/{id}`, and folded into the failure `detail` if the job goes on to fail. `0` disables it. |
+| `DEPENDENCY_INSTALL_TIMEOUT_MS` | a third of `JOB_MAX_DURATION_MS` (20m at its default) | Watchdog for the pre-agent dependency install; a timeout is reported as a failed install (exit 124), never a failed job. Derived from the job ceiling rather than fixed, and an explicit value is clamped by the same share: the agent is what waits on this, so setup can never consume the run it is preparing for. |
 | `DEPENDENCY_INSTALL_HEARTBEAT_MS` | `30000` (30s) | How often the dependency install feeds the job inactivity watchdog. A cold install is activity-silent and `JOB_INACTIVITY_MS` is tighter than its own watchdog, so without this a healthy install aborts the run as "likely hung". |
 | `VALIDATION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a pre-PR validation check; a timeout counts as a failure (exit 124) so one hung command can't wedge the loop. |
 | `REPRODUCTION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a reproduction-proof setup or check command; a timeout counts as a failure (exit 124). |
 | `REPRODUCTION_HEARTBEAT_MS` | `30000` (30s) | How often the reproduction proof feeds the job inactivity watchdog while it runs commands the agent is not producing output for. |
 | `REPRODUCTION_TOTAL_BUDGET_MS` | `2700000` (45m) | Wall-clock ceiling on the WHOLE proof phase (every attempt, both trees, setup included). Attempts multiply two full tree runs each and the heartbeat above deliberately stops the inactivity watchdog from firing, so this is what bounds the phase. Checked at phase boundaries; exceeding it settles `inconclusive`, never a run failure. |
 | `HARNESS_TRANSCRIPT_TTL_MS` | `259200000` (3d) | How long lifted subscription-CLI session transcripts are kept before the retention sweep prunes them. |
-| `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content — though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
+| `HARNESS_TRANSCRIPT_ROOT`   | `<tmpdir>/cf-agent-transcripts` | Where retained session transcripts are moved to (one dir per run). Meaningful only on a reused (warm-pool) container; a per-run container is torn down with the job. The TTL sweep deletes only dirs it created (each carries a `.cf-retained` marker), so pointing this at a shared directory never touches unrelated content, though a dedicated dir is still recommended. An override on a different filesystem than the config home falls back to copy-then-remove. |
 
 ## Build / test
 
@@ -283,11 +298,11 @@ pnpm --filter @cat-factory/executor-harness run image:publish
 The script ([`scripts/publish-image.sh`](./scripts/publish-image.sh)) builds the
 multi-arch image once and pushes it to the selected registries. Override defaults
 via env vars (`REGISTRIES`, `GHCR_OWNER`, `DOCKERHUB_ORG`, `TAG`, `PUSH_LATEST`,
-`PLATFORMS`, `EXTRA_CA`) — see the header of the script. Example: GHCR only —
+`PLATFORMS`, `EXTRA_CA`): see the header of the script. Example: GHCR only;
 `REGISTRIES=ghcr pnpm --filter @cat-factory/executor-harness run image:publish`.
 
 A backend deployment references the image from `wrangler.toml`
-(`[[containers]] image = "ghcr.io/<owner>/cat-factory-executor:<version>"` — see
+(`[[containers]] image = "ghcr.io/<owner>/cat-factory-executor:<version>"`: see
 [`deploy/backend`](../../../deploy/backend)); a self-hosted runner pool pulls the
 same image (see [`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md)).
 The worker library's own test/dev `wrangler.toml` still references this

package/dist/agent-capabilities.d.ts

@@ -64,6 +64,19 @@ export declare function parseSkillSpecs(value: unknown): SkillSpec[] | undefined
  * `src/host-markdown.ts` uses.
  */
 export declare const MCP_SERVER_ID_PATTERN: RegExp;
+/**
+ * A tool name an `allowedTools` entry may name. Kept byte-identical to kernel's
+ * `MCP_TOOL_NAME_PATTERN` for the same reason {@link MCP_SERVER_ID_PATTERN} is a copy, and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts`.
+ *
+ * The comma is the reason the rule exists on THIS side of the boundary too:
+ * {@link claudeAllowedToolPatterns} builds the list that the runner joins into one
+ * `--allowedTools` argument with commas, so an entry carrying one splits into two patterns of which
+ * the second matches no tool the CLI has. Dropped rather than passed through, because the entries
+ * that survive are what narrows the session: a bad one would silently take the run's whole MCP
+ * surface with it.
+ */
+export declare const MCP_TOOL_NAME_PATTERN: RegExp;
 /**
  * Whether an HTTP tool server's URL may be started. Mirrors kernel's `isAllowedMcpHttpUrl` (see
  * {@link MCP_SERVER_ID_PATTERN} for why it is a copy, and the conformity suite that pins it):
@@ -116,9 +129,13 @@ export declare const CLAUDE_BUILT_IN_TOOLS: readonly string[];
 export declare function claudeAllowedToolPatterns(servers: McpServerSpec[]): string[] | undefined;
 /**
  * The `[mcp_servers.<id>]` TOML block Codex reads from its `CODEX_HOME/config.toml`. Codex's MCP
- * client is stdio-only, so an `http` server is skipped here — the backend states such a server as
- * unavailable when it declares `harnesses: ['claude-code']`, and a deployment that wires an HTTP
- * server for Codex gets a no-op rather than a malformed config.
+ * client is stdio-only, so an `http` server is skipped here.
+ *
+ * The skip is now a BACKSTOP rather than the decision: the backend knows which transports each
+ * harness reaches (`MCP_HARNESS_TRANSPORTS`) and drops an `http` server from a Codex dispatch under
+ * its own `transport_unsupported` reason, so the prompt states the gap instead of advertising a tool
+ * this writer then silently omitted. It stays because a body that reached the container by any other
+ * route must still produce a valid config rather than a malformed one.
  */
 export declare function codexMcpConfigToml(servers: McpServerSpec[]): string;
 /**

package/dist/agent-capabilities.js

@@ -125,6 +125,19 @@ function sanitizeServerId(value) {
         return undefined;
     return MCP_SERVER_ID_PATTERN.test(value) ? value : undefined;
 }
+/**
+ * A tool name an `allowedTools` entry may name. Kept byte-identical to kernel's
+ * `MCP_TOOL_NAME_PATTERN` for the same reason {@link MCP_SERVER_ID_PATTERN} is a copy, and pinned
+ * against it by `test/agent-capabilities.conformity.test.ts`.
+ *
+ * The comma is the reason the rule exists on THIS side of the boundary too:
+ * {@link claudeAllowedToolPatterns} builds the list that the runner joins into one
+ * `--allowedTools` argument with commas, so an entry carrying one splits into two patterns of which
+ * the second matches no tool the CLI has. Dropped rather than passed through, because the entries
+ * that survive are what narrows the session: a bad one would silently take the run's whole MCP
+ * surface with it.
+ */
+export const MCP_TOOL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 /**
  * Whether an HTTP tool server's URL may be started. Mirrors kernel's `isAllowedMcpHttpUrl` (see
  * {@link MCP_SERVER_ID_PATTERN} for why it is a copy, and the conformity suite that pins it):
@@ -166,6 +179,17 @@ function parseStringArray(value) {
     const out = value.filter((v) => typeof v === 'string');
     return out.length ? out : undefined;
 }
+/**
+ * The `allowedTools` list: string entries that are single tool NAMES (see
+ * {@link MCP_TOOL_NAME_PATTERN}). Undefined when nothing survives, which is the same answer as an
+ * absent field (every tool the server exposes) and the right one: the alternative is a list whose
+ * only surviving entries are the platform's own built-in tool names, i.e. a run narrowed to no MCP
+ * tools at all. The backend refuses these at registration; this is the boundary check.
+ */
+function parseAllowedTools(value) {
+    const names = parseStringArray(value)?.filter((name) => MCP_TOOL_NAME_PATTERN.test(name));
+    return names?.length ? names : undefined;
+}
 /** Validate one `mcpServers` entry, or undefined when malformed for its transport. */
 function parseMcpServerSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -174,7 +198,7 @@ function parseMcpServerSpec(value) {
     const id = sanitizeServerId(o.id);
     if (!id)
         return undefined;
-    const allowedTools = parseStringArray(o.allowedTools);
+    const allowedTools = parseAllowedTools(o.allowedTools);
     const secretKeys = parseStringArray(o.secretKeys);
     if (o.transport === 'http') {
         // https anywhere, plain http only on loopback: the CLI would happily be pointed at a
@@ -313,9 +337,13 @@ function tomlString(value) {
 }
 /**
  * The `[mcp_servers.<id>]` TOML block Codex reads from its `CODEX_HOME/config.toml`. Codex's MCP
- * client is stdio-only, so an `http` server is skipped here — the backend states such a server as
- * unavailable when it declares `harnesses: ['claude-code']`, and a deployment that wires an HTTP
- * server for Codex gets a no-op rather than a malformed config.
+ * client is stdio-only, so an `http` server is skipped here.
+ *
+ * The skip is now a BACKSTOP rather than the decision: the backend knows which transports each
+ * harness reaches (`MCP_HARNESS_TRANSPORTS`) and drops an `http` server from a Codex dispatch under
+ * its own `transport_unsupported` reason, so the prompt states the gap instead of advertising a tool
+ * this writer then silently omitted. It stays because a body that reached the container by any other
+ * route must still produce a valid config rather than a malformed one.
  */
 export function codexMcpConfigToml(servers) {
     const blocks = [];

package/dist/agent-runner.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from './logger.js';
-import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress } from './pi.js';
+import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress, type ToolSpan } from './pi.js';
 import { type McpServerSpec, type SkillSpec } from './agent-capabilities.js';
 import { type ProgressGuardLimits } from './progress-guard.js';
 import { type SliceReview } from './subagents.js';
@@ -72,6 +72,13 @@ export interface SubscriptionRunOptions {
     onActivity?: () => void;
     /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
     onProgress?: (progress: TodoProgress) => void;
+    /**
+     * Called once per completed tool call with a {@link ToolSpan}: the run's TRAJECTORY. The CLI's
+     * tool loop is internal to the CLI and never touches our proxy, so its own event stream is the
+     * only place these exist — without this hook a subscription-harness run's account of what it
+     * DID dies with the container.
+     */
+    onSpan?: (span: ToolSpan) => void;
     /**
      * Called with the FULL set of per-slice reviews each time one lands, so the backend can persist
      * a parallel review's completed work as it happens instead of only from the terminal result.

package/dist/agent-runner.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js';
 import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js';
+import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { ProgressGuard } from './progress-guard.js';
@@ -372,6 +373,27 @@ function createClaudeProgressGuard(opts) {
         reason: () => guardReason,
     };
 }
+/**
+ * The run's TRAJECTORY, on the claude-code stream: each `tool_use` block paired with the
+ * `tool_result` that answers it on the following user turn, numbered and captured (scrubbed +
+ * capped). The CLI's stream is the only place this loop is visible at all — its tool calls never
+ * touch our proxy — so without this a subscription-harness run's account of what it DID dies with
+ * the container.
+ *
+ * Both halves are no-ops when the caller wants no spans, so a driver that only needs the run's
+ * output never pays to serialise a body nothing will read. Split out of {@link runClaudeCode} for
+ * the per-function line budget, like {@link createClaudeProgressGuard}.
+ */
+function createClaudeToolTrajectory(opts, secrets) {
+    if (!opts.onSpan)
+        return { onToolUse: () => { }, onToolResults: () => { } };
+    const onSpan = opts.onSpan;
+    const tracker = new ToolCallTracker(secrets);
+    return {
+        onToolUse: (id, name, input) => tracker.started(id, name, input),
+        onToolResults: (content) => recordClaudeToolResults(tracker, content, (call) => onSpan({ ...call, bodies: 'stored' })),
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -459,6 +481,7 @@ export async function runClaudeCode(opts) {
     // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
     const progressGuard = createClaudeProgressGuard(opts);
     const { rememberTool, feedGuard, guardAbort } = progressGuard;
+    const trajectory = createClaudeToolTrajectory(opts, secrets);
     const onEvent = (event, meta) => {
         const type = event.type;
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
@@ -481,6 +504,7 @@ export async function runClaudeCode(opts) {
                 // `is_error` its `tool_result` carries on the next `user` turn.
                 if (typeof block.id === 'string' && typeof block.name === 'string') {
                     rememberTool(block.id, block.name);
+                    trajectory.onToolUse(block.id, block.name, block.input);
                 }
                 if (block.name === 'TodoWrite') {
                     const progress = todosToProgress(block.input?.todos);
@@ -506,6 +530,9 @@ export async function runClaudeCode(opts) {
                 // would kill nothing and only convert a clean exit into a spurious failure.
                 if (!meta?.final)
                     feedGuard(content);
+                // The trajectory's other half — fed on the FINAL flush too, unlike the guard, since a
+                // CLI that has exited is exactly when the last calls' results matter.
+                trajectory.onToolResults(content);
                 telemetry.onToolResult(dispatchId, content);
             }
         }

package/dist/job.d.ts

@@ -493,6 +493,8 @@ export interface GuardLimitsSpec {
     maxToolCallsWithoutEdit?: number;
     maxConsecutiveErrors?: number;
     maxConsecutiveWebCalls?: number;
+    maxConsecutiveMcpCalls?: number;
+    maxConsecutiveNonActionCalls?: number;
 }
 /**
  * The record of standing the service's docker-compose dependencies up before a tester

package/dist/job.js

@@ -36,12 +36,18 @@ function parseGuardLimits(value) {
     const noEdit = posInt(o.maxToolCallsWithoutEdit);
     const errors = posInt(o.maxConsecutiveErrors);
     const web = posInt(o.maxConsecutiveWebCalls);
+    const mcp = posInt(o.maxConsecutiveMcpCalls);
+    const nonAction = posInt(o.maxConsecutiveNonActionCalls);
     if (noEdit !== undefined)
         spec.maxToolCallsWithoutEdit = noEdit;
     if (errors !== undefined)
         spec.maxConsecutiveErrors = errors;
     if (web !== undefined)
         spec.maxConsecutiveWebCalls = web;
+    if (mcp !== undefined)
+        spec.maxConsecutiveMcpCalls = mcp;
+    if (nonAction !== undefined)
+        spec.maxConsecutiveNonActionCalls = nonAction;
     return Object.keys(spec).length > 0 ? spec : undefined;
 }
 /**

package/dist/pi-workspace.js

@@ -182,6 +182,9 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             expectsEdits: spec.expectsEdits ?? true,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
+            // and a proxied one produce the same evidence rather than one of them producing none.
+            onSpan: opts.onSpan,
             // Per-slice review capture, so a parallel review's finished slices are persisted as they
             // land rather than only in the terminal output. Only the subscription runners fan work out
             // across subagents, so this is the only path that can produce it.

package/dist/pi.d.ts

@@ -187,18 +187,39 @@ export interface TodoProgress {
     items?: TodoItem[];
 }
 /**
- * One tool invocation in Pi's loop, captured for the run's observability trace.
- * Metadata only (name + timing + ok) — never the tool's args or result — so the
- * harness buffer stays tiny. The backend drains these on its existing job poll and
- * emits them as child spans under the run trace.
+ * One tool invocation in an agent's loop, captured for the run's TRAJECTORY: the ordered
+ * account of what the agent did, drained by the backend on its existing job poll and
+ * both persisted and emitted as a child span under the run trace.
+ *
+ * It carries the call's arguments and result (scrubbed and capped at capture — see
+ * `tool-trajectory.ts`), because the question asked of a finished run is which command
+ * ran against what, not how long a tool named `bash` took. Whether those bodies are
+ * RETAINED is the backend's decision, taken against the deployment switch and the
+ * workspace's opt-out; the harness's job is to capture them bounded and scrubbed.
  */
 export interface ToolSpan {
     tool: string;
-    /** Epoch ms the tool call started (approximated as the previous tool's end). */
+    /**
+     * The call's 0-based ordinal within this job. Two calls routinely land in the same
+     * millisecond, so this is the only thing that orders the trajectory — and it is what
+     * makes the backend's stored row id deterministic, so a replayed poll re-records
+     * instead of duplicating.
+     */
+    seq: number;
+    /** Epoch ms the tool call started (the previous call's end when no start was seen). */
     startedAt: number;
     /** Epoch ms the tool call ended (when its `tool_execution_end` event arrived). */
     endedAt: number;
     ok: boolean;
+    /** Whether the bodies below were captured at all — always `'stored'` from this harness. */
+    bodies: 'stored' | 'withheld';
+    /** The call's arguments, serialised, scrubbed and capped. `''` when it took none. */
+    args: string;
+    /** What the tool returned, scrubbed and capped. `''` when it returned nothing. */
+    result: string;
+    /** Characters the cap dropped from {@link args} / {@link result}; 0 when nothing was cut. */
+    argsDropped: number;
+    resultDropped: number;
 }
 /**
  * What the agent actually did this run, independent of any file changes. Used to