@cat-factory/executor-harness 1.114.0 → 1.116.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,7 +328,7 @@ 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.                                                    |

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

package/dist/git.js

@@ -91,6 +91,48 @@ export function isGitTimeoutKill(err, aborted) {
 function gitSubcommand(args) {
     return args.find((a) => a !== '' && !a.startsWith('-')) ?? 'command';
 }
+/**
+ * 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) {
+    // 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 = {
+    '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
@@ -102,6 +144,11 @@ function gitSubcommand(args) {
  */
 export function describeGitFailure(stderr) {
     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.
@@ -154,13 +201,21 @@ function gitFailure(err, args, aborted) {
     }
     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;
@@ -851,15 +906,113 @@ 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, branch, ghToken, signal) {
-    await git(['push', '-u', 'origin', branch], {
+export async function pushBranch(dir, branch, ghToken, signal, opts = {}) {
+    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, branch, sha, signal) {
+    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) {
+    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) {
+    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 {};
 }
 /**
  * Reset the working tree's git history to a single bootstrap commit and push it

package/package.json

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

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 {}
 }
 
 /**