omp-conductor 0.15.2 → 0.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "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 };
 }
 
 /**

package/src/lifecycle.ts

@@ -364,9 +364,19 @@ export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<StopRe
  * Same ownership rule as {@link stopDaemon}: when the unit owns the live pid,
  * `systemctl restart` is the *only* path — a failed manager call is terminal,
  * never a fallthrough to raw signals. An *unanswered* ownership query is also
- * terminal: "dbus blipped" is not "no unit". Falling back to stop+start is
- * reserved for a confirmed hand-started daemon (no systemd, inactive unit, or
- * a unit whose MainPID is someone else).
+ * terminal: "dbus blipped" is not "no unit". A *failed* installed unit is the
+ * third non-fallthrough: it must be restored through the manager
+ * (`reset-failed` + `start`), because a detached CLI daemon beside a failed
+ * unit is exactly the "restarted, but the fleet is still down" lie this
+ * module exists to prevent (#376). Falling back to stop+start is reserved for
+ * a confirmed hand-started daemon (no systemd, inactive unit, or a unit whose
+ * MainPID is someone else).
+ *
+ * Success is reported only after the service manager is re-probed and proven
+ * to own the daemon: the unit's MainPID must equal the daemon record pid AND
+ * `/healthz` must answer. The manager call returning is not that proof — for
+ * `Type=simple` the unit is active as soon as the process is forked, before
+ * the daemon has bound its port.
  *
  * Returns the record of the process that is now answering `/healthz`.
  */
@@ -379,6 +389,16 @@ export async function restartDaemon(
     throw new Error(ownershipUnknown("restart", ownership.reason));
   }
 
+  if (ownership.kind === "failed") {
+    // An installed unit in failed state: reset the failure record and let
+    // systemd start the service. Never fall through to stopDaemon() +
+    // startDaemon() — that leaves the unit failed while handing the operator
+    // a healthy-looking but unmanaged pid (the 12:17Z incident in #376).
+    // Any manager refusal is terminal; so is unproven ownership afterwards.
+    const record = await restoreFailedUnit(o.timeoutMs);
+    return { previous, record, via: "systemctl" };
+  }
+
   const unitOwns =
     ownership.kind === "active" && (previous === undefined || previous.pid === ownership.pid);
 
@@ -393,26 +413,95 @@ export async function restartDaemon(
     // systemctl restart returns once the new MainPID is up; the pidfile is
     // written by the daemon itself on boot, so wait for that rather than
     // inventing a record from the unit alone.
-    const deadline = Date.now() + READY_TIMEOUT_MS;
-    for (;;) {
-      const rec = livingDaemon();
-      if (rec !== undefined) {
-        const health = await healthCheck(rec.port);
-        if (health.ok) return { previous, record: rec, via: "systemctl" };
-      }
-      if (Date.now() >= deadline) break;
-      await sleep(READY_POLL_MS);
-    }
-    throw new Error(
-      `systemctl restart ${SYSTEMD_UNIT} returned, but the daemon never answered /healthz`,
-    );
+    const record = await waitForOwnedDaemon("restart", o.timeoutMs);
+    return { previous, record, via: "systemctl" };
   }
 
+  // Confirmed unmanaged: no unit, an inactive unit, or a unit whose MainPID
+  // is somebody else. The detached CLI daemon is the only path left.
   await stopDaemon({ timeoutMs: o.timeoutMs });
   const record = await startDaemon({ port: o.port ?? previous?.port, project: o.project ?? previous?.project });
   return { previous, record, via: "cli" };
 }
 
