@cat-factory/executor-harness 1.94.0 → 1.98.0

package/dist/runner.d.ts

@@ -2,8 +2,10 @@ 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 ToolProgressWindow } from './tool-silence.js';
 import { type FailureCause } from './failure.js';
 /** Non-secret correlation fields a job carries on every log line (jobId, repo, branch, …). */
 type LogFields = Record<string, unknown>;
@@ -15,6 +17,22 @@ export interface RunOptions {
     onProgress?: (progress: TodoProgress) => void;
     /** Receives one compact {@link ToolSpan} per completed tool call (observability). */
     onSpan?: (span: ToolSpan) => void;
+    /**
+     * Opens the tool-silence window (stuck-run audit F13) for ONE agent stream, returning the
+     * handle that stream beats on every completed tool call and closes when it ends.
+     *
+     * Called by the agent-CLI runners themselves rather than by the phase marker, because the
+     * window is only meaningful while something able to RESET it is running and only the runner
+     * knows whether its CLI reports completed tool calls at all. A caller that runs no tool loop
+     * (the inline one-shot completion) simply does not forward this, which is a statement, not an
+     * omission: the run stays bounded by the inactivity and max-duration watchdogs, and a window
+     * nothing could ever beat would only be able to expire.
+     *
+     * Absent ⇒ no window is opened and this watchdog is silent for that work. It fails toward NOT
+     * killing on purpose: this audit exists as much to stop recovery machinery ending healthy runs
+     * as to bound wedged ones, and the wall-clock cap is underneath either way.
+     */
+    beginToolWindow?: () => ToolProgressWindow;
     /** Receives the forward-looking follow-up / question items the Coder streamed since the last poll. */
     onFollowUp?: (items: FollowUpLine[]) => void;
     /**
@@ -40,6 +58,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 +235,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 {
@@ -224,6 +263,20 @@ export interface RunnerLimits {
      * progress, which counts as activity). Set to 0 to disable.
      */
     coldStartMs: number;
+    /**
+     * Stuck-run audit F13: force-fail the job if a running agent stream completes no tool call for
+     * this long. The gap the other two watchdogs structurally cannot see — a model that keeps
+     * talking (or thinking out loud) resets the inactivity timer on every chunk while completing
+     * nothing, so the only remaining bound was the full wall-clock cap and the engine's
+     * ~70-minute poll budget behind it.
+     *
+     * Armed only for as long as a stream that REPORTS completed tool calls is running (see
+     * {@link RunOptions.beginToolWindow}), so the activity-silent stretches — clone, dependency
+     * install, push, a validation loop's check commands — are outside it by construction: they
+     * legitimately complete no tool calls, and they are bounded by their own per-command timeouts.
+     * Set to 0 to disable.
+     */
+    toolSilenceMs: number;
 }
 export declare function loadRunnerLimits(env?: NodeJS.ProcessEnv): RunnerLimits;
 /**

package/dist/runner.js

@@ -1,6 +1,7 @@
 import { redactSecrets } from './redact.js';
 import { log } from './logger.js';
-import { failureCauseOf, inactivityAbortMessage, maxDurationAbortMessage, } from './failure.js';
+import { ToolSilenceWatchdog } from './tool-silence.js';
+import { failureCauseOf, inactivityAbortMessage, maxDurationAbortMessage, toolSilenceAbortMessage, } from './failure.js';
 function intEnv(value, fallback) {
     const n = value ? Number(value) : NaN;
     return Number.isFinite(n) && n > 0 ? n : fallback;
@@ -13,22 +14,43 @@ function intEnvAllowZero(value, fallback) {
     return Number.isFinite(n) && n >= 0 ? n : fallback;
 }
 export function loadRunnerLimits(env = process.env) {
+    const maxDurationMs = intEnv(env.JOB_MAX_DURATION_MS, 60 * 60_000);
+    const inactivityMs = intEnv(env.JOB_INACTIVITY_MS, 10 * 60_000);
     return {
         // 60 minutes: generous headroom for serious multi-file coding tasks while
         // still bounding a runaway container.
-        maxDurationMs: intEnv(env.JOB_MAX_DURATION_MS, 60 * 60_000),
+        maxDurationMs,
         // 10 minutes of zero output is treated as hung (a single long LLM/tool call
         // is far shorter; Pi streams events as it works). The per-git command ceiling
         // (`GIT_TIMEOUT_MS` in git.ts) is DERIVED from this value — a fixed margin below
         // it — so a slow clone/push (which emits no activity events) always times out
         // with git's own clear reason rather than this watchdog's "likely hung" message,
         // for any configured window. See the invariant note in git.ts.
-        inactivityMs: intEnv(env.JOB_INACTIVITY_MS, 10 * 60_000),
+        inactivityMs,
         // 2 minutes: comfortably longer than a warm agent's time-to-first-token yet far
         // under the 10-minute inactivity kill, so a truly output-less start is flagged early.
         coldStartMs: intEnvAllowZero(env.JOB_COLD_START_MS, 2 * 60_000),
+        toolSilenceMs: intEnvAllowZero(env.JOB_TOOL_SILENCE_MS, toolSilenceDefault(maxDurationMs, inactivityMs)),
     };
 }
+/**
+ * The tool-silence window when the operator has not set one: HALF the configured wall-clock cap,
+ * DERIVED rather than a constant so lowering `JOB_MAX_DURATION_MS` tightens it too (a fixed
+ * 30 minutes would sit past the whole budget of a deployment that runs 20-minute jobs, i.e. be
+ * silently disabled).
+ *
+ * Floored at the inactivity window so the default never races the gone-quiet diagnostic more
+ * often than it has to. The floor is a sizing choice, NOT the thing that keeps the two watchdogs
+ * apart: they anchor on different events (the last completed tool call vs the last byte of
+ * output), so the tool-silence anchor is always the earlier of the two and equal windows would
+ * still have it firing first. What actually keeps this watchdog off a hang is the expiry test in
+ * {@link ToolSilenceWatchdog}, which fires only when output arrived DURING the window that
+ * elapsed — and which also holds for an operator who sets `JOB_TOOL_SILENCE_MS` below
+ * `JOB_INACTIVITY_MS`, where no default-side clamp applies at all.
+ */
+function toolSilenceDefault(maxDurationMs, inactivityMs) {
+    return Math.max(Math.round(maxDurationMs / 2), inactivityMs);
+}
 function toView(entry) {
     const { promise: _promise, spanBuffer: _spanBuffer, followUpBuffer: _followUpBuffer, callMetricBuffer: _callMetricBuffer, callMetricSeq: _callMetricSeq, abort: _abort, ...view } = entry;
     return { ...view };
@@ -224,6 +246,20 @@ export class JobRegistry {
         // spoken yet" test and, on a failure, the difference between a run that died mid-work and one
         // that never got going at all.
         let lastActivityAt;
+        // Stuck-run audit F13: the third watchdog, and the only one that can see a model which keeps
+        // TALKING while completing nothing — its output resets the inactivity timer on every chunk,
+        // and it is nowhere near the wall-clock cap. It is armed by the agent stream itself rather
+        // than by the phase marker (see `RunOptions.beginToolWindow`) and reads `lastActivityAt` at
+        // expiry, which is what keeps the gone-quiet case with the inactivity watchdog that owns it.
+        const toolSilence = new ToolSilenceWatchdog({
+            windowMs: this.limits.toolSilenceMs,
+            lastActivityAt: () => lastActivityAt,
+            onExpired: () => {
+                // First watchdog to fire wins the reason (see `resetInactivity` above).
+                killReason ??= 'no-tool-progress';
+                controller.abort(new Error('no tool progress'));
+            },
+        });
         // ADR 0026 D4: a one-shot cold-start watchdog. If the job produces no activity within
         // `coldStartMs`, record a structured diagnostic (a likely onboarding/auth wedge) so it
         // is legible early — it does NOT abort the run (the inactivity watchdog still owns
@@ -261,6 +297,7 @@ export class JobRegistry {
                     entry.spanBuffer.push(span);
                     lastTool = { name: span.tool, at: span.endedAt };
                 },
+                beginToolWindow: () => toolSilence.open(),
                 onFollowUp: (items) => {
                     entry.followUpBuffer.push(...items);
                 },
@@ -270,6 +307,9 @@ export class JobRegistry {
                 onSliceReviews: (reviews) => {
                     entry.sliceReviews = reviews;
                 },
+                onToolServers: (observed) => {
+                    entry.toolServers = observed;
+                },
                 onReproductionProof: (report) => {
                     entry.reproductionReport = report;
                 },
@@ -335,6 +375,7 @@ export class JobRegistry {
             clearTimeout(inactivity);
             clearTimeout(cap);
             clearTimeout(coldStart);
+            toolSilence.stop();
             entry.abort = undefined;
             entry.heartbeatAt = Date.now();
         }
@@ -373,6 +414,15 @@ export class JobRegistry {
                 detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.${cold}`),
             };
         }
+        if (ctx.killReason === 'no-tool-progress') {
+            return {
+                // The breadcrumb carries the last completed tool, which is the whole diagnostic here:
+                // it names what the agent was doing when it stopped doing anything.
+                message: redactSecrets(`${toolSilenceAbortMessage(this.limits.toolSilenceMs)} (${breadcrumb})`),
+                cause: 'no-tool-progress',
+                detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.${cold}`),
+            };
+        }
         const raw = ctx.error instanceof Error ? ctx.error.message : String(ctx.error);
         // A thrown error tagged with a structured cause (a git op / an upstream API call) keeps
         // it; an untagged throw is a generic agent failure.

package/dist/structured-output.js

@@ -1,6 +1,7 @@
 import { redact, redactSecrets, secretsToRedact } from './redact.js';
 import { log } from './logger.js';
-import { PI_MAX_OUTPUT_TOKENS, phasedProxyBaseUrl } from './pi.js';
+import { phasedProxyBaseUrl } from './pi.js';
+import { PI_MAX_OUTPUT_TOKENS } from './pi-reduction.js';
 // A reusable abstraction for the "agent returns a structured JSON document as its
 // final assistant message" pattern (requirements, blueprint, merger — and any future
 // kind). An agent of this kind emits its result as text, not a tool call, and the

package/dist/tool-silence.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The live window for ONE tool-reporting agent stream. Opened by the stream, beaten by each
+ * completed tool call, closed when the stream ends (cleanly or not) — so the window can never
+ * outlive the only thing able to reset it.
+ */
+export interface ToolProgressWindow {
+    /** A tool call completed: the only evidence this watchdog accepts as progress. */
+    toolCompleted(): void;
+    /** The stream ended; the window closes with it. Idempotent. */
+    close(): void;
+}
+/**
+ * A window that measures nothing: what the watchdog hands out when disabled, and what a producer
+ * substitutes when its caller wired no watchdog at all. Having one means every producer holds a
+ * real window and states its tool progress unconditionally, rather than guarding each call site
+ * with a `?.` that reads as though beating the window were optional.
+ */
+export declare const NO_TOOL_WINDOW: ToolProgressWindow;
+export interface ToolSilenceDeps {
+    /** The window length. `<= 0` disables the watchdog entirely (every window is inert). */
+    windowMs: number;
+    /**
+     * When the run last produced ANY output, or undefined if it never has — the same clock the
+     * inactivity watchdog resets on. Read at EXPIRY (see {@link ToolSilenceWatchdog.open}), which
+     * is what keeps this watchdog off the gone-quiet case.
+     */
+    lastActivityAt: () => number | undefined;
+    /** Called when a window expires with the run demonstrably still talking. */
+    onExpired: () => void;
+}
+/**
+ * Hands out {@link ToolProgressWindow}s and fires `onExpired` for one that goes a full window
+ * without a completed tool call while the run keeps producing output.
+ *
+ * ONE window is open at a time (a job runs one agent stream at a time, and a repair loop runs
+ * them in sequence). Opening a second supersedes the first, and a superseded handle's calls are
+ * ignored rather than reaching back into the live window — a stale `close()` from a stream that
+ * finished after its successor started would otherwise disarm the watchdog for the rest of the job.
+ */
+export declare class ToolSilenceWatchdog {
+    private readonly deps;
+    private timer;
+    /** Identity of the window currently open; every handout takes the next number. */
+    private openId;
+    /** When the live window was last armed — the start of the span `onExpired` is a verdict about. */
+    private armedAt;
+    constructor(deps: ToolSilenceDeps);
+    /** Open a window for one agent stream. Returns an inert handle when the watchdog is disabled. */
+    open(): ToolProgressWindow;
+    /** Disarm for good (the job settled). Safe to call with no window open. */
+    stop(): void;
+    private arm;
+    /**
+     * A window elapsed with no completed tool call. Fire ONLY if the run was talking through it.
+     *
+     * `no-tool-progress` claims something specific — output arrived, but nothing got done — and
+     * that is only a truthful reading when output actually arrived DURING the window that just
+     * expired. A window that passed in total silence is the INACTIVITY watchdog's fact, whose
+     * diagnostic ("the container went quiet") is the one an operator can act on; relabelling it as
+     * a rabbit-hole would send them looking at the model instead of at the hang.
+     *
+     * This is a structural guard, not a tie-breaker: the two timers anchor on different events (the
+     * last tool call vs the last byte of output), so no arithmetic between the two window LENGTHS
+     * can order them. Equal windows put the tool-silence anchor strictly earlier — it fires first —
+     * and an operator setting `JOB_TOOL_SILENCE_MS` below `JOB_INACTIVITY_MS` gets that on every
+     * quiet run. Deciding from what the expired window actually SAW is independent of both numbers.
+     *
+     * A deferred window re-arms rather than standing down, so a run that goes quiet and then
+     * resumes its monologue is still caught, one full window later. The deferral terminates:
+     * either output resumes (the next expiry has output in its window and fires) or it does not
+     * (inactivity fires).
+     */
+    private expire;
+}

package/dist/tool-silence.js

@@ -0,0 +1,99 @@
+// The tool-silence watchdog (stuck-run audit F13): the third bound on a job, and the only one
+// that can see a model which keeps TALKING while completing nothing. Its output resets the
+// inactivity timer on every chunk, and it is nowhere near the wall-clock cap.
+//
+// WHY THIS IS ITS OWN MODULE — the window is only meaningful while something that REPORTS
+// completed tool calls is running, and only that producer knows whether it does. Keying the
+// window on the job's coarse phase label instead looked equivalent and was not: `agent` is a
+// telemetry breadcrumb several call sites mark for several different things (a Codex pass, a
+// tool-less inline completion, the label restored around a repair loop's shell commands), so a
+// phase-armed window spent most of its time armed over work that could not possibly reset it.
+// The producer opens its own window instead, which makes "armed" and "can beat" the same fact by
+// construction rather than by two call sites agreeing.
+/**
+ * A window that measures nothing: what the watchdog hands out when disabled, and what a producer
+ * substitutes when its caller wired no watchdog at all. Having one means every producer holds a
+ * real window and states its tool progress unconditionally, rather than guarding each call site
+ * with a `?.` that reads as though beating the window were optional.
+ */
+export const NO_TOOL_WINDOW = { toolCompleted: () => { }, close: () => { } };
+/**
+ * Hands out {@link ToolProgressWindow}s and fires `onExpired` for one that goes a full window
+ * without a completed tool call while the run keeps producing output.
+ *
+ * ONE window is open at a time (a job runs one agent stream at a time, and a repair loop runs
+ * them in sequence). Opening a second supersedes the first, and a superseded handle's calls are
+ * ignored rather than reaching back into the live window — a stale `close()` from a stream that
+ * finished after its successor started would otherwise disarm the watchdog for the rest of the job.
+ */
+export class ToolSilenceWatchdog {
+    deps;
+    timer;
+    /** Identity of the window currently open; every handout takes the next number. */
+    openId = 0;
+    /** When the live window was last armed — the start of the span `onExpired` is a verdict about. */
+    armedAt = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Open a window for one agent stream. Returns an inert handle when the watchdog is disabled. */
+    open() {
+        if (this.deps.windowMs <= 0)
+            return NO_TOOL_WINDOW;
+        const id = ++this.openId;
+        this.arm();
+        const live = () => this.openId === id;
+        return {
+            toolCompleted: () => {
+                if (live())
+                    this.arm();
+            },
+            close: () => {
+                if (!live())
+                    return;
+                // Retire the id as well as the timer, so a late `toolCompleted()` from this stream
+                // cannot re-arm a window whose producer has already gone.
+                this.openId++;
+                this.stop();
+            },
+        };
+    }
+    /** Disarm for good (the job settled). Safe to call with no window open. */
+    stop() {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    arm() {
+        clearTimeout(this.timer);
+        this.armedAt = Date.now();
+        this.timer = setTimeout(() => this.expire(), this.deps.windowMs);
+    }
+    /**
+     * A window elapsed with no completed tool call. Fire ONLY if the run was talking through it.
+     *
+     * `no-tool-progress` claims something specific — output arrived, but nothing got done — and
+     * that is only a truthful reading when output actually arrived DURING the window that just
+     * expired. A window that passed in total silence is the INACTIVITY watchdog's fact, whose
+     * diagnostic ("the container went quiet") is the one an operator can act on; relabelling it as
+     * a rabbit-hole would send them looking at the model instead of at the hang.
+     *
+     * This is a structural guard, not a tie-breaker: the two timers anchor on different events (the
+     * last tool call vs the last byte of output), so no arithmetic between the two window LENGTHS
+     * can order them. Equal windows put the tool-silence anchor strictly earlier — it fires first —
+     * and an operator setting `JOB_TOOL_SILENCE_MS` below `JOB_INACTIVITY_MS` gets that on every
+     * quiet run. Deciding from what the expired window actually SAW is independent of both numbers.
+     *
+     * A deferred window re-arms rather than standing down, so a run that goes quiet and then
+     * resumes its monologue is still caught, one full window later. The deferral terminates:
+     * either output resumes (the next expiry has output in its window and fires) or it does not
+     * (inactivity fires).
+     */
+    expire() {
+        const lastActivityAt = this.deps.lastActivityAt();
+        if (lastActivityAt === undefined || lastActivityAt <= this.armedAt) {
+            this.arm();
+            return;
+        }
+        this.deps.onExpired();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.94.0",
+  "version": "1.98.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.267.0",
+    "@cat-factory/server": "0.247.0",
+    "@cat-factory/spend": "0.15.35"
   },
   "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