@cat-factory/executor-harness 1.94.0 → 1.96.0

package/README.md

@@ -1,7 +1,7 @@
 # @cat-factory/executor-harness
 
 The payload that runs **inside** a per-run Cloudflare Container (or a
-[self-hosted runner](../../docs/runner-pool-integration.md)) to perform real
+[self-hosted runner](https://github.com/kibertoad/cat-factory/blob/main/backend/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
@@ -33,7 +33,7 @@ replayed `POST` **re-attaches** to the running job rather than starting a
 duplicate (the durable driver's retries/replays are safe). Pi's todo-tool counts
 are surfaced as `progress` while a job runs. The exact request/response shapes
 cat-factory sends are documented in
-[`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md).
+[`docs/runner-pool-integration.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/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
@@ -62,7 +62,7 @@ The implementation job (`POST /run`) is the canonical sequence:
    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)),
+   (see [token-burn instrumentation](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/token-burn-instrumentation.md)),
 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
@@ -71,7 +71,7 @@ The implementation job (`POST /run`) is the canonical sequence:
    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)),
+   [dependency prepopulation](https://github.com/kibertoad/cat-factory/blob/main/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
    GitLab's `.gitlab/merge_request_templates/`, read straight off the checkout (a symlinked template
@@ -85,11 +85,11 @@ The implementation job (`POST /run`) is the canonical sequence:
 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)),
+   as its instruction (see [pre-PR validation](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/pre-pr-validation.md)),
 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/adr/0033-bugfix-reproduction-proof.md)). Unlike
+   [bugfix reproduction proof](https://github.com/kibertoad/cat-factory/blob/main/backend/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,
@@ -120,7 +120,7 @@ PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 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)).
+[`backend/docs/adr/0029-agent-kind-capabilities.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/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
@@ -279,7 +279,7 @@ docker.io/<org>/cat-factory-executor:<version>
 Each is tagged with the package `version`, the commit `sha-…`, and `latest`.
 
 **CI** does this automatically:
-[`.github/workflows/docker-publish.yml`](../../../.github/workflows/docker-publish.yml)
+[`.github/workflows/docker-publish.yml`](https://github.com/kibertoad/cat-factory/blob/main/.github/workflows/docker-publish.yml)
 republishes on every push to `main` that touches image content (`src/**`,
 `Dockerfile`, `tsconfig.json`, `package.json`). Docker Hub is gated on the
 `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` repo secrets; without them it publishes
@@ -303,9 +303,9 @@ via env vars (`REGISTRIES`, `GHCR_OWNER`, `DOCKERHUB_ORG`, `TAG`, `PUSH_LATEST`,
 
 A backend deployment references the image from `wrangler.toml`
 (`[[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)).
+[`deploy/backend`](https://github.com/kibertoad/cat-factory/tree/main/deploy/backend)); a self-hosted runner pool pulls the
+same image (see [`docs/runner-pool-integration.md`](https://github.com/kibertoad/cat-factory/blob/main/backend/docs/runner-pool-integration.md)).
 The worker library's own test/dev `wrangler.toml` still references this
 `Dockerfile` by local path so the acceptance suite can build it. Because the
 version is the image tag, **bump this package via a changeset whenever you change
-image content** (see [`CONTRIBUTING.md`](../../../CONTRIBUTING.md)).
+image content** (see [`CONTRIBUTING.md`](https://github.com/kibertoad/cat-factory/blob/main/CONTRIBUTING.md)).

package/dist/agent-capabilities.d.ts

@@ -42,6 +42,67 @@ export interface McpServerSpec {
      */
     secretKeys?: string[];
 }
