@cat-factory/executor-harness 1.64.4 → 1.68.0

package/src/agent-runner.ts

@@ -14,9 +14,17 @@ import {
   type PiRunStats,
   type TodoProgress,
 } from './pi.js'
+import {
+  claudeAllowedToolPatterns,
+  codexMcpConfigToml,
+  mcpServerSecretValues,
+  writeClaudeMcpConfig,
+  type McpServerSpec,
+  type SkillSpec,
+} from './agent-capabilities.js'
 import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { killChildProcess, spawnDetached } from './process.js'
-import { redact, secretsToRedact } from './redact.js'
+import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
 import { createSliceTracker, startSubagentWatcher } from './subagents.js'
 import {
   createTaskPlanTracker,
@@ -76,18 +84,19 @@ export interface SubscriptionRunOptions {
    */
   ambientAuth?: boolean
   /**
-   * A repo-sourced Claude Skill to install natively before launch (repo-sourced Claude Skills,
-   * slice 2). The claude-code runner writes it to `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md`
-   * (+ resource files) so the CLI loads it — but ONLY when it owns an isolated config home, i.e.
-   * NOT under `ambientAuth`. The codex runner ignores it outright. Every case that skips the
-   * native install reads the checkout's `.cat-context/skill/`, materialised by the caller.
+   * The skills to install natively before launch. The claude-code runner writes each to
+   * `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md` (+ resource files) so the CLI loads them — but ONLY
+   * when it owns an isolated config home, i.e. NOT under `ambientAuth`. The codex runner ignores
+   * them outright. Every case that skips the native install reads the checkout's
+   * `.cat-context/skill/<name>/`, materialised by the caller.
    */
-  skill?: {
-    name: string
-    description: string
-    instructions: string
-    resources: { relPath: string; content: string }[]
-  }
+  skills?: SkillSpec[]
+  /**
+   * Tool servers (MCP) to wire into the CLI for this run. Written to a PER-RUN config the CLI is
+   * pointed at — never a HOME-global one, which a second concurrent job would clobber and which
+   * carries this job's credentials. Absent ⇒ the CLI's built-in tools only.
+   */
+  mcpServers?: McpServerSpec[]
   /**
    * Extra environment for the CLI child, scoped to this job (the tester's secrets, a
    * private-registry npmrc pointer). Merged over the inherited `process.env` at spawn, so the
@@ -320,10 +329,7 @@ export function carryClaudeSystemPrompt(
  * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
  * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
  */
-async function writeNativeSkill(
-  skillsRoot: string,
-  skill: NonNullable<SubscriptionRunOptions['skill']>,
-): Promise<void> {
+async function writeNativeSkill(skillsRoot: string, skill: SkillSpec): Promise<void> {
   const dir = join(skillsRoot, skill.name)
   await mkdir(dir, { recursive: true })
   const name = JSON.stringify(skill.name)
@@ -337,6 +343,49 @@ async function writeNativeSkill(
   }
 }
 
+/**
+ * Prepare the Claude Code CLI's MCP wiring for one run: write the servers to a PER-RUN config and
+ * return the argv that points the CLI at it, plus the cleanup for a directory we had to mint.
+ *
+ * Two decisions live here. `--strict-mcp-config` makes that file the ONLY source of servers, so an
+ * ambient run on a developer's own machine can never silently hand the agent their personal ones.
+ * And `--allowedTools` is passed ONLY when a server actually narrows its tools — an allow-list is
+ * whole-session, not MCP-scoped, so `claudeAllowedToolPatterns` re-grants the CLI's built-in
+ * file/bash tools in the same list; see it for why that holds whichever way the run's permission
+ * mode treats an allow-list.
+ *
+ * The config carries this job's resolved credentials, so it goes in the isolated config home when
+ * we own one and a throwaway per-JOB directory otherwise — never the checkout (it would land in a
+ * commit) and never a shared HOME path (a concurrent job would clobber it).
+ */
+async function setUpClaudeMcp(
+  servers: McpServerSpec[] | undefined,
+  configHome: string | undefined,
+): Promise<{ args: string[]; cleanup: () => Promise<void> }> {
+  const noop = { args: [], cleanup: async () => {} }
+  if (!servers?.length) return noop
+  // Before anything can spawn: a failing MCP server echoes its own argv/headers into stderr, and
+  // that tail is carried onto the step's diagnostics.
+  registerKnownSecrets(mcpServerSecretValues(servers))
+  const home = configHome ?? (await mkdtemp(join(tmpdir(), 'cf-claude-mcp-')))
+  const owned = home === configHome ? undefined : home
+  const cleanup = async (): Promise<void> => {
+    if (owned) await rm(owned, { recursive: true, force: true }).catch(() => {})
+  }
+  const configPath = await writeClaudeMcpConfig(home, servers)
+  if (!configPath) return { args: [], cleanup }
+  const allowedTools = claudeAllowedToolPatterns(servers)
+  return {
+    args: [
+      '--mcp-config',
+      configPath,
+      '--strict-mcp-config',
+      ...(allowedTools?.length ? ['--allowedTools', allowedTools.join(',')] : []),
+    ],
+    cleanup,
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -518,17 +567,23 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log)
   }
 
-  // Repo-sourced Claude Skill (slice 2): install it 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 from
-  // different repos would clobber each other. An ambient run reads the skill from the checkout
-  // instead (`.cat-context/skill/`, materialised by the caller). Best-effort: a write failure must
-  // not wedge the run — the prompt still names the skill.
-  if (opts.skill && configHome) {
-    await writeNativeSkill(join(configHome, 'skills'), opts.skill).catch(() => {})
+  // 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)
 
   // ADR 0026 D3 (path corrected by ADR 0027 Defect A): while the run is live, tail the CLI's
@@ -572,6 +627,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           'bypassPermissions',
           '--model',
           opts.model,
+          ...mcp.args,
           ...appendArgs,
         ],
       },
@@ -613,6 +669,8 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     throw err
   } finally {
     await subagents?.stop()
+    // The ambient-mode MCP config dir (credential-bearing) never outlives the run.
+    await mcp.cleanup()
     if (configHome) {
       // 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
@@ -747,7 +805,11 @@ function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number
 export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
-  let usage: { inputTokens: number; outputTokens: number } | undefined
+  // The running CUMULATIVE total, kept in its reported (inclusive) form plus the cached share
+  // it contains. `PiRunOutcome.usage` needs the inclusive figure — it is the key-rotation
+  // weight — while the fallback call metric below needs the split, so both are derived from
+  // this one value rather than one being reconstructed from the other.
+  let cumulative: CodexCumulativeUsage | undefined
 
   // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
   // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
@@ -775,7 +837,20 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
   const codexHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-codex-'))
   if (codexHome) {
     await writeFile(join(codexHome, 'auth.json'), opts.subscriptionToken!, { mode: 0o600 })
-    await writeFile(join(codexHome, 'config.toml'), 'cli_auth_credentials_store = "file"\n', 'utf8')
+    // Tool servers (MCP) ride the SAME per-run config.toml, so they are scoped to this job and
+    // torn down with the home. Under AMBIENT auth there is no per-run home — and writing servers
+    // into the developer's own `~/.codex/config.toml` would outlive the run and race a concurrent
+    // job — so an ambient codex run gets no MCP servers; the backend states them as unavailable
+    // the same way it does for a harness with no MCP client at all.
+    // Registered before the CLI starts, for the same reason the claude path does it: a server that
+    // fails to launch puts its own command line into the stderr tail we keep.
+    if (opts.mcpServers?.length) registerKnownSecrets(mcpServerSecretValues(opts.mcpServers))
+    const mcpToml = opts.mcpServers?.length ? codexMcpConfigToml(opts.mcpServers) : ''
+    await writeFile(
+      join(codexHome, 'config.toml'),
+      `cli_auth_credentials_store = "file"\n${mcpToml ? `\n${mcpToml}` : ''}`,
+      { encoding: 'utf8', mode: 0o600 },
+    )
   }
 
   // Codex has no system-prompt flag, so fold the composed role + best-practice
@@ -812,7 +887,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     const progress = codexPlanProgress(event)
     if (progress && opts.onProgress) opts.onProgress(progress)
     const turnUsage = codexUsage(event)
-    if (turnUsage) usage = turnUsage
+    if (turnUsage) cumulative = turnUsage
     // A `token_count` event closes a model turn: pair its per-turn usage with the
     // assistant text seen since the previous turn as one telemetry call.
     const perTurn = codexLastTurnUsage(event)
@@ -826,7 +901,8 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
           responseText: redactBody(pendingText, secrets),
           reasoningText: '',
           inputTokens: perTurn.inputTokens,
-          cachedInputTokens: perTurn.cachedInputTokens,
+          cacheReadTokens: perTurn.cacheReadTokens,
+          cacheWriteTokens: perTurn.cacheWriteTokens,
           outputTokens: perTurn.outputTokens,
           finishReason: null,
         },
@@ -862,7 +938,11 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
 
     // Fallback for a CLI/version that never emits per-turn `last_token_usage`: record a
     // single call from the cumulative total + final text so the run is still observable.
-    if (calls.length === 0 && (usage || summary)) {
+    // The cumulative total is inclusive of its cached share exactly as a per-turn one is, so
+    // it is split the same way rather than being filed wholesale as fresh — which would report
+    // a cache-heavy run as if nothing had been cached, the one reading this telemetry exists
+    // to rule out.
+    if (calls.length === 0 && (cumulative || summary)) {
       publishCallMetric(
         calls,
         {
@@ -871,14 +951,23 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
           messageCount: messages.length,
           responseText: redactBody(summary, secrets),
           reasoningText: '',
-          inputTokens: usage?.inputTokens ?? 0,
-          cachedInputTokens: 0,
-          outputTokens: usage?.outputTokens ?? 0,
+          inputTokens: Math.max(
+            0,
+            (cumulative?.inputTokens ?? 0) - (cumulative?.cachedInputTokens ?? 0),
+          ),
+          cacheReadTokens: cumulative?.cachedInputTokens ?? 0,
+          // Codex reports no separate cache-WRITE class; 0 rather than guessed.
+          cacheWriteTokens: 0,
+          outputTokens: cumulative?.outputTokens ?? 0,
           finishReason: null,
         },
         opts.onCallMetric,
       )
     }
+    // The outcome's usage is the key-rotation WEIGHT, so it keeps the inclusive input count.
+    const usage = cumulative
+      ? { inputTokens: cumulative.inputTokens, outputTokens: cumulative.outputTokens }
+      : undefined
     return {
       summary,
       stats,
@@ -949,6 +1038,19 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
   return toProgress(items)
 }
 
+/**
+ * Codex's running cumulative usage, kept in the form the CLI reports it: `inputTokens` is the
+ * TOTAL prompt count (OpenAI semantics) with `cachedInputTokens` a SUBSET already inside it,
+ * never a bucket to add on top. The cached share is carried rather than discarded so a
+ * consumer that needs the fresh figure can subtract it at the point of use, instead of the
+ * only two readings of this number being "inclusive" and "lost".
+ */
+interface CodexCumulativeUsage {
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+}
+
 /**
  * Best-effort: pull token usage out of a Codex usage event. Codex `exec --json`
  * reports a running CUMULATIVE total on `token_count` events under
@@ -956,12 +1058,8 @@ function codexPlanProgress(event: Record<string, unknown>): TodoProgress | undef
  * other shapes put it on `usage` / `info.usage` directly. We read the cumulative
  * total when present so the caller can simply overwrite (not sum) — summing
  * cumulative totals across events would multiply-count. Checked most-likely first.
- * `input_tokens` is the TOTAL prompt count (OpenAI semantics: `cached_input_tokens`
- * is a subset already inside it), so it is NOT summed with the cached share.
  */
-function codexUsage(
-  event: Record<string, unknown>,
-): { inputTokens: number; outputTokens: number } | undefined {
+function codexUsage(event: Record<string, unknown>): CodexCumulativeUsage | undefined {
   const info = isObject(event.info) ? (event.info as Record<string, unknown>) : undefined
   const raw =
     (info && isObject(info.total_token_usage) ? info.total_token_usage : undefined) ??
@@ -972,20 +1070,28 @@ function codexUsage(
   const input = numberOf(raw.input_tokens)
   const output = numberOf(raw.output_tokens)
   if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, outputTokens: output }
+  return {
+    inputTokens: input,
+    cachedInputTokens: numberOf(raw.cached_input_tokens),
+    outputTokens: output,
+  }
 }
 
 /**
  * Per-TURN Codex token usage off a `token_count` event's `info.last_token_usage` (the
  * delta for the turn just completed, as opposed to `codexUsage`'s cumulative total).
- * `input_tokens` is the total prompt count for the turn and already INCLUDES the cached
- * share (OpenAI semantics), so `cachedInputTokens` is surfaced as the subset it is —
- * NOT added on top (adding it would double-count every cached token).
+ *
+ * OpenAI semantics: `input_tokens` is the turn's WHOLE prompt count and already INCLUDES
+ * the cached share, so the fresh figure is the difference. Clamped at 0 because the two
+ * counts come off the same event and a vendor inconsistency must not mint a negative token
+ * count. Codex reports no separate cache-WRITE class, so that class is 0 here rather than
+ * guessed.
  */
 function codexLastTurnUsage(event: Record<string, unknown>):
   | {
       inputTokens: number
-      cachedInputTokens: number
+      cacheReadTokens: number
+      cacheWriteTokens: number
       outputTokens: number
     }
   | undefined {
@@ -996,7 +1102,12 @@ function codexLastTurnUsage(event: Record<string, unknown>):
   const cached = numberOf(raw.cached_input_tokens)
   const output = numberOf(raw.output_tokens)
   if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, cachedInputTokens: cached, outputTokens: output }
+  return {
+    inputTokens: Math.max(0, input - cached),
+    cacheReadTokens: cached,
+    cacheWriteTokens: 0,
+    outputTokens: output,
+  }
 }
 
 /** Dispatch to the configured subscription harness runner. */

package/src/agent-shared.ts

@@ -0,0 +1,34 @@
+import type { AgentJob, AgentResult, McpServerSpec, SkillSpec } from './job.js'
+import type { EffortReport } from './effort.js'
+
+// Small helpers shared by every agent MODE (explore / coding / bootstrap / preview). They live
+// apart from `agent.ts` so the bootstrap mode — a whole flow of its own — could move to its own
+// module without either file importing the other.
+
+/**
+ * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
+ * onto its final result. Every container mode routes its result through this so the report reaches
+ * the backend uniformly. A run that wrote no report passes through unchanged.
+ */
+export function mergeEffort(
+  result: AgentResult,
+  effortReport: EffortReport | undefined,
+): AgentResult {
+  return effortReport ? { ...result, effortReport } : result
+}
+
+/**
+ * The agent-capability fields (skills + tool servers) every agent-running flow forwards to
+ * {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow cannot silently
+ * be the one that drops a kind's declared playbook or tool server — the failure mode is invisible
+ * (the agent simply works without it) and would only show up as degraded output.
+ */
+export function agentCapabilities(job: AgentJob): {
+  skills?: SkillSpec[]
+  mcpServers?: McpServerSpec[]
+} {
+  return {
+    ...(job.skills?.length ? { skills: job.skills } : {}),
+    ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+  }
+}

package/src/agent.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import { mkdir, mkdtemp, opendir, rm } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import type {
@@ -20,17 +20,14 @@ import {
   conflictDiff,
   fetchPullRequestHead,
   fetchReferenceBranches,
-  hasAgentChanges,
   headCommit,
   mergeBranch,
   prepareExistingCheckout,
   pushBranch,
-  reinitAndPush,
   unmergedPaths,
 } from './git.js'
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi.js'
-import type { EffortReport } from './effort.js'
 import { applyPrDescription } from './pr-description.js'
 import {
   makeDirClaimer,
@@ -39,6 +36,8 @@ import {
   runMultiRepoCoding,
 } from './coding-agent.js'
 import { validationFailureMessage } from './validation-checks.js'
+import { agentCapabilities, mergeEffort } from './agent-shared.js'
+import { runBootstrap } from './bootstrap-mode.js'
 import {
   acquireRepoCheckout,
   agentNeverActed,
@@ -313,15 +312,6 @@ async function cloneServiceCheckout(
   return deriveWorkDir(dir, job.repo.serviceDirectory)
 }
 
-/**
- * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
- * onto its final result. Every container mode routes its result through this so the report reaches
- * the backend uniformly. A run that wrote no report passes through unchanged.
- */
-function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult {
-  return effortReport ? { ...result, effortReport } : result
-}
-
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise<AgentResult> {
   // An `ambientAuth` job runs in the SHARED native host process on the developer's own HOME
@@ -608,6 +598,7 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
             webSearchProxy: job.webSearch,
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
+            ...agentCapabilities(job),
           },
           agentOpts,
         )
@@ -836,6 +827,7 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
         webSearchProxy: job.webSearch,
         ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
         guardLimits: job.guardLimits,
+        ...agentCapabilities(job),
         multiRepo: true,
       },
       opts,
@@ -954,8 +946,8 @@ function buildSingleRepoCodingSpec(
     ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
     ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
     ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
-    // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
-    ...(job.skill ? { skill: job.skill } : {}),
+    // Skills + tool servers: installed/wired harness-aware by runAgentInWorkspace.
+    ...agentCapabilities(job),
     // Ralph loop: run the completion command after the agent commits and report its verdict.
     ...(job.validation
       ? {
@@ -1228,6 +1220,7 @@ async function runConflictResolution(job: AgentJob, opts: RunOptions): Promise<A
           sessionToken: job.sessionToken,
           contextFiles: job.contextFiles,
           guardLimits: job.guardLimits,
+          ...agentCapabilities(job),
         },
         opts,
       )
@@ -1328,156 +1321,6 @@ function unresolvedReason(
   )
 }
 
-/**
- * Repo-bootstrap coding flow (the bootstrapper): with a reference architecture, clone it →
- * the agent adapts it in place per the instructions; without one (`fromScratch`), start from
- * an empty directory → the agent scaffolds the new service. Either way the result's history
- * is reset to a single commit and force-pushed to the SEPARATE, pre-created target repo's
- * default branch. Diverges from the ordinary coding flow in pushing to a different repo with
- * a reinitialised history rather than a work branch + PR on the cloned repo.
- */
-async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
-  const { signal } = opts
-  const boot = job.bootstrap!
-  const fromScratch = boot.fromScratch === true
-  const logger = (opts.log ?? log).child({ target: `${boot.target.owner}/${boot.target.name}` })
-  return withWorkspace('boot', async (dir) => {
-    if (!fromScratch) {
-      opts.onPhase?.('clone')
-      logger.info('agent(bootstrap): cloning reference architecture', {
-        reference: `${job.repo.owner}/${job.repo.name}`,
-      })
-      await cloneRepo({
-        repo: { ...job.repo, baseBranch: job.branch },
-        ghToken: job.ghToken,
-        dir,
-        signal,
-      })
-    } else {
-      logger.info('agent(bootstrap): scaffolding from scratch (no reference)')
-    }
-
-    opts.onPhase?.('agent')
-    logger.info('agent(bootstrap): running agent')
-    const { summary, stats, stderrTail, usage, callMetrics, effortReport } =
-      await runAgentInWorkspace(
-        {
-          dir,
-          systemPrompt: job.systemPrompt,
-          userPrompt: job.userPrompt,
-          model: job.model,
-          harness: job.harness,
-          subscriptionToken: job.subscriptionToken,
-          subscriptionBaseUrl: job.subscriptionBaseUrl,
-          ambientAuth: job.ambientAuth,
-          proxyBaseUrl: job.proxyBaseUrl,
-          sessionToken: job.sessionToken,
-          guardLimits: job.guardLimits,
-        },
-        opts,
-      )
-
-    // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it never
-    // reached the model), and a force-push would then publish an empty tree — leaving the
-    // run "succeeded" but the repo bare. Fail with a structured error (carrying what the
-    // agent did) instead of pushing nothing.
-    if (!(await producedRepoContent(dir, !fromScratch, signal))) {
-      const error = bootstrapNoOpReason(!fromScratch, stats, summary, stderrTail)
-      logger.error('agent(bootstrap): agent produced no content, refusing to push', { ...stats })
-      return mergeEffort(
-        {
-          summary,
-          stats,
-          error,
-          failureCause: 'agent',
-          ...(usage ? { usage } : {}),
-          ...(callMetrics ? { callMetrics } : {}),
-        },
-        effortReport,
-      )
-    }
-
-    opts.onPhase?.('push')
-    logger.info('agent(bootstrap): pushing bootstrapped contents', { ...stats })
-    // Bootstrap always resets history to one commit + force-pushes (the fresh history
-    // shares no ancestor with whatever boilerplate the new repo was created with).
-    await reinitAndPush({
-      dir,
-      target: boot.target,
-      ghToken: job.ghToken,
-      message: fromScratch
-        ? 'Bootstrap new repository'
-        : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
-    })
-    logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch })
-    return mergeEffort(
-      {
-        defaultBranch: boot.target.defaultBranch,
-        summary,
-        stats,
-        ...(usage ? { usage } : {}),
-        ...(callMetrics ? { callMetrics } : {}),
-      },
-      effortReport,
-    )
-  })
-}
-
-/**
- * Whether the bootstrapper actually produced repository content, so a no-op run (the agent
- * never reached the model / never wrote anything) is failed rather than force-pushed as an
- * empty repo. With a reference architecture, "produced content" means the agent changed the
- * clone; scaffolding from scratch, it means at least one file now exists in the working
- * directory. (The harness writes its prompt context to Pi's global `~/.pi/agent/AGENTS.md`,
- * never into `dir`, so nothing here needs to be filtered out as harness boilerplate.)
- */
-export async function producedRepoContent(
-  dir: string,
-  hasReference: boolean,
-  signal?: AbortSignal,
-): Promise<boolean> {
-  if (hasReference) return hasAgentChanges(dir, signal)
-  return containsAnyFile(dir)
-}
-
-/**
- * Whether `dir` contains at least one regular file anywhere in its tree, walking
- * depth-first and stopping at the FIRST file found — so the cost is bounded by how
- * quickly a file turns up (a scaffold almost always writes a root-level file), not by
- * the size of the produced tree (a full recursive `readdir` would materialise every
- * entry before the check).
- */
-async function containsAnyFile(dir: string): Promise<boolean> {
-  const handle = await opendir(dir)
-  try {
-    for await (const entry of handle) {
-      if (entry.isFile()) return true
-      if (entry.isDirectory() && (await containsAnyFile(join(dir, entry.name)))) return true
-    }
-  } catch {
-    // A directory that vanished mid-walk has nothing to contribute.
-  }
-  return false
-}
-
-/** Human-readable bootstrap no-op reason, embedding what the agent did so the cause is visible. */
-function bootstrapNoOpReason(
-  hasReference: boolean,
-  stats: PiRunStats,
-  summary: string,
-  stderrTail: string | undefined,
-): string {
-  const what = hasReference
-    ? 'made no changes to the reference architecture'
-    : 'scaffolded no files'
-  const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : ''
-  return (
-    `the bootstrapper agent ${what} ` +
-    `(tool calls: ${stats.toolCalls}, assistant output: ${stats.assistantChars} chars).${cause}` +
-    agentOutputTail(stderrTail, summary)
-  )
-}
-
 /** Human-readable reason a read-only run produced no usable output. */
 function noOutputReason(stats: PiRunStats, stderrTail: string | undefined): string {
   const cause = agentNeverActed(stats)