@cat-factory/executor-harness 1.74.0 → 1.76.2

package/dist/dependency-install.js

@@ -0,0 +1,245 @@
+import { relative } from 'node:path';
+import { fencedOutput, runCapturedCommand } from './captured-command.js';
+import { excludePathsFromGit, listUntrackedPaths } from './git.js';
+import { loadRunnerLimits } from './runner.js';
+/**
+ * How much of a failed install's output the agent is shown. Smaller than the validation loop's
+ * repair budget (16k) on purpose: a repair prompt has to carry the whole failure because fixing
+ * it IS the task, whereas this note only has to let the agent decide whether to install
+ * something itself. The tail is where a package manager puts its actual error.
+ */
+export const DEPENDENCY_INSTALL_TAIL_CHARS = 4_000;
+/**
+ * The share of the JOB's whole wall-clock ceiling (`JOB_MAX_DURATION_MS`) the install may consume
+ * before the watchdog kills it. The install is SETUP: it runs before the agent's first turn, so
+ * every second it takes is a second the work itself does not get, and a wedged package manager
+ * that ran to a fixed 20-minute watchdog on a shortened job could leave the agent with almost
+ * nothing. A third leaves the run two thirds of its budget in the worst case.
+ */
+const DEPENDENCY_INSTALL_JOB_SHARE = 1 / 3;
+/**
+ * A floor under the DERIVED ceiling (never under an explicit override, which tests legitimately
+ * set to milliseconds): a drastically shortened job would otherwise compute a share so small that
+ * no install could ever finish inside it, turning every run's setup into a guaranteed timeout.
+ */
+const DEPENDENCY_INSTALL_CEILING_FLOOR_MS = 30_000;
+/** The default watchdog — the share above at the default 60-minute job ceiling. */
+const DEPENDENCY_INSTALL_TIMEOUT_DEFAULT_MS = 20 * 60_000;
+/**
+ * The per-install watchdog: the longest the install may run before it is killed and reported as
+ * failed. Generous (20 min at the defaults) because a cold monorepo install on a slow registry
+ * legitimately takes many minutes.
+ *
+ * DERIVED from the configured job ceiling rather than hardcoded against the default one, the same
+ * way `git.ts` derives its per-command timeout from the configured inactivity window: a constant
+ * sized against a default silently breaks its own invariant the moment an operator changes that
+ * default. An explicit `DEPENDENCY_INSTALL_TIMEOUT_MS` is honoured but still CLAMPED — the point
+ * of the share is that no configuration lets setup eat the run, and an override that could exceed
+ * the job's own ceiling would only ever be killed later by a watchdog that fails the whole job
+ * instead of degrading to a note.
+ */
+export function dependencyInstallTimeoutMs(env = process.env) {
+    const configured = Number(env.DEPENDENCY_INSTALL_TIMEOUT_MS);
+    const requested = Number.isFinite(configured) && configured > 0
+        ? Math.floor(configured)
+        : DEPENDENCY_INSTALL_TIMEOUT_DEFAULT_MS;
+    const ceiling = Math.max(DEPENDENCY_INSTALL_CEILING_FLOOR_MS, Math.floor(loadRunnerLimits(env).maxDurationMs * DEPENDENCY_INSTALL_JOB_SHARE));
+    return Math.min(requested, ceiling);
+}
+/**
+ * How often the install feeds the run's inactivity watchdog. Well under `JOB_INACTIVITY_MS`
+ * (default 10 min); matches the validation loop's and the frontend stand-up's heartbeat, which
+ * exist for exactly the same reason.
+ */
+export function dependencyInstallHeartbeatMs() {
+    const n = Number(process.env.DEPENDENCY_INSTALL_HEARTBEAT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 30_000;
+}
+/**
+ * Parse the optional DEPENDENCY INSTALL envelope off the job body. A missing/blank command
+ * returns `undefined`, so a malformed body degrades to the exact pre-feature behaviour (no
+ * install phase, the agent starts against the bare clone) rather than failing a good run.
+ *
+ * Lives with the feature rather than in `job.ts`, following the same rule the two pre-PR
+ * verification phases do: each phase owns its own job-body parser next to the code that consumes
+ * it, and `job.ts` stays the job SHAPE plus the generic assembly.
+ */
+export function parseDependencyInstallSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const raw = value.command;
+    const command = typeof raw === 'string' ? raw.trim() : '';
+    return command ? { command } : undefined;
+}
+/**
+ * Run the declared install against `cwd` and return what happened. Never throws and never fails
+ * the job: every failure shape ({@link runCapturedCommand} maps a timeout to 124, a spawn error
+ * to 127, an abort to 130) comes back as a non-zero outcome the caller turns into a prompt note.
+ *
+ * The output tail is kept ONLY for a failure. A successful install prints tens of thousands of
+ * uninteresting lines, and the agent needs to know that it succeeded, not what it resolved.
+ */
+export async function runDependencyInstall(args) {
+    const { cwd, spec, logger, opts } = args;
+    logger.info('dependencies: installing', { command: spec.command });
+    const heartbeat = setInterval(() => opts.onActivity?.(), dependencyInstallHeartbeatMs());
+    heartbeat.unref?.();
+    try {
+        const run = await runCapturedCommand({
+            cwd,
+            command: spec.command,
+            timeoutMs: dependencyInstallTimeoutMs(),
+            reportTailChars: DEPENDENCY_INSTALL_TAIL_CHARS,
+            logLabel: 'dependencies',
+            logger,
+            opts,
+        });
+        logger.info('dependencies: install finished', {
+            exitCode: run.exitCode,
+            durationMs: run.durationMs,
+        });
+        return {
+            command: spec.command,
+            exitCode: run.exitCode,
+            passed: run.passed,
+            ...(run.passed ? {} : run.outputTail ? { outputTail: run.outputTail } : {}),
+            durationMs: run.durationMs,
+            ...(run.timedOut ? { timedOut: true } : {}),
+        };
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+}
+/**
+ * THE entry point: run the phase for a mode that has a checkout, and hand back the note to fold
+ * into the agent's prompt (or `undefined` when the service declared no install, which is every
+ * dispatch today that never configured one).
+ *
+ * Everything a caller could get wrong lives here rather than at six call sites: the phase marker,
+ * the best-effort run, keeping the installed tree out of the agent's commits, and naming WHERE
+ * the install ran when that is not where the agent will be standing. A mode supplies only its
+ * three directories.
+ */
+export async function prepopulateDependencies(args) {
+    const { spec, installDir, repoDir, agentDir, logger, opts } = args;
+    if (!spec)
+        return undefined;
+    opts.onPhase?.('dependencies');
+    // Taken BEFORE the install and diffed after, so what gets excluded is what the install itself
+    // materialised — not whatever the checkout already carried.
+    const untrackedBefore = new Set(await snapshotUntracked(repoDir, opts.signal));
+    // Never rejects — every failure shape comes back as a non-zero outcome — so a caller needs no
+    // unwinding and the run continues either way. A FAILED install is snapshotted too: a partial
+    // tree is just as untracked as a complete one.
+    const outcome = await runDependencyInstall({ cwd: installDir, spec, logger, opts });
+    const untrackedAfter = await snapshotUntracked(repoDir, opts.signal);
+    const added = untrackedAfter.filter((path) => !untrackedBefore.has(path));
+    await excludeInstalledArtifacts(repoDir, added, logger, opts.signal);
+    return buildDependencyInstallNote(outcome, installScope(agentDir, installDir));
+}
+/**
+ * Fold the note into a prompt. Trivial, and deliberately not inlined: it is applied on EVERY
+ * agent pass — including the validation and reproduction REPAIR passes, which start a fresh
+ * agent that would otherwise never learn the tree is already installed and would spend a repair
+ * round reinstalling it.
+ */
+export function withDependencyNote(userPrompt, note) {
+    return note ? `${userPrompt}\n\n${note}` : userPrompt;
+}
+/**
+ * How the note names the checkout the install ran in: `undefined` when the agent will be standing
+ * in it (so it reads "this checkout"), otherwise the path from the agent's cwd. The multi-repo
+ * layout runs the agent at the workspace ROOT and a conflict resolution at the repo root, while
+ * the install belongs to a sibling checkout or a service subtree respectively — "this checkout"
+ * in either case points the agent at a directory with no dependency tree of its own.
+ *
+ * Separators are normalised because the note is prose an agent reads, and the local NATIVE
+ * transport runs this on the developer's own Windows host.
+ */
+function installScope(agentDir, installDir) {
+    const rel = relative(agentDir, installDir).replaceAll('\\', '/');
+    return rel === '' ? undefined : rel;
+}
+/**
+ * Keep whatever the install materialised out of the agent's commits.
+ *
+ * A dependency tree is untracked, and the agent's own `git add -A` does not know it did not put
+ * it there — nor does the conflict-resolution flow, which stages the whole tree to complete its
+ * merge commit. A repo that ships a `.gitignore` covering `node_modules` is fine without this;
+ * one that does not (a fresh service, a language whose convention is looser) would open a pull
+ * request containing tens of thousands of vendored files. So the paths the install ADDED are
+ * excluded locally, exactly as the harness already does for its own sentinel files.
+ *
+ * Only what the install added: a snapshot diff, never a list of well-known directory names. A
+ * name list is a guess that is both incomplete (every ecosystem has its own) and unsafe (it would
+ * exclude a `target/` directory the agent legitimately authored). Best-effort — a git hiccup here
+ * must not fail a run whose install succeeded — and the paths are LOGGED, since silently ignoring
+ * part of a checkout is exactly the kind of thing a later run's author needs to be able to see.
+ */
+async function excludeInstalledArtifacts(repoDir, paths, logger, signal) {
+    if (paths.length === 0)
+        return;
+    try {
+        await excludePathsFromGit(repoDir, paths, signal);
+        logger.info('dependencies: excluded installed artifacts from git', { paths });
+    }
+    catch (error) {
+        logger.warn('dependencies: could not exclude installed artifacts from git', {
+            paths,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * The checkout's untracked paths, or an empty list when they cannot be read.
+ *
+ * Best-effort by design: a directory that is not a git checkout (or a git that failed) must
+ * degrade to "nothing to exclude" rather than failing a phase whose whole disposition is that it
+ * never fails a run. Degrading on the BEFORE read is the safe direction too — an unreadable
+ * snapshot makes every post-install path look new, so the exclusion errs towards protecting the
+ * commit rather than towards letting a dependency tree into it. Directories are collapsed by
+ * {@link listUntrackedPaths}, so a `node_modules` of 40k files is one entry, not 40k.
+ */
+async function snapshotUntracked(repoDir, signal) {
+    return listUntrackedPaths(repoDir, signal).catch(() => []);
+}
+/**
+ * The note folded into the agent's prompt describing the checkout it is about to work in.
+ *
+ * Stated in BOTH directions on purpose. On success the agent is told the tree is ready, which is
+ * what stops it spending turns re-running an install that already ran (and, on a repo whose
+ * install is slow, spending most of its budget there). On failure it is told plainly what failed
+ * and that it may install what it needs itself — an agent that merely finds no `node_modules` and
+ * no explanation concludes the environment is offline and works around a gap that isn't there.
+ *
+ * `scope` names the checkout the install ran in and is set ONLY when that is not the agent's own
+ * working directory — the multi-repo layout runs the agent at the workspace root while the install
+ * belongs to the primary service's sibling directory. Saying "this checkout" there would point the
+ * agent at a root that has no dependency tree of its own.
+ */
+export function buildDependencyInstallNote(outcome, scope) {
+    const subject = scope ? `The \`${scope}/\` checkout's` : "This checkout's";
+    if (outcome.passed) {
+        return [
+            `${subject} dependencies have already been installed for you (\`${outcome.command}\`), so the`,
+            'installed packages are present on disk. Read them directly to confirm what a dependency',
+            'actually exposes rather than inferring its API from the manifest, and do NOT re-run the',
+            'install unless you change the dependency manifest.',
+        ].join('\n');
+    }
+    const reason = outcome.timedOut
+        ? `timed out after ${Math.round(outcome.durationMs / 1000)}s`
+        : `exited ${outcome.exitCode}`;
+    return [
+        `${subject} dependencies could NOT be installed for you: \`${outcome.command}\` ${reason}.`,
+        'The installed packages are therefore missing or incomplete. You have network access, so you',
+        'may install what you need yourself if it helps — but treat the failure below as a fact about',
+        'the environment, not as a defect to fix as part of this task, and do not change the project’s',
+        'dependency manifests to work around it.',
+        // Fenced so the captured output cannot be read as instructions — and fenced through the
+        // shared helper, because a package manager prints backticks often enough that a fixed
+        // three-tick fence would close mid-tail and spill the rest of this note's prose.
+        ...(outcome.outputTail ? ['', fencedOutput(outcome.outputTail)] : []),
+    ].join('\n');
+}

package/dist/git.js

@@ -424,6 +424,22 @@ export async function listUntrackedFiles(dir, signal) {
         .map((line) => line.replace(/\r$/, '').trim())
         .filter((path) => path !== '');
 }
+/**
+ * The untracked, non-ignored paths in the working tree with whole untracked DIRECTORIES
+ * collapsed to a single `dir/` entry (`--directory`), rather than every file beneath them.
+ *
+ * The sibling {@link listUntrackedFiles} answers "what did the agent forget to commit", where
+ * every individual file is the point. This one answers "what appeared in the tree", where it is
+ * emphatically not: a dependency install leaves tens of thousands of files under one directory,
+ * and enumerating them would cost a multi-megabyte listing to learn a single name.
+ */
+export async function listUntrackedPaths(dir, signal) {
+    const out = await git(['ls-files', '--others', '--exclude-standard', '--directory', '--no-empty-directory'], { cwd: dir, signal });
+    return out
+        .split('\n')
+        .map((line) => line.replace(/\r$/, '').trim())
+        .filter((path) => path !== '');
+}
 /**
  * Locally exclude `pattern` from this checkout via `.git/info/exclude` — a per-clone
  * ignore that never lands in the repo (unlike a `.gitignore`). Used for the harness's
@@ -441,6 +457,35 @@ export async function excludeFromGit(dir, pattern, signal) {
         void signal;
     }
 }
+/**
+ * Locally exclude LITERAL paths — never patterns — from this checkout, in ONE write.
+ *
+ * The sibling {@link excludeFromGit} takes an author-written pattern for a known sentinel. These
+ * paths instead come from the FILESYSTEM (what a dependency install left behind), so two things
+ * differ. Each is escaped, because a directory named `pkg[1]` read as a gitignore character class
+ * excludes something else entirely and, being a no-op on the real path, fails silently. And they
+ * are appended together, because a per-path append would cost one file write per entry to build
+ * a list that is already known in full.
+ *
+ * Anchored: `ls-files` reports repo-root-relative paths and a gitignore pattern containing a
+ * slash is root-anchored, which is what makes `packages/api/node_modules/` exclude that service's
+ * tree and not a same-named directory elsewhere. Best-effort, exactly like its sibling.
+ */
+export async function excludePathsFromGit(dir, paths, signal) {
+    if (paths.length === 0)
+        return;
+    // Escape every gitignore metacharacter, plus a leading `#` (comment) or `!` (negation) which
+    // are only special in that position.
+    const escaped = paths.map((p) => p.replace(/[[\]*?\\]/g, '\\$&').replace(/^([#!])/, '\\$1'));
+    try {
+        const excludePath = join(dir, '.git', 'info', 'exclude');
+        await appendFile(excludePath, `\n${escaped.join('\n')}\n`, 'utf8');
+    }
+    catch {
+        // A missing .git/info/exclude (worktree layout) or write error is non-fatal.
+        void signal;
+    }
+}
 /** Whether the branch advanced past `baseSha` via commits (the agent's own + any safety-net commit). */
 export async function branchHasCommitsSince(dir, baseSha, signal) {
     return (await headCommit(dir, signal)) !== baseSha;

package/dist/job.js

@@ -1,5 +1,6 @@
 import { parseValidationChecksSpec, } from './validation-checks.js';
 import { parseReproductionSpec, } from './reproduction-proof.js';
+import { parseDependencyInstallSpec } from './dependency-install.js';
 import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 function str(value, path) {
     if (typeof value !== 'string' || value.length === 0) {
@@ -611,6 +612,7 @@ export function parseAgentJob(input) {
         validation: parseValidationSpec(o.validation),
         validationChecks: parseValidationChecksSpec(o.validationChecks),
         reproduction: parseReproductionSpec(o.reproduction),
+        dependencyInstall: parseDependencyInstallSpec(o.dependencyInstall),
         reviewPrNumber: posInt(o.reviewPrNumber),
     });
     assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
@@ -667,7 +669,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -697,6 +699,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(validation ? { validation } : {}),
         ...(validationChecks ? { validationChecks } : {}),
         ...(reproduction ? { reproduction } : {}),
+        ...(dependencyInstall ? { dependencyInstall } : {}),
     };
 }
 /**

package/dist/process-exit.js

@@ -0,0 +1,18 @@
+// A deliberate COPY of kernel's `describeProcessExit` (`shared/process-exit.logic.ts`). The
+// container image is built from `src/` plus typescript alone, so the harness can carry no runtime
+// dependency on a workspace package — the same constraint that forces `src/host-markdown.ts` to be
+// a copy. `test/process-exit.conformity.test.ts` pins the two to identical output, so change one
+// and you must change the other.
+//
+// Kernel's module carries the rationale in full; the short version is that a `null` exit code
+// means a SIGNAL killed the process, and telling that apart from the process's own non-zero exit
+// is the first fork in the road when diagnosing a dead agent run.
+/**
+ * How a child process ended: its own exit code, or the signal that killed it.
+ *
+ * @example describeProcessExit(1, null)          // 'exited with code 1'
+ * @example describeProcessExit(null, 'SIGKILL')  // 'killed by SIGKILL'
+ */
+export function describeProcessExit(code, signal) {
+    return code === null ? `killed by ${signal ?? 'signal'}` : `exited with code ${code}`;
+}

package/dist/runner.js

@@ -171,15 +171,20 @@ export class JobRegistry {
             killReason ??= 'max-duration';
             controller.abort(new Error('max duration exceeded'));
         }, this.limits.maxDurationMs);
+        // When the run was last heard from — the agent's own output, or a synthetic keep-alive beat
+        // from an activity-silent phase (see `silenceClause`, which is careful not to claim more than
+        // that). Unset until the first of either, which is both the cold-start watchdog's "has it
+        // 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;
         // 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
         // that). Cleared the moment the first activity arrives.
-        let sawActivity = false;
         let coldStart;
         if (this.limits.coldStartMs > 0) {
             coldStart = setTimeout(() => {
-                if (sawActivity)
+                if (lastActivityAt !== undefined)
                     return;
                 const secs = Math.round(this.limits.coldStartMs / 1000);
                 const message = `agent produced no output ${secs}s after start; possible onboarding/auth wedge (phase: ${phase})`;
@@ -188,11 +193,10 @@ export class JobRegistry {
             }, this.limits.coldStartMs);
         }
         const heartbeat = () => {
-            if (!sawActivity) {
-                sawActivity = true;
+            if (lastActivityAt === undefined)
                 clearTimeout(coldStart);
-            }
-            entry.heartbeatAt = Date.now();
+            lastActivityAt = Date.now();
+            entry.heartbeatAt = lastActivityAt;
             resetInactivity();
         };
         resetInactivity();
@@ -255,7 +259,16 @@ export class JobRegistry {
             // breadcrumb names where it hung (markPhase below would otherwise overwrite it).
             const failedInPhase = phase;
             markPhase('failed');
-            const { message, cause, detail } = this.describeFailure(killReason, error, failedInPhase, lastTool, phaseTimingsMs);
+            const { message, cause, detail } = this.describeFailure({
+                killReason,
+                error,
+                phase: failedInPhase,
+                lastTool,
+                phaseTimingsMs,
+                lastActivityAt,
+                startedAt: entry.startedAt,
+                coldStart: entry.coldStart,
+            });
             entry.state = 'failed';
             entry.error = message;
             entry.failureCause = cause;
@@ -283,38 +296,93 @@ export class JobRegistry {
      * breadcrumb of where they hung, no longer a regex-stable phrase; a thrown error keeps its own
      * message and its structured cause when tagged (a git op → `git`, an upstream API call → `api`),
      * else `agent`. All strings are credential-scrubbed.
+     *
+     * `detail` is where the evidence the harness already holds but the one-line `error` has no room
+     * for lands: the phase breakdown, the {@link failureBreadcrumb} (last completed tool + how long
+     * the run had been silent), and the cold-start diagnostic when that watchdog recorded one. It is
+     * the only one of the three that reaches the run's failure record, so a diagnostic that isn't
+     * folded in here is effectively invisible outside the container log.
      */
-    describeFailure(killReason, error, phase, lastTool, phaseTimingsMs) {
-        // `lastTool` is the last tool that COMPLETED (a span is emitted on tool end), so when the
-        // hang is inside a still-running tool the breadcrumb points at the prior one — worded
-        // "last completed tool" so the reader knows the stuck call may be the next, unfinished one.
-        const breadcrumb = lastTool
-            ? `last completed tool ${lastTool.name} ${Math.round((Date.now() - lastTool.at) / 1000)}s ago`
-            : 'no tool had completed yet';
-        const phaseBreakdown = Object.entries(phaseTimingsMs)
+    describeFailure(ctx) {
+        const breadcrumb = failureBreadcrumb(ctx);
+        const phaseBreakdown = Object.entries(ctx.phaseTimingsMs)
             .map(([p, ms]) => `${p}=${Math.round(ms / 1000)}s`)
             .join(', ');
-        if (killReason === 'inactivity') {
+        const cold = ctx.coldStart ? ` Cold start: ${ctx.coldStart.message}.` : '';
+        if (ctx.killReason === 'inactivity') {
             return {
-                message: redactSecrets(`${inactivityAbortMessage(this.limits.inactivityMs)} (likely hung in ${phase} phase; ${breadcrumb})`),
+                message: redactSecrets(`${inactivityAbortMessage(this.limits.inactivityMs)} (likely hung in ${ctx.phase} phase; ${breadcrumb})`),
                 cause: 'inactivity-timeout',
-                detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.`),
+                detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.${cold}`),
             };
         }
-        if (killReason === 'max-duration') {
+        if (ctx.killReason === 'max-duration') {
             return {
                 message: redactSecrets(maxDurationAbortMessage(this.limits.maxDurationMs)),
                 cause: 'max-duration',
-                detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.`),
+                detail: redactSecrets(`Phase timings: ${phaseBreakdown || '(none)'}. ${breadcrumb}.${cold}`),
             };
         }
-        const raw = error instanceof Error ? error.message : String(error);
+        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.
         return {
             message: redactSecrets(raw),
-            cause: failureCauseOf(error) ?? 'agent',
-            detail: redactSecrets(`${phaseBreakdown ? `Phase timings: ${phaseBreakdown}. ` : ''}Failed in ${phase} phase; ${breadcrumb}.`),
+            cause: failureCauseOf(ctx.error) ?? 'agent',
+            detail: redactSecrets(`${phaseBreakdown ? `Phase timings: ${phaseBreakdown}. ` : ''}Failed in ${ctx.phase} phase; ${breadcrumb}.${cold}`),
         };
     }
 }
+/**
+ * How long a run must have been quiet before the breadcrumb calls it out. Well above a slow
+ * model turn or a long tool call, so this fires on a genuine stall rather than on normal
+ * think time.
+ */
+const SILENCE_BREADCRUMB_MS = 30_000;
+/**
+ * Where the job was, and how quiet it had gone, when it failed.
+ *
+ * The silence half matters because the exit status alone cannot distinguish a crash from a
+ * stall: an agent CLI that gives up on a failing upstream request exits NON-ZERO with nothing
+ * on stderr, which reads exactly like a crash — while its phase timing (minutes) and its
+ * silence (all of them) say "it never got an answer". Omitted when the run was producing
+ * output right up to the failure (the common case, where it is noise), and for an inactivity
+ * kill, whose own message already states the window it waited out.
+ */
+function failureBreadcrumb(ctx) {
+    const now = Date.now();
+    // `lastTool` is the last tool that COMPLETED (a span is emitted on tool end), so when the
+    // hang is inside a still-running tool the breadcrumb points at the prior one — worded
+    // "last completed tool" so the reader knows the stuck call may be the next, unfinished one.
+    const tool = ctx.lastTool
+        ? `last completed tool ${ctx.lastTool.name} ${Math.round((now - ctx.lastTool.at) / 1000)}s ago`
+        : 'no tool had completed yet';
+    return [tool, silenceClause(ctx, now)].filter(Boolean).join(', ');
+}
+/**
+ * The silence half of {@link failureBreadcrumb}; empty when silence isn't part of the story —
+ * which includes the fast failures (a missing env var, a git auth rejection) where the run was
+ * never going to have spoken yet and saying so would be pure noise.
+ *
+ * What it measures is the ACTIVITY channel, which carries the agent's own output plus the
+ * synthetic keep-alive beats the activity-silent phases feed the inactivity watchdog (dependency
+ * install, pre-PR validation, the reproduction proof, the frontend stand-up). So the wording
+ * claims no more than the channel supports — "no activity", not "no agent output": a run whose
+ * install phase beat every 30s and then died has been heard from, even though the agent itself
+ * never spoke. The window's origin is the job start, so it spans the `starting`/`clone` phases
+ * too; the phase breakdown sits beside it in the same `detail` for the reader who needs the
+ * split.
+ *
+ * Making this say "the AGENT last spoke" specifically would mean separating real output from
+ * liveness beats at the {@link RunOptions} seam, which is a change to what the cold-start and
+ * inactivity watchdogs fire on — deliberately not folded into this diagnostic-only fix.
+ */
+function silenceClause(ctx, now) {
+    if (ctx.killReason === 'inactivity')
+        return '';
+    const silentMs = now - (ctx.lastActivityAt ?? ctx.startedAt);
+    if (silentMs < SILENCE_BREADCRUMB_MS)
+        return '';
+    const secs = Math.round(silentMs / 1000);
+    return ctx.lastActivityAt === undefined ? `no activity at all in ${secs}s` : `silent for ${secs}s`;
+}

package/dist/validation-checks.js

@@ -1,4 +1,4 @@
-import { runCapturedCommand } from './captured-command.js';
+import { fencedOutput, runCapturedCommand } from './captured-command.js';
 /**
  * The ceiling the harness clamps a body-supplied `validationChecks.maxAttempts` to, and the
  * default it applies when the body omits one.
@@ -171,7 +171,11 @@ untrackedFiles = []) {
         const reason = o.timedOut
             ? `timed out after ${Math.round((o.durationMs ?? 0) / 1000)}s`
             : `exited ${o.exitCode}`;
-        return `### ${o.label} — ${reason}\n\n\`\`\`\n$ ${o.command}\n${body}\n\`\`\``;
+        // Fenced through the shared helper: a failing lint or test routinely prints backticks
+        // (a rule quoting a template literal, a fixture echoing a fenced snippet), and a fixed
+        // three-tick fence closes on the first such run — spilling the rest of the failure, and
+        // the repair INSTRUCTIONS below it, into what the model reads as prose.
+        return `### ${o.label} — ${reason}\n\n${fencedOutput(`$ ${o.command}\n${body}`)}`;
     })
         .join('\n\n');
     const remaining = report.maxAttempts - report.attempts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.74.0",
+  "version": "1.76.2",
   "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",
@@ -26,15 +26,16 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.185.1",
-    "@cat-factory/server": "0.172.2",
-    "@cat-factory/spend": "0.12.115"
+    "@cat-factory/kernel": "0.188.0",
+    "@cat-factory/server": "0.175.0",
+    "@cat-factory/spend": "0.12.118"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "start": "node dist/server.js",
     "test": "vitest run",
+    "test:run": "vitest run",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "image:publish": "bash scripts/publish-image.sh"
   }