omp-conductor 0.17.0 → 0.18.0

package/src/setup-wizard.ts

@@ -10,37 +10,70 @@
  * prompt's shape and default is a decision worth keeping, so none of them were
  * reworded in the move.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { platform } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import {
+  configBackupDir,
   configPath,
   expandHome,
   findProject,
   loadConfig,
   resolveCaps,
   saveConfig,
+  stateDir,
+  writeConfigRaw,
 } from "./config.ts";
 import { claimedTelegramTopics } from "./escalate.ts";
 import { hostRamBytes, recommendedMaxWorkers, workerOvercommit } from "./host.ts";
 import {
-  prepareConductor,
+  daemonGeneration,
+  isPaused,
+  pausedPath,
+  pauseInstance,
+  pauseSourceToken,
   previewProject,
+  readAdmissionAck,
   setPaused,
+  wakeDaemon,
+  type AdmissionAckRecord,
   type QueuePreview,
 } from "./daemon.ts";
-import { armTicks, telegramStateDir } from "./fleet.ts";
-import { restartDaemon, type RestartResult } from "./lifecycle.ts";
+import { armedMarkerPath, armTicks, fleetLayers, telegramStateDir } from "./fleet.ts";
+import {
+  healthCheck,
+  healthServesProject,
+  livingDaemon,
+  probeUnit,
+  recordPath,
+  restartDaemon,
+  SYSTEMD_UNIT,
+  type RestartResult,
+} from "./lifecycle.ts";
+import { dbPath, liveWorkersReadOnly, openStore, vacuumInto } from "./store.ts";
+import {
+  restartFenceProblem,
+  type DaemonIdentity,
+  type DrainDeps,
+  type RestartBegun,
+  type UpgradeScope,
+} from "./upgrade.ts";
 import { defaultGraphRoot, graphRepos } from "./graph.ts";
 import {
+  capturePathState,
   formatHostRuntimePlan,
   planHostRuntime,
   totalConfiguredWorkers,
+  restorePathState,
   runSetupSmoke,
   SYSTEMD_UNIT_DIR,
   tickCwdForProject,
   writeHostRuntime,
+  type CapturedPathState,
   type HostRuntimePlan,
+  type HostRuntimeWrite,
+  type RestorePathOptions,
   type SetupSmokeResult,
 } from "./setup-host.ts";
 import { runGraphInstall, runHostInstall, type GraphInstallOptions, type InstallOutcome } from "./setup-install.ts";
