@cat-factory/executor-harness 1.66.0 → 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
@@ -779,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

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)

package/src/bootstrap-mode.ts

@@ -0,0 +1,174 @@
+import { opendir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { AgentJob, AgentResult } from './job.js'
+import type { PiRunStats } from './pi.js'
+import type { RunOptions } from './runner.js'
+import {
+  NEVER_ACTED_CAUSE,
+  agentNeverActed,
+  agentOutputTail,
+  runAgentInWorkspace,
+  withWorkspace,
+} from './pi-workspace.js'
+import { cloneRepo, hasAgentChanges, reinitAndPush } from './git.js'
+import { log } from './logger.js'
+import { agentCapabilities, mergeEffort } from './agent-shared.js'
+
+// ---------------------------------------------------------------------------
+// The repo-BOOTSTRAP mode: adapt a reference architecture (or scaffold from scratch) into a
+// pre-created empty repo and force-push it as a single commit. Extracted from `agent.ts` as a
+// cohesive collaborator — it is a whole MODE with its own push semantics (a separate target repo
+// and a reinitialised history, not a work branch + PR), and it shares only the small agent-run
+// helpers in `agent-shared.ts` with the coding/explore flows.
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export 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,
+          ...agentCapabilities(job),
+        },
+        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)
+  )
+}