+/**
+ * Restores a failed installed unit through the manager: `reset-failed` then
+ * `start`, and proves the result the same way any managed restart is proven
+ * (see {@link waitForOwnedDaemon}). Refusal or unproven ownership is terminal
+ * — never a fallthrough to the detached CLI daemon.
+ */
+async function restoreFailedUnit(timeoutMs?: number): Promise<DaemonRecord> {
+  const reset = systemctl(["reset-failed", SYSTEMD_UNIT]);
+  if (!reset.ok) {
+    throw new Error(systemctlFailure("reset-failed", reset));
+  }
+  const started = systemctl(["start", SYSTEMD_UNIT]);
+  if (!started.ok) {
+    throw new Error(systemctlFailure("start", started));
+  }
+  return await waitForOwnedDaemon("start", timeoutMs);
+}
+
+/**
+ * Waits for the daemon a manager call was just made to boot, and refuses to
+ * report success until the service manager is proven to own it: the unit's
+ * MainPID must equal the daemon record pid AND `/healthz` must answer. A unit
+ * that went back to `failed` is a confirmed negative and fails fast — waiting
+ * cannot un-fail it. Any other unproven state fails at the deadline with a
+ * diagnostic that names the mismatch, never a bare "not ready".
+ */
+async function waitForOwnedDaemon(verb: "restart" | "start", timeoutMs?: number): Promise<DaemonRecord> {
+  const via = `systemctl ${verb} ${SYSTEMD_UNIT} returned`;
+  const inspect = `systemctl status ${SYSTEMD_UNIT}`;
+  const deadline = Date.now() + (timeoutMs ?? READY_TIMEOUT_MS);
+  for (;;) {
+    const rec = livingDaemon();
+    const ownership = probeUnit();
+    if (rec !== undefined && ownership.kind === "active" && ownership.pid === rec.pid) {
+      const health = await healthCheck(rec.port);
+      if (health.ok) return rec;
+    } else if (ownership.kind === "failed") {
+      // A confirmed negative: the start did not take and the unit is failed
+      // again. Waiting longer cannot un-fail it.
+      throw new Error(
+        `${via}, but the unit went back to failed — the daemon is NOT running; check \`${inspect}\``,
+      );
+    }
+    if (Date.now() >= deadline) break;
+    await sleep(READY_POLL_MS);
+  }
+
+  // Failed to prove ownership. Name what is wrong rather than a bare timeout,
+  // so the operator knows whether to fix the unit or hunt the foreign pid.
+  const rec = livingDaemon();
+  const ownership = probeUnit();
+  if (rec === undefined) {
+    throw new Error(
+      `${via}, but no live daemon record appeared — the daemon did not come back; check \`${inspect}\``,
+    );
+  }
+  if (ownership.kind === "active") {
+    if (ownership.pid === rec.pid) {
+      throw new Error(
+        `${via}, but the daemon never answered /healthz on :${rec.port} — ` +
+          `the service manager owns pid ${rec.pid}, but it is not serving; ` +
+          `check \`${inspect}\` and ${rec.logFile}`,
+      );
+    }
+    throw new Error(
+      `${via}, but the unit's MainPID (${ownership.pid}) does not match the daemon record pid (${rec.pid}) — ` +
+        `the reported pid is NOT owned by the service manager; check \`${inspect}\``,
+    );
+  }
+  if (ownership.kind === "unknown") {
+    throw new Error(
+      `${via}, but ownership can no longer be determined (${ownership.reason}) — ` +
+        `cannot confirm the daemon is managed; check \`${inspect}\``,
+    );
+  }
+  throw new Error(`${via}, but the unit is not active; check \`${inspect}\``);
+}
+
 /**
  * What we know about {@link SYSTEMD_UNIT}.
  *
@@ -420,14 +509,22 @@ export async function restartDaemon(
  *   states (`activating`, `deactivating`, `reloading`, `reactivating`) — the
  *   pid is still systemd-owned, so a raw SIGTERM would bounce under
  *   `Restart=on-failure`.
- * - `inactive` — confirmed not running (MainPID absent/0), unit absent, *or*
- *   no `systemctl` binary on this host. Safe to treat as "not supervised here".
+ * - `failed` — the unit is installed and its last activation failed
+ *   (ActiveState=failed, no MainPID). systemd still owns this unit's
+ *   lifecycle, so restoring the daemon must go through the manager
+ *   (`reset-failed` + `start`); classifying a failed unit as "not supervised
+ *   here" is how `restart` launched an unmanaged daemon next to a unit that
+ *   stayed failed (#376).
+ * - `inactive` — confirmed not running (MainPID absent/0, ActiveState not
+ *   `failed`), unit absent, *or* no `systemctl` binary on this host. Safe to
+ *   treat as "not supervised here".
  * - `unknown` — the manager exists (or we cannot tell it does not) but the
  *   query failed: dbus blip, permission, timeout. Must not be collapsed into
  *   `inactive` — that is how a unit-owned daemon gets a raw SIGTERM.
  */
 export type UnitOwnership =
   | { kind: "active"; pid: number }
