omp-conductor 0.15.3 → 0.15.5

package/README.md

@@ -251,10 +251,20 @@ command exits without changing anything when all three surfaces already use that
 release, the Herdr plugin is pinned to its exact `gitHead`, and the brief is
 current.
 
-When a daemon is live, the command drains and restarts its recorded project.
-An explicit `--project` that names a different project is rejected before pause
-or installation, so an operator cannot drain one queue and kill another queue's
-workers.
+The upgrade is host-wide, because everything it replaces is: one daemon serves
+every configured project, so its restart lands on all of them at once. A bare
+`omp-conductor upgrade` therefore drains **every** project's workers and
+refreshes **every** project's brief, and pauses them with the fleet-wide
+sentinel — which leaves any per-project `hold` you set standing when it
+restores dispatch.
+
+`--project` narrows that only when it is truthful to do so. When a live daemon
+recorded a single project, the command drains and restarts that project, and an
+explicit `--project` naming a different one is rejected before pause or
+installation. When the daemon serves every configured project and there is more
+than one, `--project` is rejected too: draining one queue and then restarting
+the shared daemon would kill another queue's workers without ever counting
+them. Re-run without the flag.
 
 Ticks remain in their existing armed or disarmed state, so an ordinary update
 does not halt the exact pane or require another Telegram arm challenge. Progress
