@cat-factory/executor-harness 1.114.0 → 1.118.0

package/README.md

@@ -115,6 +115,38 @@ Bootstrap differs at the ends: it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+### The work-branch push is CHECKPOINTED, so it is lease-guarded
+
+Step 8's push is not the run's first: every `JOB_CHECKPOINT_INTERVAL_MS` (60s) the harness pushes
+whatever the agent has committed and NOT yet published, so an evicted container's work survives on
+the branch and a retry resumes on top of it. The interval is a **loss window**, not a push rate:
+`unpublishedWorkBranchTip` skips a tick whose branch tip is already published, so a long run pushes
+once per commit the agent makes rather than once a minute, and nothing here needs tuning per model.
+
+That makes the harness its own competing writer. A commit is published within a minute of being
+made, the agent cannot observe that from inside the container, and amending or resetting it
+afterwards is ordinary git hygiene, so the final push used to be refused as a non-fast-forward and
+failed the whole run with its work already on the branch.
+
+Every push after the first therefore carries `--force-with-lease` against **the sha this pass
+itself published**, never a tip it merely cloned. Two rules make that bound real, and both are
+easy to get wrong:
+
+- **The published sha comes from the push itself** (`pushBranch` names an explicit
+  `<sha>:refs/heads/<branch>` source and returns it), not from `refs/remotes/origin/<branch>`. A
+  fresh coding run clones a single branch, so `git push` creates no tracking ref for the work
+  branch and a lease read back from one never arms at all.
+- **The lease is withheld unless the branch still contains the tip this pass started from**
+  (`workBranchLease`). Once a checkpoint has landed, a rewrite reaching below that tip would lease
+  successfully against our own commit and carry an earlier run's work away with it.
+
+The run's own rewrite lands; a SECOND writer's commits, and a rewrite this pass cannot claim, still
+refuse the push. A refused push is not reported as a generic `git` fault but as the
+`branch-contended` failure cause, which the engine recovers from by re-dispatching the step onto
+the branch as it now stands (bounded by `MAX_BRANCH_CONTENTION_RECOVERIES`, counted as
+`container.branch_contended` and recorded on the step for the debug API). The agents are told the
+matching half of the rule: add commits, never rewrite them (`PLATFORM_DELIVERY_CONTRACT`).
+
 ### Reference designs
 
 A job body for a kind that CAPTURES views (the UI tester, or a deployment's own browser-driven kind)
@@ -296,13 +328,14 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/pi.ts`        | Pi provider config, non-interactive run, JSON-line event + todo-progress parsing, global `AGENTS.md` guidance. |
 | `src/pi-reduction.ts` | Reducing a Pi event stream to what the run PRODUCED (summary, stats, diagnostics, terminal failure), FOLDED as records stream rather than over a retained array — memory is O(largest record), not O(records). The array-taking entry points offline tooling uses are defined in terms of the same reducer. |
 | `src/tool-silence.ts` | The tool-silence watchdog (F13) and the `ToolProgressWindow` an agent stream opens, beats and closes. Separate from the phase marker on purpose: a window is only meaningful while something able to reset it is running. |
-| `src/git.ts`       | clone / branch / commit / push + GitHub PR creation; bootstrap history reset + force-push.              |
+| `src/git.ts`       | clone / branch / commit / push (lease-guarded: [The work-branch push is CHECKPOINTED, so it is lease-guarded](#the-work-branch-push-is-checkpointed-so-it-is-lease-guarded)) + GitHub PR creation; bootstrap history reset + force-push. |
 | `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
 | `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
 | `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
 | `src/package-registries.ts` | Private-registry (npm) auth: renders the job's allowlisted entries into an npmrc; the user `~/.npmrc` in a container, a per-job file pointed at by `npm_config_userconfig` for a native job. |
 | `src/agent-runner.ts` | The subscription-harness runners (`runClaudeCode` / `runCodex`): talk direct to the vendor with a leased OAuth token, lift per-turn usage/telemetry off the CLI event stream. |
 | `src/claude-call-aggregator.ts` | Folds Claude Code's per-CONTENT-BLOCK `stream-json` envelopes back into the model calls they belong to (by `message.id`), reconstructs each call's request transcript, and routes subagent turns off the parent's chain. **Exported as the `./claude-call-aggregator` subpath and driven by the BACKEND too** (`runtimes/local`, for an inline step running on the developer's host `claude`), so it stays the ONE implementation: the per-envelope over-count it fixes inflated a measured 1.47M tokens to 5.53M, and both drivers have to learn that only once. That second driver is why the transcript is retained only to `MAX_TRANSCRIPT_CHARS` (stating what it stopped retaining) and why assembling bodies at all is a `bodies` switch: in a container the reconstruction is one job's memory in a box sized for it, in the backend it is per concurrent inline step in the orchestrator process. Unlike the compile-only `./embed`, this subpath is a `dist` import, which is why the package emits declarations, and why a consumer's typecheck depends on Turbo's `^build` edge having built this package first (see `tsconfig.json`'s `comment:buildOrder`). |