+  | { kind: "failed" }
   | { kind: "inactive" }
   | { kind: "unknown"; reason: string };
 
@@ -454,26 +551,39 @@ export function probeUnit(unit = SYSTEMD_UNIT): UnitOwnership {
   // live pid (> 1) means systemd still owns that process — including during
   // `activating` / `deactivating` / `reloading`. Filtering on ActiveState here
   // used to label those transitional states "inactive" and hand the pid to a
-  // raw SIGTERM, which is exactly the Restart=on-failure bounce.
+  // raw SIGTERM, which is exactly the Restart=on-failure bounce. The one
+  // place ActiveState decides is the `failed` classification below: with no
+  // MainPID there is no pid to hand to anything, but the unit has not gone
+  // away either.
   const lines = ran.stdout
     .split("\n")
     .map((l) => l.trim())
     .filter((l) => l.length > 0);
   let pid: number | undefined;
+  let activeState: string | undefined;
   for (const line of lines) {
     if (/^\d+$/.test(line)) {
       const n = Number(line);
       if (Number.isInteger(n) && n > 1) pid = n;
+    } else {
+      activeState = line;
     }
   }
-  if (pid === undefined) return { kind: "inactive" };
-  return { kind: "active", pid };
+  if (pid !== undefined) return { kind: "active", pid };
+  // A failed unit is NOT the confirmed negative `inactive` claims to be: the
+  // unit is installed and the manager still owns its lifecycle, so restoring
+  // the daemon has to go through systemd (`reset-failed` + `start`). Reading
+  // `failed` as "not supervised here" is precisely how #376 ended with a
+  // healthy-looking but unmanaged pid next to a unit that stayed failed.
+  if (activeState === "failed") return { kind: "failed" };
+  return { kind: "inactive" };
 }
 
 /**
  * The MainPID of an *active* {@link SYSTEMD_UNIT}, or `undefined` when the
- * unit is confirmed inactive/absent or when ownership could not be determined.
- * Prefer {@link probeUnit} when the caller must distinguish those two.
+ * unit is confirmed inactive, failed, or absent, or when ownership could not
+ * be determined. Prefer {@link probeUnit} when the caller must distinguish
+ * those two.
  */
 export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
   const ownership = probeUnit(unit);
@@ -490,8 +600,9 @@ export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
  * - `stop` — unit is active and owns `pid` (or there is no pidfile and the
  *   unit is the only candidate). Caller MUST go through systemctl; a failed
  *   manager call is terminal.
- * - `not-ours` — confirmed inactive/absent unit, no systemd binary, or a unit
- *   whose MainPID is someone else. Caller may SIGTERM its own pidfile process.
+ * - `not-ours` — confirmed inactive/failed/absent unit, no systemd binary, or
+ *   a unit whose MainPID is someone else. Caller may SIGTERM its own pidfile
+ *   process (a failed unit owns nothing, so signalling its record is safe).
  * - `unknown` — ownership query failed. Caller MUST NOT signal.
  */
 type SystemdStopDecision =
@@ -502,7 +613,10 @@ type SystemdStopDecision =
 function decideSystemdStop(pid: number | undefined): SystemdStopDecision {
   const ownership = probeUnit();
   if (ownership.kind === "unknown") return { kind: "unknown", reason: ownership.reason };
-  if (ownership.kind === "inactive") return { kind: "not-ours" };
+  // A failed unit owns no process (MainPID 0 — systemd has already reaped or
+  // lost it), so a live record pid is a confirmed "not ours", exactly like an
+  // inactive unit. Restoring the unit is restart's job, not stop's.
+  if (ownership.kind === "inactive" || ownership.kind === "failed") return { kind: "not-ours" };
   if (pid !== undefined && ownership.pid !== pid) return { kind: "not-ours" };
   return { kind: "stop", mainPid: ownership.pid };
 }
