@cat-factory/executor-harness 1.80.0 → 1.84.0

package/dist/vcs-api.d.ts

@@ -0,0 +1,73 @@
+import type { PrSpec } from './job.js';
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export declare function describePrOpenFailure(status: number, provider: 'github' | 'gitlab'): string | undefined;
+export interface OpenPullRequestOptions {
+    owner: string;
+    name: string;
+    ghToken: string;
+    head: string;
+    base: string;
+    pr: PrSpec;
+    apiBase?: string;
+    /**
+     * The repo's clone URL. Used (when {@link provider} is absent) to detect the provider and,
+     * for GitLab, to derive the REST base + project path from its host — so the harness opens a
+     * GitLab **merge request** rather than POSTing to GitHub's pulls API. Absent ⇒ GitHub.
+     */
+    cloneUrl?: string;
+    /**
+     * The VCS provider, when the dispatcher knows it (the server derives it from the configured
+     * source-control backend and sets `repo.provider`). AUTHORITATIVE — it overrides host
+     * inference — so a self-managed GitLab on an arbitrarily-named host (e.g. `git.acme.com`,
+     * which {@link inferVcsProvider} can't recognise) still opens a merge request instead of
+     * being misrouted to GitHub's API. Absent ⇒ inferred from {@link cloneUrl}'s host.
+     */
+    provider?: 'github' | 'gitlab';
+    /**
+     * When the PR/MR for {@link head} ALREADY exists (a resumed run pushing onto a branch whose PR
+     * is open), replace its title and description with {@link pr} instead of leaving them alone.
+     *
+     * Set ONLY when {@link pr} carries the agent's own reviewer briefing. A resumed run is exactly
+     * the case that matters — eviction + re-dispatch, a ralph iteration, a retry — and without this
+     * the agent writes a briefing the platform reads, scrubs, caps and then silently drops. It must
+     * stay opt-in, though: refreshing from the GENERIC dispatch-time fallback would overwrite a
+     * description a human (or an earlier, better-informed run) had already written.
+     *
+     * The engine's managed verification-report region is carried across the rewrite by
+     * {@link preserveManagedSection}, and the update is best-effort — a failed refresh keeps the
+     * run's real outcome, which is the pushed work.
+     */
+    refreshExisting?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * The VCS host a clone URL points at. The harness is otherwise provider-agnostic (its git
+ * auth is a host-neutral GIT_ASKPASS credential), but the "open the PR/MR" REST call is not:
+ * GitHub and GitLab have different endpoints, so infer which to call from the host. GitHub is
+ * the default; a host of `gitlab.com` or one in the `gitlab.*` / `*.gitlab.*` family (covering
+ * self-managed instances named that way) is treated as GitLab.
+ */
+export declare function inferVcsProvider(cloneUrl: string): 'github' | 'gitlab';
+/** The GitLab REST v4 base for a clone URL's host, e.g. `https://gitlab.com/api/v4`. */
+export declare function gitlabApiBaseFromCloneUrl(cloneUrl: string): string;
+/**
+ * The URL-encoded GitLab project path from a clone URL — the full namespace path (so subgroups
+ * survive), with the trailing `.git` stripped, e.g.
+ * `https://gitlab.com/group/sub/proj.git` → `group%2Fsub%2Fproj`.
+ */
+export declare function gitlabProjectPath(cloneUrl: string): string;
+/**
+ * Open a PR (GitHub) or merge request (GitLab) for the pushed branch; returns its web URL.
+ * The provider is chosen from the EXPLICIT `opts.provider` when the dispatcher set it,
+ * falling back to host inference from the clone URL only when it didn't — so a self-managed
+ * GitLab whose host isn't named `gitlab.*` still opens an MR instead of being misrouted to
+ * GitHub's API. The GitHub path is unchanged.
+ */
+export declare function openPullRequest(opts: OpenPullRequestOptions): Promise<string | null>;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The running harness version, or undefined when it cannot be determined. */
+export declare const HARNESS_VERSION: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.80.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",
@@ -15,7 +15,11 @@
   "main": "./dist/server.js",
   "exports": {
     ".": "./dist/server.js",
-    "./embed": "./src/embed.ts"
+    "./embed": "./src/embed.ts",
+    "./claude-call-aggregator": {
+      "types": "./dist/claude-call-aggregator.d.ts",
+      "default": "./dist/claude-call-aggregator.js"
+    }
   },
   "publishConfig": {
     "access": "public"
@@ -26,9 +30,9 @@
     "hono": "^4.12.32",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.183.0",
-    "@cat-factory/kernel": "0.197.0",
-    "@cat-factory/spend": "0.12.127"
+    "@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/claude-call-aggregator.ts

@@ -12,6 +12,19 @@ import type { HarnessCallMetric } from './pi.js'
 // This aggregator folds every envelope sharing a `message.id` back into the one call it belongs to,
 // and buffers that call's tool_result turns so the reconstructed prompt chain keeps the shape the
 // model was actually sent: one assistant turn holding all its blocks, then the results.
+//
+// TWO CONSUMERS, and a change here reaches both. The container/host harness drives it from a
+// coding job's stdout (`agent-runner.ts`), and the BACKEND drives it from the host `claude` an
+// inline step runs on (`runtimes/local/src/harnessInline.ts`, importing this module through the
+// package's `./claude-call-aggregator` subpath). Both parse the SAME `stream-json`, and the second
+// used to carry its own lesser fold — which is how the inline path came to report one lumped call
+// per step while the container path reported every turn. Keep this the only implementation; it is
+// also the one place the per-block over-count above is fixed.
+//
+// The second consumer is why the transcript is BOUNDED and body assembly is OPTIONAL (see
+// {@link MAX_TRANSCRIPT_CHARS} and `bodies`). Inside a container the reconstruction is one job's
+// worth of memory in a box sized for it; in the backend it runs per concurrent inline step, in the
+// orchestrator process, on precisely the long tool loops worth diagnosing.
 
 /** One model call, assembled from every stream envelope that carried a piece of it. */
 export interface AggregatedClaudeCall {
@@ -134,6 +147,128 @@ interface TranscriptTurn {
   content: unknown
 }
 
+/**
+ * How much reconstructed transcript ONE conversation may retain.
+ *
+ * The stream feeds this without limit — a tool loop that reads large files grows the history by
+ * every one of them — and the reconstruction is held in the driver's own process. In the container
+ * that is a box sized for one job; in the BACKEND it is the orchestrator, where `streamCli` already
+ * refuses to retain the raw stream for exactly this reason (`harnessInline.ts` →
+ * `OUTPUT_TAIL_RETAIN_CHARS`: "a stalled tool-using run would otherwise park hundreds of MB in the
+ * orchestrator process — precisely on the runs worth diagnosing").
+ *
+ * 512 KiB because that is `LlmObservabilityService.MAX_BODY_CHARS`, the point past which the store
+ * truncates a body anyway: retaining more can only ever be thrown away. Deliberately NOT a
+ * per-deployment knob — it bounds a memory fault, and a number an operator can raise is one an
+ * operator can raise until the process dies.
+ */
+export const MAX_TRANSCRIPT_CHARS = 512 * 1024
+
+/**
+ * The role a turn carries when it is not a turn at all, but the note saying what stopped being
+ * retained. A distinct namespaced role rather than `system`, so nothing downstream can read it as a
+ * message that was actually sent — the same reason `seed` exists.
+ */
+const ELIDED_ROLE = 'cat-factory:elided'
+
+/** The growing request transcript behind a conversation's `promptText`. */
+interface Transcript {
+  /** The history as of NOW: what the call starting at this moment was sent. */
+  snapshot(): { text: string; messageCount: number }
+  /** Add a turn the conversation has now completed. */
+  append(turn: TranscriptTurn): void
+}
+
+/**
+ * Retain the transcript up to {@link MAX_TRANSCRIPT_CHARS} and then STOP, stating what it stopped
+ * retaining rather than silently ending mid-conversation.
+ *
+ * Freezing the tail (rather than evicting the head) keeps the seed and the early history — the
+ * task, and the turns that explain what the loop is doing — and keeps each call's `promptText` a
+ * stable PREFIX plus a changing note, so the backend's chain delta-compresses right up to the bound
+ * and only then degrades to storing the (now capped) array. Evicting the head would drop the task
+ * itself and break the prefix property from the first eviction on.
+ *
+ * The seed is never dropped: it is what the CALLER sent, so it is bounded by the caller's own
+ * prompt rather than by the stream, and it is the half a reader cannot reconstruct from anything
+ * else.
+ */
+function createBoundedTranscript(
+  seed: TranscriptTurn[],
+  secrets: string[],
+  maxChars: number,
+): Transcript {
+  const turns: TranscriptTurn[] = [...seed]
+  const sizeOf = (turn: TranscriptTurn): number => {
+    try {
+      return JSON.stringify(turn)?.length ?? 0
+    } catch {
+      // An un-serialisable turn cannot be retained at all, so charge it nothing and let the
+      // append below drop it on its own terms.
+      return Number.POSITIVE_INFINITY
+    }
+  }
+  let retained = turns.reduce((n, turn) => n + sizeOf(turn), 0)
+  const dropped = { turns: 0, chars: 0 }
+  return {
+    append(turn) {
+      const size = sizeOf(turn)
+      if (retained + size > maxChars) {
+        dropped.turns += 1
+        dropped.chars += Number.isFinite(size) ? size : 0
+        return
+      }
+      turns.push(turn)
+      retained += size
+    },
+    snapshot() {
+      const encoded = dropped.turns
+        ? [
+            ...turns,
+            {
+              role: ELIDED_ROLE,
+              content:
+                `${dropped.turns} later turn(s), ${dropped.chars} chars, were not retained: ` +
+                `this conversation reached the ${maxChars}-char reconstruction bound`,
+            },
+          ]
+        : turns
+      return {
+        text: redactBody(safeSerialise(encoded), secrets),
+        messageCount: encoded.length,
+      }
+    },
+  }
+}
+
+/**
+ * Count the turns and assemble NO bodies — for a driver that has nowhere to put them (the backend
+ * with `LLM_RECORD_PROMPTS` off, where the store drops every body it is handed).
+ *
+ * `messageCount` stays real, because it is a COUNT rather than a body and every consumer of the
+ * metric wants it. The point is not to omit data the gate would keep; it is that serialising a
+ * transcript the gate is about to drop is pure cost, and the whole reason bodies travel to the
+ * recorder as thunks (`CLAUDE.md` → "Telemetry & agent-context observability").
+ */
+function createCountingTranscript(seed: TranscriptTurn[]): Transcript {
+  let messageCount = seed.length
+  return {
+    append() {
+      messageCount += 1
+    },
+    snapshot: () => ({ text: '', messageCount }),
+  }
+}
+
+/** Serialise a transcript for the store, never throwing into the stream that produced it. */
+function safeSerialise(turns: TranscriptTurn[]): string {
+  try {
+    return JSON.stringify(turns) ?? ''
+  } catch {
+    return ''
+  }
+}
+
 /** The per-call telemetry the Claude Code stream yields, assembled behind one small surface. */
 export interface ClaudeStreamTelemetry {
   /** Fold an `assistant` envelope in (parent-loop turns only — see {@link isSubagentEvent}). */
@@ -155,20 +290,26 @@ export interface ClaudeStreamTelemetry {
  * was not sent. A subagent's conversation seeds EMPTY — its prompt was minted by the CLI and never
  * crosses this stream — which is also why its first call carries `messageCount: 0` (the backend's
  * `latestChainTip` skips those on purpose: there is no re-sendable chain to delta against).
- * Bodies are credential-scrubbed; they can echo the leased token.
+ * Bodies are credential-scrubbed; they can echo the leased token — and assembled at all only when
+ * {@link ClaudeStreamTelemetryOptions.bodies} says a driver has somewhere to put them. The
+ * transcript is bounded either way ({@link MAX_TRANSCRIPT_CHARS}).
  *
  * Deliberately does NOT touch {@link PiRunStats}: the run's tool/output counters describe whether
  * the agent ACTED at all (`agentNeverActed`), which is true of a subagent's turns whichever channel
  * ends up owning their telemetry rows. The caller accumulates them off the raw stream instead.
  */
-export function createClaudeStreamTelemetry(opts: {
-  seed: TranscriptTurn[]
-  secrets: string[]
-  publish: (metric: HarnessCallMetric) => void
-}): ClaudeStreamTelemetry {
-  const messages: TranscriptTurn[] = [...opts.seed]
-  let callPrompt = ''
-  let callMessageCount = 0
+export function createClaudeStreamTelemetry(
+  opts: ClaudeStreamTelemetryOptions,
+): ClaudeStreamTelemetry {
+  const bodies = opts.bodies ?? true
+  const transcript = bodies
+    ? createBoundedTranscript(
+        opts.seed,
+        opts.secrets,
+        opts.maxTranscriptChars ?? MAX_TRANSCRIPT_CHARS,
+      )
+    : createCountingTranscript(opts.seed)
+  let sent = { text: '', messageCount: 0 }
 
   // The aggregator IS the surface: the transcript and metric work happens in its callbacks, so
   // there is nothing to wrap it in.
@@ -177,16 +318,15 @@ export function createClaudeStreamTelemetry(opts: {
     // produced the response, and later envelopes of the same call must not see the turns it
     // went on to add.
     onCallStart: () => {
-      callPrompt = redactBody(JSON.stringify(messages), opts.secrets)
-      callMessageCount = messages.length
+      sent = transcript.snapshot()
     },
     onCall: (call) => {
       opts.publish({
         ...(call.model ? { model: call.model } : {}),
-        promptText: callPrompt,
-        messageCount: callMessageCount,
-        responseText: redactBody(call.text, opts.secrets),
-        reasoningText: redactBody(call.reasoning, opts.secrets),
+        promptText: sent.text,
+        messageCount: sent.messageCount,
+        responseText: bodies ? redactBody(call.text, opts.secrets) : '',
+        reasoningText: bodies ? redactBody(call.reasoning, opts.secrets) : '',
         inputTokens: call.inputTokens,
         cacheReadTokens: call.cacheReadTokens,
         cacheWriteTokens: call.cacheWriteTokens,
@@ -195,12 +335,30 @@ export function createClaudeStreamTelemetry(opts: {
       })
       // Appended only now, so each call's prompt stays a strict prefix of the next and the
       // backend's telemetry chain delta-compresses cleanly.
-      messages.push({ role: 'assistant', content: call.content })
-      for (const result of call.toolResults) messages.push({ role: 'tool', content: result })
+      transcript.append({ role: 'assistant', content: call.content })
+      for (const result of call.toolResults) transcript.append({ role: 'tool', content: result })
     },
   })
 }
 
+/** How one conversation's per-call telemetry is assembled. */
+export interface ClaudeStreamTelemetryOptions {
+  seed: TranscriptTurn[]
+  secrets: string[]
+  publish: (metric: HarnessCallMetric) => void
+  /**
+   * Whether to assemble the prompt/response BODIES at all. Absent ⇒ true (the container harness,
+   * whose job result carries them).
+   *
+   * `false` for a driver whose store will drop them — the backend with `LLM_RECORD_PROMPTS` off —
+   * where reconstructing a transcript per call is pure cost. Token counts, `messageCount` and
+   * finish reasons are unaffected: only the bodies go.
+   */
+  bodies?: boolean
+  /** Retention bound override (tests). Absent ⇒ {@link MAX_TRANSCRIPT_CHARS}. */
+  maxTranscriptChars?: number
+}
+
 /**
  * The dispatch (`Agent`/`Task` tool_use) id a stream envelope is tagged with, or `undefined` for a
  * parent-loop turn.
@@ -238,10 +396,7 @@ export function isSubagentEvent(event: Record<string, unknown>): boolean {
  * one stream: folding them into a single chain is exactly the defect this whole module removes,
  * one level down.
  */
-function createSubagentStreamTelemetry(opts: {
-  secrets: string[]
-  publish: (metric: HarnessCallMetric) => void
-}): {
+function createSubagentStreamTelemetry(opts: Omit<ClaudeStreamTelemetryOptions, 'seed'>): {
   onAssistant(dispatchId: string, message: Record<string, unknown>): void
   onToolResult(dispatchId: string, content: unknown[]): void
   flush(): void
@@ -251,11 +406,8 @@ function createSubagentStreamTelemetry(opts: {
     let telemetry = perDispatch.get(dispatchId)
     if (!telemetry) {
       // Seeded EMPTY: the CLI minted this subagent's prompt and it never crossed the stream.
-      telemetry = createClaudeStreamTelemetry({
-        seed: [],
-        secrets: opts.secrets,
-        publish: opts.publish,
-      })
+      // Each dispatch gets its OWN retention bound, since each is its own conversation.
+      telemetry = createClaudeStreamTelemetry({ ...opts, seed: [] })
       perDispatch.set(dispatchId, telemetry)
     }
     return telemetry
@@ -301,12 +453,9 @@ export interface ClaudeRunTelemetry {
  * instead, on per-dispatch transcripts of their own. Dropping them in that case would leave the run
  * billed by neither channel, and an under-count reads as a cheap run rather than as an error.
  */
-export function createClaudeRunTelemetry(opts: {
-  seed: TranscriptTurn[]
-  secrets: string[]
-  watcherOwnsSubagents: boolean
-  publish: (metric: HarnessCallMetric) => void
-}): ClaudeRunTelemetry {
+export function createClaudeRunTelemetry(
+  opts: ClaudeStreamTelemetryOptions & { watcherOwnsSubagents: boolean },
+): ClaudeRunTelemetry {
   const parent = createClaudeStreamTelemetry(opts)
   const subagents = opts.watcherOwnsSubagents ? undefined : createSubagentStreamTelemetry(opts)
   let sawSubagentTurn = false

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