@cat-factory/executor-harness 1.82.0 → 1.84.0

package/dist/agent-runner.js

@@ -326,6 +326,52 @@ async function setUpClaudeMcp(servers, configHome) {
         cleanup,
     };
 }
+/**
+ * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
+ * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
+ * the assistant turn (`rememberTool`) and hands the following user turn's content to `feedGuard`,
+ * which pairs each `tool_result`'s `is_error` with that name. The FIRST reason trips it: the
+ * diagnostic is recorded (readable via `reason()`, which the catch surfaces over the generic abort
+ * message) and `guardAbort` fires — folded into streamCli's signal so a tripped guard kills the CLI
+ * the same way the external watchdog does. Disabled when the caller supplies no limits (only the
+ * external watchdog then bounds the run).
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function createClaudeProgressGuard(opts) {
+    const guard = opts.guardLimits
+        ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
+        : undefined;
+    const toolNames = new Map();
+    const guardAbort = new AbortController();
+    let guardReason;
+    const feedGuard = (content) => {
+        if (!guard || guardReason)
+            return;
+        for (const block of content) {
+            if (!isObject(block) || block.type !== 'tool_result')
+                continue;
+            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+            const name = id ? toolNames.get(id) : undefined;
+            if (id)
+                toolNames.delete(id);
+            if (!name)
+                continue;
+            const reason = guard.observeSignal({ name, isError: block.is_error === true });
+            if (reason) {
+                guardReason = reason;
+                guardAbort.abort();
+                return;
+            }
+        }
+    };
+    return {
+        rememberTool: (id, name) => toolNames.set(id, name),
+        feedGuard,
+        guardAbort,
+        reason: () => guardReason,
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -411,37 +457,8 @@ export async function runClaudeCode(opts) {
     // `tool_use` id to feed the guard a {name,isError} signal. A tripped guard aborts the CLI via
     // `guardAbort` (folded into streamCli's signal below) and the run then fails with its
     // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
-    const guard = opts.guardLimits
-        ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
-        : undefined;
-    const toolNames = new Map();
-    const guardAbort = new AbortController();
-    let guardReason;
-    // Feed a user turn's settled tool calls to the guard, pairing each `tool_result`'s `is_error`
-    // with the name captured for its `tool_use` id on the assistant turn. The FIRST reason trips
-    // it: record the diagnostic and abort the CLI (streamCli's close handler rejects; the catch
-    // below surfaces `guardReason` over the generic abort message). A standalone closure so the
-    // per-block loop doesn't nest onEvent past the readable-depth limit.
-    const feedGuard = (content) => {
-        if (!guard || guardReason)
-            return;
-        for (const block of content) {
-            if (!isObject(block) || block.type !== 'tool_result')
-                continue;
-            const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
-            const name = id ? toolNames.get(id) : undefined;
-            if (id)
-                toolNames.delete(id);
-            if (!name)
-                continue;
-            const reason = guard.observeSignal({ name, isError: block.is_error === true });
-            if (reason) {
-                guardReason = reason;
-                guardAbort.abort();
-                return;
-            }
-        }
-    };
+    const progressGuard = createClaudeProgressGuard(opts);
+    const { rememberTool, feedGuard, guardAbort } = progressGuard;
     const onEvent = (event, meta) => {
         const type = event.type;
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
@@ -463,7 +480,7 @@ export async function runClaudeCode(opts) {
                 // Remember each call's name against its id so the guard can pair it with the
                 // `is_error` its `tool_result` carries on the next `user` turn.
                 if (typeof block.id === 'string' && typeof block.name === 'string') {
-                    toolNames.set(block.id, block.name);
+                    rememberTool(block.id, block.name);
                 }
                 if (block.name === 'TodoWrite') {
                     const progress = todosToProgress(block.input?.todos);
@@ -571,6 +588,7 @@ export async function runClaudeCode(opts) {
         // 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.
+        const guardReason = progressGuard.reason();
         if (guardReason) {
             const tail = err?.stderrTail;
             const report = capReport(redact(terminalReport, secrets).trim());

package/dist/coding-agent.d.ts

@@ -162,17 +162,6 @@ export interface CodingAgentOutcome {
      */
     reproductionReport?: ReproductionReport;
 }
