@cat-factory/executor-harness 1.72.0 → 1.76.0

package/README.md

@@ -63,21 +63,30 @@ The implementation job (`POST /run`) is the canonical sequence:
    stays distinguishable from the first pass's in telemetry; without that flag the plain path is
    used and the calls are recorded as unattributed
    (see [token-burn instrumentation](../../../docs/initiatives/token-burn-instrumentation.md)),
-3. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
-4. **validate** the checkout, when the job body carries `validationChecks` — the service's
+3. **prepopulate dependencies**, when the job body carries `dependencyInstall` — the
+   service's install command is run with `sh -c` in the checkout BEFORE the agent starts, so
+   it reads real installed packages instead of inferring a library's capabilities from a
+   manifest entry. Best-effort and never a gate: the outcome (success or the captured
+   failure) is folded into the agent's prompt — on EVERY pass, including the repair passes of
+   steps 5 and 6, which start a fresh agent — and the run continues either way. Whatever the
+   install materialises is excluded from git first, so no later `git add -A` can sweep a
+   dependency tree into the pull request (see
+   [dependency prepopulation](../../../docs/initiatives/agent-dependency-prepopulation.md)),
+4. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
+5. **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)),
-5. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
+6. **prove the reproduction**, when the job body carries `reproduction` — the declared check is
    run against the pre-fix tree and the tree the PR will open from, in two freshly-created
    symmetric `git worktree` checkouts, and only red-then-green is reported as proof (see
    [bugfix reproduction proof](../../../docs/initiatives/bugfix-reproduction-proof.md)). Unlike
-   step 4 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 4 so validation stays the last
+   step 5 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 5 so validation stays the last
    thing to touch the tree,
-6. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
-   ONLY if step 4 ended green. A spent budget returns an error result with the validation report
-   and opens no PR. Absent `validationChecks` / `reproduction`, steps 4 and 5 do not happen at
+7. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }` — but
+   ONLY if step 5 ended green. A spent budget returns an error result with the validation report
+   and opens no PR. Absent `validationChecks` / `reproduction`, steps 5 and 6 do not happen at
    all. The PR's description prefers the agent-authored reviewer briefing over the generic
    dispatch-time text the job body carries: a PR-opening agent is prompted to write one to the
    `.cat-pr-description.md` sentinel at the checkout root (one per sibling repo in a multi-repo
@@ -186,6 +195,7 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`) — talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
+| `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls — it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort — every failure shape becomes a note, never a failed job. Generic — keyed off the job body, never the agent kind. |
 | `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic — keyed off the job body, never the agent kind. |
 | `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic — keyed off the job body, never the agent kind. |
 | `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries — the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers) — with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
@@ -203,6 +213,9 @@ runner):
 | `PORT`                | `8080`          | HTTP port the harness listens on.                           |
 | `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
 | `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