@@ -52,6 +85,7 @@ import {
 } from "./setup-discover.ts";
 import {
   AMEND_AREAS,
+  ARM_PROOF_CHOICES,
   BASE_FRESHNESS_CHOICES,
   BEHIND_BASE_CHOICES,
   DRAFT_POLICY_CHOICES,
@@ -59,6 +93,7 @@ import {
   POLICY_BRIEF_NAME,
   RELEASE_REQUIREMENT_CHOICES,
   REPORT_SCOPE_CHOICES,
+  REVIEW_STRICTNESS_CHOICES,
   SETUP_DEFAULTS,
   amendChoices,
   answersFromProject,
@@ -68,6 +103,7 @@ import {
   checkTokenScopes,
   createMissingLabels,
   defaultAnswers,
+  deleteCreatedLabels,
   detectTelegram,
   formatGates,
   orchestratorBriefPath,
@@ -86,14 +122,20 @@ import {
   type ProbedProse,
 } from "./setup.ts";
 import {
+  ARM_PROOFS,
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   DEFAULT_CAPS,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
   RELEASE_REQUIREMENTS,
   INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   WEEKDAYS,
   type AuthorityHolder,
   type Caps,
@@ -106,6 +148,7 @@ import {
   type ReleaseRequirement,
   type ReportScopeChoice,
   type ResolvedGrants,
+  type ReviewPolicy,
 } from "./types.ts";
 import { withProgress } from "./ui/progress.ts";
 import type { WizardUi } from "./wizard-ui.ts";
@@ -1334,10 +1377,94 @@ const askAuthorityArea: AreaAsker = async (ui, a, _probes, discovered) => {
 /** What a merge and a release must satisfy. Asked straight after the grants:
  *  who may act, then under what conditions. The release half is only asked
  *  when the orchestrator cuts releases — with humans releasing it has no gates
- *  to configure, so it would be a dead prompt (#368). */
+ *  to configure, so it would be a dead prompt (#368). The arming proof is
+ *  asked after the preconditions: it gates `arm`, not merge or release, but it
+ *  is the same kind of declared policy, so it rides the same area (#613).
+ *
+ * The `claim-only` consequence is stated in the option's own description so an
+ * operator chooses it rather than discovering it: `arm` is already privileged,
+ * and `claim-only` means anything that can invoke it can start dispatch once
+ * the live claim and poller pass.
+ */
+/**
+ * How many review rounds one PR lifecycle may be returned at most — the hard
+ * bound against endless polishing (#678). Validated in the dialog against the
+ * same integer range the loader validates against, so an out-of-range answer
+ * is re-asked rather than written for the daemon to reject. The consequence of
+ * the ceiling is stated in the title: at it, the PR is left open and escalated
+ * once, never returned again.
+ */
+async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
+  // Bounded like askValid above: a dialog that cannot be escaped is worse than
+  // one that gives up and leaves the config alone. The `--answers` path
+  // matters here specifically — answersUi is a map, not a consumer, so every
+  // retry reads the same value and an out-of-range file used to recurse
+  // forever instead of failing closed (#678).
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const raw = await ask(
+      ui,
+      "review-max-rounds",
+      `Review rounds per PR lifecycle — an integer ${REVIEW_MAX_ROUNDS_MIN} to ${REVIEW_MAX_ROUNDS_MAX}; ` +
+        `at the ceiling the PR is left open and escalated once`,
+      String(current),
+    );
+    const value = Number(raw);
+    if (Number.isInteger(value) && value >= REVIEW_MAX_ROUNDS_MIN && value <= REVIEW_MAX_ROUNDS_MAX) {
+      return value;
+    }
+    ui.notify(
+      `Review rounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX} ` +
+        `— shown the current value again.`,
+      "warning",
+    );
+  }
+  throw new Cancelled();
+}
+
+/**
+ * How green PRs are reviewed (#678), asked with the merge preconditions and
+ * the arming proof: they are the same kind of declared policy — a typed,
+ * mechanical boundary on what may happen to a PR — so they ride the same area.
+ *
+ * The three levels and their bars are shown before the select, with the
+ * recommended level marked, so an operator chooses between named thresholds
+ * rather than between three words. The select cursor opens on the current
+ * answer (the configured level on a re-run, the recommended default on a
+ * first run); the rounds are a validated integer within the same range the
+ * loader enforces.
+ */
+async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPolicy> {
+  ui.notify(
+    REVIEW_STRICTNESS.map((level) => `${level}${level === DEFAULT_REVIEW_STRICTNESS ? " (recommended)" : ""} — ${REVIEW_STRICTNESS_CHOICES[level]}`).join(
+      "\n",
+    ),
+    "info",
+  );
+  return {
+    strictness: await askLiteral(
+      ui,
+      "review-strictness",
+      "Review strictness for green PRs",
+      REVIEW_STRICTNESS,
+      REVIEW_STRICTNESS_CHOICES,
+      a.review.strictness,
+    ),
+    maxRounds: await askReviewRounds(ui, a.review.maxRounds),
+  };
+}
+
 const askPolicy: AreaAsker = async (ui, a) => ({
   ...a,
   policy: await askPolicyPreconditions(ui, a.policy, a.authority.release),
+  armProof: await askLiteral(
+    ui,
+    "arm-proof",
+    "Arming — how should `arm` prove a human approved dispatch?",
+    ARM_PROOFS,
+    ARM_PROOF_CHOICES,
+    a.armProof,
+  ),
+  review: await askReviewPolicy(ui, a),
 });
 
 /** How a stuck run reaches a human, and who triages it when it does. */
@@ -1395,14 +1522,25 @@ const askEscalation: AreaAsker = async (ui, a) => {
 /**
  * Forum topic for tier-2 pages. Claimed threads from omp-telegram's
  * `threads.json` are offered when readable; a missing file is silent and the
- * operator can still type an id or keep flat chat (#318).
+ * operator can still type an id or keep flat chat (#318). A registry that is
+ * *present but unreadable* is the opposite: the bridge is in a state the
+ * wizard cannot read, so the manual id would be a guess against unverifiable
+ * state — surface the problem before the fallback instead of silently offering
+ * either (#626).
  */
 async function askTelegramTopicId(
   ui: WizardUi,
   stateDir: string,
   prior: number | undefined,
 ): Promise<number | undefined> {
-  const claimed = claimedTelegramTopics(stateDir);
+  const result = claimedTelegramTopics(stateDir);
+  if (result.kind === "unavailable") {
+    ui.notify(
+      `Cannot offer claimed topics: omp-telegram's claim registry is unreadable (${result.problem}) — check the bridge state before typing a topic id, or keep flat chat`,
+      "warning",
+    );
+  }
+  const claimed = result.kind === "ok" ? result.claims : [];
   const manual = "Enter thread id manually";
   const none = "None — flat chat (0.13 behaviour)";
   if (claimed.length > 0) {
@@ -2027,10 +2165,39 @@ export interface SetupApplyDeps {
   labels: (trackerRepo: string, a: SetupAnswers) => Promise<LabelPlan[]>;
   preview: (project: ProjectConfig) => Promise<QueuePreview>;
   createLabels: (trackerRepo: string, plan: LabelPlan[]) => Promise<string[]>;
+  /**
+   * Compensation half of {@link createLabels}: deletes exactly the labels a
+   * failed apply created, so the tracker returns to its pre-entry state.
+   * Called only on rollback, where a deletion failure is a reported
+   * restoration failure — the orphaned label is named, never silently left
+   * behind (#652).
+   */
+  deleteLabels: (trackerRepo: string, created: string[]) => Promise<void>;
+  /**
+   * Proves a healthy runtime generation serves the COMPLETE prior configured
+   * project set after a failed apply rolled the disk state back (#650). The
+   * surviving entry-generation process predates the rollback: its store
+   * handle points at the file the rollback replaced (writes diverge into the
+   * unlinked inode until its next restart) and its in-memory config may be
+   * the rejected generation — so "proving health" is never the proof. The
+   * default implementation restarts through the same lifecycle seam the
+   * apply's own restart leg uses and then proves /healthz names every prior
+   * project. Returns false when the proof cannot be made — the caller then
+   * stays fail-closed (a setup hold stays in force, with the recovery
+   * command named) rather than resuming dispatch onto an unproven runtime.
+   */
+  proveRuntime: (priorProjects: readonly string[]) => Promise<boolean>;
+  /**
+   * The lifecycle/drain seam the acknowledged quiescence barrier runs on —
+   * the same `DrainDeps` `upgrade`, `restart` and `setup host` use, so the
+   * freeze, its token proof and its staleness checks are the seam's, never a
+   * second counter-only fence (#618). Injectable so a regression can drive
+   * the exact admission interleaving through real barrier code.
+   */
+  drain: DrainDeps;
   smoke: (project: string) => Promise<SetupSmokeResult>;
   restart: (o: { project?: string }) => Promise<RestartResult>;
   arm: (project: string) => Promise<string>;
-  resume: (project: string) => void;
   hostInstall: (
     project: ProjectConfig,
     caps: Caps,
@@ -2044,20 +2211,593 @@ export interface SetupApplyDeps {
   ) => Promise<InstallOutcome>;
 }
 
+/**
+ * The default drain accessors the setup apply barrier runs on, wired exactly
+ * like `setup host`'s (`setup-install.ts`) — except the pause names `setup`
+ * as the actor and the barrier refuses on live workers instead of waiting for
+ * a drain.
+ *
+ * Two deliberate divergences from the drop-in lifecycle accessors, both
+ * because a setup apply owns a *host-global* transaction rather than the one
+ * project a restart drains:
+ *
+ *  - `snapshot` counts live workers through {@link liveWorkersReadOnly}, never
+ *    `statusSnapshot`: the observation that gates the barrier must be
+ *    read-only, because database preparation is itself one of the mutations
+ *    the barrier precedes (#651 review #2).
+ *  - `layers` reports the *global* sentinel's paused flag, not the project
+ *    bare-read `fleetLayers` derives — the barrier freezes the whole host
+ *    through the one global pause sentinel (`scope.pauseKey === undefined`),
+ *    so the fence it must re-prove is that sentinel, never a per-project one
+ *    (#651 review #4).
+ */
+function defaultSetupDrain(): DrainDeps {
+  return {
+    snapshot: (project) => ({ liveWorkers: liveWorkersReadOnly(project) }),
+    layers: () => ({ ...fleetLayers(), paused: isPaused() }),
+    projectNames: () => loadConfig().projects.map((p) => p.name),
+    daemonIdentity: setupDaemonIdentity,
+    pauseState: (project) => pauseInstance(project),
+    setPaused: (v, project) => setPaused(v, { source: pauseSourceToken("setup"), reason: "setup apply fence" }, project),
+    // The daemon-side admission acknowledgement: the file the running daemon
+    // itself writes when it observes the fence at an admission boundary, so
+    // the barrier never mistakes a second synchronous count for the daemon's
+    // own word that it will claim nothing (#651 review #3).
+    admissionAck: () => readAdmissionAck(),
+    sleep: Bun.sleep,
+    log: () => {},
+  };
+}
+
+/**
+ * The daemon identity the setup barrier acknowledges and re-proves: the known
+ * pidfile record when one is live, else an ACTIVE `omp-conductor.service`
+ * unit whose runtime record went missing — a supervised daemon is still a
+ * running daemon without its record, and its MainPID is the generation that
+ * identifies the exact instance (#651, review #2). An UNKNOWN systemd query
+ * throws: "dbus blipped" is not "no daemon", and the barrier must fail closed
+ * rather than acknowledge quiescence it cannot prove.
+ */
+function setupDaemonIdentity(): DaemonIdentity {
+  const ownership = probeUnit(SYSTEMD_UNIT);
+  if (ownership.kind === "unknown") {
+    throw new Error(
+      `cannot prove whether the daemon is running: systemd ownership probe failed (${ownership.reason})`,
+    );
+  }
+  const daemon = livingDaemon();
+  if (daemon !== undefined) {
+    // The record names the exact instance; `daemonGeneration` formats the
+    // same generation the daemon's own admission acknowledgement records, so
+    // the two sides of the acknowledged fence always compare like for like.
+    return { running: true, project: daemon.project, generation: daemonGeneration() };
+  }
+  if (ownership.kind === "active") {
+    // The unit owns a live MainPID but the record is absent (a crash raced a
+    // re-record, an unmanaged start never wrote one): the daemon is running,
+    // and the MainPID is the generation that lets the fence spot a restart.
+    return { running: true, generation: `systemd:${ownership.pid}` };
+  }
+  return { running: false };
+}
+
 export const DEFAULT_APPLY: SetupApplyDeps = {
   scopes: checkTokenScopes,
   labels: planLabels,
   preview: previewProject,
   createLabels: createMissingLabels,
+  deleteLabels: deleteCreatedLabels,
+  proveRuntime: async (priorProjects) => {
+    // No short-circuit on a healthy daemon: whatever process is still
+    // answering predates the rollback, so it holds a handle on the store file
+    // the rollback replaced and may serve the rejected config. Restart
+    // through the same fail-closed lifecycle seam the apply's own restart leg
+    // uses — whose `waitForOwnedDaemon` proves MainPID + /healthz and that a
+    // fresh boot loaded the restored/rolled-back state — then prove the new
+    // generation serves EVERY prior configured project, not just health on
+    // one (#650, PR #700 review #1).
+    try {
+      const restarted = await restartDaemon({});
+      const health = await healthCheck(restarted.record.port);
+      if (!health.ok) return false;
+      return priorProjects.every((project) => healthServesProject(health.body, project));
+    } catch {
+      return false;
+    }
+  },
+  drain: defaultSetupDrain(),
   smoke: runSetupSmoke,
   restart: (o) => restartDaemon(o),
   arm: (project) => ensureSetupArm(project),
-  resume: (project) => setPaused(false, undefined, project),
   hostInstall: (project, caps, telegramStateDir, ui) =>
     runHostInstall(project, caps, telegramStateDir, ui),
   graphInstall: (project, ui, options) => runGraphInstall(project, ui, options),
 };
 
+/** One pause sentinel's pre-entry state, four-valued so absence, readable-valid
+ *  bytes, malformed bytes and unreadability are never conflated.
+ *  - `{ kind: "absent" }` — no file on entry; rollback removes one the barrier
+ *    created.
+ *  - `{ kind: "bytes", bytes }` — readable AND valid on entry; rollback writes
+ *    these bytes back verbatim, so the pre-entry owner token and timestamp
+ *    survive a refused apply instead of being replaced by a fresh equivalent
+ *    pause (#618, continuation #7).
+ *  - `{ kind: "malformed", bytes, path }` — readable but not a valid pause
+ *    instance (an unparseable timestamp or provenance line). This is
+ *    unreadable-as-state: the barrier must fail closed BEFORE changing
+ *    anything and never delete it, because collapsing it to absence would
+ *    remove an operator hold it could not prove (#650).
+ *  - `{ kind: "unreadable", path }` — the file exists but cannot be read. The
+ *    barrier must fail closed BEFORE changing anything: collapsing this to
+ *    absence and later deleting the path would remove an operator hold it
+ *    never saw (#651 review #5). */
+type CapturedPause =
+  | { kind: "absent" }
+  | { kind: "bytes"; bytes: string }
+  | { kind: "malformed"; bytes: string; path: string }
+  | { kind: "unreadable"; path: string };
+
+/** Whether one sentinel's bytes parse as a valid pause instance — the exact
+ *  grammar {@link pauseInstance} reads in `daemon.ts` (a parseable ISO
+ *  timestamp line, then a `source=` provenance line). Readable bytes that
+ *  fail this are an unreadable-as-state malformed hold: valid bytes are
+ *  restored verbatim, malformed ones are refused at entry and never deleted
+ *  (#650). */
+function isValidPauseBytes(bytes: string): boolean {
+  const [line1, line2] = bytes.split("\n");
+  if (!Number.isFinite(Date.parse(line1?.trim() ?? ""))) return false;
+  if (line2 === undefined) return false;
+  return /^source=(\S+)(?: reason="(.*)")?$/.test(line2.trim());
+}
+
+/** Reads one pause sentinel, keeping absence, readable-valid bytes, malformed
+ *  bytes and unreadability apart — never conflated: collapsing malformed to
+ *  absence would let a refusal delete an operator hold it could not parse. */
+function readSentinel(p: string): CapturedPause {
+  if (!existsSync(p)) return { kind: "absent" };
+  try {
+    const bytes = readFileSync(p, "utf8");
+    return isValidPauseBytes(bytes) ? { kind: "bytes", bytes } : { kind: "malformed", bytes, path: p };
+  } catch {
+    return { kind: "unreadable", path: p };
+  }
+}
+
+/**
+ * The pre-entry pause sentinel the setup apply itself can change. Setup
+ * freezes the whole host through the one *global* sentinel — it must never
+ * write a project's pause instead, which left the wrong project held when
+ * adding a neighbour next to a daemon recorded for the existing project
+ * (#651 review #4) — so the captured path is the global one, its scope is
+ * preserved exactly (a successful apply or a refusal restores that same
+ * path's pre-entry bytes, never a project-scoped sentinel), and an entry
+ * that is already paused — valid, malformed or unreadable — fails closed in
+ * its own way rather than being rebuilt or deleted (#650).
+ */
+function capturePause(): CapturedPause {
+  return readSentinel(pausedPath());
+}
+
+/** Restores the sentinel {@link capturePause} captured — but only while the
+ *  sentinel on disk is still the fence THIS transaction froze (the bytes it
+ *  wrote, or the pre-entry hold it inherited). A `resume` or a newer operator
+ *  hold that replaced the setup freeze is a takeover the stale transaction
+ *  must preserve: writing the entry bytes back over it, or removing the file
+ *  it owns, would delete a safety hold a later actor wrote in the meantime
+ *  (#651 review #3). An unreadable or malformed current sentinel is also left
+ *  alone — overwriting what cannot be read (or parsed) is the same
+ *  overwrite-of-the-unseen this guard exists to prevent. Never called with a
+ *  malformed entry state: the barrier fails closed before mutating then; the
+ *  branch exists so a malformed state would still be restored byte for byte
+ *  rather than deleted, never treated as absence. */
+function restorePause(state: CapturedPause, owned: CapturedPause): void {
+  const p = pausedPath();
+  const current = readSentinel(p);
+  // Only this transaction's own fence may be undone. An unreadable or
+  // malformed sentinel is left alone (overwriting what cannot be read or
+  // parsed is overwriting a hold the barrier never saw); a sentinel that no
+  // longer matches the bytes this transaction froze was replaced by a takeover
+  // — a resume or a newer hold — and that takeover stands.
+  let isOwnFence = false;
+  if (current.kind === "bytes" && owned.kind === "bytes") {
+    isOwnFence = current.bytes === owned.bytes;
+  } else if (current.kind === "absent" && owned.kind === "absent") {
+    isOwnFence = true;
+  }
+  if (!isOwnFence) return;
+  if (state.kind === "bytes" || state.kind === "malformed") {
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, state.bytes);
+  } else {
+    rmSync(p, { force: true });
+  }
+}
+
+// -------------------------------------------------- the mutation inventory --
+//
+// Child 2 of the setup-transaction decomposition (#652): before the first
+// mutation the apply records the COMPLETE inventory of every surface it can
+// write — config, briefs, staged units/scripts/tick, the AGENTS link, the run
+// store, the daemon record, the arm marker, the config backups and the
+// tracker labels — with byte-exact pre-entry state. Any later exception or
+// failed smoke restores every one of them (or removes what a first install
+// created), compensates the tracker exactly, and reports the first
+// restoration failure honestly instead of pretending the prior state is
+// coherent. The one surface a rollback never undoes blindly is the pause
+// sentinel: {@link restorePause} keeps child 1's ownership rule — only the
+// fence THIS transaction froze is undone, and a newer actor's hold stands.
+
+/** The run store's pre-entry state: a byte-consistent snapshot when the
+ *  store exists, absence on a first install. */
+interface StoreCapture {
+  path: string;
+  kind: "absent" | "snapshot";
+  snapshotPath?: string;
+}
+
+/** The complete pre-entry mutation inventory of one setup apply (#652). */
+interface SetupInventory {
+  /** `config.json` pre-entry state (bytes, absence, or unreadable). */
+  config: CapturedPathState;
+  /** The pre-entry configured project set — what the prior runtime generation
+   *  must be proven to serve after a rollback restores the config (#650). */
+  priorProjects: string[];
+  /** The brief files the apply will write: `POLICY.md` + `ORCHESTRATOR.md`. */
+  briefs: CapturedPathState[];
+  /** Every staged host-runtime path the apply may write (units, scripts, tick). */
+  runtime: CapturedPathState[];
+  /** The AGENTS.md brief link the apply will create/update, when planned. */
+  briefLink?: CapturedPathState;
+  /** The run store: byte-consistent snapshot when it exists, absence on a first install. */
+  store: StoreCapture;
+  /** The daemon pidfile record the smoke/restart legs write. */
+  record: CapturedPathState;
+  /** The external-heartbeat arm marker, when an external orchestrator is planned. */
+  armMarker?: CapturedPathState;
+  /** Directories the apply may create (workspace/tick cwds), absent at entry;
+   *  rollback removes them only while still empty, so operator content that
+   *  landed in one is never destroyed. */
+  dirs: string[];
+  /** Pre-entry listing of the config backup dir; backups the apply created
+   *  are removed on rollback so the backups return to their entry set. */
+  backups: { dir: string; files: string[] };
+}
+
+/** A byte-consistent pre-entry copy of the run store: VACUUM INTO reads main
+ *  file + WAL as one, so the snapshot holds every committed row even while a
+ *  paused daemon holds a writer handle. The snapshot lives under the state
+ *  dir for the transaction's lifetime and is removed on commit and rollback
+ *  alike; a partial snapshot from a throwing VACUUM is removed immediately,
+ *  never left as a stray temp copy in the state dir (#650, review #2). */
+function captureStore(path: string): StoreCapture {
+  if (!existsSync(path)) return { path, kind: "absent" };
+  const snapshotPath = join(stateDir(), `.conductor.db.setup-${process.pid}.${randomUUID()}.snapshot`);
+  try {
+    vacuumInto(path, snapshotPath);
+  } catch (err) {
+    rmSync(snapshotPath, { force: true });
+    throw err;
+  }
+  return { path, kind: "snapshot", snapshotPath };
+}
+
+/** The backup dir listing, or the empty set when the dir does not exist yet. */
+function readdirIfPresent(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The full pre-entry mutation inventory of one apply, read BEFORE the first
+ * mutation. Throws when any captured path exists but cannot be read: an
+ * unreadable pre-entry path is a fault, never absence — collapsing it would
+ * let a rollback delete state the apply never saw, the same fail-closed rule
+ * the pause sentinel capture already applies (#651 review #5).
+ *
+ * `priorProjectNames` is the pre-entry configured project set (from the
+ * config `setup()` loaded before the interview): the set a failed apply must
+ * prove the restored runtime serves again. It comes from the entry load, not
+ * a post-rollback re-read, so an un-restored config cannot make the proof
+ * measure the wrong set (#650).
+ */
+function captureInventory(
+  plan: DerivedPlan,
+  answers: SetupAnswers,
+  priorProjectNames: string[],
+): SetupInventory {
+  const runtime: CapturedPathState[] = [];
+  const captureIfWritten = (w: { action: string; path: string } | undefined): void => {
+    // Only paths the plan says will actually be written: a `keep` path is
+    // untouched by the apply and needs no pre-entry state.
+    if (w !== undefined && w.action !== "keep") runtime.push(capturePathState(w.path));
+  };
+  captureIfWritten(plan.runtime.service);
+  captureIfWritten(plan.runtime.herdrUnit);
+  captureIfWritten(plan.runtime.herdrConfig);
+  captureIfWritten(plan.runtime.herdrEnv);
+  captureIfWritten(plan.runtime.recoverUnit);
+  captureIfWritten(plan.runtime.recoverScript);
+  captureIfWritten(plan.runtime.tick);
+
+  const briefs = answers.writeOrchestratorBrief
+    ? [policyPathForProject(plan.project), briefPathForProject(plan.project)].map(capturePathState)
+    : [];
+  const briefLink =
+    plan.runtime.briefLink !== undefined &&
+    (plan.runtime.briefLink.action === "create" || plan.runtime.briefLink.action === "update")
+      ? capturePathState(plan.runtime.briefLink.path)
+      : undefined;
+  const record = capturePathState(recordPath());
+  const armMarker =
+    plan.project.escalation.orchestrator === "external"
+      ? capturePathState(armedMarkerPath(plan.project.name))
+      : undefined;
+
+  // Unreadable check across every captured path, before anything is written.
+  const all = [
+    capturePathState(configPath()),
+    ...briefs,
+    ...runtime,
+    ...(briefLink === undefined ? [] : [briefLink]),
+    record,
+    ...(armMarker === undefined ? [] : [armMarker]),
+  ];
+  const unreadable = all.find((c) => c.kind === "unreadable");
+  if (unreadable !== undefined) {
+    throw new Error(
+      `the path ${unreadable.path} exists but could not be read — refusing to start the apply rather than ` +
+        "risk overwriting state it never saw",
+    );
+  }
+
+  // Directories the apply can create (the workspace root via the brief write,
+  // the fleet cwd via the AGENTS link and the tick config). Only absent ones
+  // are recorded; rollback removes them only while still empty.
+  const dirs = new Set<string>();
+  if (answers.writeOrchestratorBrief) dirs.add(dirname(briefPathForProject(plan.project)));
+  if (briefLink !== undefined) dirs.add(dirname(briefLink.path));
+  if (plan.runtime.tick !== undefined && plan.runtime.tick.action !== "keep") {
+    dirs.add(dirname(plan.runtime.tick.path));
+  }
+
+  return {
+    config: all[0]!,
+    priorProjects: priorProjectNames,
+    briefs,
+    runtime,
+    ...(briefLink === undefined ? {} : { briefLink }),
+    store: captureStore(dbPath()),
+    record,
+    ...(armMarker === undefined ? {} : { armMarker }),
+    dirs: [...dirs].filter((d) => !existsSync(d)),
+    backups: { dir: configBackupDir(), files: readdirIfPresent(configBackupDir()) },
+  };
+}
+
+/**
+ * Restores every captured surface on a failed apply (#652): the config and
+ * the backups the apply created, the briefs, the staged runtime files, the
+ * AGENTS link, the run store, the daemon record and the arm marker; removes
+ * what a first install created; and compensates tracker labels exactly.
+ * Returns every restoration failure — the first included — so the caller
+ * reports the rollback honestly instead of implying the prior state is
+ * coherent. Never touches the pause sentinel: that restore keeps child 1's
+ * ownership rule and is the caller's.
+ */
+async function restoreInventory(
+  inventory: SetupInventory,
+  trackerRepo: string,
+  createdLabels: string[],
+  deleteLabels: SetupApplyDeps["deleteLabels"],
+): Promise<string[]> {
+  const failures: string[] = [];
+  const restore = (state: CapturedPathState | undefined, opts?: RestorePathOptions): void => {
+    if (state === undefined) return;
+    const failure = restorePathState(state, opts);
+    if (failure !== undefined) failures.push(failure);
+  };
+
+  // The config first — the file everything else derives from. Restored
+  // through the atomic temp-then-rename writer the upgrade rollback uses, so
+  // a crash mid-restore cannot leave a truncated config; the backup that
+  // writer makes of the failed config is pruned with the rest of the apply's
+  // new backups below, returning the backup dir to its entry listing.
+  if (inventory.config.kind === "bytes") {
+    try {
+      writeConfigRaw(inventory.config.bytes);
+    } catch (err) {
+      failures.push(
+        `could not restore config.json: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  } else {
+    restore(inventory.config);
+  }
+  const currentBackups = readdirIfPresent(inventory.backups.dir);
+  for (const name of currentBackups) {
+    if (inventory.backups.files.includes(name)) continue;
+    try {
+      rmSync(join(inventory.backups.dir, name), { force: true });
+    } catch (err) {
+      failures.push(
+        `could not remove backup ${join(inventory.backups.dir, name)}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  for (const brief of inventory.briefs) restore(brief);
+  for (const path of inventory.runtime) restore(path);
+  // The AGENTS link: only a symlink is ever removed or re-linked, so an
+  // operator's regular file that appeared mid-flight survives — reported as a
+  // failure, because the prior state is then not coherent.
+  restore(inventory.briefLink, { preserveRegularFile: true });
+
+  // The run store: replace from the byte-consistent snapshot (or remove it
+  // entirely on a first-install rollback).
+  try {
+    rmSync(inventory.store.path, { force: true });
+    rmSync(`${inventory.store.path}-wal`, { force: true });
+    rmSync(`${inventory.store.path}-shm`, { force: true });
+    if (inventory.store.kind === "snapshot") {
+      copyFileSync(inventory.store.snapshotPath!, inventory.store.path);
+    }
+  } catch (err) {
+    failures.push(
+      `could not restore the run store at ${inventory.store.path}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // The daemon record: only while no daemon is live. A live process owns its
+  // record — restoring the entry bytes over it would describe a daemon that
+  // no longer runs, or remove the record of one that does.
+  if (livingDaemon() === undefined) restore(inventory.record);
+  restore(inventory.armMarker);
+
+  // Directories the apply created: removed only while empty (rmdirSync, never
+  // a recursive rm — operator content that landed in one must survive).
+  for (const dir of inventory.dirs) {
+    try {
+      rmdirSync(dir);
+    } catch {
+      // Non-empty, missing, or busy — leave it; this is not a restoration failure.
+    }
+  }
+
+  // Tracker compensation: exactly the labels THIS apply created.
+  if (createdLabels.length > 0) {
+    try {
+      await deleteLabels(trackerRepo, createdLabels);
+    } catch (err) {
+      failures.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  return failures;
+}
+
+/**
+ * The host-global scope a setup apply's barrier covers: every configured
+ * project served by the daemon, and the global pause sentinel so one write
+ * pauses the whole host. Deliberately NOT {@link resolveScope}'s
+ * project-narrowing — which would pause the daemon's recorded project's
+ * sentinel instead of the host-wide one when adding a neighbour next to it
+ * (review #4). A first install has no config and no daemon, so the scope names
+ * the bare selector and the observation proves zero without any reader.
+ */
+function setupScope(drain: DrainDeps): UpgradeScope {
+  let configured: readonly string[] = [];
+  try {
+    configured = drain.projectNames();
+  } catch (err) {
+    // An existing config that cannot be enumerated is a fault, never absence:
+    // collapsing it to the bare selector would read "zero workers" for a fleet
+    // the config still describes, then overwrite the unreadable file (#651,
+    // review #2). Only a truly absent config legitimately yields the bare
+    // selector (a first install), and even there the observation still fails
+    // closed against the daemon identity.
+    if (existsSync(configPath())) {
+      throw new Error(
+        `the configured projects could not be read: ${err instanceof Error ? err.message : String(err)} — ` +
+          "zero workers cannot be proven while the config is unreadable",
+      );
+    }
+  }
+  // A daemon serves projects from its own memory, not from the on-disk
+  // config: a project the config no longer names (or never named — a neighbour
+  // this host is mid-migrating to) still owns live runs the daemon admits and
+  // sweeps. If the daemon's recorded project is not among the configured
+  // ones, the host-global scope must still cover it, or its workers are
+  // silently skipped while setup mutates underneath them (#651 review #3). An
+  // identity that cannot be proven throws here — before any freeze — so the
+  // scope never reads "zero" for a fleet it cannot see.
+  const daemon = drain.daemonIdentity();
+  if (daemon.running && daemon.project !== undefined && !configured.includes(daemon.project)) {
+    configured = [...configured, daemon.project];
+  }
+  return {
+    selectors: configured.length === 0 ? [undefined] : configured,
+    pauseKey: undefined,
+  };
+}
+
+/** Live worker runs across every project a host-wide transaction covers.
+ *  Throws — refusing — when the fleet cannot be proven quiescent: a missing
+ *  config does not prove zero workers while a daemon runs from its own
+ *  in-memory config and still owns runs (review #3), and an unreadable store
+ *  is a fault, never absence. */
+function liveWorkersInScope(drain: DrainDeps, scope: UpgradeScope): number {
+  if (!existsSync(configPath()) && drain.daemonIdentity().running) {
+    throw new Error(
+      "config.json is absent while a daemon is running, so zero workers cannot be proven; " +
+        "the daemon serves projects from memory",
+    );
+  }
+  return scope.selectors.reduce((n, s) => n + drain.snapshot(s).liveWorkers, 0);
+}
+
+/** How long the barrier waits — after one best-effort daemon wake — for the
+ *  running daemon to acknowledge the setup fence before refusing with nothing
+ *  written. Bounded and fail-closed: an unacknowledged fence is an unproven
+ *  one, and the answer is a re-run, never an unproven proceed. */
+const FENCE_ACK_WAIT_MS = 60_000;
+const FENCE_ACK_POLL_MS = 250;
+
+/**
+ * Why the daemon's admission acknowledgement no longer covers the fence the
+ * barrier froze, or `undefined` when it does: the acknowledgement must name
+ * the exact pause instance the barrier proved (not some other pause, however
+ * similar) and the exact daemon generation the barrier began with (not an
+ * older or newer instance's word) (#651 review #3).
+ */
+function fenceAckProblem(ack: AdmissionAckRecord | undefined, begun: RestartBegun): string | undefined {
+  if (ack === undefined) return "the running daemon has not acknowledged the setup admission fence";
+  if (
+    ack.pause.source !== begun.pauseToken.source ||
+    ack.pause.since !== begun.pauseToken.since ||
+    ack.pause.reason !== begun.pauseToken.reason
+  ) {
+    return "the running daemon acknowledged a different pause than the setup admission fence";
+  }
+  if (ack.daemon !== begun.daemon.generation) {
+    return "the running daemon's acknowledgement belongs to a different daemon generation";
+  }
+  return undefined;
+}
+
+/**
+ * Why the acknowledged barrier no longer holds, or `undefined` when it does:
+ * a live worker anywhere in scope, the daemon-side admission acknowledgement
+ * no longer covering the frozen fence (when one is required), or the fence
+ * its own pause/daemon-generation check (the reused lifecycle seam,
+ * {@link restartFenceProblem}) says was lifted or replaced. The acknowledged
+ * quiescence barrier re-runs this after every async boundary it must not
+ * proceed across (#651 review #6).
+ */
+function barrierDispute(
+  drain: DrainDeps,
+  scope: UpgradeScope,
+  begun: RestartBegun,
+  requireAck: boolean,
+): string | undefined {
+  try {
+    const live = liveWorkersInScope(drain, scope);
+    if (live > 0) return `${live} live worker(s) appeared under the setup admission freeze`;
+    if (requireAck && begun.daemon.running) {
+      const problem = fenceAckProblem(drain.admissionAck?.(scope.pauseKey), begun);
+      if (problem !== undefined) return problem;
+    }
+    // The fence's own pause/daemon-generation proof (the reused lifecycle
+    // seam) — wrapped with the worker count so a throwing accessor (an
+    // unknown systemd probe in the identity, say) is a dispute to refuse on,
+    // never an exception escaping with the freeze still written.
+    return restartFenceProblem(drain, scope, begun, "setup");
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
 /**
  * The post-apply code-graph offer. Shared by the tail and the live-worker early
  * return, so neither path can silently leave the graph install unreferenced.
@@ -2111,7 +2851,7 @@ export async function setup(
   }
   // `answers` is mutable below: the review loop re-asks one area at a time and
   // replaces only the fields that area owns, so everything else carries across.
-  const { amend, added } = collected;
+  const { amend } = collected;
   let answers = collected.answers;
 
   const scopes = await apply.scopes();
@@ -2262,7 +3002,12 @@ export async function setup(
         : "",
       d.project.escalation.orchestrator === "external"
         ? "Dispatch stays paused until the existing arm marker or a new inbound Telegram proof makes the heartbeat live."
-        : "Dispatch resumes after the smoke succeeds.",
+        : "Dispatch resumes after the smoke succeeds and the daemon is proven to serve the config it was just written.",
+      // The acknowledged quiescence barrier (#618): the whole sequence refuses
+      // before the first write while any configured project has a live worker
+      // and until the running daemon has acknowledged the admission fence, so
+      // the consent names the gate the apply runs behind.
+      "Refuses before any write while any configured project has a live worker, and until the running daemon acknowledges the admission fence.",
       "Issues are only claimed after every setup gate succeeds.",
     ]
       .filter((s) => s.length > 0)
@@ -2351,91 +3096,525 @@ export async function setup(
     ui.notify(planBlock(plan), "info");
   }
 
-  // Hold first. Any later filesystem, tracker, smoke, or channel error leaves a
-  // partially applied setup unable to claim work. Everything below reads the
-  // last re-derivation: the loop above can only break here on a final "Apply",
-  // so this one-writer sequence runs exactly once per setup run.
-  prepareConductor(plan.project.name);
-  const created = await withProgress("Creating tracker labels", "Tracker labels ready", () =>
-    apply.createLabels(answers.trackerRepo, plan.labels),
-  );
-  saveConfig(plan.nextConfig);
-  const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
-  const runtimeFiles = writeHostRuntime(plan.runtime);
-  for (const warning of runtimeFiles.warnings) ui.notify(warning, "warning");
-  const smoke = await withProgress("Running setup smoke", "Setup smoke passed", () =>
-    apply.smoke(plan.project.name),
-  );
-  let smokeLine =
-    `paused daemon --once; temporary /healthz on :${smoke.daemon.port}; ` +
-    `stored status for ${smoke.status.project}`;
+  // ------------------------------------------------------------------ #618 --
+  // The acknowledged quiescence barrier. A setup apply replaces config and
+  // runs a paused-daemon smoke that is itself a dispatcher (it settles rows,
+  // projects labels, salvages workers), and every write below happens
+  // underneath a daemon that may still admit or own workers. The fail-closed
+  // envelope, reusing the same lifecycle/drain seam `upgrade`, `restart` and
+  // `setup host` run on rather than a second counter-only fence: refuse before
+  // the first mutation when any configured project has a live worker; freeze
+  // admission host-wide — through the one global sentinel, never a project's —
+  // and prove the freeze is in force (#552); then acknowledge — re-check every
+  // project in scope under the proven freeze, and prove the fence still holds.
+  // A pass admitted between the first zero-worker observation and that
+  // acknowledgement refuses with the exact pre-entry pause restored and
+  // nothing else written. After the acknowledgement, every awaited mutation/
+  // lifecycle step re-proves the fence and the zero-worker scope before it
+  // acts (a concurrent `resume` during the awaited label I/O is the shape that
+  // used to slip through and orphan an admitted run).
+  //
+  // The pre-acknowledgement refusal paths are all pre-write, so "nothing has
+  // been changed" is literal: no label, no config byte, no brief, no runtime
+  // file, no store write, no smoke and no service mutation. The observation
+  // that gates the barrier is read-only — it can never be the thing that
+  // creates or upgrades the store, because database preparation is itself one
+  // of the mutations the barrier precedes.
+
+  // The exact pre-entry host-global pause sentinel (owner token and timestamp
+  // byte for byte), captured before anything mutates so a refusal — or the end
+  // of a successful apply — restores it verbatim. Setup freezes the whole host
+  // through the one global sentinel, so that is the only path it may change
+  // (review #4); an unreadable pre-existing sentinel fails closed here, before
+  // any change, rather than being read as absence and deleted (review #5).
+  let scope: UpgradeScope;
+  try {
+    scope = setupScope(apply.drain);
+  } catch (err) {
+    ui.notify(
+      `Setup stopped before writing anything: ${err instanceof Error ? err.message : String(err)}. ` +
+        "Nothing has been changed; fix the config and re-run setup.",
+      "error",
+    );
+    return false;
+  }
+  const priorPause = capturePause();
+  if (priorPause.kind === "unreadable") {
+    ui.notify(
+      `Setup stopped before writing anything: the pause sentinel at ${priorPause.path} exists but ` +
+        "could not be read — refusing rather than risk overwriting an operator hold. Nothing has been changed.",
+      "error",
+    );
+    return false;
+  }
+  // A malformed sentinel is unreadable-as-state: readable bytes that parse as
+  // no pause instance are still an operator's hold, and rebuilding them as a
+  // fresh setup pause would lose the owner identity the fence preserves. Fail
+  // closed before any change and never delete the file (#650).
+  if (priorPause.kind === "malformed") {
+    ui.notify(
+      `Setup stopped before writing anything: the pause sentinel at ${priorPause.path} exists but is ` +
+        "malformed (not a readable pause instance) — refusing rather than rebuild an operator hold setup " +
+        "cannot prove. Nothing has been changed.",
+      "error",
+    );
+    return false;
+  }
+
+  // First refusal — before ANY durable mutation, the freeze included. A live
+  // worker in any project the daemon serves would be orphaned, salvaged and
+  // requeued by the config write and the paused-daemon smoke that follow. The
+  // observation is read-only (it never creates or upgrades the store) and
+  // fails closed when quiescence cannot be proven — including when the scope
+  // itself cannot be enumerated (an unreadable config is a fault, never bare
+  // scope, review #2) or the daemon identity cannot be proven (an unknown
+  // systemd probe, review #2).
+  let entryWorkers: number;
+  try {
+    entryWorkers = liveWorkersInScope(apply.drain, scope);
+  } catch (err) {
+    ui.notify(
+      `Setup stopped before writing anything: ${err instanceof Error ? err.message : String(err)}. ` +
+        "Nothing has been changed; re-run setup once the fleet is provably quiet.",
+      "error",
+    );
+    return false;
+  }
+  if (entryWorkers > 0) {
+    ui.notify(
+      [
+        `Setup stopped before writing anything: ${entryWorkers} live worker(s) run under the active daemon.`,
+        "A setup apply replaces config and runs a paused-daemon smoke that would orphan, salvage and requeue those runs.",
+        "Let the workers finish, then re-run setup — nothing has been changed.",
+      ].join("\n"),
+      "error",
+    );
+    return false;
+  }
+
+  // Freeze admission host-wide, then prove the freeze is in force before
+  // anything is re-checked (#552): a pause that cannot be read back as an
+  // instance is a fence that cannot be acknowledged, so the barrier restores
+  // the exact entry pause and refuses instead of proceeding unproven.
+  const initialPaused = apply.drain.layers(scope.pauseKey).paused;
+  if (!initialPaused) apply.drain.setPaused(true, scope.pauseKey);
+  // The sentinel THIS transaction now owns — the bytes it just wrote, or the
+  // pre-entry hold it inherited. Every later restore only touches the disk
+  // while it still matches these exact bytes, so a takeover (a resume, a
+  // newer hold) is preserved rather than overwritten (#651 review #3).
+  const ownedFence = readSentinel(pausedPath(scope.pauseKey));
+  const pauseToken = apply.drain.pauseState(scope.pauseKey);
+  if (pauseToken === undefined) {
+    restorePause(priorPause, ownedFence);
+    ui.notify(
+      "Setup stopped before writing anything: the setup freeze could not be proven and was released. " +
+        "Nothing has been changed; re-run setup once dispatch is quiet.",
+      "error",
+    );
+    return false;
+  }
+
+  // Acknowledge the barrier: every project in scope is re-checked under the
+  // proven freeze, and the fence must still hold — the pause token we proved
+  // and the daemon generation we began with. A worker admitted after the
+  // first zero-worker observation but before this acknowledgement (a dispatch
+  // pass that passed its own pause gate before the freeze landed), a `resume`
+  // that lifted the freeze, or an identity that can no longer be proven (an
+  // unknown systemd probe) refuses here with the exact pre-entry pause
+  // restored and nothing else written.
+  let begun: RestartBegun;
+  try {
+    begun = { pauseToken, daemon: apply.drain.daemonIdentity() };
+  } catch (err) {
+    restorePause(priorPause, ownedFence);
+    ui.notify(
+      `Setup stopped before writing anything: ${err instanceof Error ? err.message : String(err)}. ` +
+        "The setup freeze was released; nothing has been changed; re-run setup once the fleet is provably quiet.",
+      "error",
+    );
+    return false;
+  }
+
+  // The daemon-side admission acknowledgement (#651 review #3): the fence is
+  // acknowledged only when the daemon ITSELF has observed it at an admission
+  // boundary and written that observation down — a second synchronous worker
+  // count is not an acknowledgement, because a tick already past its own
+  // pause gate can claim after it and before setup mutates. A running daemon
+  // that has not yet acknowledged is woken to prompt an immediate pass; one
+  // that cannot be reached (its record is missing) or that still has not
+  // acknowledged by the bounded deadline refuses before anything is written.
+  let requireAck = true;
+  if (begun.daemon.running) {
+    let ack = apply.drain.admissionAck?.(scope.pauseKey);
+    let acknowledged = fenceAckProblem(ack, begun) === undefined;
+    if (!acknowledged) {
+      const reachable = livingDaemon();
+      if (reachable !== undefined) {
+        ui.notify(
+          "The running daemon has not yet acknowledged the setup admission fence — waking it to prompt a pass.",
+          "info",
+        );
+        void wakeDaemon(reachable.port);
+        // `OMP_CONDUCTOR_TEST_FENCE_ACK_WAIT_MS` is the #399 test seam: a
+        // regression proving this refusal burns the short test deadline
+        // instead of the production 60s.
+        const deadline =
+          Date.now() + Number(process.env["OMP_CONDUCTOR_TEST_FENCE_ACK_WAIT_MS"] ?? FENCE_ACK_WAIT_MS);
+        while (!acknowledged && Date.now() < deadline) {
+          await apply.drain.sleep(FENCE_ACK_POLL_MS);
+          ack = apply.drain.admissionAck?.(scope.pauseKey);
+          acknowledged = fenceAckProblem(ack, begun) === undefined;
+        }
+      }
+    }
+    if (!acknowledged) {
+      restorePause(priorPause, ownedFence);
+      ui.notify(
+        "Setup stopped before writing anything: the running daemon has not acknowledged the setup admission " +
+          "fence, so quiescence cannot be proven. Nothing has been changed; stop the daemon, or re-run setup " +
+          "once it has acknowledged the fence.",
+        "error",
+      );
+      return false;
+    }
+  }
+  const ackDispute = barrierDispute(apply.drain, scope, begun, requireAck);
+  if (ackDispute !== undefined) {
+    restorePause(priorPause, ownedFence);
+    ui.notify(
+      `Setup stopped before writing anything: ${ackDispute}. ` +
+        "Nothing has been changed; re-run setup once dispatch is quiet.",
+      "error",
+    );
+    return false;
+  }
+
+  // The re-proof every later awaited-mutation/lifecycle step stands on: the
+  // acknowledged fence must still hold (pause owned, acknowledgement current,
+  // daemon generation unchanged) and no worker may have appeared. A concurrent
+  // `resume` while label creation is pending can reopen admission, after which
+  // config/runtime/smoke would proceed with no further token or worker check
+  // and orphan the admitted run (review #6) — so every one of them re-runs
+  // `barrierDispute` and restores the exact entry pause on a dispute.
+  const barrierHolds = (needAck: boolean): string | undefined =>
+    barrierDispute(apply.drain, scope, begun, needAck);
+
+  // The after-acknowledgement crosscheck: a claim that lands after the
+  // acknowledgement and before the first mutation (a daemon tick that passed
+  // its own pause gate before the freeze and reaches its claim now) must
+  // refuse here with NOTHING written — this read is the one that makes the
+  // `[0, 0, 1]` interleaving a pre-write refusal, not a post-store one
+  // (#651 review #3). The acknowledgement itself cannot see it: the ack is
+  // the daemon's word, and this synchronous crosscheck is the last moment
+  // the envelope can stay literal about "nothing has been changed".
+  const preMutationReproof = barrierHolds(requireAck);
+  if (preMutationReproof !== undefined) {
+    restorePause(priorPause, ownedFence);
+    ui.notify(
+      `Setup stopped before writing anything: ${preMutationReproof}. ` +
+        "Nothing has been changed; re-run setup once dispatch is quiet.",
+      "error",
+    );
+    return false;
+  }
+
+  // The one-writer transaction — runs exactly once per setup run, only after
+  // the loop above broke on a final "Apply", and only under the acknowledged
+  // barrier held above. Database preparation is the first mutation, in the
+  // order the envelope promises: barrier first, then store, config,
+  // brief/runtime files, smoke, service activation, tracker labels, the
+  // heartbeat proof last — immediately before the commit. The labels sit
+  // BEFORE the heartbeat proof so the deliberate arm-failure hold keeps the
+  // tracker's planned labels while it holds the fleet (#650, PR #700 review
+  // #3); every rollback path after them compensates exactly through the
+  // inventory, and every failure path before them has created none (#652). A
+  // throw anywhere in this leg, or a re-proof dispute after the first
+  // mutation, rolls the WHOLE inventory back as one unit; the pre-write
+  // refusal paths above are untouched.
+  let created: string[] = [];
+  let briefPath: string | undefined;
+  let runtimeFiles: HostRuntimeWrite = { wrote: [], warnings: [] };
+  let smoke: SetupSmokeResult | undefined;
+  let smokeLine = "";
   let restartVia: "systemctl" | "cli" | undefined;
-  if (smoke.mode === "existing") {
-    if (smoke.status.liveWorkers > 0) {
-      // Runs are live: never yank the daemon. Print the reload command; the new
-      // project only joins the multi-tenant loop after restart (#319).
+  let armLine = "embedded orchestrator — no heartbeat arm marker";
+
+  // The complete pre-entry mutation inventory (#652): every path the apply
+  // can write — config, briefs, staged units/scripts/tick, the AGENTS link,
+  // the run store, the daemon record, the arm marker, the config backups —
+  // with byte-exact pre-entry state, read BEFORE the first mutation so a
+  // failure anywhere in the write/smoke/activation leg can restore all of
+  // them. An unreadable pre-entry path refuses here: nothing has been changed.
+  let inventory: SetupInventory;
+  try {
+    inventory = captureInventory(plan, answers, existing?.projects.map((p) => p.name) ?? []);
+  } catch (err) {
+    // The freeze was already written by this point, so it is released with
+    // the refusal — an unreadable pre-entry path must not leave a setup-owned
+    // sentinel wedging dispatch for every project (review #2).
+    restorePause(priorPause, ownedFence);
+    ui.notify(
+      `Setup stopped before writing anything: ${err instanceof Error ? err.message : String(err)}. ` +
+        "The setup freeze was released; nothing has been changed; re-run setup once the fleet is provably quiet.",
+      "error",
+    );
+    return false;
+  }
+  // Whether a daemon was live at entry, captured before the first mutation: a
+  // failed restart leg can stop that daemon without proving a replacement, so
+  // only a run that entered with one must prove the runtime back before
+  // dispatch may resume (#652). The capture lives INSIDE the transaction try
+  // below so its refusal path is covered by the same `finally` that removes
+  // the store snapshot — the byte-consistent capture the inventory just made
+  // must never leak a stray temp copy in the state dir when the identity
+  // cannot be proven (#650, PR #700 review #2).
+  let hadLiveDaemonAtEntry = false;
+  try {
+    try {
+      hadLiveDaemonAtEntry = apply.drain.daemonIdentity().running;
+    } catch (err) {
+      // The freeze was already written by this point, so it is released with
+      // the refusal — an identity that cannot be proven must not leave a
+      // setup-owned sentinel wedging dispatch for every project (review #2).
+      restorePause(priorPause, ownedFence);
       ui.notify(
-        [
-          `Setup files are updated, but ${smoke.status.liveWorkers} live worker(s) still use the old daemon config.`,
-          "Dispatch remains paused. Let those workers finish.",
-          "Then run `omp-conductor restart --now`.",
-          plan.project.escalation.orchestrator === "external"
-            ? `Run \`omp-conductor arm --project ${plan.project.name}\` if ticks are disarmed, then run \`omp-conductor resume --project ${plan.project.name}\`.`
-            : `Then run \`omp-conductor resume --project ${plan.project.name}\`.`,
-        ].join("\n"),
-        "warning",
+        `Setup stopped before writing anything: ${err instanceof Error ? err.message : String(err)}. ` +
+          "The setup freeze was released; nothing has been changed; re-run setup once the fleet is provably quiet.",
+        "error",
       );
-      // The early return must not swallow the graph offer. This host is the
-      // live reproduction: the shared reindex units were already installed by
-      // the first project, so only the clone+seed are outstanding — and nothing
-      // above names them. Offer regardless of live workers: cloning seeds and
-      // enables the timer, which does not touch the running daemon.
-      await offerCodeGraph(plan.project, ui, apply.graphInstall);
-      ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
       return false;
     }
-    // No live workers: still prefer an explicit reload when this run *added* a
-    // neighbour — auto-restart would bounce every other project's heartbeat for
-    // a config change they did not ask for. Amends of the only/same project keep
-    // the old auto-restart so a first-time install still comes up alone.
-    if (added === true) {
+    openStore(dbPath()).close();
+    saveConfig(plan.nextConfig);
+    briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
+    runtimeFiles = writeHostRuntime(plan.runtime);
+    for (const warning of runtimeFiles.warnings) ui.notify(warning, "warning");
+
+    // Re-prove before the smoke: the paused-daemon smoke is itself a dispatcher,
+    // so it must never run under a reopened fence or beside a worker admitted
+    // since the acknowledgement (review #6). The store/config/brief/runtime
+    // writes above are rolled back with the whole inventory (review #652).
+    const smokeReproof = barrierHolds(requireAck);
+    if (smokeReproof !== undefined) {
+      const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, created, apply.deleteLabels);
+      restorePause(priorPause, ownedFence);
       ui.notify(
-        [
-          "Setup files are updated. The running daemon does not serve the new project until it reloads.",
-          "No live workers — safe to reload now:",
-          "  omp-conductor restart --now",
-        ].join("\n"),
-        "info",
+        `Setup stopped before the daemon smoke: ${smokeReproof}. ` +
+          (restoreFailures.length === 0
+            ? "The prior state was restored."
+            : `Rollback could not fully restore the prior state: ${restoreFailures.join("; ")}`),
+        "error",
       );
-    } else {
+      return false;
+    }
+    smoke = await withProgress("Running setup smoke", "Setup smoke ran", () =>
+      apply.smoke(plan.project.name),
+    );
+
+    // Re-prove AFTER the awaited smoke too (review #2): the smoke is itself a
+    // dispatcher, and a fence resumed while it ran — or a worker it admitted —
+    // must stop the restart and heartbeat actions that follow. The restart,
+    // if any, is the very next action, so this single re-proof covers it.
+    const postSmokeReproof = barrierHolds(requireAck);
+    if (postSmokeReproof !== undefined) {
+      const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, created, apply.deleteLabels);
+      restorePause(priorPause, ownedFence);
+      ui.notify(
+        `Setup stopped after the daemon smoke: ${postSmokeReproof}. ` +
+          (restoreFailures.length === 0
+            ? "The prior state was restored."
+            : `Rollback could not fully restore the prior state: ${restoreFailures.join("; ")}`),
+        "error",
+      );
+      return false;
+    }
+
+    smokeLine =
+      smoke.mode === "temporary"
+        ? `paused daemon --once; temporary /healthz on :${smoke.daemon.port}; ` +
+          `stored status for ${smoke.status.project}`
+        : // An existing daemon (record or active unit) never ran a `--once` tick
+          // and never staged a temporary one — the restart line below replaces
+          // this one whenever the restart runs.
+          `existing daemon; stored status for ${smoke.status.project}`;
+    if (smoke.mode === "existing") {
+      // The barrier acknowledged zero workers in every project under a proven
+      // host-wide freeze before the first write, so a live worker here can only
+      // mean the fence itself was bypassed. The old soft return — applied config
+      // and a wedged setup pause left underneath that worker, with a "let them
+      // finish" note — is the exact incident shape (#618) and is refused instead,
+      // with the whole inventory rolled back (review #2, #652).
+      if (smoke.status.liveWorkers > 0) {
+        const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, created, apply.deleteLabels);
+        restorePause(priorPause, ownedFence);
+        ui.notify(
+          `${smoke.status.liveWorkers} live worker(s) appeared under the setup admission freeze — ` +
+            "refusing to apply over a bypassed fence. " +
+            (restoreFailures.length === 0
+              ? "The prior state was restored."
+              : `Rollback could not fully restore the prior state: ${restoreFailures.join("; ")}`),
+          "error",
+        );
+        return false;
+      }
+      // The added-project contract (#650): the newly loaded runtime must be
+      // proven to serve the added project BEFORE setup reports success — and
+      // more generally, an "existing" smoke means a daemon is serving the
+      // config that was just replaced, so it must reload the applied config
+      // through the lifecycle seam. The deferral to a manual `restart --now`
+      // an operator may never run left dispatch ready on a daemon that did
+      // not serve the config it was just written, so it is gone: every
+      // existing-mode apply restarts, even when the smoke proved health, and
+      // the seam's `waitForOwnedDaemon` proves MainPID + /healthz + that the
+      // (added) project is served before the apply reports success.
       const restarted = await apply.restart({ project: plan.project.name });
       restartVia = restarted.via;
       smokeLine =
         `existing /healthz and stored status; restarted through ${restarted.via}; ` +
         `new /healthz on :${restarted.record.port}`;
+      // The intentional restart is the generation boundary: from here the
+      // fence protects the daemon we just started, not the one we began with.
+      // Refresh the acknowledged world — pause re-proven, identity re-captured
+      // — and drop the acknowledgement requirement, because a daemon this
+      // apply itself started cannot have been mid-claim when the fence landed
+      // (its first admission boundary is the tick gate, above routing); its
+      // own first gate re-acknowledges on the next pass. A fence that vanished
+      // while the restart ran (a concurrent resume) refuses here instead of
+      // proceeding under an unproven freeze (review #3).
+      const refreshedPause = apply.drain.pauseState(scope.pauseKey);
+      if (refreshedPause === undefined) {
+        const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, created, apply.deleteLabels);
+        restorePause(priorPause, ownedFence);
+        ui.notify(
+          "Setup stopped after the daemon restart: the setup pause was lifted while the daemon restarted, so " +
+            "the acknowledged world no longer exists. " +
+            (restoreFailures.length === 0
+              ? "The prior state was restored."
+              : `Rollback could not fully restore the prior state: ${restoreFailures.join("; ")}`),
+          "error",
+        );
+        return false;
+      }
+      begun = { pauseToken: refreshedPause, daemon: apply.drain.daemonIdentity() };
+      requireAck = false;
     }
-  }
 
-  let armLine = "embedded orchestrator — no heartbeat arm marker";
-  if (plan.project.escalation.orchestrator === "external") {
-    ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
-    try {
-      armLine = await apply.arm(plan.project.name);
-    } catch (err) {
+    // The tracker labels — before the heartbeat proof, so the deliberate
+    // arm-failure hold (which keeps its writes by design) leaves the tracker
+    // with the planned labels instead of a config whose routing keys and
+    // queue label do not exist yet (#650, PR #700 review #3). Every rollback
+    // path AFTER this point compensates them exactly through the inventory;
+    // every failure path before it has created none.
+    created = await withProgress("Creating tracker labels", "Tracker labels ready", () =>
+      apply.createLabels(answers.trackerRepo, plan.labels),
+    );
+
+    if (plan.project.escalation.orchestrator === "external") {
       ui.notify(
-        [
-          "Setup files passed the paused daemon smoke, but the fleet remains held.",
-          err instanceof Error ? err.message : String(err),
-          `Start the external orchestrator in ${plan.project.workspaceRoot}, then run \`omp-conductor arm --project ${plan.project.name}\`.`,
-          "After the arm proof succeeds, run `omp-conductor resume`.",
-        ].join("\n"),
-        "warning",
+        smoke.healthProven
+          ? "Setup smoke passed. Proving the external heartbeat channel…"
+          : "Setup smoke staged — the restart proved /healthz. Proving the external heartbeat channel…",
+        "info",
+      );
+      try {
+        armLine = await apply.arm(plan.project.name);
+      } catch (err) {
+        ui.notify(
+          [
+            "Setup files passed the paused daemon smoke, but the fleet remains held.",
+            created.length > 0 ? `Tracker labels were created (${created.join(", ")}).` : "Planned labels already existed.",
+            err instanceof Error ? err.message : String(err),
+            `Start the external orchestrator in ${plan.project.workspaceRoot}, then run \`omp-conductor arm --project ${plan.project.name}\`.`,
+            "After the arm proof succeeds, run `omp-conductor resume`.",
+          ].join("\n"),
+          "warning",
+        );
+        ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
+        return false;
+      }
+    }
+
+    // The final barrier boundary: the awaited label and heartbeat I/O are the
+    // last steps before the commit, and a fence resumed while either ran — or
+    // a worker admitted — must refuse with the tracker compensated and every
+    // captured path restored.
+    const finalReproof = barrierHolds(requireAck);
+    if (finalReproof !== undefined) {
+      const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, created, apply.deleteLabels);
+      restorePause(priorPause, ownedFence);
+      ui.notify(
+        `Setup stopped before committing: ${finalReproof}. ` +
+          (restoreFailures.length === 0
+            ? "The prior state was restored."
+            : `Rollback could not fully restore the prior state: ${restoreFailures.join("; ")}`),
+        "error",
       );
-      ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
       return false;
     }
+  } catch (err) {
+    // Roll the whole apply back as one transaction (#652): every captured
+    // path restored byte-for-byte (or removed on a first install), the
+    // tracker compensated exactly, and — because a failed restart leg may
+    // have stopped the entry daemon without proving a replacement — a healthy
+    // daemon proven to serve the restored config before dispatch may resume.
+    // If that proof cannot be made, stay fail-closed: a setup hold stays in
+    // force with the recovery command named, and the thrown error reports the
+    // first restoration failure honestly rather than implying the prior state
+    // is coherent.
+    //
+    // The labels created before a mid-way createLabels throw ride on the
+    // error (createMissingLabels attaches its partial list), so compensation
+    // stays exact even when the tracker step itself failed.
+    const createdLabels = created.length > 0 ? created : ((err as { created?: string[] }).created ?? []);
+    const restoreFailures = await restoreInventory(inventory, answers.trackerRepo, createdLabels, apply.deleteLabels);
+    let runtimeProved = !hadLiveDaemonAtEntry;
+    if (hadLiveDaemonAtEntry) {
+      // The proof targets the PRE-ENTRY configured set the rollback restored,
+      // never the rejected generation's: the restarted runtime must be proven
+      // to serve every project the prior runtime served (#650).
+      runtimeProved = await apply.proveRuntime(inventory.priorProjects).catch(() => false);
+    }
+    // The pause ownership rule (#651 review #3): only the fence this
+    // transaction froze is undone; a takeover stands.
+    restorePause(priorPause, ownedFence);
+    const failures = [...restoreFailures];
+    if (!runtimeProved) {
+      // Fail-closed: only an entry that was actually unpaused needs a hold
+      // re-asserted — an entry already held keeps that exact sentinel, and a
+      // takeover that replaced the fence is preserved, never overwritten.
+      // The re-asserted hold is ALWAYS the host-global sentinel, never a
+      // project-scoped one: a fresh `paused-<project>` written under a
+      // failure that entered under a global pause is the silent fake this
+      // slice exists to forbid — when the global hold later clears, the
+      // hidden project pause would remain and deadlock the fleet (#650).
+      if (priorPause.kind === "absent" && readSentinel(pausedPath(scope.pauseKey)).kind === "absent") {
+        setPaused(true, {
+          source: pauseSourceToken("setup"),
+          reason: "setup apply failed and no healthy daemon could be proven",
+        });
+      }
+      failures.push(
+        `no healthy daemon could be proven after the rollback — the fleet stays held; ` +
+          `run \`omp-conductor restart --project ${plan.project.name}\` to recover`,
+      );
+    }
+    if (failures.length > 0) {
+      throw new Error(
+        `setup apply failed (${err instanceof Error ? err.message : String(err)}) and the prior state could not ` +
+          `be fully restored: ${failures.join("; ")}`,
+      );
+    }
+    throw err;
+  } finally {
+    // The byte-consistent store snapshot exists only for this transaction.
+    if (inventory.store.kind === "snapshot") rmSync(inventory.store.snapshotPath!, { force: true });
   }
-  apply.resume(plan.project.name);
+  // Lift the setup freeze and restore the exact pre-entry pause: an entry that
+  // was already paused (an operator hold, say) keeps that sentinel byte for
+  // byte, and an entry that was unpaused resumes dispatch exactly as the old
+  // `resume` did. A takeover that replaced the setup fence meanwhile is
+  // preserved, never overwritten (#651 review #3).
+  restorePause(priorPause, ownedFence);
 
   ui.notify(
     [
@@ -2447,7 +3626,7 @@ export async function setup(
       runtimeFiles.wrote.length === 0
         ? "Host runtime files were already current."
         : `Wrote host runtime file(s): ${runtimeFiles.wrote.join(", ")}`,
-      `Smoke passed: ${smokeLine}.`,
+      `Smoke ${smoke.healthProven ? "passed" : "staged; the restart proved /healthz"}: ${smokeLine}.`,
       `Heartbeat: ${armLine}.`,
       "",
       "Use the documented toy-issue drill to prove one complete worker path.",