@@ -533,11 +647,17 @@ async function runSystemdStop(pid: number, timeoutMs?: number): Promise<void> {
   }
 }
 
-function systemctlFailure(verb: "stop" | "restart", ran: SystemctlResult): string {
+function systemctlFailure(
+  verb: "stop" | "restart" | "reset-failed" | "start",
+  ran: SystemctlResult,
+): string {
   const detail = (ran.stderr.trim() || ran.stdout.trim() || "no output").split("\n")[0] ?? "no output";
+  const guard =
+    verb === "stop" || verb === "restart"
+      ? `refusing to signal a unit-owned daemon (that is how Restart=on-failure turns stop into a bounce)`
+      : `the unit was NOT restored, so the daemon would be unmanaged`;
   return (
-    `systemctl ${verb} ${SYSTEMD_UNIT} failed: ${detail} — ` +
-    `refusing to signal a unit-owned daemon (that is how Restart=on-failure turns stop into a bounce); ` +
+    `systemctl ${verb} ${SYSTEMD_UNIT} failed: ${detail} — ${guard}; ` +
     `fix the unit or run \`systemctl ${verb} ${SYSTEMD_UNIT}\` yourself`
   );
 }

package/src/omp.ts

@@ -398,6 +398,15 @@ const DRAIN_GRACE_MS = 2_000;
 /** How long a disposed child gets to exit before it is signalled. */
 const DISPOSE_GRACE_MS = 5_000;
 
+/**
+ * Thrown by {@link createSession} when the pre-spawn admission gate closes: a
+ * daemon stop landed while the session socket was binding, so the child was
+ * never spawned. The caller maps this to a stopped run, not a failed one —
+ * a shutdown must not charge an attempt against a worker it refused to start
+ * (#374).
+ */
+export class SessionAdmissionClosedError extends Error {}
+
 export interface CreateSessionOptions {
   cwd: string;
   sessionDir?: string;
@@ -430,6 +439,16 @@ export interface CreateSessionOptions {
    * its verb channel to this pid, and a channel accepts nothing until it is bound.
    */
   onSpawn?: (pid: number) => void;
+  /**
+   * Pre-spawn admission gate (#374). Consulted once, immediately after the
+   * socket bind await and immediately before `Bun.spawn` — the last window a
+   * daemon stop can land in before a child exists. A gate that returns false
+   * closes the listener, removes the socket, and throws
+   * {@link SessionAdmissionClosedError} instead of spawning; the run then
+   * settles as stopped rather than adding a worker the shutdown would have to
+   * wait for. Absent, the spawn always proceeds.
+   */
+  maySpawn?: () => boolean;
   /** Child stderr, line by line. Defaults to the process's own stderr. */
   onChildLog?: (line: string) => void;
   startupTimeoutMs?: number;
@@ -505,6 +524,21 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
       resolve();
     });
   });
+  // Pre-spawn admission recheck (#374): SIGTERM/SIGINT can land during the
+  // listen await above — after the daemon's own pre-launch checks and before
+  // this child exists. A closed gate means no child: close the listener,
+  // remove the socket (and, when this side created the directory, the
+  // directory itself — the same cleanup the failure paths below run), and
+  // signal the caller to settle the run as stopped instead of spawning a
+  // worker the shutdown would then have to wait for.
+  if (opts.maySpawn?.() === false) {
+    server.close();
+    rmSync(socketPath, { force: true });
+    if (owned) rmSync(socketDir, { recursive: true, force: true });
+    throw new SessionAdmissionClosedError(
+      "daemon shutdown began while the session socket was binding",
+    );
+  }
   // The socket is the run's own channel, and the daemon's own uid is the only
   // one that speaks on it.
   chmodSync(socketPath, 0o600);

package/src/setup-host.ts