+| `src/usage-attribution.ts` | Reconciles a subscription CLI's TWO token channels: the per-turn usage its stream narrates and the cumulative total its terminal event reports. They disagree routinely and in one direction (Claude Code's per-turn `output_tokens` is the message-START snapshot, single digits), so whatever the turns did not account for becomes ONE extra metric standing for the job (`standsForJob`, filed with a null turn index) rather than tokens grafted onto a real turn, which would make a derived number read as a measured one. Reconciled against the PARENT loop's calls alone, since the terminal cumulative covers only that conversation. |
 | `src/transcript-retention.ts` | Lifts the CLI session transcripts (`projects/` / `sessions/`) out of the isolated, credential-bearing config home before it is deleted, and prunes them on a TTL (debugging artifact retention). |
 | `src/captured-command.ts` | The one way the harness runs a declared shell command on its own behalf: `sh -c` with a per-command watchdog, abort handling, conventional exit codes (124/127/130) and a scrub-then-bound output capture. Shared by both pre-PR verification phases so a fix to one cannot miss the other. |
 | `src/dependency-install.ts` | Dependency prepopulation: `prepopulateDependencies` is the ONE seam every checkout-having mode calls; it runs the service's install command before the agent's first turn, excludes what the install materialised from git so no `git add -A` can sweep a dependency tree into the PR, and builds the prompt note describing the outcome. Best-effort: every failure shape becomes a note, never a failed job. Generic: keyed off the job body, never the agent kind. |

package/dist/agent-runner.js

@@ -3,11 +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, } from './claude-call-aggregator.js';
 import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js';
 import { log } from './logger.js';
 import { NO_TOOL_WINDOW } from './tool-silence.js';