-/**
- * Clone (or RESUME an existing branch) → write context → run Pi → push the branch
- * iff it carries work. The agent commits its OWN work (it alone knows which files
- * belong vs scratch/artifacts it created), so the harness never blanket-stages:
- * {@link commitTrackedEdits} is only a safety net for forgotten edits to ALREADY
- * tracked files, and the run is judged a no-op only when the branch never advanced
- * past its pre-run tip ({@link branchHasCommitsSince}). The harness owns push + PR;
- * it checkpoints (pushes) periodically so an evicted run's commits survive and a
- * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
- * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
- */
 export declare function runCodingAgent(spec: CodingAgentSpec, opts?: RunOptions): Promise<CodingAgentOutcome>;
 /**
  * The Ralph-loop validation watchdog: the longest a completion command may run before it is

package/dist/coding-agent.js

@@ -42,6 +42,64 @@ function followUpPollIntervalMs() {
  * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
  * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
  */
+/**
+ * The work-branch push machinery for one coding run: a single coalesced push plus the periodic
+ * checkpoint that keeps mid-run commits durable. Split out of {@link runCodingAgent} for the
+ * per-function line budget; the caller owns the interval's lifetime (it clears `checkpoint`).
+ *
+ * Serialize all pushes to the work branch through a single in-flight promise. A checkpoint tick
+ * and the final push (or two slow checkpoint ticks) must never run `git push` to the same branch
+ * concurrently: overlapping pushes race on the remote ref and can make a push fail with a
+ * ref-lock / non-fast-forward error — which, on the FINAL push, would fail the whole run even
+ * though the work is committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
+ * pushes once the branch has advanced past `baseSha`.
+ *
+ * Only push once the branch has advanced past its pre-run tip: pushing while it still sits at
+ * `baseSha` would create the work branch at the base commit (a zero-diff branch), which a later
+ * retry would see via `remoteBranchExists` and treat as resumable work — then fail to open a PR
+ * ("no commits between base and head"). So a run that never commits leaves NO branch behind,
+ * preserving the clean no-op outcome.
+ */
+function createWorkBranchPusher(args) {
+    const { dir, spec, baseSha, logger, signal } = args;
+    let pushInFlight = null;
+    const pushWorkOnce = () => {
+        if (pushInFlight)
+            return pushInFlight;
+        pushInFlight = (async () => {
+            if (!(await branchHasCommitsSince(dir, baseSha, signal)))
+                return;
+            await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
+        })().finally(() => {
+            pushInFlight = null;
+        });
+        return pushInFlight;
+    };
+    // Read the in-flight push, if any. A function (with an explicit return type) so the
+    // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
+    // only ever assigned inside closures, which flow analysis can't observe.
+    const inFlightPush = () => pushInFlight;
+    // Checkpoint the agent's committed work to the branch periodically so an eviction
+    // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
+    // agent commits its own work; this only PUSHES already-committed commits, so it
+    // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
+    // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
+    // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
+    // being durably checkpointed, so an eviction would lose it — previously invisible at
+    // info level. Still best-effort: a failed checkpoint never fails the run.
+    let checkpointFailures = 0;
+    const checkpoint = setInterval(() => {
+        pushWorkOnce().catch((err) => {
+            checkpointFailures++;
+            logger.warn('coding-agent: checkpoint push failed', {
+                reason: err instanceof Error ? err.message : String(err),
+                checkpointFailures,
+            });
+        });
+    }, checkpointIntervalMs());
+    checkpoint.unref?.();
+    return { pushWorkOnce, inFlightPush, checkpoint };
+}
 export async function runCodingAgent(spec, opts = {}) {
     const { signal } = opts;
     // The registry already binds jobId/repo/branch; add the coding kind + the push branch
@@ -51,56 +109,17 @@ export async function runCodingAgent(spec, opts = {}) {
         // Clone (or resume) the checkout, fetch any read-only reference branches, and capture the
         // pre-run branch tip. See {@link prepareCodingCheckout} for the resume-safety invariants.
         const { resumed, baseSha } = await prepareCodingCheckout(dir, spec, logger, opts);
-        // Serialize all pushes to the work branch through a single in-flight promise.
-        // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
-        // run `git push` to the same branch concurrently: overlapping pushes race on the
-        // remote ref and can make a push fail with a ref-lock / non-fast-forward error —
-        // which, on the FINAL push, would fail the whole run even though the work is
-        // committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
-        // pushes once the branch has advanced past `baseSha` (see below).
-        //
-        // Only push once the branch has advanced past its pre-run tip: pushing while it
-        // still sits at `baseSha` would create the work branch at the base commit (a
-        // zero-diff branch), which a later retry would see via `remoteBranchExists` and
-        // treat as resumable work — then fail to open a PR ("no commits between base and
-        // head"). So a run that never commits leaves NO branch behind, preserving the
-        // clean no-op outcome.
-        let pushInFlight = null;
-        const pushWorkOnce = () => {
-            if (pushInFlight)
-                return pushInFlight;
-            pushInFlight = (async () => {
-                if (!(await branchHasCommitsSince(dir, baseSha, signal)))
-                    return;
-                await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
-            })().finally(() => {
-                pushInFlight = null;
-            });
-            return pushInFlight;
-        };
-        // Read the in-flight push, if any. A function (with an explicit return type) so the
-        // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
-        // only ever assigned inside closures, which flow analysis can't observe.
-        const inFlightPush = () => pushInFlight;
-        // Checkpoint the agent's committed work to the branch periodically so an eviction
-        // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
-        // agent commits its own work; this only PUSHES already-committed commits, so it
-        // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
-        // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
-        // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
-        // being durably checkpointed, so an eviction would lose it — previously invisible at
-        // info level. Still best-effort: a failed checkpoint never fails the run.
-        let checkpointFailures = 0;
-        const checkpoint = setInterval(() => {
-            pushWorkOnce().catch((err) => {
-                checkpointFailures++;
-                logger.warn('coding-agent: checkpoint push failed', {
-                    reason: err instanceof Error ? err.message : String(err),
-                    checkpointFailures,
-                });
-            });
-        }, checkpointIntervalMs());
-        checkpoint.unref?.();
+        // The work-branch push machinery: one coalesced in-flight push plus the periodic
+        // checkpoint that keeps mid-run commits durable across an eviction. Lifted into
+        // {@link createWorkBranchPusher} so this callback stays within the per-function line budget;
+        // the invariants it upholds are documented there.
+        const { pushWorkOnce, inFlightPush, checkpoint } = createWorkBranchPusher({
+            dir,
+            spec,
+            baseSha,
+            logger,
+            signal,
+        });
         // In a monorepo the service lives in a subdirectory: run Pi with its cwd set to
         // that subtree (git stays rooted at `dir` so commits/pushes still cover the whole
         // checkout). Created if missing so a coder scaffolding a brand-new service into an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.82.0",
+  "version": "1.84.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.201.0",
-    "@cat-factory/server": "0.185.1",
-    "@cat-factory/spend": "0.12.131"
+    "@cat-factory/kernel": "0.202.0",
+    "@cat-factory/spend": "0.12.133",
+    "@cat-factory/server": "0.187.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -488,6 +488,56 @@ async function setUpClaudeMcp(
   }
 }
 
