@cat-factory/executor-harness 1.88.0 → 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/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/progress-guard.d.ts

@@ -35,11 +35,38 @@ export interface ProgressGuardLimits {
      * without it.
      */
     maxConsecutiveWebCalls?: number;
+    /**
+     * Abort after this many consecutive MCP tool-server calls (`mcp__*`) with no other
+     * tool call in between: the tool-server analogue of `maxConsecutiveWebCalls`, and
+     * present for the same reason. An `mcp__*` call is exempt from the no-edit bound (see
+     * `isMcpToolCall`), so without a streak of its own a run could query a tool server
+     * indefinitely without tripping any guard. Any non-MCP tool call resets the streak.
+     * Optional: defaults to {@link DEFAULT_PROGRESS_GUARD_LIMITS}.
+     */
+    maxConsecutiveMcpCalls?: number;
+    /**
+     * Abort after this many consecutive calls that are EXEMPT from the no-edit bound
+     * (planning, read-only exploration, subagent dispatch, `mcp__*`) with no action call
+     * in between. The backstop that makes each individual exemption mean "not counted"
+     * rather than "unbounded": every per-family streak above resets on any call outside
+     * its own family, so a run alternating `web_search` with `mcp__issues__search` (or
+     * with `read`) trips none of them and, having never made an action call, never
+     * reaches `maxToolCallsWithoutEdit` either. Only the job's wall-clock ceiling
+     * bounded that.
+     *
+     * Deliberately far above every family cap, because it is not a research bound and
+     * must not become one: reading a hundred files before the first edit is legitimate
+     * work-up, and any `bash`/edit/action call resets the streak. Optional: defaults to
+     * {@link DEFAULT_PROGRESS_GUARD_LIMITS}.
+     */
+    maxConsecutiveNonActionCalls?: number;
 }
 export declare const DEFAULT_PROGRESS_GUARD_LIMITS: {
     maxToolCallsWithoutEdit: number;
     maxConsecutiveErrors: number;
     maxConsecutiveWebCalls: number;
+    maxConsecutiveMcpCalls: number;
+    maxConsecutiveNonActionCalls: number;
 };
 /** Read {@link ProgressGuardLimits} from the environment, falling back to the defaults. */
 export declare function progressGuardLimitsFromEnv(env?: NodeJS.ProcessEnv): ProgressGuardLimits;
