@cat-factory/executor-harness 1.86.2 → 1.90.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.d.ts

@@ -46,6 +46,13 @@ export declare function buildPreviewOutcome(standUp: {
  * the restore step entirely.
  */
 export declare function testSecretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
+/**
+ * The shared `{ key, value }[]` → child-env projection behind {@link testSecretEnv} and the
+ * generative integrations' credentials. One implementation because both channels owe the same two
+ * things — the values registered for redaction, and the env returned rather than written to
+ * `process.env` — and a second copy is a second place to forget the redaction.
+ */
+export declare function secretEnv(secrets: TestSecretSpec[] | undefined): Record<string, string>;
 /**
  * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
  * peer repos or read-only reference repos). The post-commit validation command is only wired into

package/dist/agent.js

@@ -248,7 +248,16 @@ export async function handleAgent(job, opts = {}) {
         // inherit this env, so they all read the written npmrc). In a container a job with no
         // entries clears any stale ~/.npmrc from a prior job on a reused (warm-pool) container.
         const registryEnv = await configurePackageRegistries(job.packageRegistries, scopeDir ? { isolatedDir: scopeDir } : {});
-        const scoped = withAgentEnv(opts, registryEnv);
+        // The credentials of this job's GENERATIVE BINARY INTEGRATIONS, layered on for EVERY mode
+        // rather than inside one of them: the kinds that carry the `binary-output` trait are a
+        // deployment's own and may be explore or coding agents, and a key delivered to one mode and
+        // not the other would be an integration that works or 401s depending on how its step was
+        // registered. Per-job env like everything else here — never `process.env`, which the shared
+        // native host process makes a cross-job leak.
+        const scoped = withAgentEnv(opts, {
+            ...registryEnv,
+            ...secretEnv(job.generatorSecrets),
+        });
         if (job.mode === 'preview')
             return await runPreviewMode(job, scoped);
         return job.mode === 'coding'
@@ -369,6 +378,15 @@ async function runPreviewMode(job, opts) {
  * the restore step entirely.
  */
 export function testSecretEnv(secrets) {
+    return secretEnv(secrets);
+}
+/**
+ * The shared `{ key, value }[]` → child-env projection behind {@link testSecretEnv} and the
+ * generative integrations' credentials. One implementation because both channels owe the same two
+ * things — the values registered for redaction, and the env returned rather than written to
+ * `process.env` — and a second copy is a second place to forget the redaction.
+ */
+export function secretEnv(secrets) {
     if (!secrets?.length)
         return {};
     registerKnownSecrets(secrets.map((s) => s.value));

package/dist/job-env.d.ts

@@ -0,0 +1,44 @@
+/** A required non-empty string field of the job body. */
+export declare function str(value: unknown, path: string): string;
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+export declare const RESERVED_ENV_NAMES: Set<string>;
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+export declare function isReservedEnvName(key: string): boolean;
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+export declare function parseInfraEnv(raw: unknown): Record<string, string>;
+/**
+ * One sensitive test credential the tester receives: an env-var name + its (secret) value.
+ * The backend seals these at rest and decrypts them at dispatch; the harness injects each as an
+ * environment variable the tester's shell can read (out of band — the value is NEVER in the
+ * prompt/telemetry). See {@link parseSecretEnvPairs}.
+ */
+export interface TestSecretSpec {
+    key: string;
+    value: string;
+}
+/**
+ * Validate a `{ key, value }` env-pair list under `field`. Shared by the tester's `testSecrets`
+ * and by `generatorSecrets` (the credentials of a step's generative binary integrations), because
+ * both are secret values the harness turns into environment variables of the agent's own process
+ * and both owe the same guarantees: valid env-var names, no toolchain-critical
+ * ({@link isReservedEnvName}) names, no duplicates. A second copy of these rules would be a second
+ * place for a drifted body to clobber PATH.
+ */
+export declare function parseSecretEnvPairs(value: unknown, field: string): TestSecretSpec[];

package/dist/job-env.js

@@ -0,0 +1,108 @@
+// The primitive VALUE rules of the untrusted job body: what counts as a required string, which
+// environment-variable names a body may never set, and how the two env-bearing fields (the
+// tester's `testSecrets`, a generative integration's `generatorSecrets`, and a frontend binding's
+// `env`) are parsed against those rules.
+//
+// Extracted from `job.ts` when the generative-integration credentials arrived (the file-size
+// ratchet: split along a cohesive seam, never raise the budget). The seam is a real one — every
+// rule here answers "may this raw value become part of a child process's environment", which is
+// the harness's sharpest untrusted-input boundary, and it is now shared by three parsers rather
+// than being one parser's private business.
+/** A required non-empty string field of the job body. */
+export function str(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid job: '${path}' must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+export const RESERVED_ENV_NAMES = new Set([
+    'PATH',
+    'HOME',
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'NODE_EXTRA_CA_CERTS',
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'BASH_ENV',
+    'ENV',
+    'SHELL',
+    'IFS',
+]);
+/**
+ * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
+ * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
+ * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
+ * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
+ * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
+ * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
+ */
+const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_'];
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+export function isReservedEnvName(key) {
+    if (RESERVED_ENV_NAMES.has(key))
+        return true;
+    const lower = key.toLowerCase();
+    return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
+}
+/**
+ * Collect only string→string entries from a raw `env` bag. A non-string value is dropped so a
+ * malformed binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved
+ * names that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+ * dropped too: they are spread over `process.env` at build time, so a binding named `PATH` would
+ * replace it with a URL and the build would no longer find its tools. Extracted from the infra
+ * parsers to keep their cyclomatic complexity down.
+ */
+export function parseInfraEnv(raw) {
+    const env = {};
+    if (typeof raw === 'object' && raw !== null) {
+        for (const [key, val] of Object.entries(raw)) {
+            if (key && !isReservedEnvName(key) && typeof val === 'string')
+                env[key] = val;
+        }
+    }
+    return env;
+}
+/** A valid POSIX shell variable name (letters, digits, underscore; not starting with a digit). */
+const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Validate a `{ key, value }` env-pair list under `field`. Shared by the tester's `testSecrets`
+ * and by `generatorSecrets` (the credentials of a step's generative binary integrations), because
+ * both are secret values the harness turns into environment variables of the agent's own process
+ * and both owe the same guarantees: valid env-var names, no toolchain-critical
+ * ({@link isReservedEnvName}) names, no duplicates. A second copy of these rules would be a second
+ * place for a drifted body to clobber PATH.
+ */
+export function parseSecretEnvPairs(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`Invalid job: '${field}' must be an array`);
+    const entries = [];
+    const seen = new Set();
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new Error(`Invalid job: '${field}[${i}]' must be an object`);
+        }
+        const entry = raw;
+        const key = str(entry.key, `${field}[${i}].key`).trim();
+        if (!ENV_VAR_NAME_PATTERN.test(key)) {
+            throw new Error(`Invalid job: '${field}[${i}].key' must be a valid environment variable name`);
+        }
+        if (isReservedEnvName(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        entries.push({ key, value: str(entry.value, `${field}[${i}].value`) });
+    }
+    return entries;
+}