+/**
+ * What the agent's CLI reported about ONE wired tool server when it started up.
+ *
+ * This is the OBSERVED half of the run's tool-server record, and it answers a question the
+ * backend's own half structurally cannot: the dispatch record says why the platform WITHHELD a
+ * tool, while this says a server the platform wired failed to start anyway. A vendor endpoint
+ * that 500s, an `npx` package that no longer resolves, a credential the vendor has since revoked
+ * — every one of those leaves the prompt promising a tool the agent then cannot call, and before
+ * this the only evidence was the agent saying so in prose, if it noticed at all.
+ *
+ * OBSERVED, never decided: nothing here changes what the run does. The harness reports what the
+ * CLI said and the backend records it beside what it decided; no code path branches on it.
+ */
+export interface ObservedMcpServer {
+    /** The server id the CLI named — the same id the backend declared (`--strict-mcp-config`). */
+    id: string;
+    status: ObservedMcpStatus;
+    /**
+     * How many of the CLI's exposed tools belong to this server (`mcp__<id>__…`).
+     *
+     * ABSENT and `0` are different facts and both are worth having: absent means this image counted
+     * nothing for the server, while `0` means it counted and the server contributed none: a server
+     * that connected and exposes nothing, which reads to the agent exactly like a server that was
+     * never wired. Never defaulted to 0.
+     *
+     * Two things leave it absent, and neither is "the server has no tools": the CLI listed no tools
+     * at all, or the tool namespace cannot say which of two declared servers a name belongs to (see
+     * {@link tallyToolsByServer}).
+     */
+    toolCount?: number;
+}
+/**
+ * The status vocabulary of {@link ObservedMcpServer}, normalised from the CLI's own word.
+ *
+ * A CLOSED list mapped from an OPEN one, which is why `unknown` is a member rather than a reason
+ * to drop the row. The CLI's status strings are a third party's vocabulary and it may add to them;
+ * a server whose status this image cannot name is still a server the CLI knows about, and the
+ * honest report is "it was there, this image could not read its state" rather than silence
+ * (which reads as a server the CLI never mentioned) or a guess at `ready` (which would report a
+ * dead tool as a live one, the precise failure the whole unavailability vocabulary exists to
+ * prevent).
+ *
+ * `unknown` covers two causes that share one remedy, which is why they share one member: a word
+ * this image cannot map, and a word the CLI uses for a state that is not resolved YET. Neither
+ * says anything about the server, and the surface paints neither as a fault.
+ */
+export type ObservedMcpStatus = 'ready' | 'failed' | 'needs_auth' | 'unknown';
+/**
+ * Read the claude-code CLI's startup report (`{"type":"system","subtype":"init"}`) into one
+ * {@link ObservedMcpServer} per server the CLI knows about.
+ *
+ * The CLI announces its resolved session ONCE, before the first model call: which MCP servers it
+ * loaded and with what status, and the flat list of tool names it will expose. Both halves are
+ * read here because neither answers the question alone — a `ready` server exposing no tools is as
+ * useless to the agent as a failed one, and a tool count with no status cannot say why.
+ *
+ * Returns `undefined` when the event names no servers at all, which keeps "this run wired none"
+ * and "this image observed none" from collapsing into an empty list on the backend's record.
+ * Pure, so the parsing is testable without a CLI: {@link runClaudeCode} feeds it the raw event.
+ */
+export declare function observeClaudeMcpInit(event: Record<string, unknown>): ObservedMcpServer[] | undefined;
 /**
  * The credential values carried by a run's tool servers, for {@link registerKnownSecrets}. An MCP
  * server that fails to start routinely echoes its own argv or request headers into stderr, and

package/dist/agent-capabilities.js

@@ -1,5 +1,118 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+/**
+ * Map one status word from the CLI onto {@link ObservedMcpStatus}.
+ *
+ * The synonyms are grouped rather than listed one-to-one because the CLI has spelled the same
+ * two states more than one way across versions (`connected`/`ready`, `failed`/`error`), and an
+ * image that pinned the exact spelling would silently start reporting `unknown` for every server
+ * on a CLI upgrade — a regression that looks identical to a genuine outage.
+ */
+function normalizeMcpStatus(value) {
+    if (typeof value !== 'string')
+        return 'unknown';
+    const status = value.trim().toLowerCase();
+    if (status === 'connected' || status === 'ready' || status === 'ok')
+        return 'ready';
+    if (status === 'failed' || status === 'error')
+        return 'failed';
+    // The vendor spells the OAuth-required state with a hyphen; the underscore form costs nothing
+    // to accept and is what a JSON-ish vocabulary tends to drift toward.
+    if (status === 'needs-auth' || status === 'needs_auth')
+        return 'needs_auth';
+    // Everything else, INCLUDING the CLI's `pending`. A server still handshaking when the session
+    // was announced has no resolved state, which is exactly what `unknown` says, and `needs_auth` is
+    // the tempting wrong guess for it: the surface paints that one amber as "waiting for you to
+    // authorize it", sending an operator to re-issue a working credential for a server that was
+    // merely slow and came up a second later.
+    return 'unknown';
+}
+/**
+ * Read the claude-code CLI's startup report (`{"type":"system","subtype":"init"}`) into one
+ * {@link ObservedMcpServer} per server the CLI knows about.
+ *
+ * The CLI announces its resolved session ONCE, before the first model call: which MCP servers it
+ * loaded and with what status, and the flat list of tool names it will expose. Both halves are
+ * read here because neither answers the question alone — a `ready` server exposing no tools is as
+ * useless to the agent as a failed one, and a tool count with no status cannot say why.
+ *
+ * Returns `undefined` when the event names no servers at all, which keeps "this run wired none"
+ * and "this image observed none" from collapsing into an empty list on the backend's record.
+ * Pure, so the parsing is testable without a CLI: {@link runClaudeCode} feeds it the raw event.
+ */
+export function observeClaudeMcpInit(event) {
+    if (event.type !== 'system' || event.subtype !== 'init')
+        return undefined;
+    const reported = event.mcp_servers;
+    if (!Array.isArray(reported) || reported.length === 0)
+        return undefined;
+    const rows = [];
+    const declared = new Set();
+    for (const entry of reported) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const id = sanitizeServerId(record.name);
+        // An id this image cannot hold is dropped rather than reported under a mangled name: the
+        // whole row is only useful if it JOINS the backend's declaration, and `--strict-mcp-config`
+        // means every server the CLI loaded came from the config this harness wrote.
+        if (!id || declared.has(id))
+            continue;
+        declared.add(id);
+        rows.push({ id, status: normalizeMcpStatus(record.status) });
+    }
+    if (rows.length === 0)
+        return undefined;
+    // Counted from the CLI's own tool list rather than from a per-server field, because there is no
+    // per-server field: the CLI flattens every server's tools into one array namespaced by server
+    // id. A missing/non-array list leaves every count ABSENT rather than 0 (see `toolCount`).
+    const tally = tallyToolsByServer(event.tools, declared);
+    return rows.map((row) => ({
+        ...row,
+        ...(tally && !tally.ambiguous.has(row.id) ? { toolCount: tally.counts.get(row.id) ?? 0 } : {}),
+    }));
+}
+/**
+ * Tally the CLI's flat tool list (`mcp__<id>__<tool>`) against the servers the SAME event
+ * declared, or `undefined` when it carried no list, which is the distinction
+ * {@link ObservedMcpServer.toolCount} preserves.
+ *
+ * Matched against the declared ids rather than split on the first `__`, because the id vocabulary
+ * ({@link MCP_SERVER_ID_PATTERN}) permits an underscore: a server named `code__search` owns
+ * `mcp__code__search__query`, which a first-separator split files under a server called `code`,
+ * leaving the real one reporting `toolCount: 0`. That is the single most diagnostic value on the
+ * field, so the mis-split renders a fully healthy server as one that started and exposes nothing.
+ *
+ * The same underscore makes genuine ambiguity representable: with both `code` and `code__search`
+ * declared, `mcp__code__search__query` is a name either could own and nothing in the report says
+ * which. Neither server is counted then, and both are named `ambiguous` so their count stays
+ * absent. Guessing an owner would move a real tool onto the wrong server and take the other's
+ * count to a `0` that reads as a fault.
+ */
+function tallyToolsByServer(tools, declared) {
+    if (!Array.isArray(tools))
+        return undefined;
+    const counts = new Map();
+    const ambiguous = new Set();
+    for (const tool of tools) {
+        if (typeof tool !== 'string' || !tool.startsWith('mcp__'))
+            continue;
+        const owners = [];
+        for (const id of declared) {
+            const prefix = `mcp__${id}__`;
+            // The tool name after the prefix must be non-empty: `mcp__slack__` names no tool.
+            if (tool.length > prefix.length && tool.startsWith(prefix))
+                owners.push(id);
+        }
+        const [owner] = owners;
+        if (owners.length === 1 && owner)
+            counts.set(owner, (counts.get(owner) ?? 0) + 1);
+        else
+            for (const id of owners)
+                ambiguous.add(id);
+    }
+    return { counts, ambiguous };
+}
 /**
  * The credential values carried by a run's tool servers, for {@link registerKnownSecrets}. An MCP
  * server that fails to start routinely echoes its own argv or request headers into stderr, and

package/dist/agent-runner.d.ts

@@ -1,6 +1,6 @@
 import type { Logger } from './logger.js';
 import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress, type ToolSpan } from './pi.js';
-import { type McpServerSpec, type SkillSpec } from './agent-capabilities.js';
+import { type McpServerSpec, type ObservedMcpServer, type SkillSpec } from './agent-capabilities.js';
 import { type ProgressGuardLimits } from './progress-guard.js';
 import { type SliceReview } from './subagents.js';
 /** Which subscription harness to run (the Pi harness uses `runPi` directly). */