@@ -69,6 +96,8 @@ export declare class ProgressGuard {
     private edits;
     private consecutiveErrors;
     private consecutiveWebCalls;
+    private consecutiveMcpCalls;
+    private consecutiveNonActionCalls;
     constructor(limits: ProgressGuardLimits, 
     /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
     expectsEdits?: boolean);

package/dist/progress-guard.js

@@ -28,6 +28,16 @@ export const DEFAULT_PROGRESS_GUARD_LIMITS = {
     // A genuine research burst is a handful of searches; an uninterrupted run of this
     // many web calls (with no read/edit/bash between) is a search loop, not progress.
     maxConsecutiveWebCalls: 25,
+    // Looser than the web cap: a tool server is usually the agent's route to the SYSTEM OF
+    // RECORD (the issue tracker, the advisory database, the design source), and reading a
+    // list and then each of its items is a normal opening move, not a rabbit-hole. A run
+    // that makes this many in a row with no read, edit or bash between is looping.
+    maxConsecutiveMcpCalls: 40,
+    // Well clear of every family cap above, and of any plausible read-up: a run that makes
+    // this many exempt calls with not one action call between them has stopped converging,
+    // whatever mix of reads, searches and lookups it is cycling through. Sized as a
+    // backstop rather than a judgement, because the families are where judgement belongs.
+    maxConsecutiveNonActionCalls: 200,
 };
 // Tool names that mutate files, so a call to one clears the no-edit suspicion. Kept
 // broad on purpose: different models/extensions name the same capability differently
@@ -98,6 +108,28 @@ const EXPLORATION_TOOLS = new Set([
 // call between) can be caught as a search loop — see `maxConsecutiveWebCalls`. Covers both
 // Pi's `web_search`/`web_fetch` and Claude Code's `WebSearch`/`WebFetch`.
 const WEB_TOOLS = new Set(['web_search', 'web_fetch', 'websearch', 'webfetch']);
+// A call to a tool server (MCP). Every MCP client names these `mcp__<server>__<tool>`, and
+// the prefix is the ONLY thing the harness can know about them: what a given server's tools
+// do is a backend registration this image has never seen, so the guard classifies by shape.
+//
+// Matched, rather than enumerated in EXPLORATION_TOOLS, because the set is open: it is
+// whatever tool servers the running kind was wired with. A prefix test is also why this is a
+// function, `name.startsWith` on the already-lower-cased name, so `MCP__Issues__search`
+// classifies the same as `mcp__issues__search`.
+function isMcpToolCall(loweredName) {
+    return loweredName.startsWith('mcp__');
+}
+// Whether a call is EXEMPT from the no-edit bound: planning and bookkeeping, read-only
+// exploration, a subagent dispatch, or a tool-server call. One predicate rather than the
+// four tests inlined at the branch, because the combined non-action streak and the no-edit
+// exemption must be the SAME set: a family exempted in one place and missed in the other is
+// either an unbounded loop or a run killed for a call the bound says it may make.
+function isNonActionToolCall(loweredName) {
+    return (PLANNING_TOOLS.has(loweredName) ||
+        EXPLORATION_TOOLS.has(loweredName) ||
+        SUBAGENT_DISPATCH_TOOLS.has(loweredName) ||
+        isMcpToolCall(loweredName));
+}
 /** Read {@link ProgressGuardLimits} from the environment, falling back to the defaults. */
 export function progressGuardLimitsFromEnv(env = process.env) {
     const num = (raw, fallback) => {
@@ -108,6 +140,8 @@ export function progressGuardLimitsFromEnv(env = process.env) {
         maxToolCallsWithoutEdit: num(env.JOB_MAX_TOOLCALLS_WITHOUT_EDIT, DEFAULT_PROGRESS_GUARD_LIMITS.maxToolCallsWithoutEdit),
         maxConsecutiveErrors: num(env.JOB_MAX_CONSECUTIVE_TOOL_ERRORS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveErrors),
         maxConsecutiveWebCalls: num(env.JOB_MAX_CONSECUTIVE_WEB_CALLS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls),
+        maxConsecutiveMcpCalls: num(env.JOB_MAX_CONSECUTIVE_MCP_CALLS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls),
+        maxConsecutiveNonActionCalls: num(env.JOB_MAX_CONSECUTIVE_NON_ACTION_CALLS, DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls),
     };
 }
 /**
@@ -127,9 +161,12 @@ export function mergeGuardLimits(base, overrides) {
     return {
         maxToolCallsWithoutEdit: loosen(base.maxToolCallsWithoutEdit, overrides.maxToolCallsWithoutEdit),
         maxConsecutiveErrors: loosen(base.maxConsecutiveErrors, overrides.maxConsecutiveErrors),
-        // `maxConsecutiveWebCalls` is optional on the interface (callers may omit it), so
-        // fall back to the default before loosening — keeps `loosen`'s base a concrete number.
+        // The streak knobs are optional on the interface (callers may omit them), so fall back
+        // to the default before loosening: it keeps `loosen`'s base a concrete number.
         maxConsecutiveWebCalls: loosen(base.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls, overrides.maxConsecutiveWebCalls),
+        maxConsecutiveMcpCalls: loosen(base.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls, overrides.maxConsecutiveMcpCalls),
+        maxConsecutiveNonActionCalls: loosen(base.maxConsecutiveNonActionCalls ??
+            DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls, overrides.maxConsecutiveNonActionCalls),
     };
 }
 /**
@@ -146,6 +183,8 @@ export class ProgressGuard {
     edits = 0;
     consecutiveErrors = 0;
     consecutiveWebCalls = 0;
+    consecutiveMcpCalls = 0;
+    consecutiveNonActionCalls = 0;
     constructor(limits, 
     /** When false (assess-only runs like the merger), the no-edit bound is skipped. */
     expectsEdits = true) {
@@ -189,14 +228,49 @@ export class ProgressGuard {
         else {
             this.consecutiveWebCalls = 0;
         }
-        // Planning, read-only exploration and subagent-dispatch calls don't count toward the
-        // no-edit bound (see PLANNING_TOOLS / EXPLORATION_TOOLS / SUBAGENT_DISPATCH_TOOLS) —
-        // only "action" calls without an edit do.
-        if (PLANNING_TOOLS.has(name) ||
-            EXPLORATION_TOOLS.has(name) ||
-            SUBAGENT_DISPATCH_TOOLS.has(name)) {
+        // Tool-server (MCP) calls: bounded as their own streak for exactly the reason the web
+        // streak exists. They are exempt from the no-edit bound below, and an exemption with no
+        // counter-bound is a loop the guard cannot see. Any non-MCP call resets it.
+        if (isMcpToolCall(name)) {
+            this.consecutiveMcpCalls++;
+            const mcpCap = this.limits.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls;
+            if (this.consecutiveMcpCalls >= mcpCap) {
+                return (`no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
+                    `any other action. The agent is stuck querying its tools instead of doing the work. ` +
+                    `Aborting.`);
+            }
+        }
+        else {
+            this.consecutiveMcpCalls = 0;
+        }
+        // Planning, read-only exploration, subagent-dispatch and tool-server calls don't count
+        // toward the no-edit bound (see `isNonActionToolCall`): only "action" calls without an
+        // edit do.
+        //
+        // An `mcp__*` call is exempt for the same reason a `read` is: the bound targets the
+        // credential rabbit-hole (endless `bash` probing with nothing implemented), and reaching
+        // a registered tool server is the platform TELLING the agent to look something up
+        // ("prefer them over guessing"). Counting them would abort an edits-expected kind for
+        // consulting the issue tracker the deployment wired for it, punishing the run for
+        // following its own prompt. They are neutral rather than edit-satisfying, exactly like a
+        // subagent dispatch: a read-only lookup must not clear the suspicion the bound holds.
+        //
+        // The exempt calls carry ONE streak of their own, and it is what keeps every exemption
+        // above from adding up to an unbounded run: each per-family cap resets on any call
+        // outside its family, so alternating two exempt families trips neither, and a run that
+        // never makes an action call never reaches the no-edit bound either.
+        if (isNonActionToolCall(name)) {
+            this.consecutiveNonActionCalls++;
+            const nonActionCap = this.limits.maxConsecutiveNonActionCalls ??
+                DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls;
+            if (this.consecutiveNonActionCalls >= nonActionCap) {
+                return (`no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
+                    `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
+                    `The agent is cycling through research instead of doing the work. Aborting.`);
+            }
             return null;
         }
+        this.consecutiveNonActionCalls = 0;
         this.toolCalls++;
         if (FILE_EDIT_TOOLS.has(name))
             this.edits++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.88.0",
+  "version": "1.90.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.12.33",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.215.0",
-    "@cat-factory/server": "0.195.0",
-    "@cat-factory/spend": "0.13.2"
+    "@cat-factory/kernel": "0.232.0",
+    "@cat-factory/server": "0.210.0",
+    "@cat-factory/spend": "0.14.7"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -178,6 +178,20 @@ function sanitizeServerId(value: unknown): string | 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):
@@ -219,13 +233,25 @@ function parseStringArray(value: unknown): string[] | undefined {
   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: unknown): string[] | undefined {
+  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: unknown): McpServerSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
   const o = value as Record<string, unknown>
   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
@@ -370,9 +396,13 @@ function tomlString(value: string): string {
 
 /**
  * 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: McpServerSpec[]): string {
   const blocks: string[] = []

package/src/job.ts

@@ -181,9 +181,13 @@ function parseGuardLimits(value: unknown): GuardLimitsSpec | undefined {
   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
 }
 
@@ -874,6 +878,8 @@ export interface GuardLimitsSpec {
   maxToolCallsWithoutEdit?: number
   maxConsecutiveErrors?: number
   maxConsecutiveWebCalls?: number
+  maxConsecutiveMcpCalls?: number
+  maxConsecutiveNonActionCalls?: number
 }
 
 /**

package/src/progress-guard.ts

@@ -50,6 +50,31 @@ export interface ProgressGuardLimits {
    * without it.
    */
   maxConsecutiveWebCalls?: number
+  /**
+   * Abort after this many consecutive MCP tool-server calls (`mcp__*`) with no other
+   * tool call in between: the tool-server analogue of `maxConsecutiveWebCalls`, and
+   * present for the same reason. An `mcp__*` call is exempt from the no-edit bound (see
+   * `isMcpToolCall`), so without a streak of its own a run could query a tool server
+   * indefinitely without tripping any guard. Any non-MCP tool call resets the streak.
+   * Optional: defaults to {@link DEFAULT_PROGRESS_GUARD_LIMITS}.
+   */
+  maxConsecutiveMcpCalls?: number
+  /**
+   * Abort after this many consecutive calls that are EXEMPT from the no-edit bound
+   * (planning, read-only exploration, subagent dispatch, `mcp__*`) with no action call
+   * in between. The backstop that makes each individual exemption mean "not counted"
+   * rather than "unbounded": every per-family streak above resets on any call outside
+   * its own family, so a run alternating `web_search` with `mcp__issues__search` (or
+   * with `read`) trips none of them and, having never made an action call, never
+   * reaches `maxToolCallsWithoutEdit` either. Only the job's wall-clock ceiling
+   * bounded that.
+   *
+   * Deliberately far above every family cap, because it is not a research bound and
+   * must not become one: reading a hundred files before the first edit is legitimate
+   * work-up, and any `bash`/edit/action call resets the streak. Optional: defaults to
+   * {@link DEFAULT_PROGRESS_GUARD_LIMITS}.
+   */
+  maxConsecutiveNonActionCalls?: number
 }
 
 // `satisfies` (not a type annotation) so each property keeps its concrete `number`
@@ -63,6 +88,16 @@ export const DEFAULT_PROGRESS_GUARD_LIMITS = {
   // A genuine research burst is a handful of searches; an uninterrupted run of this
   // many web calls (with no read/edit/bash between) is a search loop, not progress.
   maxConsecutiveWebCalls: 25,
+  // Looser than the web cap: a tool server is usually the agent's route to the SYSTEM OF
+  // RECORD (the issue tracker, the advisory database, the design source), and reading a
+  // list and then each of its items is a normal opening move, not a rabbit-hole. A run
+  // that makes this many in a row with no read, edit or bash between is looping.
+  maxConsecutiveMcpCalls: 40,
+  // Well clear of every family cap above, and of any plausible read-up: a run that makes
+  // this many exempt calls with not one action call between them has stopped converging,
+  // whatever mix of reads, searches and lookups it is cycling through. Sized as a
+  // backstop rather than a judgement, because the families are where judgement belongs.
+  maxConsecutiveNonActionCalls: 200,
 } satisfies ProgressGuardLimits
 
 // Tool names that mutate files, so a call to one clears the no-edit suspicion. Kept
@@ -139,6 +174,32 @@ const EXPLORATION_TOOLS = new Set([
 // Pi's `web_search`/`web_fetch` and Claude Code's `WebSearch`/`WebFetch`.
 const WEB_TOOLS = new Set(['web_search', 'web_fetch', 'websearch', 'webfetch'])
 
+// A call to a tool server (MCP). Every MCP client names these `mcp__<server>__<tool>`, and
+// the prefix is the ONLY thing the harness can know about them: what a given server's tools
+// do is a backend registration this image has never seen, so the guard classifies by shape.
+//
+// Matched, rather than enumerated in EXPLORATION_TOOLS, because the set is open: it is
+// whatever tool servers the running kind was wired with. A prefix test is also why this is a
+// function, `name.startsWith` on the already-lower-cased name, so `MCP__Issues__search`
+// classifies the same as `mcp__issues__search`.
+function isMcpToolCall(loweredName: string): boolean {
+  return loweredName.startsWith('mcp__')
+}
+
+// Whether a call is EXEMPT from the no-edit bound: planning and bookkeeping, read-only
+// exploration, a subagent dispatch, or a tool-server call. One predicate rather than the
+// four tests inlined at the branch, because the combined non-action streak and the no-edit
+// exemption must be the SAME set: a family exempted in one place and missed in the other is
+// either an unbounded loop or a run killed for a call the bound says it may make.
+function isNonActionToolCall(loweredName: string): boolean {
+  return (
+    PLANNING_TOOLS.has(loweredName) ||
+    EXPLORATION_TOOLS.has(loweredName) ||
+    SUBAGENT_DISPATCH_TOOLS.has(loweredName) ||
+    isMcpToolCall(loweredName)
+  )
+}
+
 /** Read {@link ProgressGuardLimits} from the environment, falling back to the defaults. */
 export function progressGuardLimitsFromEnv(
   env: NodeJS.ProcessEnv = process.env,
@@ -160,6 +221,14 @@ export function progressGuardLimitsFromEnv(
       env.JOB_MAX_CONSECUTIVE_WEB_CALLS,
       DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls,
     ),
+    maxConsecutiveMcpCalls: num(
+      env.JOB_MAX_CONSECUTIVE_MCP_CALLS,
+      DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls,
+    ),
+    maxConsecutiveNonActionCalls: num(
+      env.JOB_MAX_CONSECUTIVE_NON_ACTION_CALLS,
+      DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls,
+    ),
   }
 }
 
@@ -186,12 +255,21 @@ export function mergeGuardLimits(
       overrides.maxToolCallsWithoutEdit,
     ),
     maxConsecutiveErrors: loosen(base.maxConsecutiveErrors, overrides.maxConsecutiveErrors),
-    // `maxConsecutiveWebCalls` is optional on the interface (callers may omit it), so
-    // fall back to the default before loosening — keeps `loosen`'s base a concrete number.
+    // The streak knobs are optional on the interface (callers may omit them), so fall back
+    // to the default before loosening: it keeps `loosen`'s base a concrete number.
     maxConsecutiveWebCalls: loosen(
       base.maxConsecutiveWebCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveWebCalls,
       overrides.maxConsecutiveWebCalls,
     ),
+    maxConsecutiveMcpCalls: loosen(
+      base.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls,
+      overrides.maxConsecutiveMcpCalls,
+    ),
+    maxConsecutiveNonActionCalls: loosen(
+      base.maxConsecutiveNonActionCalls ??
+        DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls,
+      overrides.maxConsecutiveNonActionCalls,
+    ),
   }
 }
 
@@ -207,6 +285,8 @@ export class ProgressGuard {
   private edits = 0
   private consecutiveErrors = 0
   private consecutiveWebCalls = 0
+  private consecutiveMcpCalls = 0
+  private consecutiveNonActionCalls = 0
 
   constructor(
     private readonly limits: ProgressGuardLimits,
@@ -257,16 +337,55 @@ export class ProgressGuard {
       this.consecutiveWebCalls = 0
     }
 
-    // Planning, read-only exploration and subagent-dispatch calls don't count toward the
-    // no-edit bound (see PLANNING_TOOLS / EXPLORATION_TOOLS / SUBAGENT_DISPATCH_TOOLS) —
-    // only "action" calls without an edit do.
-    if (
-      PLANNING_TOOLS.has(name) ||
-      EXPLORATION_TOOLS.has(name) ||
-      SUBAGENT_DISPATCH_TOOLS.has(name)
-    ) {
+    // Tool-server (MCP) calls: bounded as their own streak for exactly the reason the web
+    // streak exists. They are exempt from the no-edit bound below, and an exemption with no
+    // counter-bound is a loop the guard cannot see. Any non-MCP call resets it.
+    if (isMcpToolCall(name)) {
+      this.consecutiveMcpCalls++
+      const mcpCap =
+        this.limits.maxConsecutiveMcpCalls ?? DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveMcpCalls
+      if (this.consecutiveMcpCalls >= mcpCap) {
+        return (
+          `no progress: ${this.consecutiveMcpCalls} consecutive tool-server (MCP) calls without ` +
+          `any other action. The agent is stuck querying its tools instead of doing the work. ` +
+          `Aborting.`
+        )
+      }
+    } else {
+      this.consecutiveMcpCalls = 0
+    }
+
+    // Planning, read-only exploration, subagent-dispatch and tool-server calls don't count
+    // toward the no-edit bound (see `isNonActionToolCall`): only "action" calls without an
+    // edit do.
+    //
+    // An `mcp__*` call is exempt for the same reason a `read` is: the bound targets the
+    // credential rabbit-hole (endless `bash` probing with nothing implemented), and reaching
+    // a registered tool server is the platform TELLING the agent to look something up
+    // ("prefer them over guessing"). Counting them would abort an edits-expected kind for
+    // consulting the issue tracker the deployment wired for it, punishing the run for
+    // following its own prompt. They are neutral rather than edit-satisfying, exactly like a
+    // subagent dispatch: a read-only lookup must not clear the suspicion the bound holds.
+    //
+    // The exempt calls carry ONE streak of their own, and it is what keeps every exemption
+    // above from adding up to an unbounded run: each per-family cap resets on any call
+    // outside its family, so alternating two exempt families trips neither, and a run that
+    // never makes an action call never reaches the no-edit bound either.
+    if (isNonActionToolCall(name)) {
+      this.consecutiveNonActionCalls++
+      const nonActionCap =
+        this.limits.maxConsecutiveNonActionCalls ??
+        DEFAULT_PROGRESS_GUARD_LIMITS.maxConsecutiveNonActionCalls
+      if (this.consecutiveNonActionCalls >= nonActionCap) {
+        return (
+          `no progress: ${this.consecutiveNonActionCalls} consecutive read-only calls (searching, ` +
+          `reading, tool-server lookups, subagent dispatches) with no action call between them. ` +
+          `The agent is cycling through research instead of doing the work. Aborting.`
+        )
+      }
       return null
     }
+    this.consecutiveNonActionCalls = 0
     this.toolCalls++
     if (FILE_EDIT_TOOLS.has(name)) this.edits++