omp-conductor 0.16.2 → 0.17.0

package/src/commands/setup.ts

@@ -17,7 +17,16 @@ import { AMEND_AREA_IDS, type AmendAreaId } from "../setup.ts";
 import { runGraphInstall, runHostInstall, type InstallOutcome } from "../setup-install.ts";
 import { DEFAULT_PROBES, NO_PROBES, setup } from "../setup-wizard.ts";
 import { telegramStateDir } from "../fleet.ts";
+import {
+  answersUi,
+  guardNonInteractiveUi,
+  loadAnswersFile,
+  recordingAnswersUi,
+  saveAnswersFile,
+  type RecordedAnswersUi,
+} from "../setup-answers.ts";
 import { terminalUi, type WizardUi } from "../wizard-ui.ts";
+import { interactiveUi } from "../ui/progress.ts";
 import type { ConductorConfig, ProjectConfig } from "../types.ts";
 
 /**
@@ -30,7 +39,7 @@ const SETUP_USAGE = `omp-conductor setup — interview, then write config.json,
 and the staged host files behind one confirm.
 
 usage:
-  omp-conductor setup [area] [--no-ai] [--project NAME]
+  omp-conductor setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--project NAME]
   omp-conductor setup host [NAME] [--project NAME]
   omp-conductor setup graph [--no-seed] [--print] [--project NAME]
 
@@ -44,9 +53,11 @@ amend areas:
   ${AMEND_AREA_IDS.join(", ")}
 
 flags:
-  --project NAME   the project to configure or amend (or NAME positionally
-                   for \`setup host\`)
-  --no-ai          ask every question, propose nothing (no AI repo reads)`;
+  --project NAME       the project to configure or amend (or NAME positionally
+                       for \`setup host\`)
+  --no-ai              ask every question, propose nothing (no AI repo reads)
+  --answers FILE       answer every prompt from JSON; never opens a prompt
+  --save-answers FILE  save successful prompt answers as replayable JSON`;
 
 /**
  * Resolve the project an install subcommand (`setup host`, `setup graph`)
@@ -97,6 +108,7 @@ async function offerCompletionInstall(ui: WizardUi): Promise<void> {
   const install = await ui.confirm(
     "Install shell completions?",
     "Writes a generated completion script and one idempotent source line to your shell rc file.",
+    { key: "install-shell-completions" },
   );
   if (install !== true) return;
 
@@ -107,13 +119,26 @@ async function offerCompletionInstall(ui: WizardUi): Promise<void> {
       { label: "zsh", description: "Install through ~/.zshrc" },
       { label: "bash", description: "Install through ~/.bashrc" },
     ],
-    { initialIndex: detected === "bash" ? 1 : 0 },
+    { key: "completion-shell", initialIndex: detected === "bash" ? 1 : 0 },
   );
   if (selected !== "zsh" && selected !== "bash") return;
   const installed = await installShellCompletions(selected);
   ui.notify(`Installed completions at ${installed.scriptPath}; sourced from ${installed.rcPath}.`);
 }
 
+function setupValueFlag(argv: readonly string[], name: "--answers" | "--save-answers"): string | undefined {
+  const inline = argv.find((arg) => arg.startsWith(`${name}=`));
+  const at = argv.indexOf(name);
+  if (inline !== undefined && at !== -1) throw new Error(`${name} may be passed only once`);
+  const value = inline?.slice(name.length + 1) ?? (at === -1 ? undefined : argv[at + 1]);
+  if (value === undefined) {
+    if (at !== -1) throw new Error(`${name} requires a file path`);
+    return undefined;
+  }
+  if (value.length === 0 || value.startsWith("--")) throw new Error(`${name} requires a file path`);
+  return value;
+}
+
 export async function setupCommand(ctx: CommandContext): Promise<void> {
 // Help first, and only in the first trailing position: a help request
 // must never open a UI, read config, probe GitHub or pause dispatch.
@@ -125,10 +150,22 @@ if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
 }
 const sub = ctx.argv[1];
 const positional = sub !== undefined && !sub.startsWith("--") ? sub : undefined;
-// The terminal surface owns stdin for whichever path runs, and is released
-// in a finally: a throw with readline still attached leaves the operator's
-// shell without an echo.
-const ui = terminalUi();
+// Clack owns an interactive terminal. Pipes retain the byte-pinned readline
+// protocol, while --answers installs a prompt-free driver.
+const answersPath = setupValueFlag(ctx.argv, "--answers");
+const saveAnswersPath = setupValueFlag(ctx.argv, "--save-answers");
+const useClack = answersPath === undefined && interactiveUi();
+const baseUi = answersPath
+  ? answersUi(loadAnswersFile(answersPath))
+  : useClack
+    ? (await import("../clack-ui.ts")).clackUi()
+    : terminalUi();
+const guardedUi = answersPath === undefined && !process.stdin.isTTY ? guardNonInteractiveUi(baseUi) : baseUi;
+const recording: RecordedAnswersUi | undefined =
+  saveAnswersPath === undefined ? undefined : recordingAnswersUi(guardedUi);
+const ui = recording?.ui ?? guardedUi;
+let saveCompletedAnswers = false;
+let closeMessage = "Setup failed.";
 try {
   // `host` and `graph` are install subcommands, checked BEFORE the amend
   // areas. They are not areas — routing them through the area validation
@@ -170,6 +207,8 @@ try {
     // `staged` is a success on a host that has no systemd: the files are
     // real, only the enable step is impossible.
     if (outcome.kind === "refused" || outcome.kind === "failed") process.exit(1);
+    saveCompletedAnswers = outcome.kind !== "declined";
+    closeMessage = outcome.kind === "declined" ? "Setup incomplete." : "Setup complete.";
     return;
   }
   let area: AmendAreaId | undefined;
@@ -203,7 +242,19 @@ try {
       );
     }
   }
+  saveCompletedAnswers = completed;
+  closeMessage = completed ? "Setup complete." : "Setup incomplete.";
 } finally {
-  ui.close();
+  try {
+    if (saveCompletedAnswers && saveAnswersPath !== undefined && recording !== undefined) {
+      saveAnswersFile(saveAnswersPath, recording.answers);
+      ui.notify(`Saved setup answers to ${saveAnswersPath}.`);
+    }
+  } catch (err) {
+    closeMessage = "Setup failed.";
+    throw err;
+  } finally {
+    ui.close(closeMessage);
+  }
 }
 }

package/src/commands/stats.ts

@@ -13,6 +13,7 @@ import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { dbPath, openStore, utcDay } from "../store.ts";
 import { computeStats, renderStatsHuman, type StatsWindow } from "../stats.ts";
+import { heading } from "../ui/style.ts";
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
 const DATE_FORM = /^\d{4}-\d{2}-\d{2}$/;
@@ -120,11 +121,14 @@ export async function statsCommand(ctx: CommandContext): Promise<void> {
       ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
       runs: store.statsRuns(project.name, window.sinceEpochMs),
     });
-    process.stdout.write(
-      ctx.argv.includes("--json")
-        ? `${JSON.stringify(report, null, 2)}\n`
-        : renderStatsHuman(report),
-    );
+    if (ctx.argv.includes("--json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    else {
+      const human = renderStatsHuman(report);
+      const newline = human.indexOf("\n");
+      process.stdout.write(
+        newline < 0 ? heading(human) : `${heading(human.slice(0, newline))}${human.slice(newline)}`,
+      );
+    }
   } finally {
     store.close();
   }

package/src/commands/status.ts

@@ -10,8 +10,9 @@ import type { CommandContext } from "./context.ts";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stateDir } from "../config.ts";
-import { renderStatus } from "../fleet.ts";
+import { collectFleetStatus, renderFleetStatusReport } from "../fleet.ts";
 import { STALL_MARKER_FILE } from "../orchestrator-tick.ts";
+import { fail, heading, ok, warn } from "../ui/style.ts";
 
 /**
  * The orchestrator half, and the one thing `status` has ever known about the
@@ -40,9 +41,35 @@ function stallLine(): string | undefined {
   return `orchestrator   STALLED since ${since === "" ? "an unrecorded time" : since}${diagnosis}`;
 }
 
+function styleStatus(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => {
+      if (
+        line === "caps" ||
+        line === "daemon" ||
+        line === "active runs" ||
+        line === "active runs  (none)" ||
+        line.startsWith("project   ")
+      )
+        return heading(line);
+      if (line.includes("STALLED")) return fail(line);
+      if (/^(dispatch|ticks|pane|herdr|telegram|  healthz)\s+.*\b(running|healthy|ok)\b/.test(line))
+        return ok(line);
+      if (/^(dispatch|ticks|daemon)\s+.*\b(paused|stopped|not running|overdue)\b/.test(line))
+        return warn(line);
+      return line;
+    })
+    .join("\n");
+}
+
 export async function statusCommand(ctx: CommandContext): Promise<void> {
-const project = ctx.projectFlag;
-const text = await renderStatus(project);
-const stalled = stallLine();
-process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
+  const report = await collectFleetStatus(ctx.projectFlag);
+  const stalled = stallLine();
+  if (ctx.argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({ ...report, orchestratorStall: stalled }, null, 2)}\n`);
+    return;
+  }
+  const text = styleStatus(renderFleetStatusReport(report));
+  process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${fail(stalled)}\n`}`);
 }

package/src/commands/tail.ts

@@ -13,6 +13,7 @@ import { findProject, loadConfig } from "../config.ts";
 import { dbPath, LIVE_STATES, openStore } from "../store.ts";
 import { formatTranscriptLine, prop } from "../transcript.ts";
 import type { Store } from "../types.ts";
+import { dim, fail, ok, warn } from "../ui/style.ts";
 
 /** How often `tail` re-stats the transcripts it is following. */
 const TAIL_POLL_MS = 1_000;
