@cat-factory/executor-harness 1.114.0 → 1.118.0

package/src/agent-runner.ts

@@ -3,7 +3,12 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js'
-import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js'
+import { claudeUsage, unaccountedUsageCall } from './usage-attribution.js'
+import {
+  createClaudeRunTelemetry,
+  subagentDispatchId,
+  type ClaudeRunTelemetry,
+} from './claude-call-aggregator.js'
 import {
   ToolCallTracker,
   type TrackedToolCall,
@@ -12,9 +17,7 @@ import {
 import { log, type Logger } from './logger.js'
 import { NO_TOOL_WINDOW, type ToolProgressWindow } from './tool-silence.js'
 import {
-  createCallMetricPublisher,
   publishCallMetric,
-  type CallMetricPublisher,
   type HarnessCallMetric,
   type PiRunOutcome,
   type TodoProgress,
@@ -202,24 +205,6 @@ export interface SubscriptionRunOptions {
   log?: Logger
 }
 
-/**
- * Fallback token attribution: if a CLI reported a cumulative total but no per-turn
- * usage (so every captured call has zero tokens), pin the whole total onto the LAST
- * call rather than dropping it — the run's tokens are still accounted, just not split
- * per turn. A no-op when the calls already carry per-turn tokens.
- */
-function attributeCumulativeUsage(
-  calls: HarnessCallMetric[],
-  usage: { inputTokens: number; outputTokens: number } | undefined,
-): void {
-  if (!usage || calls.length === 0) return
-  const anyTokens = calls.some((c) => c.inputTokens > 0 || c.outputTokens > 0)
-  if (anyTokens) return
-  const last = calls[calls.length - 1]!
-  last.inputTokens = usage.inputTokens
-  last.outputTokens = usage.outputTokens
-}
-
 /**
  * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
  * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
@@ -711,6 +696,75 @@ function carriesToolResult(content: unknown[]): boolean {
   return content.some((block) => isObject(block) && block.type === 'tool_result')
 }
 
+/** One claude-code run's per-call telemetry: what was captured, and how it is settled. */
+interface ClaudeCallCapture {
+  /** Every captured call, terminal-result order — the parent's, the subagents', the remainder. */
+  calls: HarnessCallMetric[]
+  telemetry: ClaudeRunTelemetry
+  /**
+   * File whatever the parent's narrated turns did not account for, once its terminal cumulative
+   * usage is known. A no-op when they add up. See {@link unaccountedUsageCall}.
+   */
+  settleUsage: (usage: { inputTokens: number; outputTokens: number } | undefined) => void
+}
+
+/**
+ * Open the per-call telemetry capture for one claude-code run.
+ *
+ * It reconstructs the full per-call request/response bodies from the stream.
+ * `--output-format stream-json --verbose` emits a near-verbatim Anthropic Messages envelope per
+ * response CONTENT BLOCK (not per call), so the aggregator folds the envelopes sharing a
+ * `message.id` back into one call and buffers that call's `user` tool_result turns — together the
+ * growing prompt transcript, in the shape the model was actually sent. It is SEEDED with the inputs
+ * the harness supplies (they never appear in the stream): the system + first user message when the
+ * prompt rides argv, or a single folded user turn when it doesn't, so the reconstruction never shows
+ * a system turn that was never sent. Bodies are credential-scrubbed (they can echo the leased token).
+ *
+ * The parent loop's calls are tracked SEPARATELY, by reference into the same list, because the
+ * terminal `result` event's cumulative usage covers only the parent conversation. In `ambientAuth`
+ * mode there is no transcript watcher, so the CLI's tagged subagent turns are captured here too and
+ * `calls` holds both; reconciling against that mixed list is what once billed a subagent for the
+ * parent's whole output shortfall.
+ */
+function openClaudeCallCapture(
+  opts: SubscriptionRunOptions,
+  stream: { prompt: string; folded: boolean; secrets: string[] },
+): ClaudeCallCapture {
+  const calls: HarnessCallMetric[] = []
+  const parentCalls: HarnessCallMetric[] = []
+  const publish = (metric: HarnessCallMetric): void =>
+    publishCallMetric(calls, metric, opts.onCallMetric)
+  // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring in the caller: it is started
+  // only when the CLI has an isolated config home to watch, which an `ambientAuth` run does not
+  // have. The telemetry routes the CLI's tagged subagent turns accordingly — see
+  // `createClaudeRunTelemetry`.
+  const telemetry = createClaudeRunTelemetry({
+    seed: stream.folded
+      ? [{ role: 'user', content: stream.prompt }]
+      : [
+          { role: 'system', content: opts.systemPrompt },
+          { role: 'user', content: opts.userPrompt },
+        ],
+    secrets: stream.secrets,
+    watcherOwnsSubagents: !opts.ambientAuth,
+    publish: (metric) => {
+      parentCalls.push(metric)
+      publish(metric)
+    },
+    publishSubagent: publish,
+  })
+  return {
+    calls,
+    telemetry,
+    settleUsage: (usage) => {
+      // Published like any other call so the live drain records it too, which is also what stamps
+      // its `seq` and therefore its stable row id.
+      const remainder = unaccountedUsageCall(parentCalls, usage)
+      if (remainder) publish(remainder)
+    },
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -729,34 +783,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     })
   }
 
-  // Reconstruct the full per-call request/response bodies for telemetry from the
-  // stream. `--output-format stream-json --verbose` emits a near-verbatim Anthropic
-  // Messages envelope per response CONTENT BLOCK (not per call), so the aggregator below
-  // folds the envelopes sharing a `message.id` back into one call and buffers that call's
-  // `user` tool_result turns — together the growing prompt transcript, in the shape the
-  // model was actually sent. We seed it with the inputs the harness supplies (they never
-  // appear in the stream): the system + first user message when the prompt rides argv, or
-  // a single folded user turn when it doesn't — so the reconstruction never shows a system
-  // turn that was never sent. Bodies are credential-scrubbed (they can echo the leased token).
   const secrets = opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : []
-  const calls: HarnessCallMetric[] = []
-  // Streams each call as the CLI yields it, EXCEPT one whose tokens `attributeCumulativeUsage`
-  // may still rewrite below (a published call must be final — see the publisher).
-  const publisher = createCallMetricPublisher(calls, opts.onCallMetric)
-  // `watcherOwnsSubagents` tracks the `startSubagentWatcher` wiring below: it is started only when
-  // the CLI has an isolated config home to watch, which an `ambientAuth` run does not have. The
-  // telemetry routes the CLI's tagged subagent turns accordingly — see `createClaudeRunTelemetry`.
-  const telemetry = createClaudeRunTelemetry({
-    seed: folded
-      ? [{ role: 'user', content: prompt }]
-      : [
-          { role: 'system', content: opts.systemPrompt },
-          { role: 'user', content: opts.userPrompt },
-        ],
-    secrets,
-    watcherOwnsSubagents: !opts.ambientAuth,
-    publish: (metric) => publisher.publish(metric),
-  })
+  const capture = openClaudeCallCapture(opts, { prompt, folded, secrets })
+  const telemetry = capture.telemetry
 
   // ADR 0026 D2.1 + ADR 0027 Defect B: surface live slice progress from the two views the run
   // produces of the SAME slicing. The parent's subagent dispatches + their terminal tool_results
@@ -917,8 +946,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       summary,
       stats,
       stderrTail,
-      calls,
-      publisher,
+      capture,
       usage,
       subagents,
       expectSubagentCalls: telemetry.expectsWatcherCalls(),
@@ -926,11 +954,11 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     })
   } catch (err) {
     // The stream ended abnormally (guard trip, watchdog kill, CLI crash). Complete the call in
-    // flight anyway, and release whatever the publisher was withholding: a killed run never
-    // returns an outcome, so the live channel is the ONLY record of what it spent, and dropping
-    // its last turn is what the streaming exists to avoid.
+    // flight anyway: a killed run never returns an outcome, so the live channel is the ONLY record
+    // of what it spent, and dropping its last turn is what the streaming exists to avoid. No
+    // terminal `result` event arrived, so there is no cumulative total to reconcile against and no
+    // remainder row to file — every captured turn already streamed as it was completed.
     telemetry.flush()
-    publisher.flush()
     // A tripped no-progress guard aborted the CLI; streamCli rejects with its generic abort
     // message, so replace it with the guard's actionable diagnostic — carrying the stderr tail it
     // attached, since that is usually the only evidence of what the CLI was doing when it was
@@ -1088,9 +1116,8 @@ async function assembleClaudeOutcome(args: {
   summary: string
   stats: PiRunStats
   stderrTail: string
-  calls: HarnessCallMetric[]
-  /** The live-stream publisher, flushed once attribution has finalised the calls' tokens. */
-  publisher: CallMetricPublisher
+  /** This run's per-call telemetry, settled here with the terminal usage. */
+  capture: ClaudeCallCapture
   usage: { inputTokens: number; outputTokens: number } | undefined
   subagents: ReturnType<typeof startSubagentWatcher> | undefined
   /**
@@ -1102,14 +1129,11 @@ async function assembleClaudeOutcome(args: {
   expectSubagentCalls: boolean
   log?: Logger
 }): Promise<PiRunOutcome> {
-  const { summary, stats, stderrTail, calls, publisher, usage, subagents } = args
-  // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
-  // subagent calls, which carry their own per-turn tokens, are concatenated).
-  attributeCumulativeUsage(calls, usage)
-  // The withheld calls are final only NOW, so stream them: the completion poll drains them
-  // alongside the result, and the backend records the attributed numbers rather than the zeros
-  // they carried while the run was in flight.
-  publisher.flush()
+  const { summary, stats, stderrTail, capture, usage, subagents } = args
+  const calls = capture.calls
+  // What the parent's narrated turns did not account for, as its OWN row (never tokens grafted onto
+  // a real turn).
+  capture.settleUsage(usage)
   // Final drain of any subagent transcript writes that landed after the last poll, then
   // fold the subagents' usage + per-call telemetry into the run's outcome.
   await subagents?.stop()
@@ -1138,21 +1162,6 @@ async function assembleClaudeOutcome(args: {
   }
 }
 
-function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number } | undefined {
-  if (!isObject(raw)) return undefined
-  // Count every input bucket Anthropic bills: fresh input plus BOTH cache reads and
-  // cache writes (cache_creation_input_tokens), which are real consumed tokens — and
-  // are the dominant share on a long agent run. Omitting them under-weights a token's
-  // true load in the usage-aware rotation window.
-  const input =
-    numberOf(raw.input_tokens) +
-    numberOf(raw.cache_read_input_tokens) +
-    numberOf(raw.cache_creation_input_tokens)
-  const output = numberOf(raw.output_tokens)
-  if (input === 0 && output === 0) return undefined
-  return { inputTokens: input, outputTokens: output }
-}
-
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------

package/src/claude-call-aggregator.ts

@@ -452,12 +452,25 @@ export interface ClaudeRunTelemetry {
  * `ambientAuth` run has no isolated config home to watch — the tagged turns are recorded here
  * 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.
+ *
+ * Which is also why the two are published through SEPARATE callbacks. A caller reconciling the
+ * parent's terminal cumulative usage needs the parent's calls alone, and with one shared callback
+ * the fallback channel silently mixed subagent turns into that list — where they both understated
+ * the shortfall and, being last, attracted it (`unaccountedUsageCall`). `publishSubagent` is
+ * optional so a caller that draws no distinction (a test, the settled-transcript path where nothing
+ * arrives here anyway) keeps one sink.
  */
 export function createClaudeRunTelemetry(
-  opts: ClaudeStreamTelemetryOptions & { watcherOwnsSubagents: boolean },
+  opts: ClaudeStreamTelemetryOptions & {
+    watcherOwnsSubagents: boolean
+    /** Where a SUBAGENT conversation's call goes. Absent ⇒ `publish`, the parent's sink. */
+    publishSubagent?: (metric: HarnessCallMetric) => void
+  },
 ): ClaudeRunTelemetry {
   const parent = createClaudeStreamTelemetry(opts)
-  const subagents = opts.watcherOwnsSubagents ? undefined : createSubagentStreamTelemetry(opts)
+  const subagents = opts.watcherOwnsSubagents
+    ? undefined
+    : createSubagentStreamTelemetry({ ...opts, publish: opts.publishSubagent ?? opts.publish })
   let sawSubagentTurn = false
 
   return {

package/src/coding-agent.ts

@@ -24,6 +24,8 @@ import {
   pushBranch,
   refreshFromBaseIfClean,
   remoteBranchExists,
+  unpublishedWorkBranchTip,
+  workBranchLease,
 } from './git.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
 import type { HarnessCallMetric } from './pi.js'
@@ -280,13 +282,35 @@ function followUpPollIntervalMs(): number {
  * 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`.
+ * pushes what is UNPUBLISHED ({@link unpublishedWorkBranchTip}: past `baseSha`, and not already the
+ * tip the last push published).
  *
- * 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.
+ * Every push after the first LEASES against the sha this pass published (see
+ * {@link pushBranch}), because the checkpoint makes the harness its own competing writer: it
+ * publishes a commit within a minute of the agent making it, and the agent is then free to amend,
+ * reset or rebase that commit, which is perfectly ordinary git hygiene, and the delivery contract
+ * asks it to validate AFTER committing, exactly the sequence that produces an amend. Without the
+ * lease the final push is refused as a non-fast-forward and the whole run fails with its work
+ * already on the branch. The lease is what keeps that recovery from becoming a blanket `--force`:
+ * a SECOND writer (a concurrent dispatch for the same block) still refuses the push, which is the
+ * "never clobber another run's commits" property the resume design leans on.
+ *
+ * The lease alone does not bound the force to THIS pass's own commits, and that is the property
+ * the design promises, so it is checked rather than assumed: once one checkpoint has landed, a
+ * rewrite that drops `baseSha` (the tip the pass started from, which on a RESUMED branch is an
+ * earlier run's published work) would lease successfully against our own checkpoint and take the
+ * earlier commits with it. So the lease is armed only while the branch still CONTAINS `baseSha`;
+ * withheld, the push goes out plain, git refuses it, and the engine re-dispatches onto the branch
+ * as it stands. A rewrite this pass cannot prove is its own is never forced away.
+ *
+ * What is pushable is {@link unpublishedWorkBranchTip}'s question, and both of its answers matter
+ * here. A branch still at `baseSha` must not be pushed at all, or a later retry resumes a zero-diff
+ * branch and cannot open a PR for it. A branch already at the published tip has nothing to add, and
+ * skipping it is what keeps the interval a LOSS WINDOW rather than a push rate: an hour-long run
+ * that commits eight times pushes eight times, not sixty. That skip is invisible to the outcome by
+ * construction: `finalizeCodingRun` decides `pushed` from the BRANCH (advanced this pass, or
+ * resumed), never from whether the final call issued a `git push`, because a tip the checkpoint
+ * already published is published.
  */
 function createWorkBranchPusher(args: {
   dir: string
@@ -301,11 +325,31 @@ function createWorkBranchPusher(args: {
 } {
   const { dir, spec, baseSha, logger, signal } = args
   let pushInFlight: Promise<void> | null = null
+  // The sha THIS pass last published to the work branch, and the only value it will ever lease a
+  // force push against. Starts unset even on a RESUMED branch: the tip we merely cloned is an
+  // earlier run's work, so a rewrite of it is refused (and re-driven) rather than forced away.
+  let publishedSha: string | undefined
   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)
+      if (!(await unpublishedWorkBranchTip({ dir, baseSha, publishedSha, signal }))) return
+      // The rule the lease is entitled to lives beside the push ({@link workBranchLease}); the
+      // warn is here, because a withheld lease is how a rewrite this pass cannot claim fails the
+      // push it is about to make, and the run's log is where that is read.
+      const lease = await workBranchLease({
+        dir,
+        branch: spec.pushBranch,
+        baseSha,
+        publishedSha,
+        signal,
+        onWithheld: (probe) =>
+          logger.warn('coding-agent: push lease withheld, the branch dropped its pre-run tip', {
+            baseSha,
+            publishedSha,
+            probe,
+          }),
+      })
+      publishedSha = await pushBranch(dir, spec.pushBranch, spec.ghToken, signal, lease)
     })().finally(() => {
       pushInFlight = null
     })

package/src/failure.ts

@@ -26,6 +26,12 @@
  *                           went quiet, this one says the model rabbit-holed while streaming.
  *  - `agent`              — the agent ran but produced an unusable/failed result, or threw.
  *  - `git`                — a git operation failed (clone/push/merge/PR).
+ *  - `branch-contended`:    a push to the work branch was REFUSED because the branch carries
+ *                           commits this push would drop (a second writer, or a rewrite of an
+ *                           earlier run's history). Split out of `git` because it is the one git
+ *                           fault the ENGINE can recover from on its own: re-dispatching the step
+ *                           resumes the branch as it now stands, where every other `git` failure
+ *                           would only fail again.
  *  - `api`                — an upstream API call failed (e.g. the GitHub/GitLab PR/MR REST call).
  *  - `llm-upstream`       — the model provider rejected every call (auth/quota/rate-limit) and Pi
  *                           exhausted its retries, so the run never produced a result.
@@ -38,6 +44,7 @@ export const FAILURE_CAUSES = [
   'no-tool-progress',
   'agent',
   'git',
+  'branch-contended',
   'api',
   'llm-upstream',
   'no-usable-output',

package/src/git.ts

@@ -112,6 +112,69 @@ function gitSubcommand(args: string[]): string {
   return args.find((a) => a !== '' && !a.startsWith('-')) ?? 'command'
 }
 
+/**
+ * Why a push to the work branch was REFUSED. Both mean the branch carries commits this push
+ * would drop, and git tells them apart by whether our object database HOLDS the tip the remote
+ * reports: it does for a tip our own checkout created, so the two are distinguishable and need
+ * different remedies (see {@link PUSH_REJECTION_REMEDIES}).
+ *
+ *  - `local-rewrite`: we HAVE the remote's tip and are no longer descended from it, i.e. this
+ *    checkout amended / reset / rebased a commit that had already been pushed. Git labels it
+ *    `(non-fast-forward)`.
+ *  - `remote-writer`: the remote's tip is a commit this checkout has never seen (`(fetch first)`),
+ *    or our lease found the branch moved past what we published (`(stale info)`), so a SECOND
+ *    writer owns the branch.
+ */
+export type PushRejection = 'local-rewrite' | 'remote-writer'
+
+/**
+ * Whether `stderr` is a REFUSED push, and which shape. Ordered: the lease/fetch-first shapes are
+ * checked first, because a `(stale info)` refusal also prints the generic "failed to push some
+ * refs" line the non-fast-forward shape shares. Pure, so both branches are unit-tested against
+ * real git output rather than inferred.
+ */
+export function classifyPushRejection(stderr: string): PushRejection | undefined {
+  // A HOST-side refusal is not contention, and re-dispatching cannot help: branch protection, a
+  // pre-receive hook or a token policy is declining the write itself, and GitHub's protected-branch
+  // message says "refusing to allow a non-fast-forward push", which would otherwise read as a
+  // rewrite. Git's own labels separate the two cleanly (`! [remote rejected]` is the server
+  // declining, `! [rejected]` is git's own fast-forward/lease check), so such a failure stays a
+  // plain `git` fault with the write-access remedy below.
+  if (/remote rejected|protected branch|hook declined|refusing to allow/i.test(stderr)) {
+    return undefined
+  }
+  if (/\(stale info\)|\(fetch first\)|remote contains work that you do not/i.test(stderr)) {
+    return 'remote-writer'
+  }
+  if (
+    /\(non-fast-forward\)|tip of your current branch is behind|branch tip is behind/i.test(stderr)
+  ) {
+    return 'local-rewrite'
+  }
+  return undefined
+}
+
+/**
+ * The remedy each {@link PushRejection} earns. A `Record`, so a new rejection shape cannot be
+ * classified without saying what a human should do about it. Neither is "run `git pull`", which is
+ * what git's own hint advises and is advice for a person at a terminal, not for an autonomous run.
+ */
+const PUSH_REJECTION_REMEDIES: Record<PushRejection, string> = {
+  'local-rewrite':
+    'The push was refused because the commit it publishes is not descended from the one the work ' +
+    'branch already holds: this checkout rewrote history that had already been pushed (an amend, ' +
+    "reset or rebase of an existing commit). The platform checkpoint-pushes the agent's commits " +
+    'while it works and lets a run force over its OWN published checkpoint, so what stays refused ' +
+    'is a rewrite it cannot attribute to this pass: commits an earlier run published, or a rewrite ' +
+    'that dropped the branch tip this pass started from. The engine re-dispatches the step to ' +
+    'resume from the branch as it stands; work already on the branch is never dropped.',
+  'remote-writer':
+    'The push was refused because another writer advanced this work branch while the run was ' +
+    'working (a second dispatch for the same block, or a person pushing to it). Nothing is lost: ' +
+    "the other writer's commits stay on the branch and the engine re-dispatches the step so the " +
+    'agent resumes on top of them. If it recurs, check whether two runs are active for the same block.',
+}
+
 /**
  * Classify the common shapes of git's own stderr into an actionable remedy, else undefined
  * (an unrecognized failure keeps just its raw stderr). This is the FIRST-WRAP-POINT for
@@ -123,6 +186,10 @@ function gitSubcommand(args: string[]): string {
  */
 export function describeGitFailure(stderr: string): string | undefined {
   const s = stderr.toLowerCase()
+  // A refused push first: its stderr carries neither an auth nor an access shape, so a miss here
+  // would leave the operator git's own "use 'git pull' before pushing again" hint and nothing else.
+  const rejection = classifyPushRejection(stderr)
+  if (rejection) return PUSH_REJECTION_REMEDIES[rejection]
   // Rate-limit / abuse-detection first: the host returns these as a 403, which would
   // otherwise fall into the write-access shape below and be mislabeled as a permission
   // problem — but the fix is to wait, not to grant access.
@@ -200,13 +267,24 @@ function gitFailure(err: unknown, args: string[], aborted: boolean): HarnessFail
   }
   const stderr = typeof e?.stderr === 'string' ? e.stderr : (e?.stderr?.toString() ?? '')
   const base = e instanceof Error ? e.message : String(err)
-  const combined = stderr.trim() ? `${base}\n${stderr.trim()}` : base
-  // Append a cause + fix for the recognized auth/access shapes, keeping the raw (scrubbed)
-  // stderr above it as the detail. The remedy is static text with no secrets, so it is added
-  // after redaction.
+  // `execFile` builds its rejection message as `Command failed: <cmd>\n<stderr>`, so for the
+  // ordinary non-zero exit the stderr is ALREADY in `base`, and appending it again printed every
+  // git failure's output twice, which reads as two attempts. Append only what `base` lacks
+  // (a killed/other rejection whose message carries no output).
+  const tail = stderr.trim()
+  const combined = tail && !base.includes(tail) ? `${base}\n${tail}` : base
+  // Append a cause + fix for the recognized auth/access/push-rejection shapes, keeping the raw
+  // (scrubbed) stderr above it as the detail. The remedy is static text with no secrets, so it is
+  // added after redaction.
   const remedy = describeGitFailure(combined)
   const message = remedy ? `${redactSecrets(combined)}\n${remedy}` : redactSecrets(combined)
-  const failure = new HarnessFailure('git', message)
+  // A REFUSED push is not a generic `git` fault: the branch moved under this run, which the engine
+  // recovers from by re-dispatching the step onto the branch as it now stands. It gets its own
+  // structured cause so that recovery keys off a classification rather than this message.
+  const failure = new HarnessFailure(
+    classifyPushRejection(combined) ? 'branch-contended' : 'git',
+    message,
+  )
   if (e?.stack) failure.stack = redactSecrets(e.stack)
   return failure
 }
@@ -1054,20 +1132,145 @@ export async function fetchPullRequestHead(opts: {
 }
 
 /**
- * Push the work branch to origin. The remote URL carries only the username, so
- * the token is supplied here via the askpass env (never in argv).
+ * Push the work branch to origin and return the sha it PUBLISHED. The remote URL carries only the
+ * username, so the token is supplied here via the askpass env (never in argv).
+ *
+ * The push names an explicit SOURCE COMMIT (`<sha>:refs/heads/<branch>`) rather than the branch,
+ * which is what makes the return value exact rather than a guess. The agent commits while this
+ * runs, so `git push origin <branch>` publishes whatever the branch ref holds at the moment git
+ * reads it, and a caller that leases against a sha it read either side of that has leased against
+ * the wrong commit. Reading it back from `refs/remotes/origin/<branch>` afterwards is worse than
+ * inexact, it is EMPTY on the production checkout: a fresh coding run clones one branch
+ * (`cloneRepo`), so the remote's fetch refspec covers the base alone and `git push` creates no
+ * tracking ref for the work branch at all. Naming the sha needs no ref and no round trip.
+ *
+ * `-u` goes with it: with a non-branch source git sets no upstream config (verified), nothing in
+ * the harness reads that config, and the agent is told never to push or pull.
+ *
+ * `expectRemoteSha` turns the push into a LEASED force (`--force-with-lease=<branch>:<sha>`), which
+ * is how a run whose own checkpoint push it has since rewritten still lands. It is deliberately NOT
+ * a plain `--force`: the lease succeeds only while the remote still holds the sha THIS run
+ * published, so a second writer's commits refuse the push (`(stale info)`) instead of being
+ * clobbered. Callers therefore pass only a sha this same pass published; leasing against a tip we
+ * merely CLONED would force over an earlier run's work.
  */
 export async function pushBranch(
   dir: string,
   branch: string,
   ghToken: string,
   signal?: AbortSignal,
-): Promise<void> {
-  await git(['push', '-u', 'origin', branch], {
+  opts: { expectRemoteSha?: string } = {},
+): Promise<string> {
+  const sha = (
+    await git(['rev-parse', '--verify', `refs/heads/${branch}`], { cwd: dir, signal })
+  ).trim()
+  const lease = opts.expectRemoteSha ? [`--force-with-lease=${branch}:${opts.expectRemoteSha}`] : []
+  await git(['push', ...lease, 'origin', `${sha}:refs/heads/${branch}`], {
     cwd: dir,
     signal,
     env: await authEnv(ghToken),
   })
+  return sha
+}
+
+/**
+ * Whether `sha` is still reachable from `branch`'s tip, i.e. the branch CONTAINS it:
+ * `git rev-list --count --max-count=1 <sha> --not refs/heads/<branch>` is 0 when everything
+ * reachable from `sha` is reachable from the branch too (the tip itself counts as contained).
+ *
+ * Phrased as a rev-list rather than `merge-base --is-ancestor` on purpose: the latter answers "no"
+ * by EXITING 1, which is indistinguishable here from a broken checkout, and this probe's whole job
+ * is to be trusted only when it is a definite answer. Tri-state for the same reason (as
+ * {@link branchAheadOfBase} is):
+ *
+ *  - `true`: confirmed contained.
+ *  - `false`: confirmed dropped, so the branch was rewritten below `sha`.
+ *  - `undefined`: could not determine (an unknown object, a rev-list error). A caller must not read
+ *    a failed probe as either answer.
+ *
+ * The work-branch lease is gated on this: see {@link workBranchLease}.
+ */
+export async function branchContainsCommit(
+  dir: string,
+  branch: string,
+  sha: string,
+  signal?: AbortSignal,
+): Promise<boolean | undefined> {
+  try {
+    const out = await git(
+      ['rev-list', '--count', '--max-count=1', sha, '--not', `refs/heads/${branch}`],
+      { cwd: dir, signal },
+    )
+    const count = Number(out.trim())
+    return Number.isNaN(count) ? undefined : count === 0
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The work branch's tip when it holds something UNPUBLISHED, else undefined: the answer to whether a
+ * checkpoint tick has anything to do. Two ways of having nothing:
+ *
+ *  - the tip is still `baseSha`, so this pass has committed nothing. Pushing here would create the
+ *    work branch at the base commit, and a later retry would see that zero-diff branch via
+ *    `remoteBranchExists`, resume it as work, and fail to open a PR ("no commits between base and
+ *    head"). A pass that never commits must leave NO branch behind.
+ *  - the tip is `publishedSha`, so the last push already published it. Without this the checkpoint
+ *    re-pushed an unchanged branch on every tick: an hour-long run committing eight times issued
+ *    ~60 pushes, ~52 of them a full authenticated round trip answering "Everything up-to-date",
+ *    each one counting against the host's push rate limits.
+ *
+ * That second condition is also what keeps the INTERVAL the right knob. It expresses the acceptable
+ * loss window when a container dies (a property of the deployment's infra churn), not a rate: gated
+ * this way, the tick publishes at most one push per commit the agent makes, whatever the model or
+ * the run's length, so nothing here needs to be tuned per model.
+ */
+export async function unpublishedWorkBranchTip(args: {
+  dir: string
+  /** The branch tip this pass started from. */
+  baseSha: string
+  /** The sha this pass published, if any ({@link pushBranch}'s return). */
+  publishedSha: string | undefined
+  signal?: AbortSignal
+}): Promise<string | undefined> {
+  const head = await headCommit(args.dir, args.signal)
+  if (head === args.baseSha || head === args.publishedSha) return undefined
+  return head
+}
+
+/**
+ * The lease a work-branch push is entitled to (the `opts` {@link pushBranch} takes): the sha this
+ * pass last published, and nothing at all before it has published one.
+ *
+ * The extra condition is what bounds the force to THIS pass's own commits, which the lease alone
+ * does not do and the design promises. Once one checkpoint has landed, a rewrite that drops
+ * `baseSha` (the tip the pass started from, which on a RESUMED branch is an earlier run's published
+ * work) would still lease successfully against our own checkpoint and carry those earlier commits
+ * away with it. So the lease is withheld unless the branch still CONTAINS `baseSha`: the push then
+ * goes out plain, git refuses it as a non-fast-forward, and the engine re-dispatches onto the
+ * branch as it stands.
+ *
+ * A probe that could not answer withholds it too (`onWithheld('unreadable')`), because the two
+ * mistakes are not symmetric: withholding costs a refused rewrite and one re-dispatch, trusting an
+ * unreadable probe costs commits.
+ */
+export async function workBranchLease(args: {
+  dir: string
+  branch: string
+  /** The branch tip this pass started from. */
+  baseSha: string
+  /** The sha this pass published, if any (`pushBranch`'s return). */
+  publishedSha: string | undefined
+  signal?: AbortSignal
+  /** Told why the lease was withheld, so the harness can log it with its own logger. */
+  onWithheld?: (probe: 'unreadable' | 'dropped') => void
+}): Promise<{ expectRemoteSha?: string }> {
+  if (!args.publishedSha) return {}
+  const contains = await branchContainsCommit(args.dir, args.branch, args.baseSha, args.signal)
+  if (contains === true) return { expectRemoteSha: args.publishedSha }
+  args.onWithheld?.(contains === undefined ? 'unreadable' : 'dropped')
+  return {}
 }
 
 /**