@cat-factory/executor-harness 1.96.0 → 1.100.0

package/dist/runner.d.ts

@@ -5,6 +5,7 @@ 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>;
@@ -16,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;
     /**
@@ -246,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);
                 },
@@ -338,6 +375,7 @@ export class JobRegistry {
             clearTimeout(inactivity);
             clearTimeout(cap);
             clearTimeout(coldStart);
+            toolSilence.stop();
             entry.abort = undefined;
             entry.heartbeatAt = Date.now();
         }
@@ -376,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.96.0",
+  "version": "1.100.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.264.0",
-    "@cat-factory/server": "0.244.0",
-    "@cat-factory/spend": "0.15.32"
+    "@cat-factory/kernel": "0.272.0",
+    "@cat-factory/server": "0.252.0",
+    "@cat-factory/spend": "0.15.40"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -382,19 +382,28 @@ export const MCP_TOOL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
  * reached the container by any other route is held to the rule too.
  */
 export function isAllowedMcpHttpUrl(raw: string): boolean {
-  const match = /^(https?):\/\/([^/?#]*)/i.exec(raw)
-  if (!match) return false
-  if (match[1]!.toLowerCase() === 'https') return true
-  // Plain http from here: the host must be loopback. Strip userinfo FIRST and from the LAST `@`,
-  // or `http://127.0.0.1@evil.example` reads as loopback while the request goes to evil.example.
-  const authority = match[2]!
-  const hostPort = authority.slice(authority.lastIndexOf('@') + 1)
-  const closingBracket = hostPort.indexOf(']')
-  const host = (
-    hostPort.startsWith('[') && closingBracket !== -1
-      ? hostPort.slice(1, closingBracket) // IPv6 literal, e.g. [::1]:8080
-      : (hostPort.split(':')[0] ?? '')
-  ).toLowerCase()
+  // ASCII control characters and the space are refused ANYWHERE rather than canonicalised: the
+  // WHATWG parser trims leading/trailing C0-and-space and removes tab, LF and CR from anywhere, so
+  // a url carrying one parses to something other than what it reads as, and this url is written
+  // VERBATIM into the CLI's MCP config below.
+  for (let i = 0; i < raw.length; i += 1) if (raw.charCodeAt(i) <= 0x20) return false
+  let parsed: URL
+  try {
+    parsed = new URL(raw)
+  } catch {
+    // silent-catch-ok: an unparseable url is exactly what this predicate refuses.
+    return false
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+  if (parsed.protocol === 'https:') return true
+  // Plain http from here: the host must be loopback. `new URL` rather than a hand-written parse
+  // because it is the parser the CLI resolves the request with, so the host ruled on is the host
+  // the credential header travels to. It strips userinfo from the LAST `@` (or
+  // `http://127.0.0.1@evil.example` reads as loopback while the request goes to evil.example), and
+  // it terminates the authority at a backslash as well as at `/?#` (or
+  // `http://evil.example\@127.0.0.1` reads as loopback the same way).
+  const hostname = parsed.hostname
+  const host = hostname.startsWith('[') ? hostname.slice(1, -1) : hostname
   return host === 'localhost' || host === '::1' || /^127\.\d+\.\d+\.\d+$/.test(host)
 }