@@ -142,6 +143,16 @@ export function renderAdvisorLine(line: string): string | undefined {
   return out.length === 0 ? undefined : `[advisor] ${out.join("\n")}`;
 }
 
+function styleTailLine(line: string): string {
+  if (line.startsWith("[advisor] blocker:")) return fail(line);
+  if (line.startsWith("[advisor] warning:")) return warn(line);
+  if (line.startsWith("[advisor] nit:")) return dim(line);
+  if (line === "run ended: merged" || line === "run ended: pushed-green") return ok(line);
+  if (/^run ended: (?:failed|killed|orphaned)$/.test(line)) return fail(line);
+  if (line.startsWith("run ended:")) return warn(line);
+  return line;
+}
+
 /**
  * Follow one run's transcripts the way `tail -f` follows a log: the worker's
  * own transcript plus any `__advisor*.jsonl` sitting beside it (the mid-run
@@ -173,7 +184,8 @@ export async function tailRun(
   } = {},
 ): Promise<void> {
   const store = deps.store ?? openStore(dbPath());
-  const write = deps.write ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const write =
+    deps.write ?? ((line: string) => process.stdout.write(`${styleTailLine(line)}\n`));
   const pollMs = deps.pollMs ?? TAIL_POLL_MS;
   const quietMs = deps.quietMs ?? TAIL_QUIET_MS;
   try {

package/src/commands/watch.ts

@@ -50,18 +50,27 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
     }
 
     if (sub === "list" || sub === undefined) {
-      const watches = store.openDecisions(project.name).filter((d) => d.kind === "watch");
+      const open = store.openDecisions(project.name).filter((d) => d.kind === "watch");
+      const now = Date.now();
+      const watches = open.map((d) => ({
+        id: d.id,
+        ageHours: Math.max(0, Math.round((now - d.askedAt) / 3_600_000)),
+        blocks: d.blocks ?? null,
+        condition: d.condition === undefined ? null : d.conditionMetAt === undefined ? "pending" : "met",
+        note: d.question,
+      }));
+      if (ctx.argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify({ project: project.name, watches }, null, 2)}\n`);
+        return;
+      }
       if (watches.length === 0) {
         process.stdout.write("no watches\n");
         return;
       }
-      const now = Date.now();
-      for (const d of watches) {
-        const condition =
-          d.condition === undefined ? "-" : d.conditionMetAt === undefined ? "pending" : "met";
-        const hours = Math.max(0, Math.round((now - d.askedAt) / 3_600_000));
+      for (const watch of watches) {
         process.stdout.write(
-          `${d.id}  ${hours}h  blocks:${d.blocks ?? "-"}  condition:${condition}  ${d.question}\n`,
+          `${watch.id}  ${watch.ageHours}h  blocks:${watch.blocks ?? "-"}  ` +
+            `condition:${watch.condition ?? "-"}  ${watch.note}\n`,
         );
       }
       return;

package/src/fleet.ts

@@ -37,7 +37,7 @@ import { dbPath, openStore } from "./store.ts";
 import { renderBriefForProject } from "./setup.ts";
 import type { DaemonStop, ProjectConfig, Store } from "./types.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
-import { isPaused, setPaused, statusSnapshot } from "./daemon.ts";
+import { isPaused, setPaused, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import {
   healthCheck,
   isAlive,
@@ -1311,8 +1311,24 @@ function servedProjectName(payload: object): string | undefined {
   return undefined;
 }
 
-export async function renderStatus(projectName?: string): Promise<string> {
-  const s = statusSnapshot(projectName);
+export type FleetStatusReport = StatusSnapshot & {
+  observedAt: number;
+  layers: FleetLayers;
+  daemon: FleetDaemonProbe | undefined;
+  telegram: TelegramHealth;
+  codeGraph: CodeGraphHealth;
+  brief: string | undefined;
+  decisions: string | undefined;
+  failureClasses: string | undefined;
+  workerPhases: { issue: number; phase: WorkerPausePhase }[];
+  intake: string | undefined;
+  lastStop: DaemonStop | undefined;
+  siblings: { project: string; live: number }[];
+};
+
+/** Collects the complete status payload once for both text and JSON renderers. */
+export async function collectFleetStatus(projectName?: string): Promise<FleetStatusReport> {
+  const snapshot = statusSnapshot(projectName);
   const layers = fleetLayers(projectName);
   const project = findProject(loadConfig(), projectName);
   const rec = livingDaemon();
@@ -1325,7 +1341,7 @@ export async function renderStatus(projectName?: string): Promise<string> {
     // Read here rather than in `statusSnapshot`, which is synchronous and used
     // by callers that must not shell out. An unmetered project never spawns
     // the provider at all.
-    readPlanUsage(s.caps.planUsage, sharedUsageSource()),
+    readPlanUsage(snapshot.caps.planUsage, sharedUsageSource()),
     // Same reasoning as `planUsage`: the snapshot is synchronous, this read is
     // a shell-out, and undefined on any failure — one missing row, never a
     // broken report (#188).
@@ -1347,7 +1363,9 @@ export async function renderStatus(projectName?: string): Promise<string> {
   const healthBody = projectHealth.kind === "ok" ? rawHealth?.body : undefined;
   const cached = codeGraphFromHealthz(healthBody, project.name);
   const codeGraph = cached ?? (await probeCodeGraph(project));
-  const workerPhases = workerPhasesFromHealthz(healthBody, project.name);
+  const workerPhases = [...workerPhasesFromHealthz(healthBody, project.name)].map(
+    ([issue, phase]) => ({ issue, phase }),
+  );
   // The newest host-wide stop/restart provenance (#378). Read here — not in
   // `statusSnapshot`, which is synchronous and belongs to the daemon module —
   // and rendered identically from either project: the daemon_stops table is
@@ -1359,32 +1377,54 @@ export async function renderStatus(projectName?: string): Promise<string> {
   try {
     lastStop = store.latestDaemonStop();
     // Shared-daemon visibility (#545): every configured project other than the
-    // one being viewed, with its live-run count. Read from the same open store
-    // as the provenance above, so a status reader can tell "my fleet is idle"
-    // from "the process I am about to stop is busy".
+    // one being viewed, with its live-run count.
     siblings = loadConfig()
       .projects.filter((p) => p.name !== project.name)
       .map((p) => ({ project: p.name, live: store.liveRuns(p.name).length }));
   } finally {
     store.close();
   }
-  return formatFleetStatus(
-    { ...s, planUsage, github },
+  return {
+    ...snapshot,
+    planUsage,
+    github,
+    observedAt: Date.now(),
     layers,
     daemon,
     telegram,
-    Date.now(),
     codeGraph,
-    briefStatusLine(project),
-    decisionStatusLine(project.name),
-    failureClassBlock(project.name),
+    brief: briefStatusLine(project),
+    decisions: decisionStatusLine(project.name),
+    failureClasses: failureClassBlock(project.name),
     workerPhases,
-    intakeStatusLine(project.name),
+    intake: intakeStatusLine(project.name),
     lastStop,
     siblings,
+  };
+}
+
+export function renderFleetStatusReport(report: FleetStatusReport): string {
+  return formatFleetStatus(
+    report,
+    report.layers,
+    report.daemon,
+    report.telegram,
+    report.observedAt,
+    report.codeGraph,
+    report.brief,
+    report.decisions,
+    report.failureClasses,
+    new Map(report.workerPhases.map(({ issue, phase }) => [issue, phase])),
+    report.intake,
+    report.lastStop,
+    report.siblings,
   );
 }
 
+export async function renderStatus(projectName?: string): Promise<string> {
+  return renderFleetStatusReport(await collectFleetStatus(projectName));
+}
+
 /**
  * One line naming the brief layout, or nothing when it cannot be read.
  *

package/src/orchestrator-tick.ts

@@ -103,7 +103,7 @@ import {
   type AskResult,
 } from "./ask.ts";
 import { deliverOperatorMessage } from "./reports.ts";
-import type { RunRecord } from "./types.ts";
+import type { RecoveryAction, RunRecord } from "./types.ts";
 import { dbPath, openStore } from "./store.ts";
 import { digestDue, localDayKey } from "./digest-schedule.ts";
 import { heldNoticeId } from "./notices.ts";
@@ -471,6 +471,34 @@ export function defaultTickMessage(
  * `REPORT_SCOPES` fails to compile here instead of resolving to `undefined` at
  * the point of use.
  */
+/**
+ * Which recovery actions resolve a run without leaving human work behind.
+ * Exhaustive over {@link RecoveryAction} so adding an action to the vocabulary
+ * forces a decision here: a recovered row carrying `true` is genuinely done and
+ * may be summarised as "already handled"; `false` — `escalate`, `hold`, `none` —
+ * still needs the orchestrator's Duty 1 attention, so it must never inherit the
+ * suppressive "do not re-triage" sentence (#610).
+ */
+const AUTONOMOUS_RECOVERY_ACTIONS: Record<RecoveryAction, boolean> = {
+  requeue: true,
+  continue: true,
+  "rerun-checks": true,
+  settle: true,
+  escalate: false,
+  hold: false,
+  none: false,
+};
+
+/** Bounded name-and-count summary shared by the two recovered-row groups. */
+function recoveredSummary(group: readonly RunRecord[]): string {
+  const named = group
+    .slice(0, 5)
+    .map((r) => `${r.failureClass ?? "unknown"} #${r.issue}`)
+    .join(", ");
+  const rest = group.length > 5 ? `, +${group.length - 5} more` : "";
+  return `${group.length} (${named}${rest})`;
+}
+
 /**
  * One line naming what the daemon recovered without asking (#132).
  *
@@ -480,12 +508,23 @@ export function defaultTickMessage(
  */
 export function recoveryDigestLine(recovered: readonly RunRecord[]): string | undefined {
   if (recovered.length === 0) return undefined;
-  const named = recovered
-    .slice(0, 5)
-    .map((r) => `${r.failureClass ?? "unknown"} #${r.issue}`)
-    .join(", ");
-  const rest = recovered.length > 5 ? `, +${recovered.length - 5} more` : "";
-  return `Auto-recovered since last tick: ${recovered.length} (${named}${rest}) — already handled, do not re-triage these.`;
+  const handled: RunRecord[] = [];
+  const triage: RunRecord[] = [];
+  for (const r of recovered) {
+    if (r.recoveryAction !== undefined && AUTONOMOUS_RECOVERY_ACTIONS[r.recoveryAction]) {
+      handled.push(r);
+    } else {
+      triage.push(r);
+    }
+  }
+  const lines: string[] = [];
+  if (handled.length > 0) {
+    lines.push(`Auto-recovered since last tick: ${recoveredSummary(handled)} — already handled, do not re-triage these.`);
+  }
+  if (triage.length > 0) {
+    lines.push(`Recovered but needs Duty 1 triage: ${recoveredSummary(triage)} — inspect these runs.`);
+  }
+  return lines.join("\n");
 }
 
 /**

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/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-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) {