+/**
+ * No-progress guard on the CLI's own tool stream — the claude-code analogue of runPi's guard,
+ * which cannot see the CLI's internal turns. The caller remembers each `tool_use` id's name off
+ * the assistant turn (`rememberTool`) and hands the following user turn's content to `feedGuard`,
+ * which pairs each `tool_result`'s `is_error` with that name. The FIRST reason trips it: the
+ * diagnostic is recorded (readable via `reason()`, which the catch surfaces over the generic abort
+ * message) and `guardAbort` fires — folded into streamCli's signal so a tripped guard kills the CLI
+ * the same way the external watchdog does. Disabled when the caller supplies no limits (only the
+ * external watchdog then bounds the run).
+ *
+ * Split out of {@link runClaudeCode} for the per-function line budget.
+ */
+function createClaudeProgressGuard(opts: SubscriptionRunOptions): {
+  rememberTool: (id: string, name: string) => void
+  feedGuard: (content: unknown[]) => void
+  guardAbort: AbortController
+  reason: () => string | undefined
+} {
+  const guard = opts.guardLimits
+    ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
+    : undefined
+  const toolNames = new Map<string, string>()
+  const guardAbort = new AbortController()
+  let guardReason: string | undefined
+
+  const feedGuard = (content: unknown[]): void => {
+    if (!guard || guardReason) return
+    for (const block of content) {
+      if (!isObject(block) || block.type !== 'tool_result') continue
+      const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
+      const name = id ? toolNames.get(id) : undefined
+      if (id) toolNames.delete(id)
+      if (!name) continue
+      const reason = guard.observeSignal({ name, isError: block.is_error === true })
+      if (reason) {
+        guardReason = reason
+        guardAbort.abort()
+        return
+      }
+    }
+  }
+
+  return {
+    rememberTool: (id, name) => toolNames.set(id, name),
+    feedGuard,
+    guardAbort,
+    reason: () => guardReason,
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -576,34 +626,8 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // `tool_use` id to feed the guard a {name,isError} signal. A tripped guard aborts the CLI via
   // `guardAbort` (folded into streamCli's signal below) and the run then fails with its
   // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
-  const guard = opts.guardLimits
-    ? new ProgressGuard(opts.guardLimits, opts.expectsEdits ?? true)
-    : undefined
-  const toolNames = new Map<string, string>()
-  const guardAbort = new AbortController()
-  let guardReason: string | undefined
-
-  // Feed a user turn's settled tool calls to the guard, pairing each `tool_result`'s `is_error`
-  // with the name captured for its `tool_use` id on the assistant turn. The FIRST reason trips
-  // it: record the diagnostic and abort the CLI (streamCli's close handler rejects; the catch
-  // below surfaces `guardReason` over the generic abort message). A standalone closure so the
-  // per-block loop doesn't nest onEvent past the readable-depth limit.
-  const feedGuard = (content: unknown[]): void => {
-    if (!guard || guardReason) return
-    for (const block of content) {
-      if (!isObject(block) || block.type !== 'tool_result') continue
-      const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined
-      const name = id ? toolNames.get(id) : undefined
-      if (id) toolNames.delete(id)
-      if (!name) continue
-      const reason = guard.observeSignal({ name, isError: block.is_error === true })
-      if (reason) {
-        guardReason = reason
-        guardAbort.abort()
-        return
-      }
-    }
-  }
+  const progressGuard = createClaudeProgressGuard(opts)
+  const { rememberTool, feedGuard, guardAbort } = progressGuard
 
   const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
@@ -625,7 +649,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         // Remember each call's name against its id so the guard can pair it with the
         // `is_error` its `tool_result` carries on the next `user` turn.
         if (typeof block.id === 'string' && typeof block.name === 'string') {
-          toolNames.set(block.id, block.name)
+          rememberTool(block.id, block.name)
         }
         if (block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
@@ -739,6 +763,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     // 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.
+    const guardReason = progressGuard.reason()
     if (guardReason) {
       const tail = (err as { stderrTail?: string } | undefined)?.stderrTail
       const report = capReport(redact(terminalReport, secrets).trim())

package/src/coding-agent.ts

@@ -260,6 +260,75 @@ function followUpPollIntervalMs(): number {
  * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
  * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
  */
+/**
+ * The work-branch push machinery for one coding run: a single coalesced push plus the periodic
+ * checkpoint that keeps mid-run commits durable. Split out of {@link runCodingAgent} for the
+ * per-function line budget; the caller owns the interval's lifetime (it clears `checkpoint`).
+ *
+ * Serialize all pushes to the work branch through a single in-flight promise. A checkpoint tick
+ * and the final push (or two slow checkpoint ticks) must never run `git push` to the same branch
+ * concurrently: overlapping pushes race on the remote ref and can make a push fail with a
+ * ref-lock / non-fast-forward error — which, on the FINAL push, would fail the whole run even
+ * though the work is committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
+ * pushes once the branch has advanced past `baseSha`.
+ *
+ * Only push once the branch has advanced past its pre-run tip: pushing while it still sits at
+ * `baseSha` would create the work branch at the base commit (a zero-diff branch), which a later
+ * retry would see via `remoteBranchExists` and treat as resumable work — then fail to open a PR
+ * ("no commits between base and head"). So a run that never commits leaves NO branch behind,
+ * preserving the clean no-op outcome.
+ */
+function createWorkBranchPusher(args: {
+  dir: string
+  spec: CodingAgentSpec
+  baseSha: string
+  logger: Logger
+  signal: AbortSignal | undefined
+}): {
+  pushWorkOnce: () => Promise<void>
+  inFlightPush: () => Promise<void> | null
+  checkpoint: ReturnType<typeof setInterval>
+} {
+  const { dir, spec, baseSha, logger, signal } = args
+  let pushInFlight: Promise<void> | null = null
+  const pushWorkOnce = (): Promise<void> => {
+    if (pushInFlight) return pushInFlight
+    pushInFlight = (async () => {
+      if (!(await branchHasCommitsSince(dir, baseSha, signal))) return
+      await pushBranch(dir, spec.pushBranch, spec.ghToken, signal)
+    })().finally(() => {
+      pushInFlight = null
+    })
+    return pushInFlight
+  }
+  // Read the in-flight push, if any. A function (with an explicit return type) so the
+  // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
+  // only ever assigned inside closures, which flow analysis can't observe.
+  const inFlightPush = (): Promise<void> | null => pushInFlight
+
+  // Checkpoint the agent's committed work to the branch periodically so an eviction
+  // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
+  // agent commits its own work; this only PUSHES already-committed commits, so it
+  // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
+  // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
+  // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
+  // being durably checkpointed, so an eviction would lose it — previously invisible at
+  // info level. Still best-effort: a failed checkpoint never fails the run.
+  let checkpointFailures = 0
+  const checkpoint = setInterval(() => {
+    pushWorkOnce().catch((err) => {
+      checkpointFailures++
+      logger.warn('coding-agent: checkpoint push failed', {
+        reason: err instanceof Error ? err.message : String(err),
+        checkpointFailures,
+      })
+    })
+  }, checkpointIntervalMs())
+  checkpoint.unref?.()
+
+  return { pushWorkOnce, inFlightPush, checkpoint }
+}
+
 export async function runCodingAgent(
   spec: CodingAgentSpec,
   opts: RunOptions = {},
@@ -275,55 +344,17 @@ export async function runCodingAgent(
       // pre-run branch tip. See {@link prepareCodingCheckout} for the resume-safety invariants.
       const { resumed, baseSha } = await prepareCodingCheckout(dir, spec, logger, opts)
 
-      // Serialize all pushes to the work branch through a single in-flight promise.
-      // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
-      // run `git push` to the same branch concurrently: overlapping pushes race on the
-      // remote ref and can make a push fail with a ref-lock / non-fast-forward error —
-      // which, on the FINAL push, would fail the whole run even though the work is
-      // committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
-      // pushes once the branch has advanced past `baseSha` (see below).
-      //
-      // Only push once the branch has advanced past its pre-run tip: pushing while it
-      // still sits at `baseSha` would create the work branch at the base commit (a
-      // zero-diff branch), which a later retry would see via `remoteBranchExists` and
-      // treat as resumable work — then fail to open a PR ("no commits between base and
-      // head"). So a run that never commits leaves NO branch behind, preserving the
-      // clean no-op outcome.
-      let pushInFlight: Promise<void> | null = null
-      const pushWorkOnce = (): Promise<void> => {
-        if (pushInFlight) return pushInFlight
-        pushInFlight = (async () => {
-          if (!(await branchHasCommitsSince(dir, baseSha, signal))) return
-          await pushBranch(dir, spec.pushBranch, spec.ghToken, signal)
-        })().finally(() => {
-          pushInFlight = null
-        })
-        return pushInFlight
-      }
-      // Read the in-flight push, if any. A function (with an explicit return type) so the
-      // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
-      // only ever assigned inside closures, which flow analysis can't observe.
-      const inFlightPush = (): Promise<void> | null => pushInFlight
-
-      // Checkpoint the agent's committed work to the branch periodically so an eviction
-      // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
-      // agent commits its own work; this only PUSHES already-committed commits, so it
-      // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
-      // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
-      // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
-      // being durably checkpointed, so an eviction would lose it — previously invisible at
-      // info level. Still best-effort: a failed checkpoint never fails the run.
-      let checkpointFailures = 0
-      const checkpoint = setInterval(() => {
-        pushWorkOnce().catch((err) => {
-          checkpointFailures++
-          logger.warn('coding-agent: checkpoint push failed', {
-            reason: err instanceof Error ? err.message : String(err),
-            checkpointFailures,
-          })
-        })
-      }, checkpointIntervalMs())
-      checkpoint.unref?.()
+      // The work-branch push machinery: one coalesced in-flight push plus the periodic
+      // checkpoint that keeps mid-run commits durable across an eviction. Lifted into
+      // {@link createWorkBranchPusher} so this callback stays within the per-function line budget;
+      // the invariants it upholds are documented there.
+      const { pushWorkOnce, inFlightPush, checkpoint } = createWorkBranchPusher({
+        dir,
+        spec,
+        baseSha,
+        logger,
+        signal,
+      })
 
       // In a monorepo the service lives in a subdirectory: run Pi with its cwd set to
       // that subtree (git stays rooted at `dir` so commits/pushes still cover the whole