-import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
+import { publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js';
 import { ProgressGuard } from './progress-guard.js';
@@ -19,22 +20,6 @@ import { createSliceTracker, startSubagentWatcher } from './subagents.js';
 import { createTaskPlanTracker, mergeProgress, normalizeStatus, pickProgress, toProgress, todosToProgress, } from './progress.js';
 import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js';
 import { retainSessionTranscripts } from './transcript-retention.js';
-/**
- * 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, usage) {
-    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,
@@ -472,6 +457,59 @@ function openToolWindow(opts) {
 function carriesToolResult(content) {
     return content.some((block) => isObject(block) && block.type === 'tool_result');
 }
+/**
+ * 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, stream) {
+    const calls = [];
+    const parentCalls = [];
+    const publish = (metric) => 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) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -488,34 +526,9 @@ export async function runClaudeCode(opts) {
             bytes: Buffer.byteLength(opts.systemPrompt, 'utf8'),
         });
     }
-    // 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 = [];
-    // 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
     // appear on this stream (as do the subagents' own intermediate turns, tagged with the dispatch
@@ -668,8 +681,7 @@ export async function runClaudeCode(opts) {
             summary,
             stats,
             stderrTail,
-            calls,
-            publisher,
+            capture,
             usage,
             subagents,
             expectSubagentCalls: telemetry.expectsWatcherCalls(),
@@ -678,11 +690,11 @@ export async function runClaudeCode(opts) {
     }
     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
@@ -808,14 +820,11 @@ function buildClaudeEnv(opts, configHome) {
  * loop's telemetry must filter them (`subagentDispatchId`) for this concatenation to hold.
  */
 async function assembleClaudeOutcome(args) {
-    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();
@@ -840,21 +849,6 @@ async function assembleClaudeOutcome(args) {
         ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     };
 }
-function claudeUsage(raw) {
-    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/dist/claude-call-aggregator.d.ts

@@ -157,8 +157,17 @@ 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 declare function createClaudeRunTelemetry(opts: ClaudeStreamTelemetryOptions & {
     watcherOwnsSubagents: boolean;
+    /** Where a SUBAGENT conversation's call goes. Absent ⇒ `publish`, the parent's sink. */
+    publishSubagent?: (metric: HarnessCallMetric) => void;
 }): ClaudeRunTelemetry;
 export {};

package/dist/claude-call-aggregator.js

@@ -311,10 +311,19 @@ function createSubagentStreamTelemetry(opts) {
  * `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) {
     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 {
         onAssistant(dispatchId, message) {

package/dist/coding-agent.js

@@ -1,7 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runCapturedCommand } from './captured-command.js';
-import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, unpublishedWorkBranchTip, workBranchLease, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
 import { PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.js';
@@ -51,24 +51,65 @@ function followUpPollIntervalMs() {
  * 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) {
     const { dir, spec, baseSha, logger, signal } = args;
     let pushInFlight = 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;
     const pushWorkOnce = () => {
         if (pushInFlight)
             return pushInFlight;
         pushInFlight = (async () => {
-            if (!(await branchHasCommitsSince(dir, baseSha, signal)))
+            if (!(await unpublishedWorkBranchTip({ dir, baseSha, publishedSha, signal })))
                 return;
-            await pushBranch(dir, spec.pushBranch, spec.ghToken, signal);
+            // 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/dist/failure.d.ts

@@ -11,13 +11,19 @@
  *                           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.
  *  - `no-usable-output`   — the agent finished but returned no usable report / structured output.
  *  - `no-changes`         — a coding agent finished without producing any change to push.
  */
-export declare const FAILURE_CAUSES: readonly ['inactivity-timeout', 'max-duration', 'no-tool-progress', 'agent', 'git', 'api', 'llm-upstream', 'no-usable-output', 'no-changes'];
+export declare const FAILURE_CAUSES: readonly ['inactivity-timeout', 'max-duration', 'no-tool-progress', 'agent', 'git', 'branch-contended', 'api', 'llm-upstream', 'no-usable-output', 'no-changes'];
 /**
  * See {@link FAILURE_CAUSES}. Derived from the array rather than declared beside it so the two
  * cannot disagree, and so the list is ENUMERABLE at runtime — which is what lets

package/dist/failure.js

@@ -25,6 +25,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.
@@ -37,6 +43,7 @@ export const FAILURE_CAUSES = [
     'no-tool-progress',
     'agent',
     'git',
+    'branch-contended',
     'api',
     'llm-upstream',
     'no-usable-output',

package/dist/git.d.ts

@@ -9,6 +9,27 @@ export declare const NON_INTERACTIVE_CREDENTIAL_ARGS: string[];
  * so it must NOT be reported here as a git timeout. Pure, so the classification is unit-tested.
  */
 export declare function isGitTimeoutKill(err: unknown, aborted: boolean): boolean;
+/**
+ * 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 declare function classifyPushRejection(stderr: string): PushRejection | undefined;
 /**
  * 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
@@ -370,10 +391,104 @@ export declare function fetchPullRequestHead(opts: {
     onSkip?: (reason: string) => void;
 }): Promise<boolean>;
 /**
- * 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 declare function pushBranch(dir: string, branch: string, ghToken: string, signal?: AbortSignal, opts?: {
+    expectRemoteSha?: string;
+}): Promise<string>;
+/**
+ * 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 declare function branchContainsCommit(dir: string, branch: string, sha: string, signal?: AbortSignal): Promise<boolean | 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 declare 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>;
+/**
+ * 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 declare function pushBranch(dir: string, branch: string, ghToken: string, signal?: AbortSignal): Promise<void>;
+export declare 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;
+}>;
 /**
  * Reset the working tree's git history to a single bootstrap commit and push it
  * to the target repository's default branch. Wiping `.git` before re-initialising