@@ -2334,7 +2344,7 @@ omp-conductor help
 | `start` | Start `herdr-fleet.service` when that optional unit is installed, clearing a previous pane-recovery pin, then spawn the dispatch loop in the background and wait until it answers `GET /healthz` on `:8787`. Without systemd or that unit it keeps the standalone daemon behaviour. It never clears pause or arms ticks. Refuses if a daemon is already live, naming its pid; if the process dies or never serves, it cleans up and quotes the tail of `daemon.log`. |
 | `stop` | Prefer `systemctl stop omp-conductor.service` when that unit's MainPID is the live daemon — systemd then owns the stop and will not schedule a restart for the exit it just requested. Otherwise `SIGTERM`, then `SIGKILL` after a 10-second grace period. Prints `not running` when there is nothing to stop, and tags the confirmation with `(via systemctl)` when the unit path was used. |
 | `restart [--now] [--timeout SECONDS] [--port N] [--project NAME]` | Drains the fleet by default: pause new claims, wait until live workers reach `0 / N` (bounded by `--timeout SECONDS`, default 1800 = 30 min), restart, then restore the prior dispatch state. Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; otherwise `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them. `--now` skips the drain and restarts immediately, orphaning any live runs (old behaviour). A drain that hits `--timeout` restarts nothing and leaves dispatch paused — `omp-conductor resume` lifts it, or re-run `restart` to keep waiting. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
-| `upgrade [--to VERSION] [--project NAME]` | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
+| `upgrade [--to VERSION] [--project NAME]` | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. Host-wide by default: one daemon serves every configured project, so a bare run drains all of them and refreshes every brief. `--project` is rejected when the live daemon serves several projects — draining one queue and restarting the shared daemon would kill another's workers. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
 | `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, bounded hold groups, and the GitHub API budget (`graphql` / `core` remaining and reset, in the caps block); API failures are marked `DEGRADED` so queue starvation cannot look idle. Active-run lines overlay cooperative worker `paused`/`pausing` from `/healthz` without changing SQLite `running` state or the live worker count. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
 | `ledger [--issue N] [--limit N]` | The action audit: every [mediated-verb](#the-mediated-verbs-126) mutation and every next-attempt turn budget. Verb entries include the arguments, decision, named refusal, and resulting SHA. Turn-budget entries remain after an override is replaced or consumed. Reads (`conductor_pr_status`) are absent so polling cannot bury the signal. `--issue` narrows both histories; `--limit` defaults to 50. Recent verb refusals and pending turn overrides also appear in `status`. |
 | `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, the last 24 hours of Merged and Settled, and Parked (an issue the tracker has not confirmed closed — still open, or a label read that failed — so nothing dispatches it until a human labels it). Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.15.3",
+  "version": "0.15.5",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/cli.ts

@@ -155,7 +155,9 @@ usage:
            that hits --timeout restarts nothing and leaves dispatch paused. On boot
            the new process salvages dirty live worktrees before orphaning those
            rows — see README "Deploying a new package onto a busy fleet". Goes
-           through systemctl when the unit owns the live pid.
+           through systemctl when the unit owns the live pid; a failed
+           installed unit is reset and restarted through systemd, never
+           replaced by an unmanaged daemon.
   status   layered fleet report: dispatch (running|paused|stopped), ticks and
            next due time, pane, herdr, Telegram bot/API health, daemon, caps
            and active runs.
@@ -682,7 +684,10 @@ try {
         // Inherit the running daemon's port and project: a restart that quietly
         // moved to the default port would leave every existing health check
         // pointing at nothing. When the unit owns the live pid, restartDaemon
-        // goes through systemctl so the replacement stays supervised.
+        // goes through systemctl so the replacement stays supervised; a failed
+        // installed unit is reset and started through systemd the same way and
+        // is never replaced by an unmanaged daemon. Success is only reported
+        // after the manager is proven to own the reported pid.
         const { previous, record, via } = await restartDaemon({
           port: portFlag(argv),
           project: projectFlag,

package/src/daemon.ts

@@ -171,11 +171,25 @@ export interface DaemonOpts {
  *  model or caps — `handleIssue` destructures them at dispatch time. The rest
  *  are resolved once at startup so a tick never re-reads config mid-flight and
  *  changes its own limits underneath itself. */
+export interface DrainSignal {
+  draining: boolean;
+}
+
 interface Deps {
   project: ProjectConfig;
   caps: Caps;
   tracker: Tracker;
   store: Store;
+  /**
+   * Set true the moment a daemon stop (SIGTERM/SIGINT) begins. The run loop
+   * only sees `stopping` between whole ticks, so a pass that was already in
+   * flight when the stop landed must re-check this flag itself — before it
+   * claims and before it launches — or it creates exactly the work the
+   * shutdown is about to wait for and then lose to the stop timeout (#374).
+   * Optional only so tests that never exercise shutdown can omit it;
+   * `runDaemon` always wires the real one.
+   */
+  drain?: DrainSignal;
   /** False after a live config reload fails; autonomous delivery then holds
    * fail-closed until a later tick validates the config again. */
   deliveryPolicyValid?: boolean;
@@ -444,6 +458,40 @@ export function pauseProvenance(
   }
 }
 
+/**
+ * One pause sentinel read as a single identity: who set it, why, and the
+ * creation instant, all from the SAME file that was selected. Unlike pairing
+ * {@link pauseProvenance} with {@link pausedAt} — which can describe
+ * different files when a project pause coexists with the legacy global
+ * sentinel, letting a stale global timestamp mask a recreated project pause —
+ * this reads provenance and timestamp from one sentinel, so a caller can prove
+ * "the pause I set still exists" instead of "some pause with the same labels
+ * still exists" (#377). Per-project sentinel wins, like {@link pauseProvenance}.
+ */
+export function pauseInstance(
+  project?: string,
+): { source: string; reason?: string; since: number } | undefined {
+  const paths =
+    project === undefined
+      ? [pausedPath()]
+      : [pausedPath(project), pausedPath()];
+  const path = paths.find((candidate) => existsSync(candidate));
+  if (path === undefined) return undefined;
+  try {
+    const [line1, line2] = readFileSync(path, "utf8").split("\n");
+    const since = Date.parse(line1?.trim() ?? "");
+    if (!Number.isFinite(since)) return undefined;
+    if (line2 === undefined) return undefined;
+    const match = /^source=(\S+)(?: reason="(.*)")?$/.exec(line2.trim());
+    if (match === null) return undefined;
+    const source = match[1]!;
+    const reason = match[2];
+    return { source, since, ...(reason === undefined ? {} : { reason }) };
+  } catch {
+    return undefined;
+  }
+}
+
 export function setPaused(
   v: boolean,
   why?: { source: string; reason?: string },
@@ -1309,7 +1357,65 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
     return true;
   };
 
+  /**
+   * The daemon-wide stop fence can land after the claim but before `runWorker`
+   * exposes its controller — the same window `settleStopBeforeSession` closes
+   * for a per-run operator stop, entered from the shutdown path instead of the
+   * pause control. Settle identically (close the claim, never launch) so the
+   * drain waits only for workers admitted before the stop request, and the
+   * shutdown cannot extend its own workload (#374).
+   */
+  const settleDrainBeforeSession = async (): Promise<boolean> => {
+    if (d.drain?.draining !== true || run === undefined || workerSessionInstalled) return false;
+    turnLimit?.close();
+    turnLimit = undefined;
+    const settlement =
+      worktreePath === undefined
+        ? undefined
+        : await settleWorktree({
+            issue,
+            attempt,
+            ending: "daemon shutdown began while the run was being prepared",
+            worktree: worktreePath,
+            branch,
+            publish,
+            tree: "remove",
+            mirrorPath,
+          });
+    recordOperatorStop(store, {
+      project: project.name,
+      issue,
+      runId: run.id,
+      inProgress,
+      reason: "daemon shutdown began after the claim",
+      patch: {
+        endedAt: Date.now(),
+        turns: run.turns,
+        spendUsd: run.spendUsd,
+        worktree: worktreePath ?? run.worktree,
+        report: [
+          "Daemon shutdown began while this run was still being prepared; the worker",
+          "never started and the claim was closed so the shutdown could complete.",
+          ...(settlement?.lines ?? []),
+        ].join("\n"),
+        ...settlement?.patch,
+      },
+    });
+    log(`#${issue} not launched: daemon shutdown began after the claim`);
+    return true;
+  };
+
   try {
+    // The claim-side of the stop fence (#374): the run row is the boundary the
+    // shutdown drain waits on, so the claim itself refuses once the daemon is
+    // draining. The tick re-checks before the dispatch tail; this covers the
+    // same fence for any caller that reaches `handleIssue` without one, and
+    // makes "no post-stop run rows" a property of the claim, not of its caller.
+    if (d.drain?.draining === true) {
+      log(`#${issue} not claimed: daemon is draining`);
+      return;
+    }
+
     // Claim on the STORE first, before anything that can fail. The run row —
     // not the label — is the crash-safe guard against double dispatch: rows
     // are local, written before any network call, and the startup orphan
@@ -1351,6 +1457,7 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
     turnLimit = d.turnLimits.open(project.name, issue, runId, maxTurns);
     workerControl = d.workerControls.open(project.name, issue, runId);
     if (await settleStopBeforeSession()) return;
+    if (await settleDrainBeforeSession()) return;
 
     // A run's tree is <workspaceRoot>/<issue> and addRunRepo refuses to reuse
     // an existing path, so a retry — or a tree kept from a failed attempt — has
@@ -1360,6 +1467,7 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
     // would cost a second network fetch per attempt.
     await removeWorktree(mirrorPath, worktreePathFor(project.workspaceRoot, issue));
     if (await settleStopBeforeSession()) return;
+    if (await settleDrainBeforeSession()) return;
     const provisioned = await addRunRepo(
       r.repo,
       project.mirrorRoot,
@@ -1370,6 +1478,7 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
     worktreePath = provisioned.path;
     runRepo = { repo: r.repo, runRepoPath: worktreePath, branch };
     if (await settleStopBeforeSession()) return;
+    if (await settleDrainBeforeSession()) return;
 
     // The SDK names the transcript itself, so the daemon supplies the parent
     // directory and learns the real path back from the result. Inventing one
@@ -1409,6 +1518,7 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
       { ...(d.verbPeerReader === undefined ? {} : { peerReader: d.verbPeerReader }) },
     );
     if (await settleStopBeforeSession()) return;
+    if (await settleDrainBeforeSession()) return;
 
     store.updateRun(runId, { worktree: worktreePath, state: "running" });
 
@@ -1425,6 +1535,7 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
         : {}),
     });
     if (await settleStopBeforeSession()) return;