+| `JOB_COLD_START_MS`   | `120000` (2m)   | First-output window (ADR 0026 D4). A job that has produced nothing this long records a cold-start diagnostic — a likely onboarding/auth wedge — WITHOUT being killed: logged, exposed on `GET /jobs/{id}`, and folded into the failure `detail` if the job goes on to fail. `0` disables it. |
+| `DEPENDENCY_INSTALL_TIMEOUT_MS` | a third of `JOB_MAX_DURATION_MS` (20m at its default) | Watchdog for the pre-agent dependency install; a timeout is reported as a failed install (exit 124), never a failed job. Derived from the job ceiling rather than fixed, and an explicit value is clamped by the same share — the agent is what waits on this, so setup can never consume the run it is preparing for. |
+| `DEPENDENCY_INSTALL_HEARTBEAT_MS` | `30000` (30s) | How often the dependency install feeds the job inactivity watchdog. A cold install is activity-silent and `JOB_INACTIVITY_MS` is tighter than its own watchdog, so without this a healthy install aborts the run as "likely hung". |
 | `VALIDATION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a pre-PR validation check; a timeout counts as a failure (exit 124) so one hung command can't wedge the loop. |
 | `REPRODUCTION_COMMAND_TIMEOUT_MS` | `900000` (15m) | Per-command watchdog for a reproduction-proof setup or check command; a timeout counts as a failure (exit 124). |
 | `REPRODUCTION_HEARTBEAT_MS` | `30000` (30s) | How often the reproduction proof feeds the job inactivity watchdog while it runs commands the agent is not producing output for. |

package/dist/agent-runner.js

@@ -8,6 +8,7 @@ import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { ProgressGuard } from './progress-guard.js';
 import { killChildProcess, spawnDetached } from './process.js';
+import { describeProcessExit } from './process-exit.js';
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js';
 import { createSliceTracker, startSubagentWatcher } from './subagents.js';
 import { createTaskPlanTracker, mergeProgress, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
@@ -112,7 +113,7 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
             opts.signal?.removeEventListener('abort', onAbort);
             reject(err);
         });
-        child.on('close', (code) => {
+        child.on('close', (code, signal) => {
             opts.signal?.removeEventListener('abort', onAbort);
             const stderrTail = redact(stderr, secrets).slice(-700);
             if (lineBuffer.trim())
@@ -125,13 +126,95 @@ function streamCli(cli, prompt, opts, env, secrets, onEvent) {
                 return;
             }
             if (code !== 0) {
-                reject(new Error(`${command} exited with code ${code}: ${stderrTail}`));
+                reject(new CliExitFailure({ command, exitCode: code, signal, stderrTail }));
                 return;
             }
             resolve({ stderrTail });
         });
     });
 }
+/**
+ * A CLI subprocess that ended badly — it exited non-zero, or a signal killed it.
+ *
+ * Its own class (rather than a formatted string) because the message is not final at throw time:
+ * the caller folds in the CLI's terminal report before it surfaces (see {@link withAgentReport}),
+ * and rebuilding from parts beats patching a rendered sentence. Distinct from the watchdog-abort
+ * rejection above, which owns its own diagnostic and must keep it.
+ */
+class CliExitFailure extends Error {
+    parts;
+    /**
+     * Also exposed flat, matching the watchdog-abort rejection's shape: the guard-trip branch
+     * reads `stderrTail` off whatever it caught to append to its own replacement message.
+     */
+    stderrTail;
+    constructor(parts, report = '') {
+        super(cliExitMessage(parts, report));
+        this.name = 'CliExitFailure';
+        this.parts = parts;
+        this.stderrTail = parts.stderrTail;
+    }
+}
+/**
+ * One message shape for a CLI that ended badly, with or without a report to add.
+ *
+ * How it ended is rendered through {@link describeProcessExit}, the shared vocabulary every
+ * process-reporting transport uses, so an externally-killed container job (an OOM kill, a
+ * `docker stop` racing teardown) reads differently from the CLI's own failure exit.
+ */
+function cliExitMessage(exit, report) {
+    const how = describeProcessExit(exit.exitCode, exit.signal);
+    const suffix = report ? ` Agent's last report: ${report}` : '';
+    return `${exit.command} ${how}: ${exit.stderrTail || '(no stderr output)'}${suffix}`;
+}
+/**
+ * Re-throw a bad CLI exit with the CLI's own account of how the run ended folded in.
+ *
+ * Both agent CLIs report a terminal failure on STDOUT, inside their event stream (Claude Code's
+ * `result` event, Codex's last agent message) — never on stderr. So a run the upstream API kept
+ * refusing exits non-zero with an EMPTY stderr tail, and the harness surfaces `claude exited with
+ * code 1:` and nothing else, while the reason it collected sits in a local variable only the
+ * SUCCESS path returns. That failure is indistinguishable from a crash, and the operator has no
+ * next step. Nothing else in the run records it: the CLI's session transcript dies with the
+ * per-run config home, and a local-mode container is removed the moment the job settles.
+ *
+ * Anything that is not a bad-exit rejection passes through untouched — a watchdog abort and a
+ * tripped progress guard carry more specific diagnostics already.
+ */
+function withAgentReport(err, report, secrets) {
+    if (!(err instanceof CliExitFailure))
+        return err;
+    const folded = capReport(redact(report, secrets).trim());
+    return folded ? new CliExitFailure(err.parts, folded) : err;
+}
+/** How much of the agent's terminal report the failure message carries. */
+const MAX_AGENT_REPORT_CHARS = 700;
+/**
+ * Bound the agent's terminal report, keeping its HEAD — the opposite bias from the stderr tail
+ * beside it, and deliberately so. A stderr tail is a log: the cause is whatever it ended on. A
+ * report is a written statement, and its opening is where the answer lives — the failure
+ * `subtype` {@link claudeResultReport} prepends, or the first line of Codex's last agent message.
+ * Tail-slicing it drops exactly the classification the fold exists to surface.
+ *
+ * A cut is marked, because a report that merely stops reads like an agent that trailed off.
+ */
+function capReport(report) {
+    if (report.length <= MAX_AGENT_REPORT_CHARS)
+        return report;
+    return `${report.slice(0, MAX_AGENT_REPORT_CHARS)}… (report truncated)`;
+}
+/**
+ * The CLI's own account of how the run ended, read off its terminal `result` event: the failure
+ * `subtype` it names (`error_during_execution`, `error_max_turns`, …) joined to whatever text it
+ * printed. A headless `-p` run reports an upstream API refusal HERE — on stdout, as JSON — and
+ * nowhere else, so this is what a bad exit has to carry. A clean result yields just its text.
+ */
+function claudeResultReport(event) {
+    const subtype = typeof event.subtype === 'string' ? event.subtype : '';
+    const text = typeof event.result === 'string' ? event.result.trim() : '';
+    const failed = event.is_error === true || (subtype !== '' && subtype !== 'success');
+    return failed ? [subtype || 'error', text].filter(Boolean).join(': ') : text;
+}
 /**
  * Fold a composed system prompt into the task prompt so the role + best-practice context
  * rides stdin as a single user turn. Used by the Codex runner (no system-prompt flag) and
@@ -246,6 +329,8 @@ async function setUpClaudeMcp(servers, configHome) {
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
+    /** The CLI's own account of how the run ended — see {@link claudeResultReport}. */
+    let terminalReport = '';
     let usage;
     // Decide how the composed system prompt is carried up front, so the telemetry seed below
     // reflects what actually reaches the model: a small prompt rides `--append-system-prompt`