@@ -92,6 +92,21 @@ export interface SubscriptionRunOptions {
      * same row still rides the result, so a lost poll response costs nothing.
      */
     onCallMetric?: (call: HarnessCallMetric) => void;
+    /**
+     * Called once with what the CLI reported about the tool servers it loaded, the moment it
+     * announces its resolved session (see {@link observeClaudeMcpInit}).
+     *
+     * The one thing the backend's own dispatch record cannot answer: it knows why it WITHHELD a
+     * tool, and this says a server it wired failed to start anyway. Reported even when every server
+     * came up, because "observed, all healthy" and "this image observed nothing" are different
+     * facts about a run and only the first one clears a wired server of suspicion.
+     *
+     * Whole-value latest-wins, not a delta — the CLI announces its session once, so a second call
+     * would only ever be a re-announcement of the same set. A harness whose CLI reports nothing
+     * (codex today) never calls this, which is what leaves the backend's record honestly empty
+     * rather than claiming every server failed.
+     */
+    onToolServers?: (observed: ObservedMcpServer[]) => void;
     /**
      * The per-job child logger (jobId/repo/branch correlation). Threaded so the retained
      * session-transcript path is logged for the run when the isolated config home is torn down.

package/dist/agent-runner.js

@@ -6,7 +6,7 @@ import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude
 import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js';
 import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
-import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { ProgressGuard } from './progress-guard.js';
 import { killChildProcess, spawnDetached } from './process.js';
 import { describeProcessExit } from './process-exit.js';
@@ -327,6 +327,60 @@ async function setUpClaudeMcp(servers, configHome) {
         cleanup,
     };
 }
+/**
+ * The LIVE publishers of a claude-code run: everything the stream has revealed so far that the
+ * backend should see before the run ends, rather than only in its terminal result.
+ *
+ * They are grouped because they share one rule and differ on everything else. The rule: each
+ * publishes a WHOLE current value (never a delta), so a dropped poll response costs nothing and
+ * the caller may fire them as often as it likes. What differs is what is at stake — progress is a
+ * disposable count the UI renders, while the slice reviews carry the slices' actual review WORK
+ * and are the only thing a resume of a wedged review can be rebuilt from, which is why they are
+ * published on the turn a slice lands rather than on the next progress tick.
+ *
+ * `lastTodo` is a GETTER because the event handler assigns it as the stream goes; taking the value
+ * would freeze the plan at construction time.
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function createClaudeLivePublishers(deps) {
+    const { opts, planTracker, sliceTracker } = deps;
+    return {
+        emitProgress: () => {
+            if (!opts.onProgress)
+                return;
+            const progress = mergeProgress(pickProgress(deps.lastTodo(), planTracker.progress()), sliceTracker.progress());
+            if (progress)
+                opts.onProgress(progress);
+        },
+        emitSliceReviews: () => {
+            if (!opts.onSliceReviews)
+                return;
+            const reviews = sliceTracker.sliceReviews();
+            if (reviews.length > 0)
+                opts.onSliceReviews(reviews);
+        },
+    };
+}
+/**
+ * Publish the CLI's own startup report about the tool servers it loaded — the OBSERVED half of the
+ * run's tool-server record.
+ *
+ * Handed every event because it is the one thing `runClaudeCode` reads that is neither a turn nor
+ * a result: it arrives once, ahead of the first model call, and says whether the servers the
+ * backend wired actually came up. {@link observeClaudeMcpInit} answers `undefined` for every other
+ * event and for a run that wired none, so a server-less run reports nothing and the caller's
+ * record stays honestly absent rather than empty.
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function reportToolServerStartup(event, onToolServers) {
+    if (!onToolServers)
+        return;
+    const observed = observeClaudeMcpInit(event);
+    if (observed)
+        onToolServers(observed);
+}
 /**
  * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
  * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
@@ -455,24 +509,12 @@ export async function runClaudeCode(opts) {
     const sliceTracker = createSliceTracker(secrets);
     const planTracker = createTaskPlanTracker();
     let lastTodo;
-    const emitProgress = () => {
-        if (!opts.onProgress)
-            return;
-        const progress = mergeProgress(pickProgress(lastTodo, planTracker.progress()), sliceTracker.progress());
-        if (progress)
-            opts.onProgress(progress);
-    };
-    // Publish the per-slice reviews the tracker has captured. Separate from `emitProgress` because
-    // the two answer different questions and have different lifetimes: progress is a disposable
-    // count the UI renders, while these carry the slices' actual review WORK and are persisted so a
-    // run that dies before its aggregation can be resumed from them.
-    const emitSliceReviews = () => {
-        if (!opts.onSliceReviews)
-            return;
-        const reviews = sliceTracker.sliceReviews();
-        if (reviews.length > 0)
-            opts.onSliceReviews(reviews);
-    };
+    const { emitProgress, emitSliceReviews } = createClaudeLivePublishers({
+        opts,
+        planTracker,
+        sliceTracker,
+        lastTodo: () => lastTodo,
+    });
     // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
     // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
     // turn and that call's RESULT (`is_error`) on the following `user` turn, so correlate them by
@@ -484,6 +526,7 @@ export async function runClaudeCode(opts) {
     const trajectory = createClaudeToolTrajectory(opts, secrets);
     const onEvent = (event, meta) => {
         const type = event.type;
+        reportToolServerStartup(event, opts.onToolServers);
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
         // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
         // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on

package/dist/pi-workspace.js

@@ -189,6 +189,11 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             // land rather than only in the terminal output. Only the subscription runners fan work out
             // across subagents, so this is the only path that can produce it.
             onSliceReviews: opts.onSliceReviews,
+            // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
+            // harnesses even though only claude-code's stream carries the report today: the hook is a
+            // pass-through, and a codex run that never calls it leaves the backend's record honestly
+            // absent rather than claiming every server it wired failed to start.
+            onToolServers: opts.onToolServers,
             // Stream this run's per-call telemetry to the job's live drain. The subscription
             // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
             // proxy as they happen), so this is the only path that needs the hook.

package/dist/runner.d.ts

@@ -2,6 +2,7 @@ import type { FollowUpLine } from './follow-ups.js';
 import type { ValidationReport } from './validation-checks.js';
 import type { ReproductionReport } from './reproduction-proof.js';
 import type { SliceReview } from './subagents.js';
+import type { ObservedMcpServer } from './agent-capabilities.js';
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js';
 import { type Logger } from './logger.js';
 import { type FailureCause } from './failure.js';
@@ -40,6 +41,15 @@ export interface RunOptions {
      * already persisted. Absent for a job that dispatched no subagents.
      */
     onSliceReviews?: (reviews: SliceReview[]) => void;
+    /**
+     * Receives what the agent's CLI reported about the tool servers (MCP) it loaded, once it
+     * announces its resolved session. Latest-wins (NOT a drain buffer) for the same reason as
+     * {@link onValidationReport}, with an extra one of its own: the CLI announces the set ONCE,
+     * near the start of the run, so a drain buffer would hand it to whichever poll happened to
+     * land next and lose it entirely if that poll response were dropped — on the single fact this
+     * whole channel exists to carry. Absent for a job that wired no tool servers.
+     */
+    onToolServers?: (observed: ObservedMcpServer[]) => void;
     /**
      * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
      * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
@@ -208,6 +218,18 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
      * from. Absent for a job that dispatched no subagents.
      */
     sliceReviews?: SliceReview[];
+    /**
+     * What the agent's CLI reported about the tool servers (MCP) wired for this job when it started
+     * up: per server, the status the CLI gave it and how many tools it contributed. A whole-value
+     * latest publish like {@link validationReport}, not drain-on-read — the CLI announces this once
+     * and every later poll re-reports the same set, so no poll can be the one that loses it.
+     *
+     * The complement of what the BACKEND recorded at dispatch, and the only source for the half it
+     * cannot see: the dispatch record says why the platform withheld a tool, this says a wired
+     * server failed to start anyway. Absent for a job that wired none, and for a harness whose CLI
+     * reports nothing — which is why it is absent rather than empty (see `ObservedMcpServer`).
+     */
+    toolServers?: ObservedMcpServer[];
 }
 /** Watchdog windows that bound every job. Tunable via the container's env. */
 export interface RunnerLimits {

package/dist/runner.js

@@ -270,6 +270,9 @@ export class JobRegistry {
                 onSliceReviews: (reviews) => {
                     entry.sliceReviews = reviews;
                 },
+                onToolServers: (observed) => {
+                    entry.toolServers = observed;
+                },
                 onReproductionProof: (report) => {
                     entry.reproductionReport = report;
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.94.0",
+  "version": "1.96.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.13.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.249.0",
-    "@cat-factory/server": "0.229.0",
-    "@cat-factory/spend": "0.15.14"
+    "@cat-factory/kernel": "0.264.0",
+    "@cat-factory/server": "0.244.0",
+    "@cat-factory/spend": "0.15.32"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -59,6 +59,169 @@ export interface McpServerSpec {
   secretKeys?: string[]
 }
 
+/**
+ * What the agent's CLI reported about ONE wired tool server when it started up.
+ *
+ * This is the OBSERVED half of the run's tool-server record, and it answers a question the
+ * backend's own half structurally cannot: the dispatch record says why the platform WITHHELD a
+ * tool, while this says a server the platform wired failed to start anyway. A vendor endpoint
+ * that 500s, an `npx` package that no longer resolves, a credential the vendor has since revoked
+ * — every one of those leaves the prompt promising a tool the agent then cannot call, and before
+ * this the only evidence was the agent saying so in prose, if it noticed at all.
+ *
+ * OBSERVED, never decided: nothing here changes what the run does. The harness reports what the
+ * CLI said and the backend records it beside what it decided; no code path branches on it.
+ */
+export interface ObservedMcpServer {
+  /** The server id the CLI named — the same id the backend declared (`--strict-mcp-config`). */
+  id: string
+  status: ObservedMcpStatus
+  /**
+   * How many of the CLI's exposed tools belong to this server (`mcp__<id>__…`).
+   *
+   * ABSENT and `0` are different facts and both are worth having: absent means this image counted
+   * nothing for the server, while `0` means it counted and the server contributed none: a server
+   * that connected and exposes nothing, which reads to the agent exactly like a server that was
+   * never wired. Never defaulted to 0.
+   *
+   * Two things leave it absent, and neither is "the server has no tools": the CLI listed no tools
+   * at all, or the tool namespace cannot say which of two declared servers a name belongs to (see
+   * {@link tallyToolsByServer}).
+   */
+  toolCount?: number
+}
+
+/**
+ * The status vocabulary of {@link ObservedMcpServer}, normalised from the CLI's own word.
+ *
+ * A CLOSED list mapped from an OPEN one, which is why `unknown` is a member rather than a reason
+ * to drop the row. The CLI's status strings are a third party's vocabulary and it may add to them;
+ * a server whose status this image cannot name is still a server the CLI knows about, and the
+ * honest report is "it was there, this image could not read its state" rather than silence
+ * (which reads as a server the CLI never mentioned) or a guess at `ready` (which would report a
+ * dead tool as a live one, the precise failure the whole unavailability vocabulary exists to
+ * prevent).
+ *
+ * `unknown` covers two causes that share one remedy, which is why they share one member: a word
+ * this image cannot map, and a word the CLI uses for a state that is not resolved YET. Neither
+ * says anything about the server, and the surface paints neither as a fault.
+ */
+export type ObservedMcpStatus = 'ready' | 'failed' | 'needs_auth' | 'unknown'
+
+/**
+ * Map one status word from the CLI onto {@link ObservedMcpStatus}.
+ *
+ * The synonyms are grouped rather than listed one-to-one because the CLI has spelled the same
+ * two states more than one way across versions (`connected`/`ready`, `failed`/`error`), and an
+ * image that pinned the exact spelling would silently start reporting `unknown` for every server
+ * on a CLI upgrade — a regression that looks identical to a genuine outage.
+ */
+function normalizeMcpStatus(value: unknown): ObservedMcpStatus {
+  if (typeof value !== 'string') return 'unknown'
+  const status = value.trim().toLowerCase()
+  if (status === 'connected' || status === 'ready' || status === 'ok') return 'ready'
+  if (status === 'failed' || status === 'error') return 'failed'
+  // The vendor spells the OAuth-required state with a hyphen; the underscore form costs nothing
+  // to accept and is what a JSON-ish vocabulary tends to drift toward.
+  if (status === 'needs-auth' || status === 'needs_auth') return 'needs_auth'
+  // Everything else, INCLUDING the CLI's `pending`. A server still handshaking when the session
+  // was announced has no resolved state, which is exactly what `unknown` says, and `needs_auth` is
+  // the tempting wrong guess for it: the surface paints that one amber as "waiting for you to
+  // authorize it", sending an operator to re-issue a working credential for a server that was
+  // merely slow and came up a second later.
+  return 'unknown'
+}
+
+/**
+ * Read the claude-code CLI's startup report (`{"type":"system","subtype":"init"}`) into one
+ * {@link ObservedMcpServer} per server the CLI knows about.
+ *
+ * The CLI announces its resolved session ONCE, before the first model call: which MCP servers it
+ * loaded and with what status, and the flat list of tool names it will expose. Both halves are
+ * read here because neither answers the question alone — a `ready` server exposing no tools is as
+ * useless to the agent as a failed one, and a tool count with no status cannot say why.
+ *
+ * Returns `undefined` when the event names no servers at all, which keeps "this run wired none"
+ * and "this image observed none" from collapsing into an empty list on the backend's record.
+ * Pure, so the parsing is testable without a CLI: {@link runClaudeCode} feeds it the raw event.
+ */
+export function observeClaudeMcpInit(
+  event: Record<string, unknown>,
+): ObservedMcpServer[] | undefined {
+  if (event.type !== 'system' || event.subtype !== 'init') return undefined
+  const reported = event.mcp_servers
+  if (!Array.isArray(reported) || reported.length === 0) return undefined
+  const rows: { id: string; status: ObservedMcpStatus }[] = []
+  const declared = new Set<string>()
+  for (const entry of reported) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const record = entry as Record<string, unknown>
+    const id = sanitizeServerId(record.name)
+    // An id this image cannot hold is dropped rather than reported under a mangled name: the
+    // whole row is only useful if it JOINS the backend's declaration, and `--strict-mcp-config`
+    // means every server the CLI loaded came from the config this harness wrote.
+    if (!id || declared.has(id)) continue
+    declared.add(id)
+    rows.push({ id, status: normalizeMcpStatus(record.status) })
+  }
+  if (rows.length === 0) return undefined
+  // Counted from the CLI's own tool list rather than from a per-server field, because there is no
+  // per-server field: the CLI flattens every server's tools into one array namespaced by server
+  // id. A missing/non-array list leaves every count ABSENT rather than 0 (see `toolCount`).
+  const tally = tallyToolsByServer(event.tools, declared)
+  return rows.map((row) => ({
+    ...row,
+    ...(tally && !tally.ambiguous.has(row.id) ? { toolCount: tally.counts.get(row.id) ?? 0 } : {}),
+  }))
+}
+
+/** What {@link tallyToolsByServer} read out of the CLI's flat tool list. */
+interface ToolTally {
+  /** Tools attributed to each declared server. A server with none is simply absent from the map. */
+  counts: ReadonlyMap<string, number>
+  /**
+   * Servers whose count could not be established, because at least one tool name belongs to more
+   * than one of them. Their count is reported ABSENT rather than short.
+   */
+  ambiguous: ReadonlySet<string>
+}
+
+/**
+ * Tally the CLI's flat tool list (`mcp__<id>__<tool>`) against the servers the SAME event
+ * declared, or `undefined` when it carried no list, which is the distinction
+ * {@link ObservedMcpServer.toolCount} preserves.
+ *
+ * Matched against the declared ids rather than split on the first `__`, because the id vocabulary
+ * ({@link MCP_SERVER_ID_PATTERN}) permits an underscore: a server named `code__search` owns
+ * `mcp__code__search__query`, which a first-separator split files under a server called `code`,
+ * leaving the real one reporting `toolCount: 0`. That is the single most diagnostic value on the
+ * field, so the mis-split renders a fully healthy server as one that started and exposes nothing.
+ *
+ * The same underscore makes genuine ambiguity representable: with both `code` and `code__search`
+ * declared, `mcp__code__search__query` is a name either could own and nothing in the report says
+ * which. Neither server is counted then, and both are named `ambiguous` so their count stays
+ * absent. Guessing an owner would move a real tool onto the wrong server and take the other's
+ * count to a `0` that reads as a fault.
+ */
+function tallyToolsByServer(tools: unknown, declared: ReadonlySet<string>): ToolTally | undefined {
+  if (!Array.isArray(tools)) return undefined
+  const counts = new Map<string, number>()
+  const ambiguous = new Set<string>()
+  for (const tool of tools) {
+    if (typeof tool !== 'string' || !tool.startsWith('mcp__')) continue
+    const owners: string[] = []
+    for (const id of declared) {
+      const prefix = `mcp__${id}__`
+      // The tool name after the prefix must be non-empty: `mcp__slack__` names no tool.
+      if (tool.length > prefix.length && tool.startsWith(prefix)) owners.push(id)
+    }
+    const [owner] = owners
+    if (owners.length === 1 && owner) counts.set(owner, (counts.get(owner) ?? 0) + 1)
+    else for (const id of owners) ambiguous.add(id)
+  }
+  return { counts, ambiguous }
+}
+
 /**
  * The credential values carried by a run's tool servers, for {@link registerKnownSecrets}. An MCP
  * server that fails to start routinely echoes its own argv or request headers into stderr, and

package/src/agent-runner.ts

@@ -24,8 +24,10 @@ import {
   claudeAllowedToolPatterns,
   codexMcpConfigToml,
   mcpServerSecretValues,
+  observeClaudeMcpInit,
   writeClaudeMcpConfig,
   type McpServerSpec,
+  type ObservedMcpServer,
   type SkillSpec,
 } from './agent-capabilities.js'
 import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
@@ -149,6 +151,21 @@ export interface SubscriptionRunOptions {
    * same row still rides the result, so a lost poll response costs nothing.
    */
   onCallMetric?: (call: HarnessCallMetric) => void
+  /**
+   * Called once with what the CLI reported about the tool servers it loaded, the moment it
+   * announces its resolved session (see {@link observeClaudeMcpInit}).
+   *
+   * The one thing the backend's own dispatch record cannot answer: it knows why it WITHHELD a
+   * tool, and this says a server it wired failed to start anyway. Reported even when every server
+   * came up, because "observed, all healthy" and "this image observed nothing" are different
+   * facts about a run and only the first one clears a wired server of suspicion.
+   *
+   * Whole-value latest-wins, not a delta — the CLI announces its session once, so a second call
+   * would only ever be a re-announcement of the same set. A harness whose CLI reports nothing
+   * (codex today) never calls this, which is what leaves the backend's record honestly empty
+   * rather than claiming every server failed.
+   */
+  onToolServers?: (observed: ObservedMcpServer[]) => void
   /**
    * The per-job child logger (jobId/repo/branch correlation). Threaded so the retained
    * session-transcript path is logged for the run when the isolated config home is torn down.
@@ -501,6 +518,67 @@ async function setUpClaudeMcp(
   }
 }
 
+/**
+ * The LIVE publishers of a claude-code run: everything the stream has revealed so far that the
+ * backend should see before the run ends, rather than only in its terminal result.
+ *
+ * They are grouped because they share one rule and differ on everything else. The rule: each
+ * publishes a WHOLE current value (never a delta), so a dropped poll response costs nothing and
+ * the caller may fire them as often as it likes. What differs is what is at stake — progress is a
+ * disposable count the UI renders, while the slice reviews carry the slices' actual review WORK
+ * and are the only thing a resume of a wedged review can be rebuilt from, which is why they are
+ * published on the turn a slice lands rather than on the next progress tick.
+ *
+ * `lastTodo` is a GETTER because the event handler assigns it as the stream goes; taking the value
+ * would freeze the plan at construction time.
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function createClaudeLivePublishers(deps: {
+  opts: SubscriptionRunOptions
+  planTracker: ReturnType<typeof createTaskPlanTracker>
+  sliceTracker: ReturnType<typeof createSliceTracker>
+  lastTodo: () => TodoProgress | undefined
+}): { emitProgress: () => void; emitSliceReviews: () => void } {
+  const { opts, planTracker, sliceTracker } = deps
+  return {
+    emitProgress: () => {
+      if (!opts.onProgress) return
+      const progress = mergeProgress(
+        pickProgress(deps.lastTodo(), planTracker.progress()),
+        sliceTracker.progress(),
+      )
+      if (progress) opts.onProgress(progress)
+    },
+    emitSliceReviews: () => {
+      if (!opts.onSliceReviews) return
+      const reviews = sliceTracker.sliceReviews()
+      if (reviews.length > 0) opts.onSliceReviews(reviews)
+    },
+  }
+}
+
+/**
+ * Publish the CLI's own startup report about the tool servers it loaded — the OBSERVED half of the
+ * run's tool-server record.
+ *
+ * Handed every event because it is the one thing `runClaudeCode` reads that is neither a turn nor
+ * a result: it arrives once, ahead of the first model call, and says whether the servers the
+ * backend wired actually came up. {@link observeClaudeMcpInit} answers `undefined` for every other
+ * event and for a run that wired none, so a server-less run reports nothing and the caller's
+ * record stays honestly absent rather than empty.
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function reportToolServerStartup(
+  event: Record<string, unknown>,
+  onToolServers: ((observed: ObservedMcpServer[]) => void) | undefined,
+): void {
+  if (!onToolServers) return
+  const observed = observeClaudeMcpInit(event)
+  if (observed) onToolServers(observed)
+}
+
 /**
  * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
  * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
@@ -645,23 +723,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   const sliceTracker = createSliceTracker(secrets)
   const planTracker = createTaskPlanTracker()
   let lastTodo: TodoProgress | undefined
-  const emitProgress = (): void => {
-    if (!opts.onProgress) return
-    const progress = mergeProgress(
-      pickProgress(lastTodo, planTracker.progress()),
-      sliceTracker.progress(),
-    )
-    if (progress) opts.onProgress(progress)
-  }
-  // Publish the per-slice reviews the tracker has captured. Separate from `emitProgress` because
-  // the two answer different questions and have different lifetimes: progress is a disposable
-  // count the UI renders, while these carry the slices' actual review WORK and are persisted so a
-  // run that dies before its aggregation can be resumed from them.
-  const emitSliceReviews = (): void => {
-    if (!opts.onSliceReviews) return
-    const reviews = sliceTracker.sliceReviews()
-    if (reviews.length > 0) opts.onSliceReviews(reviews)
-  }
+  const { emitProgress, emitSliceReviews } = createClaudeLivePublishers({
+    opts,
+    planTracker,
+    sliceTracker,
+    lastTodo: () => lastTodo,
+  })
 
   // No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
   // absent on this path until now. Claude Code reports a tool CALL (its name) on the `assistant`
@@ -675,6 +742,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
 
   const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
+    reportToolServerStartup(event, opts.onToolServers)
     // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
     // `telemetry` routes them off the parent's chain (and decides who bills them). Progress, slice
     // tracking, the guard and `stats` below deliberately see EVERY event: a subagent grinding on

package/src/pi-workspace.ts

@@ -332,6 +332,11 @@ export async function runAgentInWorkspace(
       // land rather than only in the terminal output. Only the subscription runners fan work out
       // across subagents, so this is the only path that can produce it.
       onSliceReviews: opts.onSliceReviews,
+      // What the CLI reported about the tool servers it loaded. Wired for BOTH subscription
+      // harnesses even though only claude-code's stream carries the report today: the hook is a
+      // pass-through, and a codex run that never calls it leaves the backend's record honestly
+      // absent rather than claiming every server it wired failed to start.
+      onToolServers: opts.onToolServers,
       // Stream this run's per-call telemetry to the job's live drain. The subscription
       // harnesses are the only producers of `callMetrics` (Pi's calls are metered by the LLM
       // proxy as they happen), so this is the only path that needs the hook.

package/src/runner.ts

@@ -3,6 +3,7 @@ import type { FollowUpLine } from './follow-ups.js'
 import type { ValidationReport } from './validation-checks.js'
 import type { ReproductionReport } from './reproduction-proof.js'
 import type { SliceReview } from './subagents.js'
+import type { ObservedMcpServer } from './agent-capabilities.js'
 import type { HarnessCallMetric, TodoProgress, ToolSpan } from './pi.js'
 import { log, type Logger } from './logger.js'
 import {
@@ -56,6 +57,15 @@ export interface RunOptions {
    * already persisted. Absent for a job that dispatched no subagents.
    */
   onSliceReviews?: (reviews: SliceReview[]) => void
+  /**
+   * Receives what the agent's CLI reported about the tool servers (MCP) it loaded, once it
+   * announces its resolved session. Latest-wins (NOT a drain buffer) for the same reason as
+   * {@link onValidationReport}, with an extra one of its own: the CLI announces the set ONCE,
+   * near the start of the run, so a drain buffer would hand it to whichever poll happened to
+   * land next and lose it entirely if that poll response were dropped — on the single fact this
+   * whole channel exists to carry. Absent for a job that wired no tool servers.
+   */
+  onToolServers?: (observed: ObservedMcpServer[]) => void
   /**
    * Receives each per-call telemetry row the moment the agent's CLI stream yields it, so a
    * run's model calls reach `llm_call_metrics` WHILE it runs rather than only in its terminal
@@ -224,6 +234,18 @@ export interface JobView<TResult extends JobResultBase = JobResultBase> {
    * from. Absent for a job that dispatched no subagents.
    */
   sliceReviews?: SliceReview[]
+  /**
+   * What the agent's CLI reported about the tool servers (MCP) wired for this job when it started
+   * up: per server, the status the CLI gave it and how many tools it contributed. A whole-value
+   * latest publish like {@link validationReport}, not drain-on-read — the CLI announces this once
+   * and every later poll re-reports the same set, so no poll can be the one that loses it.
+   *
+   * The complement of what the BACKEND recorded at dispatch, and the only source for the half it
+   * cannot see: the dispatch record says why the platform withheld a tool, this says a wired
+   * server failed to start anyway. Absent for a job that wired none, and for a harness whose CLI
+   * reports nothing — which is why it is absent rather than empty (see `ObservedMcpServer`).
+   */
+  toolServers?: ObservedMcpServer[]
 }
 
 interface JobEntry<TResult extends JobResultBase> extends JobView<TResult> {
@@ -543,6 +565,9 @@ export class JobRegistry<TJob = unknown, TResult extends JobResultBase = JobResu
         onSliceReviews: (reviews) => {
           entry.sliceReviews = reviews
         },
+        onToolServers: (observed) => {
+          entry.toolServers = observed
+        },
         onReproductionProof: (report) => {
           entry.reproductionReport = report
         },