+    if (await settleDrainBeforeSession()) return;
 
     const repoSlug = githubRepo(r.repo.cloneUrl);
 
@@ -1470,6 +1581,12 @@ export async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<
         // and a path written at completion is a path nobody can follow live. The
         // completion-time update below writes the same value again, harmlessly.
         onSessionFile: (f) => store.updateRun(runId, { sessionFile: f }),
+        // The last fence (#374): every pre-launch settle check above has
+        // passed, but the stop can still land while the session socket is
+        // binding inside `createSession`. This gate is re-checked there,
+        // immediately before the child spawn, and closes the run as stopped
+        // instead of launching a worker the shutdown would have to wait for.
+        maySpawn: () => d.drain?.draining !== true,
       }, d.workerDeps);
     } finally {
       // This is the authoritative settlement edge for `extend`: close before
@@ -3273,6 +3390,21 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   }
 
   const pass = await admitCandidates(d, routed, slots);
+
+  // The stop fence (#374): the run loop only re-reads `stopping` between
+  // whole ticks, so a pass already in flight when SIGTERM/SIGINT landed must
+  // re-check the drain signal here — after candidate admission, before any
+  // claim or launch — or the shutdown path admits exactly the work it is
+  // about to wait for and then loses to the stop timeout. The candidates keep
+  // their queue labels; the next daemon start re-dispatches them.
+  if (d.drain?.draining === true) {
+    recordDispatch(0, [
+      ...routingHolds,
+      ...pass.holds,
+      ...pass.admitted.map((a) => ({ issue: a.r.issue.number, reason: "shutting-down" as const })),
+    ]);
+    return;
+  }
   recordDispatch(pass.admitted.length, [...routingHolds, ...pass.holds]);
 
   if (pass.admitted.length === 0) return;