@@ -397,49 +482,11 @@ export async function runClaudeCode(opts) {
             if (typeof event.result === 'string')
                 summary = event.result;
             usage = claudeUsage(event.usage) ?? usage;
+            terminalReport = claudeResultReport(event) || terminalReport;
         }
     };
-    // Native (ambient) mode: run the developer's installed `claude` with its OWN login —
-    // no isolated config home, no injected credential, no onboarding pre-seed. Otherwise,
-    // Claude Code persists user config/credentials under its config dir; point that at an
-    // isolated, per-run temp dir OUTSIDE the cloned checkout (`opts.cwd`). Otherwise the
-    // agents that finish with `git add -A` (blueprint/requirements/bootstrap) could stage a
-    // stray `.claude/` directory — and any cached credential in it — into the pushed branch.
-    // Mirrors the Codex CODEX_HOME isolation below; removed in `finally`.
-    if (!opts.ambientAuth && !opts.subscriptionToken) {
-        throw new Error('claude-code harness requires a subscription token (or ambientAuth)');
-    }
-    const configHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-claude-'));
-    // The config dir is brand-new every run, so Claude Code would otherwise treat this
-    // as a first launch and BLOCK on the interactive onboarding / "trust this folder" /
-    // bypass-permissions acknowledgement prompts — which never get answered headlessly,
-    // hanging the job until the watchdog kills it. Pre-seed the config that marks those
-    // as already accepted so `-p` starts straight into the run. Best-effort: written
-    // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
-    // (Ambient mode skips this — the developer's own config is already onboarded.)
-    // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
-    // version, so a future first-run gate this set doesn't cover (which looks identical to
-    // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
-    if (configHome) {
-        await writeOnboardingPreseed(configHome);
-        await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
-    }
-    // Skills: install each as a native skill under the config dir's `skills/<name>/` so the CLI
-    // discovers and can invoke it. ONLY into the isolated per-run config home — never the
-    // developer's own `~/.claude` (ambient/native mode), where it would persist in their personal
-    // setup after the run and two concurrent jobs carrying same-named skills would clobber each
-    // other. An ambient run reads the skills from the checkout instead (`.cat-context/skill/<name>/`,
-    // materialised by the caller). Best-effort: a write failure must not wedge the run — the prompt
-    // still names the skills.
-    if (configHome) {
-        for (const skill of opts.skills ?? []) {
-            await writeNativeSkill(join(configHome, 'skills'), skill).catch(() => { });
-        }
-    }
-    // Tool servers (MCP): the CLI is pointed at a per-run config rather than discovering an ambient
-    // one. See `setUpClaudeMcp` for why that matters and what has to be cleaned up afterwards.
-    const mcp = await setUpClaudeMcp(opts.mcpServers, configHome);
-    const env = buildClaudeEnv(opts, configHome);
+    const home = await openClaudeRunHome(opts);
+    const { configHome } = home;
     // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
     // subagent `*.jsonl` transcripts so a parallel-subagent review keeps the inactivity
     // heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible token spend is