@@ -314,21 +314,49 @@ function tickSearchRoots(project: ProjectConfig): string[] {
  * have been a deliberate per-project choice — it *is* the collision — so it is
  * rewritten; anything else is operator intent and survives untouched.
  */
-function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrite<TickConfig> {
-  let existing: { path: string; config: TickConfig } | undefined;
+/**
+ * This project's tick config, wherever it actually lives. A config stamped for
+ * another project is that project's file: the search roots overlap, and
+ * restamping it here would hand this project's identity to the other fleet's cwd.
+ */
+function findProjectTick(
+  project: ProjectConfig,
+): { root: string; path: string; config: TickConfig } | undefined {
   for (const root of tickSearchRoots(project)) {
     const result = readTickConfig(root);
     if (result.kind === "invalid") {
       throw new Error(`tick config invalid at ${result.path}: ${result.problem}; fix or remove it before setup`);
     }
-    // A config stamped for another project is that project's file: the search
-    // roots overlap, and restamping it here would hand this project's identity
-    // to the other fleet's cwd.
     if (result.kind === "ok" && tickConfigMatchesProject(result.config, project.name)) {
-      existing = { path: result.path, config: result.config };
-      break;
+      return { root, path: result.path, config: result.config };
     }
   }
+  return undefined;
+}
+
+/**
+ * The directory this project's fleet pane runs in, which is **not** always
+ * `workspaceRoot`.
+ *
+ * A fleet that predates per-project roots keeps its `.conductor-tick.json` in the
+ * state dir, and that is the cwd its pane and `FLEET_CWD` already point at. Naming
+ * `workspaceRoot` instead sends `recover.sh` somewhere with no tick config, where
+ * `tick_agent_name` falls back to `fleet` and no longer matches the renamed pane —
+ * silently costing a live project its recovery. Falls back to `workspaceRoot`,
+ * which is where a brand-new project's config is written.
+ */
+export function tickCwdForProject(project: ProjectConfig): string {
+  try {
+    return findProjectTick(project)?.root ?? project.workspaceRoot;
+  } catch {
+    // An invalid config is setup's problem to report, not the handoff's.
+    return project.workspaceRoot;
+  }
+}
+
+function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrite<TickConfig> {
+  const found = findProjectTick(project);
+  const existing = found === undefined ? undefined : { path: found.path, config: found.config };
 
   const armedFile = join(stateDir(), `armed-${project.name}`);
   const path = existing?.path ?? join(project.workspaceRoot, TICK_CONFIG_FILE);

package/src/setup-wizard.ts

@@ -37,6 +37,7 @@ import {
   totalConfiguredWorkers,
   runSetupSmoke,
   SYSTEMD_UNIT_DIR,
+  tickCwdForProject,
   writeHostRuntime,
 } from "./setup-host.ts";
 import { runGraphInstall, runHostInstall } from "./setup-install.ts";
@@ -1639,18 +1640,22 @@ export async function collectSetup(
  */
 export function formatHerdrHandoff(project: ProjectConfig, cfg: ConductorConfig): string {
   const session = process.env["HERDR_SESSION"] ?? "conductor";
-  const cwds = cfg.projects.map((p) => p.workspaceRoot).join(":");
+  // Every entry is the cwd that owns that project's tick config — the directory its
+  // pane runs in — not `workspaceRoot`. They differ on any fleet whose config
+  // predates per-project roots, and recovery keys on the tick config.
+  const paneCwd = tickCwdForProject(project);
+  const cwds = cfg.projects.map((p) => tickCwdForProject(p)).join(":");
   return [
     "herdr handoff (CLI cannot do these — exact herdr argv):",
-    `  1. In session "${session}", create a workspace for project "${project.name}" at its workspaceRoot:`,
-    `       herdr --session ${session} workspace create --cwd ${project.workspaceRoot} --label ${project.name} --no-focus`,
+    `  1. In session "${session}", create a workspace for project "${project.name}" at its fleet cwd:`,
+    `       herdr --session ${session} workspace create --cwd ${paneCwd} --label ${project.name} --no-focus`,
     "     Read root_pane.pane_id from the JSON reply (jq -r '((.result // .).root_pane.pane_id) // empty').",
     `  2. Start omp in that empty pane. The agent NAME must match tick config agentName ("${project.name}"):`,
     `       herdr --session ${session} agent start ${project.name} --kind omp --pane <pane-id>`,
     "     The pane must be at a shell prompt with no agent on it. Never agent-start into a live orchestrator pane.",
     `  3. Point herdr-conductor recovery at every fleet cwd (colon-separated; see #320):`,
     `       FLEET_CWDS=${cwds}`,
-    `     Legacy single-fleet hosts can keep FLEET_CWD=${project.workspaceRoot} until multi-fleet recovery lands.`,
+    `     Legacy single-fleet hosts can keep FLEET_CWD=${paneCwd} until multi-fleet recovery lands.`,
     "  4. Reload the daemon so it serves every configured project:",
     "       omp-conductor restart --now",
     "     (printed, not auto-run, when workers are live or a neighbour was just added)",

package/src/types.ts

@@ -1154,6 +1154,7 @@ export type AdmissionHoldReason =
   | "unsalvaged-wip"
   | "daily-spend-cap"
   | "plan-usage-cap"
+  | "shutting-down"
   | "unroutable:no-repo-label"
   | "unroutable:multiple-repo-labels"
   | "unroutable:unknown-repo";

package/src/upgrade.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import { inspectBriefLayout, type BriefLayout } from "./brief-upgrade.ts";
-import { setPaused, statusSnapshot } from "./daemon.ts";
+import { pauseInstance, setPaused, statusSnapshot } from "./daemon.ts";
 import {
   DEFAULT_HERDR_SESSION,
   fleetLayers,
@@ -52,7 +52,21 @@ export interface UpgradeDeps {
   snapshot(project?: string): { liveWorkers: number };
   layers(project?: string): FleetLayers;
   brief(project?: string): { kind: BriefLayout["kind"]; current: boolean };
-  daemonIdentity(): { running: boolean; project?: string };
+  /**
+   * The daemon the transaction targets, when one is running. `generation`
+   * identifies the exact instance (pid + start time) so a later restart cannot
+   * stop an instance created after the request began (#377).
+   */
+  daemonIdentity(): { running: boolean; project?: string; generation?: string };
+  /**
+   * The durable pause sentinel this fleet currently holds, as an *instance*,
+   * read from one selected file (the per-project sentinel first): who set it,
+   * why, and when that sentinel was created. Two pauses with identical
+   * provenance are still different instances if `since` differs, so a drain
+   * can tell its own sentinel from one a later actor re-created after a
+   * resume lifted it — even when a legacy global sentinel coexists (#377).
+   */
+  pauseState(project?: string): { source: string; reason?: string; since: number } | undefined;
   setPaused(value: boolean, project?: string): void;
   restartDaemon(): Promise<void>;
   sleep(ms: number): Promise<void>;
@@ -91,8 +105,14 @@ export const DEFAULT_DEPS: UpgradeDeps = {
   },
   daemonIdentity: () => {
     const daemon = livingDaemon();
-    return daemon === undefined ? { running: false } : { running: true, project: daemon.project };
+    if (daemon === undefined) return { running: false };
+    return {
+      running: true,
+      project: daemon.project,
+      generation: `${daemon.pid}@${daemon.startedAt}`,
+    };
   },
+  pauseState: (project) => pauseInstance(project),
   setPaused: (v, project) =>
     setPaused(v, { source: "upgrade", reason: "upgrade, draining" }, project),
   restartDaemon: async () => {
@@ -248,9 +268,20 @@ function previousHerdrInstall(source: string): readonly [string, readonly string
   ];
 }
 
-async function waitForDrain(deps: UpgradeDeps, project?: string, deadlineAt?: number): Promise<void> {
+async function waitForDrain(
+  deps: UpgradeDeps,
+  project?: string,
+  deadlineAt?: number,
+  stale?: () => string | undefined,
+): Promise<void> {
   let last = -1;
   while (true) {
+    // A transaction that is no longer the fleet's current intent exits before
+    // it waits on anyone else's workers: a resume lifted its pause or the
+    // daemon it began with was replaced, so there is nothing left to drain
+    // and nothing it may stop (#377).
+    const cancelled = stale?.();
+    if (cancelled !== undefined) throw new Error(cancelled);
     const workers = deps.snapshot(project).liveWorkers;
     if (workers === 0) return;
     if (deadlineAt !== undefined && Date.now() >= deadlineAt) {
@@ -264,10 +295,71 @@ async function waitForDrain(deps: UpgradeDeps, project?: string, deadlineAt?: nu
   }
 }
 
+/**
+ * What a draining restart captured when it began: the restart-owned pause and
+ * the daemon instance it is entitled to stop. Every later fence check compares
+ * live state against this snapshot, so the destructive restart call only ever
+ * acts on the world the request began in (#377).
+ */
+interface RestartBegun {
+  /** The durable pause sentinel this request relies on, proved readable as an instance. */
+  pauseToken: { source: string; reason?: string; since: number };
+  /** The daemon instance the restart targets, with its generation identity. */
+  daemon: ReturnType<UpgradeDeps["daemonIdentity"]>;
+}
+
+/**
+ * Why a draining restart can no longer act, or `undefined` when it still owns
+ * the pause and the daemon generation it began with. The pause check is the
+ * *restart-owned sentinel instance* — `drainAndRestart` proves ownership up
+ * front, so a token that cannot be re-read (sentinel removed, unreadable, or
+ * re-created — even under the same source and reason) means this request's own
+ * pause no longer exists and it must cancel. The generation check is the
+ * later-daemon fence: a daemon created after this request began — by
+ * `restart --now`, a crash-restart, or an operator start — must never be
+ * stopped by it.
+ */
+function restartFenceProblem(
+  deps: UpgradeDeps,
+  project: string | undefined,
+  begun: RestartBegun,
+): string | undefined {
+  if (!deps.layers(project).paused) {
+    return "restart cancelled: dispatch was resumed while the drain was in progress — nothing was restarted";
+  }
+  const owned = deps.pauseState(project);
+  if (
+    owned === undefined ||
+    owned.since !== begun.pauseToken.since ||
+    owned.source !== begun.pauseToken.source ||
+    owned.reason !== begun.pauseToken.reason
+  ) {
+    return "restart cancelled: the restart-owned pause was lifted and replaced while the drain was in progress — nothing was restarted";
+  }
+  const now = deps.daemonIdentity();
+  if (now.running !== begun.daemon.running || (begun.daemon.running && now.generation !== begun.daemon.generation)) {
+    return "restart cancelled: the daemon instance was replaced while the drain was in progress — the newer daemon was left running";
+  }
+  return undefined;
+}
+
 /**
  * Pause, drain, restart, restore — the trusted restart transaction, minus the
  * install/verify steps of {@link upgradeConductor}.
  *
+ * Generation-scoped (#377): the transaction captures the restart-owned pause
+ * and the daemon generation when it begins and revalidates both on every drain
+ * poll and once more immediately before the destructive restart call. A
+ * `resume`, a `restart --now`, or any other action that lifts the pause or
+ * replaces the daemon while the drain waits makes the transaction stale: it
+ * exits nonzero without stopping anything, so a timed-out or disconnected
+ * restart caller cannot leave a delayed stop aimed at a later daemon
+ * generation. The stale transaction restores nothing and leaves whatever
+ * pause the fleet now has exactly as it found it. Ownership is proven up
+ * front: a sentinel that cannot be read as an instance at transaction start
+ * aborts before any drain or restart, because a lock the fence cannot compare
+ * against is a lock the fence cannot protect.
+ *
  * Mirrors the upgrade's fail-closed posture: on ANY throw after the pause the
  * fleet stays paused (no resume in a catch) and the error rethrows, so a
  * systemd-owned restart that fails or a drain that outlives `timeoutMs` cannot
@@ -280,7 +372,26 @@ export async function drainAndRestart(
 ): Promise<void> {
   const initial = deps.layers(o.project);
   if (!initial.paused) deps.setPaused(true, o.project);
-  await waitForDrain(deps, o.project, Date.now() + o.timeoutMs);
+  // The lock must be provable NOW. A pause that cannot be read as an instance
+  // — sentinel malformed or unreadable — would make the whole fence fail open
+  // (nothing to compare against), so the transaction refuses before waiting
+  // on anything it cannot act upon either way.
+  const pauseToken = deps.pauseState(o.project);
+  if (pauseToken === undefined) {
+    throw new Error(
+      "restart cancelled: cannot prove the restart-owned pause — the active pause sentinel is unreadable or malformed; nothing was restarted",
+    );
+  }
+  const begun: RestartBegun = {
+    pauseToken,
+    daemon: deps.daemonIdentity(),
+  };
+  const stale = () => restartFenceProblem(deps, o.project, begun);
+  await waitForDrain(deps, o.project, Date.now() + o.timeoutMs, stale);
+  // The drain completed; the world may have moved on while it did. Re-prove
+  // the pause and the generation an instant before the destructive call.
+  const cancelled = stale();
+  if (cancelled !== undefined) throw new Error(cancelled);
   await deps.restartDaemon();
   if (!initial.paused) deps.setPaused(false, o.project);
 }

package/src/worker.ts

@@ -10,7 +10,7 @@
  * sliding into a merge queue.
  */
 
-import { createSession, disposeSession } from "./omp.ts";
+import { createSession, disposeSession, SessionAdmissionClosedError, type AgentSessionLike } from "./omp.ts";
 import type { ReleaseBlockContext } from "./release-policy.ts";
 import type { Caps, ReleaseShape, ResolvedGrants, RunState } from "./types.ts";
 
@@ -123,6 +123,13 @@ export interface WorkerOpts {
    * exists; absent = no pause surface (tests, one-shot callers).
    */
   onPauseControl?: (control: WorkerPauseControl) => void;
+  /**
+   * Pre-spawn admission gate, forwarded to `createSession` (#374): the daemon
+   * closes it the moment its stop begins, so a stop that lands while the
+   * session socket is binding refuses the spawn and the run settles `stopped`
+   * instead of `failed`. Absent, the spawn always proceeds.
+   */
+  maySpawn?: () => boolean;
 }
 
 /**
@@ -253,20 +260,39 @@ export async function runWorker(
   const now = deps.now ?? Date.now;
   const schedule = deps.schedule ?? scheduleWallClock;
 
-  const session = await deps.createSession({
-    cwd: o.cwd,
-    ...(o.sessionDir === undefined ? {} : { sessionDir: o.sessionDir }),
-    ...(o.model === undefined ? {} : { model: o.model }),
-    // Prevention half of #24: as a worker, structured file tools cannot leave
-    // this worktree, and no release grant can ever reach this session (#122).
-    role: "worker",
-    ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
-    ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
-    ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
-    ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
-    ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
-    ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
-  });
+  let session: AgentSessionLike;
+  try {
+    session = await deps.createSession({
+      cwd: o.cwd,
+      ...(o.sessionDir === undefined ? {} : { sessionDir: o.sessionDir }),
+      ...(o.model === undefined ? {} : { model: o.model }),
+      // Prevention half of #24: as a worker, structured file tools cannot leave
+      // this worktree, and no release grant can ever reach this session (#122).
+      role: "worker",
+      ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
+      ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
+      ...(o.onSpawn === undefined ? {} : { onSpawn: o.onSpawn }),
+      ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
+      ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
+      ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
+      ...(o.maySpawn === undefined ? {} : { maySpawn: o.maySpawn }),
+    });
+  } catch (err) {
+    // The pre-spawn gate closed (#374): a daemon stop landed while the session
+    // socket was binding, so no child was ever created. That is a stop, not a
+    // failure — reporting `failed` here would charge an attempt against a
+    // worker the shutdown refused to start. `onSpawn` was never called.
+    if (err instanceof SessionAdmissionClosedError) {
+      return {
+        state: "stopped",
+        turns: 0,
+        spendUsd: 0,
+        report: "",
+        stoppedReason: "daemon shutdown began before the worker session started",
+      };
+    }
+    throw err;
+  }
 
   // Before the first turn, not after the last: a caller that only learns the
   // transcript path from the result learns it once the run it wanted to watch