@@ -4553,6 +4685,14 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   const alive = livingDaemon();
   const runtimes: ProjectRuntime[] = [];
 
+  // The stop fence (#374): one signal shared by every project's tick.
+  // `stopping` gates the run loop between whole ticks; `drain.draining` is
+  // the same event visible *inside* a tick already in flight, so a pass that
+  // was mid-admission when the stop landed re-checks it before claiming or
+  // launching. Created here, before the loop, so `stop` below and every
+  // project's `Deps` reference the same object.
+  const drain: DrainSignal = { draining: false };
+
   log(`verb transport: ${transportBanner(verbDir, verbPeerReader)}`);
   log(`package integrity baseline: ${integrity.baseline.size} files under ${import.meta.dir}`);
 
@@ -4675,6 +4815,7 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
       caps,
       tracker,
       store,
+      drain,
       deliveryPolicyValid: false,
       usage,
       escalate: (event) => escalator.escalate(event),
@@ -4754,6 +4895,11 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   const stop = (): void => {
     if (stopping) return;
     stopping = true;
+    // Close the admission fence before the loop is told, so a tick already in
+    // flight — parked at an await when the signal landed — sees `draining`
+    // when it resumes and cannot create the work this shutdown is about to
+    // wait for (#374).
+    drain.draining = true;
     log("shutting down after active workers finish");
     wake?.();
   };

package/src/gitops.ts