@@ -478,10 +525,10 @@ export async function runClaudeCode(opts) {
                 'bypassPermissions',
                 '--model',
                 opts.model,
-                ...mcp.args,
+                ...home.mcpArgs,
                 ...appendArgs,
             ],
-        }, prompt, { ...opts, signal: runSignal }, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        }, prompt, { ...opts, signal: runSignal }, home.env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
         // The stream has ended, so the last call has no successor envelope to complete it.
         telemetry.flush();
         return await assembleClaudeOutcome({
@@ -504,20 +551,80 @@ export async function runClaudeCode(opts) {
         telemetry.flush();
         publisher.flush();
         // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
-        // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail
-        // it attached, since that is usually the only evidence of what the CLI was doing when it was
-        // killed. Byte-for-byte the shape `runPi` fails with.
+        // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail it
+        // attached, since that is usually the only evidence of what the CLI was doing when it was
+        // killed. The leading clauses are byte-for-byte the shape `runPi` fails with; a terminal
+        // report is appended after them when the CLI managed to emit one before it was killed, which
+        // is uncommon but is the same evidence a bad exit now carries — a guard trip is no reason to
+        // discard it.
         if (guardReason) {
             const tail = err?.stderrTail;
-            throw new Error(tail ? `${guardReason} Agent stderr: ${tail}` : guardReason);
+            const report = capReport(redact(terminalReport, secrets).trim());
+            throw new Error([
+                guardReason,
+                tail ? `Agent stderr: ${tail}` : '',
+                report ? `Agent's last report: ${report}` : '',
+            ]
+                .filter(Boolean)
+                .join(' '));
         }
-        throw err;
+        throw withAgentReport(err, terminalReport, secrets);
     }
     finally {
         await subagents?.stop();
-        // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
-        await mcp.cleanup();
-        if (configHome) {
+        await home.dispose();
+    }
+}
+async function openClaudeRunHome(opts) {
+    // Native (ambient) mode: run the developer's installed `claude` with its OWN login —
+    // no isolated config home, no injected credential, no onboarding pre-seed. Otherwise,
+    // Claude Code persists user config/credentials under its config dir; point that at an
+    // isolated, per-run temp dir OUTSIDE the cloned checkout (`opts.cwd`). Otherwise the
+    // agents that finish with `git add -A` (blueprint/requirements/bootstrap) could stage a
+    // stray `.claude/` directory — and any cached credential in it — into the pushed branch.
+    // Mirrors the Codex CODEX_HOME isolation below; removed by `dispose`.
+    if (!opts.ambientAuth && !opts.subscriptionToken) {
+        throw new Error('claude-code harness requires a subscription token (or ambientAuth)');
+    }
+    const configHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-claude-'));
+    // The config dir is brand-new every run, so Claude Code would otherwise treat this
+    // as a first launch and BLOCK on the interactive onboarding / "trust this folder" /
+    // bypass-permissions acknowledgement prompts — which never get answered headlessly,
+    // hanging the job until the watchdog kills it. Pre-seed the config that marks those
+    // as already accepted so `-p` starts straight into the run. Best-effort: written
+    // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
+    // (Ambient mode skips this — the developer's own config is already onboarded.)
+    // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
+    // version, so a future first-run gate this set doesn't cover (which looks identical to
+    // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
+    if (configHome) {
+        await writeOnboardingPreseed(configHome);
+        await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log);
+    }
+    // Skills: install each as a native skill under the config dir's `skills/<name>/` so the CLI
+    // discovers and can invoke it. ONLY into the isolated per-run config home — never the
+    // developer's own `~/.claude` (ambient/native mode), where it would persist in their personal
+    // setup after the run and two concurrent jobs carrying same-named skills would clobber each
+    // other. An ambient run reads the skills from the checkout instead (`.cat-context/skill/<name>/`,
+    // materialised by the caller). Best-effort: a write failure must not wedge the run — the prompt
+    // still names the skills.
+    if (configHome) {
+        for (const skill of opts.skills ?? []) {
+            await writeNativeSkill(join(configHome, 'skills'), skill).catch(() => { });
+        }
+    }
+    // Tool servers (MCP): the CLI is pointed at a per-run config rather than discovering an ambient
+    // one. See `setUpClaudeMcp` for why that matters and what has to be cleaned up afterwards.
+    const mcp = await setUpClaudeMcp(opts.mcpServers, configHome);
+    return {
+        configHome,
+        mcpArgs: mcp.args,
+        env: buildClaudeEnv(opts, configHome),
+        dispose: async () => {
+            // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
+            await mcp.cleanup();
+            if (!configHome)
+                return;
             // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
             // home is deleted — the credential lives at the home root, never in `projects/`, so this
             // keeps the debugging artifact without leaking the token. Best-effort; never throws.
@@ -527,8 +634,8 @@ export async function runClaudeCode(opts) {
             });
             // Never leave the config dir (and any cached credential) on disk past the run.
             await rm(configHome, { recursive: true, force: true }).catch(() => { });
-        }
-    }
+        },
+    };
 }
 /**
  * Build the child-process env for the `claude` CLI: an isolated config home plus subscription
@@ -770,6 +877,11 @@ export async function runCodex(opts) {
             ...(calls.length ? { callMetrics: calls } : {}),
         };
     }
+    catch (err) {
+        // Codex surfaces its terminal failure the same way Claude Code does — in the stdout event
+        // stream, not on stderr — so a bad exit carries the last thing the agent said.
+        throw withAgentReport(err, summary, secrets);
+    }
     finally {
         if (codexHome) {
             // Lift the CLI session transcripts (`sessions/`) out for short-lived retention BEFORE the

package/dist/agent.js

@@ -11,6 +11,7 @@ import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
+import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';
 import { runBootstrap } from './bootstrap-mode.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
@@ -451,6 +452,24 @@ async function runExploreMode(job, opts) {
             });
             logger.info('agent(explore): PR head fetch', { number: job.reviewPrNumber, fetched });
         }
+        // DEPENDENCY PREPOPULATION, before the agent's first turn. An EXPLORE run is the case this
+        // exists for: a reviewer or architect reading a fresh clone can see that a library is
+        // depended upon but not what it actually exposes, so it reasons about the manifest instead
+        // of the code. Best-effort — the outcome is stated in the prompt either way and never fails
+        // the run. Runs in `workDir` so a monorepo service installs from its own subtree.
+        //
+        // BEFORE the stand-up below, deliberately. The frontend stand-up runs the service's own
+        // install and then SERVES what it built: installing after it would pay for a second install
+        // and, worse, rewrite the `node_modules` the running app resolves out of. Prepopulation is
+        // setup for everything that follows, so it goes first.
+        const dependencyNote = await prepopulateDependencies({
+            spec: job.dependencyInstall,
+            installDir: workDir,
+            repoDir: dir,
+            agentDir: workDir,
+            logger,
+            opts,
+        });
         // Optional infra stand-up (the tester): bring the service's docker-compose
         // dependencies up at the repo root for the duration of the run, tearing them down in
         // the `finally`. A stand-up failure is non-fatal — it's surfaced to the agent as a
@@ -463,9 +482,7 @@ async function runExploreMode(job, opts) {
         // failure) is flagged as a concern; a frontend serve URL points the UI tester at the
         // app it just built + served (the backend env resolution already reached the harness).
         const infraNotes = managed ? buildInfraNotes(managed) : [];
-        const userPrompt = infraNotes.length
-            ? `${job.userPrompt}\n\nNote: ${infraNotes.join(' ')}`
-            : job.userPrompt;
+        const userPrompt = withDependencyNote(infraNotes.length ? `${job.userPrompt}\n\nNote: ${infraNotes.join(' ')}` : job.userPrompt, dependencyNote);
         // The stand-up record (success or failure, with its captured logs) rides back on EVERY
         // result branch — the backend surfaces it on the Tester step regardless of whether the
         // agent then produced a usable report.
@@ -668,12 +685,32 @@ async function runMultiRepoExplore(job, opts) {
                 });
             }
         }
+        // DEPENDENCY PREPOPULATION for the PRIMARY leg. The install is declared on ONE service frame
+        // (the primary repo's), so it is run in that leg's checkout — never fanned out across the
+        // peers, whose services declare their own configs the dispatch never resolved. The agent runs
+        // at the workspace ROOT and reads across every sibling, which is exactly why this matters
+        // here: a cross-repo investigator reasoning about a manifest instead of the packages is the
+        // complaint that motivated the feature. Same treatment as the reference branches above.
+        //
+        // The note names the sibling directory rather than saying "this checkout": the agent's cwd is
+        // the workspace root, which has no dependency tree of its own.
+        const primaryLeg = legs[0];
+        const dependencyNote = primaryLeg
+            ? await prepopulateDependencies({
+                spec: job.dependencyInstall,
+                installDir: join(root, primaryLeg.dirName),
+                repoDir: join(root, primaryLeg.dirName),
+                agentDir: root,
+                logger,
+                opts,
+            })
+            : undefined;
         opts.onPhase?.('agent');
         logger.info('multi-repo-explore: running agent', { repos: legs.map((l) => l.dirName) });
         const run = await runAgentInWorkspace({
             dir: root,
             systemPrompt: job.systemPrompt,
-            userPrompt: job.userPrompt,
+            userPrompt: withDependencyNote(job.userPrompt, dependencyNote),
             model: job.model,
             harness: job.harness,
             subscriptionToken: job.subscriptionToken,
@@ -814,6 +851,10 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
         // (see docs/initiatives/bugfix-reproduction-proof.md). Forwarded straight off the job body —
         // like the checks above, the loop is generic machinery keyed on the data, not the agent kind.
         ...(job.reproduction ? { reproduction: job.reproduction } : {}),
+        // Dependency prepopulation: the service's install, run against the checkout BEFORE the
+        // agent's first turn (see docs/initiatives/agent-dependency-prepopulation.md). Forwarded
+        // straight off the job body like the two phases above — generic machinery keyed on the data.
+        ...(job.dependencyInstall ? { dependencyInstall: job.dependencyInstall } : {}),
     };
 }
 /**
@@ -1022,10 +1063,27 @@ async function runConflictResolution(job, opts) {
         // there were conflicts), so it would drift onto the original feature task. Lead with the
         // conflict; keep the task only as trailing reference.
         const conflicted = await unmergedPaths(dir, signal);
+        // DEPENDENCY PREPOPULATION, before this mode's agent turn. Resolving a conflict is a READING
+        // task before it is a writing one — the agent has to understand what both sides do — so it
+        // needs the dependency tree as much as any other kind. Placed AFTER the clean-merge branches
+        // above so a conflict-free run (the common case) never pays for an install it has no agent to
+        // hand the tree to; and the artifact exclusion inside matters here more than anywhere, because
+        // this flow finishes its merge commit with a whole-tree `git add -A`.
+        const workDir = await deriveWorkDir(dir, job.repo.serviceDirectory);
+        const dependencyNote = await prepopulateDependencies({
+            spec: job.dependencyInstall,
+            installDir: workDir,
+            repoDir: dir,
+            // The agent resolves at the repo ROOT (git's conflict state is repo-wide), so a monorepo
+            // service's install ran somewhere the agent is not standing and the note has to say where.
+            agentDir: dir,
+            logger,
+            opts,
+        });
         opts.onPhase?.('agent');
         logger.info('agent(conflict): resolving conflicts with agent', { conflicted });
         const diff = await conflictDiff(dir, conflicted, signal);
-        const userPrompt = buildConflictPrompt(mergeBase, job.branch, conflicted, diff, job.userPrompt);
+        const userPrompt = withDependencyNote(buildConflictPrompt(mergeBase, job.branch, conflicted, diff, job.userPrompt), dependencyNote);
         const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             dir,
             systemPrompt: job.systemPrompt,

package/dist/captured-command.js

@@ -103,6 +103,22 @@ export async function runCapturedCommand(args) {
         child.on('close', (code) => finish(code ?? 1));
     });
 }
+/**
+ * Wrap captured command output in a fenced block that the output itself cannot break out of.
+ *
+ * Every consumer of a captured tail embeds it in markdown a MODEL then reads — a repair prompt,
+ * the dependency-install note — and a package manager legitimately prints backticks (a linter
+ * quoting a template literal, a test echoing a fenced snippet from a fixture). A fixed three-tick
+ * fence closes on the first such run, and everything after it reads as prose: the remaining
+ * output, and worse, the INSTRUCTIONS that follow the block. Sizing the fence one tick longer than
+ * the longest run in the body is what CommonMark specifies for exactly this, so the block always
+ * spans the whole tail.
+ */
+export function fencedOutput(text) {
+    const longestRun = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return `${fence}\n${text}\n${fence}`;
+}
 /** Bound an already-scrubbed output tail to what a REPORT carries, saying what it dropped. */
 export function boundTail(scrubbed, maxChars) {
     if (scrubbed.length <= maxChars)

package/dist/coding-agent.js

@@ -10,6 +10,7 @@ import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorksp
 import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
 import { runReproductionLoop, } from './reproduction-proof.js';
+import { prepopulateDependencies, withDependencyNote, } from './dependency-install.js';
 /**
  * How often the harness checkpoints the agent's work mid-run by pushing the branch.
  * A per-run container can be evicted at any moment; pushing the agent's commits
@@ -133,13 +134,32 @@ export async function runCodingAgent(spec, opts = {}) {
             }, followUpPollIntervalMs());
             followUpTick.unref?.();
         }
+        // DEPENDENCY PREPOPULATION: install the service's dependencies into the checkout BEFORE the
+        // agent's first turn, so it reads real packages instead of inferring capabilities from a
+        // manifest. Runs in `workDir` (a monorepo service installs from its own subtree, exactly
+        // where its manifest and lockfile live), and its outcome is STATED to the agent either way —
+        // a silent absence of dependencies reads to an agent as "this environment is offline".
+        // Best-effort by construction: a failed install never fails the run. Keyed purely off the
+        // job body (no agent-kind switch); absent ⇒ this is a no-op.
+        const dependencyNote = await prepopulateDependencies({
+            spec: spec.dependencyInstall,
+            installDir: workDir,
+            repoDir: dir,
+            agentDir: workDir,
+            logger,
+            opts,
+        });
         // One agent pass over this checkout, parameterised only by the prompt — so the pre-PR
         // validation loop below can re-run the agent with a repair instruction without
         // re-deriving (or drifting from) the dispatch's own settings.
+        //
+        // The dependency note rides EVERY pass, not just the first: a repair round starts a fresh
+        // agent, and one that is not told the tree is already installed spends the round it was
+        // given to fix something reinstalling it instead.
         const runAgentPass = (userPrompt) => runAgentInWorkspace({
             dir: workDir,
             systemPrompt: spec.systemPrompt,
-            userPrompt,
+            userPrompt: withDependencyNote(userPrompt, dependencyNote),
             model: spec.model,
             harness: spec.harness,
             subscriptionToken: spec.subscriptionToken,
@@ -702,6 +722,28 @@ export async function runMultiRepoCoding(job, opts = {}) {
         // Clone (or resume) every sibling checkout under the workspace root and fetch the primary's
         // reference branches. Mutates each leg's `dir`/`resumed`/`baseSha` in place.
         await prepareMultiRepoCheckouts(root, legs, job, logger, opts);
+        // DEPENDENCY PREPOPULATION for the PRIMARY leg, exactly as the read-only multi-repo fan-out
+        // does it. The install is declared on ONE service frame (the primary repo's), so it runs in
+        // that leg's checkout and is never fanned out across peers, whose own frames declare configs
+        // this dispatch never resolved — running a `pnpm install` inside a Go checkout is not a
+        // degraded outcome, it is a wrong one. A cross-repo implementer needs its dependencies for
+        // the same reason a cross-repo investigator does; the note names the sibling directory
+        // because the agent itself stands at the workspace root.
+        //
+        // At the leg's checkout ROOT, not a `serviceDirectory` subtree: this layout applies no
+        // service-directory scoping anywhere (the agent runs at the root and the prompt explains the
+        // sibling checkouts), and a root install is the one that resolves a monorepo workspace whole.
+        const primaryLeg = legs.find((leg) => leg.primary);
+        const dependencyNote = primaryLeg
+            ? await prepopulateDependencies({
+                spec: job.dependencyInstall,
+                installDir: primaryLeg.dir,
+                repoDir: primaryLeg.dir,
+                agentDir: root,
+                logger,
+                opts,
+            })
+            : undefined;
         // Run the agent ONCE with its cwd at the workspace root, so it sees every sibling checkout
         // and can change them coherently. No monorepo/service-directory scoping — the multi-repo
         // note + the backend system-prompt section explain the layout.
@@ -710,7 +752,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
         const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
             dir: root,
             systemPrompt: job.systemPrompt,
-            userPrompt: job.userPrompt,
+            userPrompt: withDependencyNote(job.userPrompt, dependencyNote),
             model: job.model,
             harness: job.harness,
             subscriptionToken: job.subscriptionToken,