@cat-factory/executor-harness 1.74.0 → 1.76.0

package/src/agent-runner.ts

@@ -24,6 +24,7 @@ import {
 } from './agent-capabilities.js'
 import { ProgressGuard, type ProgressGuardLimits } 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 {
@@ -246,7 +247,7 @@ function streamCli(
       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()) processLine(lineBuffer.trim(), true)
@@ -258,7 +259,7 @@ function streamCli(
         return
       }
       if (code !== 0) {
-        reject(new Error(`${command} exited with code ${code}: ${stderrTail}`))
+        reject(new CliExitFailure({ command, exitCode: code, signal, stderrTail }))
         return
       }
       resolve({ stderrTail })
@@ -266,6 +267,100 @@ function streamCli(
   })
 }
 
+/**
+ * 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 {
+  readonly parts: CliExit
+  /**
+   * 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.
+   */
+  readonly stderrTail: string
+  constructor(parts: CliExit, report = '') {
+    super(cliExitMessage(parts, report))
+    this.name = 'CliExitFailure'
+    this.parts = parts
+    this.stderrTail = parts.stderrTail
+  }
+}
+
+interface CliExit {
+  command: string
+  /** The exit code, or `null` when a signal killed the CLI instead. */
+  exitCode: number | null
+  signal: NodeJS.Signals | null
+  stderrTail: string
+}
+
+/**
+ * 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: CliExit, report: string): string {
+  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: unknown, report: string, secrets: string[]): unknown {
+  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: string): string {
+  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: Record<string, unknown>): string {
+  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
@@ -389,6 +484,8 @@ async function setUpClaudeMcp(
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
+  /** The CLI's own account of how the run ended — see {@link claudeResultReport}. */
+  let terminalReport = ''
   let usage: { inputTokens: number; outputTokens: number } | undefined
 
   // Decide how the composed system prompt is carried up front, so the telemetry seed below
@@ -537,54 +634,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     } else if (type === 'result') {
       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
@@ -627,13 +682,13 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           'bypassPermissions',
           '--model',
           opts.model,
-          ...mcp.args,
+          ...home.mcpArgs,
           ...appendArgs,
         ],
       },
       prompt,
       { ...opts, signal: runSignal },
-      env,
+      home.env,
       opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [],
       onEvent,
     )
@@ -659,19 +714,105 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     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 as { stderrTail?: string } | undefined)?.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()
+  }
+}
+
+/**
+ * The isolated, per-run home the `claude` CLI runs against: a temp config dir OUTSIDE the cloned
+ * checkout, pre-seeded past the first-launch prompts, carrying the run's native skills and MCP
+ * config, plus the child env pointing the CLI at it. {@link ClaudeRunHome.dispose} is the other
+ * half of the same concern — the leased credential must never outlive the run — so acquisition
+ * and teardown are defined together rather than split across a `finally` forty lines away.
+ *
+ * Ambient (native) mode has NO home: the developer's installed CLI uses its own `~/.claude`
+ * login, so nothing is created, nothing is pre-seeded, and `dispose` only clears the MCP config.
+ */
+interface ClaudeRunHome {
+  /** The per-run config dir; `undefined` in ambient mode (the developer's own login is used). */
+  configHome: string | undefined
+  /** The CLI argv selecting the run's tool servers; empty when it has none. */
+  mcpArgs: string[]
+  /** The child-process env (see {@link buildClaudeEnv}). */
+  env: Record<string, string>
+  dispose: () => Promise<void>
+}
+
+async function openClaudeRunHome(opts: SubscriptionRunOptions): Promise<ClaudeRunHome> {
+  // 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.
@@ -681,7 +822,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       })
       // Never leave the config dir (and any cached credential) on disk past the run.
       await rm(configHome, { recursive: true, force: true }).catch(() => {})
-    }
+    },
   }
 }
 
@@ -975,6 +1116,10 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
       ...(usage ? { usage } : {}),
       ...(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/src/agent.ts

@@ -36,6 +36,7 @@ import {
   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 {
@@ -541,6 +542,25 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
         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
@@ -553,9 +573,10 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
       // 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.
@@ -809,13 +830,34 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
       }
     }
 
+    // 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,
@@ -972,6 +1014,10 @@ function buildSingleRepoCodingSpec(
     // (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 } : {}),
   }
 }
 
@@ -1204,10 +1250,32 @@ async function runConflictResolution(job: AgentJob, opts: RunOptions): Promise<A
     // 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(

package/src/captured-command.ts

@@ -136,6 +136,23 @@ export async function runCapturedCommand(args: {
   })
 }
 
+/**
+ * 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: string): string {
+  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: string, maxChars: number): string {
   if (scrubbed.length <= maxChars) return scrubbed

package/src/coding-agent.ts

@@ -58,6 +58,11 @@ import {
   type ReproductionReport,
   type ReproductionSpec,
 } from './reproduction-proof.js'
+import {
+  prepopulateDependencies,
+  withDependencyNote,
+  type DependencyInstallSpec,
+} from './dependency-install.js'
 
 // The shared skeleton for the container coding agents that clone a repo, run Pi
 // against it and push the result on a branch. The implementation (`/run`) and
@@ -130,6 +135,13 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * `docs/initiatives/pre-pr-validation.md`.
    */
   validationChecks?: ValidationChecksSpec
+  /**
+   * DEPENDENCY PREPOPULATION: the service's install command, run against the checkout BEFORE the
+   * agent's first turn so it works against a tree whose dependencies are present. Best-effort —
+   * a failure becomes a note in the agent's prompt, never a failed run. Absent ⇒ no install
+   * phase. See `docs/initiatives/agent-dependency-prepopulation.md`.
+   */
+  dependencyInstall?: DependencyInstallSpec
   /**
    * BUGFIX REPRODUCTION PROOF: the run's declared reproduction command + test files. When set, the
    * harness runs that command against the pre-fix tree AND the tree the PR will open from, feeding
@@ -337,9 +349,29 @@ export async function runCodingAgent(
         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: string,
       ): Promise<Awaited<ReturnType<typeof runAgentInWorkspace>>> =>
@@ -347,7 +379,7 @@ export async function runCodingAgent(
           {
             dir: workDir,
             systemPrompt: spec.systemPrompt,
-            userPrompt,
+            userPrompt: withDependencyNote(userPrompt, dependencyNote),
             model: spec.model,
             harness: spec.harness,
             subscriptionToken: spec.subscriptionToken,
@@ -1038,6 +1070,29 @@ export async function runMultiRepoCoding(
     // 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.
@@ -1048,7 +1103,7 @@ export async function runMultiRepoCoding(
         {
           dir: root,
           systemPrompt: job.systemPrompt,
-          userPrompt: job.userPrompt,
+          userPrompt: withDependencyNote(job.userPrompt, dependencyNote),
           model: job.model,
           harness: job.harness,
           subscriptionToken: job.subscriptionToken,