@@ -112,17 +112,30 @@ export function repoSlugFor(repo: RepoTarget): string {
  * hop that touches the network happens here, so the dispatcher observes the
  * exact sha it recorded.
  *
- * Both hops are fast-forward only and there is no force path anywhere in this
- * package. The fetch refspec deliberately carries **no leading `+`** — that
- * single character is the difference between "advance the mirror's copy of this
- * branch" and "make the mirror's copy whatever the run says it is", and a run
- * repo is the one place in this system that model-executed code fully controls.
- * The push carries no `--force` and no `--force-with-lease`: a lease is still a
- * force, and a rejected push is a decision for a human, not a retry.
+ * The run-repo hop carries **no leading `+`** — that single character is the
+ * difference between "advance the mirror's copy of this branch" and "make the
+ * mirror's copy whatever the run says it is", and a run repo is the one place
+ * in this system that model-executed code fully controls. The push carries no
+ * `--force` and no `--force-with-lease`: a lease is still a force, and a
+ * rejected push is a decision for a human, not a retry.
+ *
+ * The one exception is narrower than it looks. The mirror's copy of a run
+ * branch can be stale in a way that is not the run's fault:
+ * `conductor_pr_update_branch` moves — and on a rewritten history, replaces —
+ * the remote branch server-side after a run's last push, so a continuation
+ * that incorporated the reviewed baseline can propose a head the *live remote*
+ * is an ancestor of while the mirror's old copy is not. That is a legitimate
+ * fast-forward, not a divergence, so when the plain copy is refused this push
+ * reconciles the mirror's remote-tracking ref of the run branch with the live
+ * remote and asks git whether the live head is an ancestor of the proposed
+ * head. Only that proof lets the mirror's copy be refreshed, and the push hop
+ * still re-checks the ancestor relation against the live remote itself.
+ * Everything else is refused carrying the exact proposed and live SHAs so a
+ * real divergence is diagnosable.
  *
  * A rejection — non-fast-forward, protected ref, unauthorised — comes back as a
- * value carrying git's stderr verbatim, because the caller settles the run
- * `failed` on it and a paraphrase is worthless in that report.
+ * value carrying the reason, because the caller settles the run `failed` on it
+ * and a paraphrase is worthless in that report.
  */
 export async function pushRunBranch(
   project: Pick<ProjectConfig, "mirrorRoot">,
@@ -131,24 +144,93 @@ export async function pushRunBranch(
 ): Promise<PushOutcome> {
   const mirror = mirrorPath(project, run.repo);
   const ref = `refs/heads/${run.branch}`;
+  const tracked = `refs/remotes/origin/${run.branch}`;
   const env = credentialedEnv();
 
+  // Copy the run's branch into the mirror, fast-forward only.
   const fetched = await exec(["git", "-C", mirror, "fetch", "--no-tags", run.runRepoPath, `${ref}:${ref}`], { env });
-  if (fetched.code !== 0) {
-    return { ok: false, stderr: scrubUserinfo(fetched.stderr.trim() || fetched.stdout.trim() || `git fetch exited ${String(fetched.code)}`) };
+
+  // The proposed head is read from the run repo itself: when the copy above
+  // was refused, the mirror's copy of the branch is exactly the stale one.
+  const proposedRun = await exec(["git", "-C", run.runRepoPath, "rev-parse", ref], { env });
+  if (proposedRun.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(proposedRun.stderr.trim() || `git rev-parse ${ref} exited ${String(proposedRun.code)}`) };
+  }
+  const proposed = proposedRun.stdout.trim();
+
+  // Reconcile with the live remote before enforcing anything: the ancestry
+  // that decides a fast-forward is the live remote's, not the mirror's copy's
+  // (see the docstring above). ls-remote answers "is the branch published at
+  // all" and "what does GitHub hold" in one call.
+  const liveListed = await exec(["git", "-C", mirror, "ls-remote", "origin", ref], { env });
+  if (liveListed.code !== 0) {
+    return { ok: false, stderr: scrubUserinfo(liveListed.stderr.trim() || `git ls-remote origin ${ref} exited ${String(liveListed.code)}`) };
+  }
+  const live = liveListed.stdout
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .find((line) => line.endsWith(`\t${ref}`))
+    ?.split(/\s+/, 1)[0];
+
+  if (live !== undefined && live !== proposed) {
+    // The branch is published and the run proposes something different. Pull
+    // the live branch's history into the mirror once (which also keeps the
+    // tracked ref a reattach reads fresh), then prove the fast-forward.
+    const reconciled = await exec(["git", "-C", mirror, "fetch", "--no-tags", "origin", `+${ref}:${tracked}`], { env });
+    if (reconciled.code !== 0) {
+      return { ok: false, stderr: scrubUserinfo(reconciled.stderr.trim() || reconciled.stdout.trim() || `git fetch origin exited ${String(reconciled.code)}`) };
+    }
+
+    const isAncestor = await exec(["git", "-C", mirror, "merge-base", "--is-ancestor", live, proposed], { env });
+    if (isAncestor.code === 128) {
+      // git could not perform the check at all (an object it was asked to
+      // resolve is missing, not merely unrelated). That is a failed
+      // verification, not a divergence verdict: refuse with git's own words,
+      // still naming both SHAs so the report carries the mismatch.
+      return {
+        ok: false,
+        stderr: scrubUserinfo(
+          isAncestor.stderr.trim() ||
+            isAncestor.stdout.trim() ||
+            `git merge-base --is-ancestor ${live} ${proposed} exited ${String(isAncestor.code)}`,
+        ),
+      };
+    }
+    if (isAncestor.code !== 0) {
+      // A real divergence: no fast-forward exists, and the mirror is left
+      // exactly where it was. Both SHAs are named so the mismatch is
+      // diagnosable instead of a bare "non-fast-forward".
+      return {
+        ok: false,
+        stderr:
+          `refusing non-fast-forward push of ${run.branch}: the live remote tip ${live} is not an ancestor of ` +
+          `the proposed head ${proposed}. Fetch the live branch and rebase or merge it before pushing again.`,
+      };
+    }
   }
 
-  const resolved = await exec(["git", "-C", mirror, "rev-parse", ref], { env });
-  if (resolved.code !== 0) {
-    return { ok: false, stderr: scrubUserinfo(resolved.stderr.trim() || `git rev-parse ${ref} exited ${String(resolved.code)}`) };
+  if (fetched.code !== 0 && live === undefined) {
+    // The mirror refused the plain copy and there is no published branch to
+    // validate the run's head against: a rewritten branch that was never
+    // published must not rewrite the mirror either. Refuse with git's words.
+    return { ok: false, stderr: scrubUserinfo(fetched.stderr.trim() || fetched.stdout.trim() || `git fetch exited ${String(fetched.code)}`) };
+  }
+  if (fetched.code !== 0) {
+    // The proposed head is a legitimate fast-forward over the live remote (it
+    // equals the live head or the ancestor test above passed), so the only
+    // thing the plain copy refused on was the mirror's own stale copy.
+    // Refresh it; the push below still re-checks against the live remote.
+    const refreshed = await exec(["git", "-C", mirror, "fetch", "--no-tags", run.runRepoPath, `+${ref}:${ref}`], { env });
+    if (refreshed.code !== 0) {
+      return { ok: false, stderr: scrubUserinfo(refreshed.stderr.trim() || refreshed.stdout.trim() || `git fetch exited ${String(refreshed.code)}`) };
+    }
   }
-  const sha = resolved.stdout.trim();
 
   const pushed = await exec(["git", "-C", mirror, "push", "origin", `${ref}:${ref}`], { env });
   if (pushed.code !== 0) {
     return { ok: false, stderr: scrubUserinfo(pushed.stderr.trim() || pushed.stdout.trim() || `git push exited ${String(pushed.code)}`) };
   }
-  return { ok: true, sha };
+  return { ok: true, sha: proposed };
 }
 
 /**