omp-conductor 0.16.2 → 0.17.1

package/src/privileged.ts

@@ -88,6 +88,8 @@ export interface RunPrivilegedOptions {
   deps?: PrivilegedDeps;
   /** Confirm title. Defaults to a generic one; callers name their verb. */
   title?: string;
+  /** Stable answer-file key for this batch's confirmation. */
+  answerKey?: string;
   /** Extra lines shown above the step list — what this batch is for. */
   preamble?: readonly string[];
   /**
@@ -201,6 +203,7 @@ export async function runPrivileged(
   const go = await ui.confirm(
     options.title ?? "Run these steps now?",
     `${steps.length} step(s), in the order shown. Anything that fails stops the rest and prints what is left.`,
+    { key: options.answerKey ?? "run-privileged-steps" },
   );
   // `undefined` is a dismissal rather than a "no", but for a batch that has not
   // started they mean the same thing: run nothing.

package/src/release-policy.ts

@@ -280,7 +280,7 @@ function wholePackageBunTest(segment: string): boolean {
  * the host were all plain invocations, and refusing the sanctioned parse check
  * would teach workers to skip it rather than stop the load.
  */
-const SHARED_HOST_SCRIPTS = [
+export const SHARED_HOST_SCRIPTS: readonly string[] = [
   "herdr/test/recover-test.sh",
   "test/setup-test.sh",
   "setup.sh",
@@ -298,6 +298,147 @@ function sharedHostScriptMatch(segment: string): string | undefined {
   return undefined;
 }
 
+/** The `git [-C <dir>] tag` prefix; the tail after it decides read vs write. */
+const GIT_TAG_HEAD = /^git(?:\s+-[Cc]\s+\S+)*\s+tag(?=\s|$)/;
+
+/**
+ * Whether a segment that opens with `git [-C <dir>] tag` is a write — tag
+ * creation or deletion — rather than a read. The tripwire used to match the
+ * `git tag` prefix alone (#696), so a worker orienting itself with
+ * `git tag | head -5` was refused as an attempted release and the refusal
+ * reached the digest as release-policy drift. Git writes tags in exactly two
+ * shapes, and every other form is a read:
+ *
+ * - creation needs a tagname operand: `git tag <name>` and the
+ *   `-a`/`-s`/`-u`/`-t`/`-m`/`-F`/`-f` forms;
+ * - deletion needs `-d`/`--delete`;
+ * - bare `git tag`, `-l`/`--list` (with an optional pattern), `-n`,
+ *   `--contains`, `--points-at`, `--sort`, `--merged`/`--no-merged`,
+ *   `--format`, `--column` and `-v`/`--verify` all only read.
+ *
+ * A creation flag with no name is still gated: git rejects the command, but a
+ * create attempt is not a read, and the tripwire errs toward refusing a
+ * release act.
+ */
+function gitTagIsWrite(segment: string): boolean {
+  const head = GIT_TAG_HEAD.exec(segment);
+  if (head === null) return false;
+  const tokens = segment.slice(head[0].length).trim().split(/\s+/).filter((token) => token.length > 0);
+
+  let deletion = false; // -d / --delete
+  let listRead = false; // a read-only list flag
+  let verifyRead = false; // -v / --verify
+  let createSignal = false; // -a / -s / -f / -m / -u / -t / -F
+  let hasOperand = false; // a positional tagname, pattern or commit
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    // A `--` ends option parsing: whatever follows is a plain operand, the
+    // created or deleted tag's name.
+    if (token === "--") {
+      hasOperand = true;
+      break;
+    }
+    if (token.startsWith("--")) {
+      const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+      switch (flag) {
+        case "--delete":
+          deletion = true;
+          break;
+        case "--list":
+        case "--contains":
+        case "--no-contains":
+        case "--points-at":
+        case "--merged":
+        case "--no-merged":
+        case "--sort":
+        case "--format":
+        case "--column":
+        case "--no-column":
+        case "--color":
+        case "--no-color":
+        case "--ignore-case":
+        case "--no-ignore-case":
+          listRead = true;
+          break;
+        case "--verify":
+          verifyRead = true;
+          break;
+        case "--annotate":
+        case "--sign":
+        case "--force":
+          createSignal = true;
+          break;
+        case "--local-user":
+        case "--object":
+        case "--message":
+        case "--file":
+          // The flag's operand is part of the create parameters, not a
+          // tagname; `--flag value` must not be read as `--flag` plus a name.
+          createSignal = true;
+          if (!token.includes("=")) i++;
+          break;
+        default:
+          break; // an unknown flag: no conclusion either way
+      }
+      continue;
+    }
+    if (token.startsWith("-") && token.length > 1) {
+      // Combined short options (`-an5` is `-a -n 5`). An option with a
+      // required operand takes the rest of its token or the next token.
+      let consumeNext = false;
+      for (let j = 1; j < token.length; j++) {
+        const flag = token[j];
+        switch (flag) {
+          case "d":
+            deletion = true;
+            break;
+          case "a":
+          case "s":
+          case "f":
+            createSignal = true;
+            break;
+          case "l":
+            listRead = true;
+            break;
+          case "v":
+            verifyRead = true;
+            break;
+          case "n":
+            // `-n[<num>]` — the digit run belongs to the flag, so `-n5`
+            // is one token and never an operand.
+            listRead = true;
+            while (j + 1 < token.length && token[j + 1]! >= "0" && token[j + 1]! <= "9") j++;
+            break;
+          case "m":
+          case "u":
+          case "t":
+          case "F":
+            createSignal = true;
+            if (j + 1 < token.length) {
+              j = token.length;
+            } else {
+              consumeNext = true;
+            }
+            break;
+          default:
+            break; // an unknown short flag: no conclusion either way
+        }
+      }
+      if (consumeNext) i++;
+      continue;
+    }
+    // A plain operand: with a list flag it is a pattern or commit for the
+    // read; without one it is the tagname a creation needs.
+    hasOperand = true;
+  }
+
+  if (deletion) return true;
+  if (listRead || verifyRead) return false;
+  if (hasOperand) return true;
+  return createSignal;
+}
+
 /**
  * Classify a shell command and the segment that fired. The segment is what a
  * triager reads: `bun test src/foo.test.ts && npm publish` matches on its
@@ -323,7 +464,7 @@ function releaseCommandMatch(command: string): { shape: GateShape; matched: stri
     // any future spelling under the upgrade family all need the install shape,
     // and a session without that grant is refused before the shell runs.
     if (/^omp-conductor\s+upgrade(?:\b|$)/.test(segment)) return { shape: "install", matched: segment };
-    if (/^git(?:\s+-[Cc]\s+\S+)*\s+tag(?:\s|$)/.test(segment)) return { shape: "git-tag", matched: segment };
+    if (gitTagIsWrite(segment)) return { shape: "git-tag", matched: segment };
     if (
       /^git(?:\s+-[Cc]\s+\S+)*\s+push\b/.test(segment) &&
       GIT_PUSH_TAG_SHAPE.test(segment)
@@ -513,8 +654,10 @@ export function releaseShapeFromTool(
 /**
  * The refusal wording for the shared-host gate (#428). The whole-package
  * `bun test` form names the focused alternative (a guard that only denies
- * teaches nothing and gets worked around); the shell suites get their own
- * because there is no focused form of a suite script.
+ * teaches nothing and gets worked around); a refused shell suite names the
+ * script that fired and the sanctioned `bash -n` parse check (#687), because
+ * there is no focused form of a suite script — the alternative is to drop the
+ * execution segment and keep the allowed prefix, not to run something else.
  */
 function sharedHostRefusalReason(matched: string | undefined): string {
   if (matched !== undefined && /^bun\s+test\b/.test(matched)) {
@@ -524,10 +667,39 @@ function sharedHostRefusalReason(matched: string | undefined): string {
       "Run a focused `bun test <file>.test.ts` instead."
     );
   }
+  if (matched !== undefined) {
+    return (
+      `Blocked by sharedHostPolicy: \`${matched}\` is a shared-host shell suite and not a worker's proof ` +
+      "path on this shared host (it overloads the 4-core VPS that also runs Langfuse and the fleet). " +
+      `\`bash -n ${matched}\` is the sanctioned local check — parsing never executes the script — and CI's ` +
+      "`herdr plugin + installer shell suites` job owns executing it. Drop the segment that fired and keep " +
+      "the `bash -n` parse gate."
+    );
+  }
   return (
     "Blocked by sharedHostPolicy: this shell suite is not a worker's proof path on this shared host " +
     "(it overloads the 4-core VPS that also runs Langfuse and the fleet). " +
-    "Run focused `bun test <file>.test.ts` unit tests instead."
+    "`bash -n <path>` is the sanctioned local check; CI's `herdr plugin + installer shell suites` job owns " +
+    "executing it."
+  );
+}
+
+/**
+ * The worker-brief notice for the shared-host gate (#687): the guarded suite
+ * paths and the sanctioned local check, derived from
+ * {@link SHARED_HOST_SCRIPTS} so the rendered brief and the refusal can never
+ * disagree about what is guarded. One line and non-empty whenever the list is:
+ * the brief's rendered line count must equal its template's, which the
+ * buildBrief tests pin, so the notice must never carry an internal newline.
+ */
+export function sharedHostBriefNotice(): string {
+  if (SHARED_HOST_SCRIPTS.length === 0) return "";
+  const paths = SHARED_HOST_SCRIPTS.map((script) => `\`${script}\``).join(", ");
+  return (
+    `**Shared-host guard:** ${paths} are never executed on this shared host — \`bash -n\` on them is the ` +
+    "sanctioned local check (parsing never executes), and CI's `herdr plugin + installer shell suites` job " +
+    "owns executing them. A command that executes one is refused, and the refusal names the segment; drop " +
+    "that segment and keep the `bash -n` parse gate."
   );
 }
 

package/src/setup-answers.ts

@@ -0,0 +1,135 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+
+import type { PromptOptions, SelectOptions, TerminalUi, WizardUi } from "./wizard-ui.ts";
+
+const answerFileSchema = z.record(z.string(), z.union([z.string(), z.boolean()]));
+
+export type SetupAnswerValues = Record<string, string | boolean>;
+
+function promptName(title: string, options: PromptOptions): string {
+  return `answer "${options.key}" for "${title}"`;
+}
+
+function requiredAnswer(answers: SetupAnswerValues, title: string, options: PromptOptions): string | boolean {
+  if (!Object.hasOwn(answers, options.key)) {
+    throw new Error(`missing ${promptName(title, options)}; add it to the --answers file`);
+  }
+  return answers[options.key]!;
+}
+
+/** A prompt-free WizardUi backed only by validated answers. */
+export function answersUi(
+  answers: SetupAnswerValues,
+  notify: WizardUi["notify"] = (message) => process.stdout.write(`${message}\n`),
+): TerminalUi {
+  return {
+    notify,
+    close: () => {},
+    async confirm(title, _message, options) {
+      const answer = requiredAnswer(answers, title, options);
+      if (typeof answer !== "boolean") {
+        throw new Error(`${promptName(title, options)} must be a boolean`);
+      }
+      return answer;
+    },
+    async input(title, _placeholder, options) {
+      const answer = requiredAnswer(answers, title, options);
+      if (typeof answer !== "string") {
+        throw new Error(`${promptName(title, options)} must be a string`);
+      }
+      return answer;
+    },
+    async select(title, choices, options) {
+      const answer = requiredAnswer(answers, title, options);
+      if (typeof answer !== "string") {
+        throw new Error(`${promptName(title, options)} must be a listed label`);
+      }
+      if (!choices.some((choice) => choice.label === answer)) {
+        throw new Error(`${promptName(title, options)} must be a listed label`);
+      }
+      return answer;
+    },
+  };
+}
+
+export function loadAnswersFile(path: string): SetupAnswerValues {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    throw new Error(`could not read answers file "${path}": ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`answers file "${path}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const parsed = answerFileSchema.safeParse(decoded);
+  if (!parsed.success) {
+    throw new Error(`answers file "${path}" must be a JSON object whose values are strings or booleans`);
+  }
+  return parsed.data;
+}
+
+export interface RecordedAnswersUi {
+  ui: TerminalUi;
+  answers: SetupAnswerValues;
+}
+
+type ClosableWizardUi = WizardUi & Partial<Pick<TerminalUi, "close">>;
+
+/** Decorates any driver and records only answers that were actually returned. */
+export function recordingAnswersUi(inner: ClosableWizardUi): RecordedAnswersUi {
+  const answers: SetupAnswerValues = {};
+  return {
+    answers,
+    ui: {
+      notify: (message, type) => inner.notify(message, type),
+      close: (message) => inner.close?.(message),
+      async confirm(title, message, options) {
+        const answer = await inner.confirm(title, message, options);
+        if (answer !== undefined) answers[options.key] = answer;
+        return answer;
+      },
+      async input(title, placeholder, options) {
+        const answer = await inner.input(title, placeholder, options);
+        if (answer !== undefined) answers[options.key] = answer;
+        return answer;
+      },
+      async select(title, choices, options) {
+        const answer = await inner.select(title, choices, options);
+        if (answer !== undefined) answers[options.key] = answer;
+        return answer;
+      },
+    },
+  };
+}
+
+export function saveAnswersFile(path: string, answers: SetupAnswerValues): void {
+  writeFileSync(path, `${JSON.stringify(answers, null, 2)}\n`, "utf8");
+}
+
+/** Turns exhausted scripted stdin into an actionable non-interactive failure. */
+export function guardNonInteractiveUi(inner: TerminalUi): TerminalUi {
+  const exhausted = (title: string, options: PromptOptions): never => {
+    throw new Error(
+      `stdin ended before ${promptName(title, options)}; provide more piped answers or use setup --answers FILE`,
+    );
+  };
+  return {
+    notify: (message, type) => inner.notify(message, type),
+    close: (message) => inner.close(message),
+    async confirm(title, message, options) {
+      return (await inner.confirm(title, message, options)) ?? exhausted(title, options);
+    },
+    async input(title, placeholder, options) {
+      return (await inner.input(title, placeholder, options)) ?? exhausted(title, options);
+    },
+    async select(title, choices, options: SelectOptions) {
+      return (await inner.select(title, choices, options)) ?? exhausted(title, options);
+    },
+  };
+}

package/src/setup-host.ts

@@ -15,10 +15,13 @@ import {
   DEFAULT_PORT,
   healthCheck,
   livingDaemon,
+  probeUnit,
   startDaemon,
   stopDaemon,
+  SYSTEMD_UNIT,
   type DaemonRecord,
   type StopResult,
+  type UnitOwnership,
 } from "./lifecycle.ts";
 import {
   legacyArmedMarkerPath,
@@ -48,7 +51,7 @@ export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";
 export const RECOVER_SERVICE_NAME = "omp-conductor-recover.service";
 
 /** The playbook file shipped in the package's `systemd/` directory. */
-const RECOVER_SCRIPT_FILE = "omp-conductor-recover.sh";
+export const RECOVER_SCRIPT_FILE = "omp-conductor-recover.sh";
 
 /**
  * Where `setup host` installs the recovery playbook so the unit's ExecStart is
@@ -1512,8 +1515,125 @@ export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
   return { wrote, warnings };
 }
 
+// ---------------------------------------------------------- rollback (#652) --
+//
+// The inverse of the writes above, for the setup apply's mutation inventory:
+// every path the apply can write is captured byte-for-byte (or as absence, or
+// as unreadable — never conflated) before the first mutation, and restored on
+// any later failure. `capturePathState` is the read half, `restorePathState`
+// the write half; the transaction that owns them lives in `setup-wizard.ts`.
+
+/** One path's pre-entry state, three-valued so absence is never confused with
+ *  unreadability:
+ *  - `absent` — nothing at the path; rollback removes what the apply created.
+ *  - `bytes` — readable on entry (a regular file with its mode, or a symlink
+ *    with its target); rollback writes those exact bytes/mode or re-links it.
+ *  - `unreadable` — something exists but cannot be read. The transaction must
+ *    fail closed before changing anything: collapsing this to absence and
+ *    later deleting the path would remove state the apply never saw. */
+export type CapturedPathState =
+  | { path: string; kind: "absent" }
+  | { path: string; kind: "bytes"; bytes: string; mode: number; symlink: boolean }
+  | { path: string; kind: "unreadable" };
+
+/** Reads {@link CapturedPathState} for one path. Symlinks are captured as
+ *  their target (readlink), never followed — the brief link is a symlink by
+ *  contract, and a dangling one is still state worth restoring. */
+export function capturePathState(path: string): CapturedPathState {
+  let st: Stats;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return { path, kind: "absent" };
+  }
+  try {
+    if (st.isSymbolicLink()) {
+      return { path, kind: "bytes", bytes: readlinkSync(path, "utf8"), mode: st.mode & 0o7777, symlink: true };
+    }
+    return { path, kind: "bytes", bytes: readFileSync(path, "utf8"), mode: st.mode & 0o7777, symlink: false };
+  } catch {
+    return { path, kind: "unreadable" };
+  }
+}
+
+/** Options for {@link restorePathState}. */
+export interface RestorePathOptions {
+  /**
+   * Never remove or replace a regular file: only a symlink (or absence) is
+   * touched, so an operator's file that appeared mid-transaction survives a
+   * rollback that cannot clobber it — the same guard the brief-link write
+   * itself applies (#652). A regular file where the entry state said
+   * "absent"/"symlink" therefore reports a restoration failure: the prior
+   * state is not coherent and the operator must be told.
+   */
+  preserveRegularFile?: boolean;
+}
+
+/** Restores {@link CapturedPathState} captured before the first mutation:
+ *  writes the entry bytes back (with their mode), re-links a symlink's entry
+ *  target, or removes what the apply created when nothing was there. Returns
+ *  `undefined` on a complete restore, else the first failure's message — a
+ *  rollback that could not restore a path must be reported, never implied
+ *  complete. */
+export function restorePathState(state: CapturedPathState, opts: RestorePathOptions = {}): string | undefined {
+  const { path } = state;
+  try {
+    if (state.kind === "bytes" && state.symlink) {
+      // Re-link the entry target. Under `preserveRegularFile` a regular file
+      // that replaced the link mid-flight is left alone — and reported — so a
+      // rollback never clobbers an operator's file it did not create.
+      let current: Stats | undefined;
+      try {
+        current = lstatSync(path);
+      } catch {
+        current = undefined;
+      }
+      if (current !== undefined && !current.isSymbolicLink() && opts.preserveRegularFile === true) {
+        return `could not restore the symlink at ${path}: a regular file now occupies it`;
+      }
+      rmSync(path, { force: true });
+      mkdirSync(dirname(path), { recursive: true });
+      symlinkSync(state.bytes, path);
+      return undefined;
+    }
+    if (state.kind === "bytes") {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, state.bytes);
+      // Mode is part of the pre-entry state (a staged unit 0644, the tick
+      // config 0600, the recovery playbook 0755): writeFileSync preserves an
+      // existing file's mode, so chmod explicitly restores the captured one.
+      chmodSync(path, state.mode);
+      return undefined;
+    }
+    // Absent at entry: remove what the apply created. A regular file that
+    // appeared where the entry was absent is the operator's own unless the
+    // caller says otherwise.
+    let current: Stats | undefined;
+    try {
+      current = lstatSync(path);
+    } catch {
+      return undefined; // already gone — a complete restore.
+    }
+    if (current.isSymbolicLink() || opts.preserveRegularFile !== true) {
+      rmSync(path, { force: true });
+      return undefined;
+    }
+    return `could not restore ${path}: a regular file appeared where nothing was at entry`;
+  } catch (err) {
+    return `could not restore ${path}: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
+
 export interface SetupSmokeResult {
   mode: "temporary" | "existing";
+  /**
+   * Whether the smoke itself proved the daemon answers `/healthz` on
+   * {@link daemon}.port. A record-less active unit has no port to probe, so
+   * its "existing" smoke is unproven: it cannot count as passed until the
+   * caller restarts the daemon through the lifecycle seam, whose
+   * `waitForOwnedDaemon` proves MainPID + `/healthz` (#651, review #2).
+   */
+  healthProven: boolean;
   status: StatusSnapshot;
   daemon: DaemonRecord;
 }
@@ -1522,6 +1642,15 @@ export interface SetupSmokeDeps {
   paused(project: string): boolean;
   runOnce(project: string): Promise<void>;
   living(): DaemonRecord | undefined;
+  /**
+   * systemd ownership of the `omp-conductor.service` supervisor unit, probed
+   * independently of the pidfile/runtime record. An active unit is a live
+   * supervised daemon even when its record is missing or unreadable (#618):
+   * it must never be run beside a `--once` tick, and `start()` must never be
+   * aimed at it. `unknown` is preserved — never collapsed into `inactive` —
+   * so a possibly-live supervised daemon is not run beside (#651, review #2).
+   */
+  unitOwnership(): UnitOwnership;
   health(port: number): Promise<{ ok: boolean; body?: string }>;
   start(project: string): Promise<DaemonRecord>;
   stop(): Promise<StopResult>;
@@ -1532,30 +1661,90 @@ const DEFAULT_SMOKE_DEPS: SetupSmokeDeps = {
   paused: isPaused,
   runOnce: async (project) => await runDaemon({ once: true, project }),
   living: livingDaemon,
+  unitOwnership: () => probeUnit(SYSTEMD_UNIT),
   health: healthCheck,
   start: async (project) => await startDaemon({ project }),
   stop: stopDaemon,
   status: statusSnapshot,
 };
 
+/** The daemon record a smoke attributes to a live but record-less supervisor.
+ *  The port is unknown (the record would have named it); the "existing" mode
+ *  caller restarts the daemon through the lifecycle seam and recomputes the
+ *  real /healthz line from that restart, so this satisfies the result shape
+ *  without pretending to know a port. `healthProven: false` marks that this
+ *  is a placeholder until that restart proves the unit's MainPID answers. */
+function unrecordedDaemon(mainPid: number): DaemonRecord {
+  return {
+    pid: 0,
+    port: 0,
+    startedAt: 0,
+    logFile: `<record missing — supervised daemon MainPID ${mainPid} via systemd>`,
+  };
+}
+
 export async function runSetupSmoke(
   project: string,
   deps: SetupSmokeDeps = DEFAULT_SMOKE_DEPS,
 ): Promise<SetupSmokeResult> {
   if (!deps.paused(project)) throw new Error("setup smoke requires paused dispatch");
-  await deps.runOnce(project);
+  // Detect a live daemon BEFORE the mutating `--once` tick (#618). A paused
+  // `--once` run is itself a dispatcher: it settles rows, projects labels,
+  // admits and salvages workers. Running one beside a live daemon orphans and
+  // salvages the runs the live process owns — exactly what the incident did to
+  // three workers before failing its restart check. An already-active daemon
+  // needs only its health proving (the caller restarts it through the lifecycle
+  // seam so the new config takes effect) — no `--once` process ever runs beside
+  // it, and no `systemctl start` is aimed at a unit that is already active.
   const existing = deps.living();
   if (existing !== undefined) {
     const health = await deps.health(existing.port);
     if (!health.ok) throw new Error(`existing daemon on :${existing.port} did not answer /healthz`);
-    return { mode: "existing", status: deps.status(project), daemon: existing };
+    return { mode: "existing", healthProven: true, status: deps.status(project), daemon: existing };
   }
 
+  // The pidfile record is absent, but that is not "no daemon": an active
+  // systemd-owned unit is a live supervised dispatcher even when its record
+  // went missing (a crash raced a re-record, or an unmanaged start never wrote
+  // one). Without this independent probe the smoke runs a second `--once`
+  // beside it, and `start()` targets the already-active unit — two dispatchers
+  // owning the same state, the #618 incident shape. Treat it as an existing
+  // daemon: no competing tick, no activation; the caller restarts the unit so
+  // the new config takes effect (#651, review #1).
+  const ownership = deps.unitOwnership();
+  if (ownership.kind === "unknown") {
+    // A probe failure is not the confirmed negative `inactive` claims to be:
+    // collapsing `unknown` here is how a unit-owned daemon gets a second one
+    // started beside it (#651, review #2). The mutating `--once` tick refuses
+    // instead.
+    throw new Error(
+      `cannot prove whether a daemon is running: systemd ownership probe failed (${ownership.reason}) — ` +
+        "refusing to run the setup smoke beside a possibly-live daemon",
+    );
+  }
+  if (ownership.kind === "active") {
+    // No record to read a port from, so no /healthz proof is possible here:
+    // the smoke reports `existing` honestly as *unproven*, and the caller
+    // must restart the unit through the lifecycle seam — whose
+    // `waitForOwnedDaemon` proves MainPID + `/healthz` — before the smoke
+    // counts as passed (#651, review #2).
+    return {
+      mode: "existing",
+      healthProven: false,
+      status: deps.status(project),
+      daemon: unrecordedDaemon(ownership.pid),
+    };
+  }
+
+  // Confirmed inactive (or failed, which owns no process): a paused `--once`
+  // smoke can run by itself, then a temporary daemon proves the new runtime,
+  // then it is stopped again.
+  await deps.runOnce(project);
   const daemon = await deps.start(project);
   try {
     const health = await deps.health(daemon.port);
     if (!health.ok) throw new Error(`temporary daemon on :${daemon.port} did not answer /healthz`);
-    return { mode: "temporary", status: deps.status(project), daemon };
+    return { mode: "temporary", healthProven: true, status: deps.status(project), daemon };
   } finally {
     await deps.stop();
   }

package/src/setup-install.ts

@@ -275,6 +275,7 @@ export async function runHostInstall(
   const outcome = await runPrivileged(plan.steps, ui, {
     ...(deps.privileged === undefined ? {} : { deps: deps.privileged }),
     title: "Install and start the supervised session?",
+    answerKey: "install-host",
     preamble: [
       `Installs ${plan.service.path} as ${installed}, then enables and restarts it.`,
       ...(plan.herdrUnit === undefined
@@ -547,6 +548,7 @@ export async function runGraphInstall(
   const outcome = await runPrivileged([...clones, ...install], ui, {
     ...(options.privileged === undefined ? {} : { deps: options.privileged }),
     title: unitsCurrent ? "Clone the code-graph checkouts and seed them?" : "Clone, install and enable the code-graph timer?",
+    answerKey: `install-code-graph.${project.name}`,
     preamble: [
       `Staged: ${staged.written.join(", ")}.`,
       ...(clones.length === 0

package/src/setup-probe.ts

@@ -402,6 +402,7 @@ export async function probeProse(
   const keep = await ui.confirm(
     `Keep this ${heading}?`,
     "It becomes part of POLICY.md, which the orchestrator re-reads on every tick. You can edit that file afterwards. Declining keeps the stub.",
+    { key: `keep-probe.${name}` },
   );
   // A dismissed prompt is not a yes. `undefined` means the operator walked away.
   if (keep !== true) {