omp-conductor 0.13.0 → 0.15.0

package/src/setup-wizard.ts

@@ -0,0 +1,1946 @@
+/**
+ * The setup wizard: prompts, per-area amend, and the one-writer apply sequence.
+ *
+ * Extracted (#305) so the interview lived behind the `WizardUi` interface rather
+ * than inside the omp plugin's dialog surface; #309 then deleted that surface, and
+ * the terminal `omp-conductor setup` verb is now its only caller. It is
+ * presentation only — it turns a `WizardUi` into questions and, behind one consent
+ * gate,
+ * applies the answers through ./setup.ts which is headless and tested. Every
+ * 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 { platform } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import {
+  configPath,
+  expandHome,
+  findProject,
+  loadConfig,
+  resolveCaps,
+  saveConfig,
+} from "./config.ts";
+import { hostRamBytes, recommendedMaxWorkers, workerOvercommit } from "./host.ts";
+import {
+  prepareConductor,
+  previewProject,
+  setPaused,
+  type QueuePreview,
+} from "./daemon.ts";
+import { armTicks, telegramStateDir } from "./fleet.ts";
+import { restartDaemon } from "./lifecycle.ts";
+import { defaultGraphRoot, graphRepos } from "./graph.ts";
+import {
+  formatHostRuntimePlan,
+  planHostRuntime,
+  totalConfiguredWorkers,
+  runSetupSmoke,
+  SYSTEMD_UNIT_DIR,
+  writeHostRuntime,
+} from "./setup-host.ts";
+import { runGraphInstall, runHostInstall } from "./setup-install.ts";
+import { probeGates, probeProse, probeRepoMap, type ProbedGate, type ProbeTarget } from "./setup-probe.ts";
+import {
+  AMEND_AREAS,
+  BASE_FRESHNESS_CHOICES,
+  BEHIND_BASE_CHOICES,
+  DRAFT_POLICY_CHOICES,
+  ORCHESTRATOR_BRIEF_NAME,
+  POLICY_BRIEF_NAME,
+  RELEASE_REQUIREMENT_CHOICES,
+  REPORT_SCOPE_CHOICES,
+  SETUP_DEFAULTS,
+  amendChoices,
+  answersFromProject,
+  briefPathForProject,
+  policyPathForProject,
+  buildConfig,
+  checkTokenScopes,
+  createMissingLabels,
+  defaultAnswers,
+  detectTelegram,
+  formatGates,
+  orchestratorBriefPath,
+  planLabels,
+  summariseAmend,
+  summarisePlan,
+  writeOrchestratorBrief,
+  type AmendAreaId,
+  type OperatorJudgment,
+  type SetupAnswers,
+  type ProbedProse,
+} from "./setup.ts";
+import {
+  BASE_FRESHNESS,
+  BEHIND_BASE_ACTIONS,
+  DEFAULT_CAPS,
+  DRAFT_POLICIES,
+  RELEASE_REQUIREMENTS,
+  INTERRUPT_CATEGORIES,
+  RELEASE_SHAPES,
+  WEEKDAYS,
+  type Caps,
+  type ConductorConfig,
+  type OrchestratorMode,
+  type InterruptCategory,
+  type Weekday,
+  type ProjectConfig,
+  type ProjectPolicy,
+  type ReleaseRequirement,
+  type ReportScopeChoice,
+  type ResolvedGrants,
+} from "./types.ts";
+import type { WizardUi } from "./wizard-ui.ts";
+
+/**
+ * Dismissing any dialog abandons the whole wizard.
+ *
+ * Thrown rather than returned as a sentinel: the prompt sequence runs to a
+ * dozen questions, and a cancellation check after each one would bury the
+ * shape of the conversation under branching.
+ */
+class Cancelled extends Error {
+  constructor() {
+    super("setup cancelled");
+    this.name = "Cancelled";
+  }
+}
+
+/** The spelling `config.ts` validates tracker repos against. Checked here too
+ *  so a typo is fixed in the dialog instead of in an error an hour later. */
+const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/**
+ * One text answer. The placeholder shows the default and an empty submission
+ * takes it, because the harness has no pre-filled input dialog — so "Enter
+ * accepts what you see" is the contract the whole wizard is built on.
+ */
+async function ask(ui: WizardUi, title: string, fallback: string): Promise<string> {
+  const raw = await ui.input(title, fallback.length > 0 ? fallback : undefined);
+  if (raw === undefined) throw new Cancelled();
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+/**
+ * One yes/no answer, with a dismissal treated as leaving rather than as "no".
+ *
+ * Every confirm in this wizard defaults to no, so "no" and "dismissed" look
+ * identical if the surface collapses them — and then Ctrl-C at a yes/no prompt
+ * recorded a silent no and walked on to the next question, which is not what
+ * abandoning a run means. `undefined` is the surface saying the operator left.
+ */
+async function askYesNo(ui: WizardUi, title: string, message: string): Promise<boolean> {
+  const answer = await ui.confirm(title, message);
+  if (answer === undefined) throw new Cancelled();
+  return answer;
+}
+
+/**
+ * Re-asks until the answer passes `check`, which returns the complaint or
+ * `undefined`. Bounded at three tries: a dialog that cannot be escaped is worse
+ * than one that gives up and leaves the config alone.
+ */
+async function askValid(
+  ui: WizardUi,
+  title: string,
+  fallback: string,
+  check: (value: string) => string | undefined,
+): Promise<string> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const value = await ask(ui, title, fallback);
+    const problem = check(value);
+    if (problem === undefined) return value;
+    ui.notify(problem, "warning");
+  }
+  throw new Cancelled();
+}
+
+
+/** A cap. Unparseable input keeps the current value rather than writing a NaN
+ *  the validator would later reject — the operator sees why, immediately. */
+async function askNumber(ui: WizardUi, title: string, fallback: number): Promise<number> {
+  const raw = await ask(ui, title, String(fallback));
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    ui.notify(`"${raw}" is not a non-negative number — keeping ${fallback}.`, "warning");
+    return fallback;
+  }
+  return value;
+}
+
+/**
+ * Daily spend ceiling. Blank / "none" / "off" → null (no gate). Unparseable
+ * non-empty input keeps the current value. Distinct from askNumber so operators
+ * can turn the money brake off without writing a magic 0 (which is a hard stop).
+ */
+async function askSpendCap(
+  ui: WizardUi,
+  title: string,
+  fallback: number | null,
+): Promise<number | null> {
+  const seed = fallback === null ? "" : String(fallback);
+  const raw = (await ask(ui, title, seed)).trim().toLowerCase();
+  if (raw === "" || raw === "none" || raw === "off" || raw === "null") return null;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    ui.notify(
+      `"${raw}" is not a non-negative number or blank — keeping ${fallback === null ? "no cap" : fallback}.`,
+      "warning",
+    );
+    return fallback;
+  }
+  return value;
+}
+
+/**
+ * Pre-push gates as one comma-separated line, `cmd @ cwd` for a subdirectory:
+ * `bun run check, bun test @ server`. Shown through `formatGates`, the same
+ * spelling the amend menu reads a repo's current gates back with.
+ *
+ * ponytail: the ceiling is a command containing a comma or a literal " @ ",
+ * which this would split wrongly. Rare in a lint or test invocation, and the
+ * config file is hand-editable. Upgrade path is `ui.editor()`, a real
+ * multi-line buffer, once someone hits it.
+ */
+async function askGates(
+  ui: WizardUi,
+  repoName: string,
+  seed: { cmd: string; cwd: string }[],
+  probed: { cmd: string; cwd: string }[] = [],
+): Promise<{ cmd: string; cwd: string }[]> {
+  // A proposal fills the prompt only where the operator has not already decided.
+  // Overwriting gates they typed with a model's reading would be the one place a
+  // probe stopped being a proposal; `probeGates` has already shown them what it
+  // found, so it is on screen either way.
+  const raw = await ask(
+    ui,
+    `Pre-push gates for ${repoName} — exactly what CI runs, comma separated`,
+    formatGates(seed.length > 0 ? seed : probed),
+  );
+
+  const gates: { cmd: string; cwd: string }[] = [];
+  for (const chunk of raw.split(",")) {
+    const entry = chunk.trim();
+    if (entry.length === 0) continue;
+    const at = entry.lastIndexOf(" @ ");
+    if (at === -1) gates.push({ cmd: entry, cwd: "." });
+    else gates.push({ cmd: entry.slice(0, at).trim(), cwd: entry.slice(at + 3).trim() });
+  }
+
+  if (gates.length === 0) {
+    // Loud, because an unattended push with no gate is how a lint failure
+    // reaches the runners at 03:00 with nobody watching.
+    ui.notify(`No gates for ${repoName} — nothing will be verified before a push.`, "warning");
+  }
+  return gates;
+}
+
+/**
+ * How loud the orchestrator should be. A list rather than a confirm: "report
+ * scope" has no natural yes, and phrasing it as one would bury which answer
+ * means silence. The cursor starts on the current setting so Enter re-affirms
+ * it, the same contract every other prompt here has.
+ */
+async function askReportScope(ui: WizardUi, current: ReportScopeChoice): Promise<ReportScopeChoice> {
+  const options = REPORT_SCOPE_CHOICES.map((c) => ({ label: c.label, description: c.description }));
+  const at = REPORT_SCOPE_CHOICES.findIndex((c) => c.scope === current);
+  const picked = await ui.select("What should the orchestrator report unprompted?", options, {
+    initialIndex: at === -1 ? 0 : at,
+  });
+  if (picked === undefined) throw new Cancelled();
+
+  const choice = REPORT_SCOPE_CHOICES.find((c) => c.label === picked);
+  if (choice === undefined) {
+    // The harness answers with a label we did not offer only if the dialog
+    // contract changed under us; keeping the current scope is the answer that
+    // changes nothing, and it is said out loud rather than assumed.
+    ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
+    return current;
+  }
+  return choice.scope;
+}
+
+/**
+ * One value out of a closed vocabulary, described in the operator's words.
+ *
+ * A select rather than a confirm, and the cursor starts on the configured value
+ * so Enter re-affirms it — the contract every prompt here has. It cannot be a
+ * confirm: a precondition's safe answer is "keep requiring it", and this
+ * harness's confirms always start on no, so a re-run that Entered through them
+ * would quietly relax the gate it was meant to leave alone.
+ *
+ * The label *is* the config value, so the answer the harness hands back needs no
+ * lookup table that could disagree with the vocabulary it was built from.
+ */
+async function askLiteral<T extends string>(
+  ui: WizardUi,
+  title: string,
+  values: readonly T[],
+  described: { readonly [K in T]: string },
+  current: T,
+): Promise<T> {
+  const at = values.findIndex((v) => v === current);
+  const picked = await ui.select(
+    title,
+    values.map((v) => ({ label: v, description: described[v] })),
+    { initialIndex: at === -1 ? 0 : at },
+  );
+  if (picked === undefined) throw new Cancelled();
+
+  const hit = values.find((v) => v === picked);
+  if (hit === undefined) {
+    // The harness answered with a label we never offered, which only happens if
+    // the dialog contract changed under us. Keeping the current value is the
+    // answer that changes nothing, and it is said out loud rather than assumed.
+    ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
+    return current;
+  }
+  return hit;
+}
+
+/** How an empty list is both shown and typed. A word, because a blank line in
+ *  this wizard means "accept what you see", not "clear it". */
+const EMPTY_LIST = "none";
+
+/** A name list as the prompt shows it and reads it back — one spelling, so the
+ *  pre-filled default and the value it round-trips to cannot drift. */
+function formatNameList(names: readonly string[]): string {
+  return names.length === 0 ? EMPTY_LIST : names.join(", ");
+}
+
+function parseNameList(answer: string): string[] {
+  if (answer.trim().toLowerCase() === EMPTY_LIST) return [];
+  return answer
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+}
+
+/** Check names, artefacts, environments: open-ended lists this package cannot
+ *  enumerate, so the only validation is the shape. */
+async function askNameList(ui: WizardUi, title: string, seed: readonly string[]): Promise<string[]> {
+  return parseNameList(await ask(ui, title, formatNameList(seed)));
+}
+
+/**
+ * The `requires` set, typed rather than picked one confirm at a time.
+ *
+ * Validated in the dialog against the same array the loader validates against,
+ * and the complaint names every accepted value — an operator who mistyped a
+ * requirement they believed they had set would otherwise find out from a release
+ * that went ahead without it.
+ */
+async function askReleaseRequirements(
+  ui: WizardUi,
+  prior: readonly ReleaseRequirement[],
+): Promise<ReleaseRequirement[]> {
+  const accepted = RELEASE_REQUIREMENTS.join(", ");
+  // The vocabulary, spelled out where it is being asked for. Built from the same
+  // data the validator reads, so a fifth requirement is offered here the moment
+  // it exists rather than staying invisible to everyone who did not read #129.
+  ui.notify(
+    RELEASE_REQUIREMENTS.map((r) => `${r} — ${RELEASE_REQUIREMENT_CHOICES[r]}`).join("\n"),
+    "info",
+  );
+  const answered = await askValid(
+    ui,
+    `Release — what must have landed first (any of ${accepted}, comma separated, or "${EMPTY_LIST}")`,
+    formatNameList(prior),
+    (value) => {
+      const unknown = parseNameList(value).filter((name) => !RELEASE_REQUIREMENTS.some((r) => r === name));
+      return unknown.length === 0 ? undefined : `Not a release requirement: ${unknown.join(", ")}. Accepted: ${accepted}.`;
+    },
+  );
+
+  const chosen = new Set(parseNameList(answered));
+  // The vocabulary's order, not the operator's: two fleets that require the same
+  // three things must read identically in the plan and in a refusal.
+  return RELEASE_REQUIREMENTS.filter((r) => chosen.has(r));
+}
+
+/**
+ * The gating conditions #126's verbs read (#129).
+ *
+ * Asked here rather than left to a hand-edit because the whole point of moving
+ * them out of POLICY.md is that they are config: a condition an operator can
+ * only reach by opening `config.json` is one that stays at its default while
+ * their prose says something else, which is the drift this key ended.
+ */
+async function askPolicyPreconditions(ui: WizardUi, prior: ProjectPolicy): Promise<ProjectPolicy> {
+  const merge = {
+    requiredChecks: await askNameList(
+      ui,
+      `Merge — required checks (comma separated, "${EMPTY_LIST}" = every check the PR reports)`,
+      prior.merge.requiredChecks,
+    ),
+    baseFreshness: await askLiteral(
+      ui,
+      "Merge — must the PR be level with its base?",
+      BASE_FRESHNESS,
+      BASE_FRESHNESS_CHOICES,
+      prior.merge.baseFreshness,
+    ),
+    drafts: await askLiteral(
+      ui,
+      "Merge — draft pull requests",
+      DRAFT_POLICIES,
+      DRAFT_POLICY_CHOICES,
+      prior.merge.drafts,
+    ),
+    whenBehindBase: await askLiteral(
+      ui,
+      "Merge — a green PR that fell behind its base",
+      BEHIND_BASE_ACTIONS,
+      BEHIND_BASE_CHOICES,
+      prior.merge.whenBehindBase,
+    ),
+  };
+
+  const release = {
+    requires: await askReleaseRequirements(ui, prior.release.requires),
+    requiredChecks: await askNameList(
+      ui,
+      `Release — required checks (comma separated, "${EMPTY_LIST}" = every check the branch reports)`,
+      prior.release.requiredChecks,
+    ),
+    artefacts: await askNameList(
+      ui,
+      `Release — artefacts this project ships (comma separated, or "${EMPTY_LIST}")`,
+      prior.release.artefacts,
+    ),
+    environments: await askNameList(
+      ui,
+      `Release — environments a deploy may target (comma separated, or "${EMPTY_LIST}")`,
+      prior.release.environments,
+    ),
+  };
+
+  return { merge, release };
+}
+
+/**
+ * Who merges and who releases. Two confirms rather than one four-way list:
+ * these are independent grants — delegating merges is routine, delegating
+ * releases is not — and a menu of four combinations frames them as equally
+ * ordinary choices, which is exactly the framing a release grant must not get.
+ *
+ * Neither confirm can start on "yes", so a re-run that Enters through the
+ * wizard revokes rather than renews. That is the safe direction, and the
+ * current grant is named in the question so the revoke is never a surprise.
+ */
+async function askAuthority(
+  ui: WizardUi,
+  prior: ProjectConfig["authority"],
+): Promise<ProjectConfig["authority"]> {
+  const merge = await askYesNo(
+    ui,
+    "Merge authority",
+    "Delegate PR merging to the orchestrator session? It would land green PRs one at a time, each " +
+      "re-checked against the base branch first. Default: humans merge" +
+      `${prior.merge === "orchestrator" ? " — currently delegated, answer no to take it back" : ""}.`,
+  );
+  const release = await askYesNo(
+    ui,
+    "Release authority",
+    "Delegate release cutting to the orchestrator session? It would tag, pin and publish by the " +
+      "procedure you write into its brief — and its brief forbids cutting one before you have. " +
+      "Default: humans release" +
+      `${prior.release === "orchestrator" ? " — currently delegated, answer no to take it back" : ""}.`,
+  );
+  return { merge: merge ? "orchestrator" : "human", release: release ? "orchestrator" : "human" };
+}
+
+/**
+ * What each shape means to the operator being asked about it, in their words
+ * rather than the classifier's. Declared as data over the closed enum so a sixth
+ * shape cannot be added without a question to ask about it — an unasked shape
+ * would silently take the deny default and read as a decision afterwards.
+ *
+ * No fleet vocabulary here on purpose (#122): every one of these is an act the
+ * package can recognise anywhere, not a step in one project's release topology.
+ */
+const RELEASE_SHAPE_QUESTIONS: { readonly [K in (typeof RELEASE_SHAPES)[number]]: string } = {
+  "git-tag": "create git tags (`git tag v1.2.3`)",
+  "git-push-tags": "push tags to the remote (`git push --follow-tags`)",
+  "package-publish": "publish packages (`npm publish` and equivalents)",
+  "github-release": "create GitHub releases (`gh release create`)",
+  deploy:
+    "deploy — change what is running: kubectl/helm/terraform, a deploy device call, a rollout. " +
+    "This is the one grant that mutates a live environment rather than producing an artifact",
+};
+
+/**
+ * The questions no probe can answer, because the answers are not in the repo.
+ *
+ * Ported from the onboarding skill, which is explicit about why each one has to
+ * be asked. Today's wizard asks none of them: `askAuthority` and
+ * `askReleaseGrants` record *who holds* each release shape and never the prose
+ * that makes a delegated release safe — and `src/briefs/policy.md` ships stubs
+ * sitting empty because of it.
+ *
+ * Asked before any prose probe runs, so intent always precedes machinery: a
+ * probe's job is to turn these words into the repo's own steps, never to invent
+ * what the operator wants.
+ */
+async function askJudgment(
+  ui: WizardUi,
+  grants: ResolvedGrants,
+  prior: OperatorJudgment,
+): Promise<OperatorJudgment> {
+  // Always asked. A tracker shows what is open, never what matters, and an
+  // orchestrator that cannot rank work grooms by recency — which is how a stale
+  // issue outranks the thing being shipped this month.
+  const roadmap = await ask(
+    ui,
+    "Where does the roadmap live, and what is the current priority?",
+    prior.roadmap ?? "",
+  );
+  const judgment: OperatorJudgment = { ...prior, ...(roadmap.length === 0 ? {} : { roadmap }) };
+
+  const delegated = RELEASE_SHAPES.filter((shape) => grants[shape] === "orchestrator");
+  if (delegated.length === 0) {
+    // Humans release: there is no boundary to draw and no procedure to write, so
+    // asking would invite prose the config does not grant.
+    return judgment;
+  }
+
+  if (delegated.length === RELEASE_SHAPES.length) {
+    // Full release. Push back once, concretely, then record what they decide —
+    // it is their fleet. Shown once, never per shape.
+    ui.notify(
+      [
+        "You have granted the orchestrator every release shape. Two things to weigh:",
+        "",
+        "  Credentials. Full release means the session holds publish tokens, registry",
+        "  credentials or deploy keys. Those sit in the environment of a session that runs",
+        "  unattended for weeks — including a turn that went wrong.",
+        "",
+        "  Rollback. An agent that can release owns the 03:00 rollback too, and a rollback",
+        "  is a judgement call under time pressure with partial information: the exact",
+        "  thing agents are worst at.",
+        "",
+        "Answer the next questions anyway if that is the fleet you want.",
+      ].join("\n"),
+      "warning",
+    );
+  }
+
+  // Not "can it release" — *where does its leg stop*. A boundary that cannot be
+  // said in one sentence is not a boundary, and a vague release mandate is what
+  // eventually publishes something at 03:00. The worked example is the skill's,
+  // so an operator has something to calibrate against.
+  judgment.boundary = await ask(
+    ui,
+    "Where does the orchestrator's leg END? One sentence " +
+      '(a real answer: "at the merged version pin — deploying it is operator territory")',
+    prior.boundary ?? "",
+  );
+
+  // All five, because the brief needs each and a missing one is a hole.
+  judgment.releaseWhat = await ask(ui, "Release — WHAT may be released, and from which branch?", prior.releaseWhat ?? "");
+  judgment.releaseWhen = await ask(
+    ui,
+    "Release — WHEN: batched how, after which named checks are green?",
+    prior.releaseWhen ?? "",
+  );
+  judgment.releaseProof = await ask(
+    ui,
+    "Release — WHAT PROOF must be held first (results actually read, not an impression)?",
+    prior.releaseProof ?? "",
+  );
+  judgment.releaseAsk = await ask(ui, "Release — what must still be ASKED, every time?", prior.releaseAsk ?? "");
+  judgment.releaseForbidden = await ask(
+    ui,
+    "Release — what stays permanently FORBIDDEN?",
+    prior.releaseForbidden ?? "force-push, secrets, production data",
+  );
+
+  // The batching unit, in the operator's own vocabulary. Without it the
+  // orchestrator either releases per merge — a stream of meaningless versions
+  // burning shared runners — or never releases at all. Distinct from
+  // `RELEASE_REQUIREMENTS`, which are mechanical preconditions, not a unit.
+  judgment.worthCutting = await ask(
+    ui,
+    "What is a release worth cutting? (a sprint, an epic's children all closed, N merged issues, urgency)",
+    prior.worthCutting ?? "",
+  );
+
+  judgment.rollbackOwner = await ask(ui, "Who owns the rollback?", prior.rollbackOwner ?? "");
+  if (namesAPerson(judgment.rollbackOwner)) {
+    // Honour the consequence rather than recording a contradiction: if a person
+    // rolls it back, that person owns the release, and the boundary belongs
+    // before the irreversible step whatever the authority answer sounded like.
+    judgment.rollbackMovesBoundary = await askYesNo(
+      ui,
+      "Rollback owner is a person",
+      `You named "${judgment.rollbackOwner}" as the rollback owner. That person already owns the release, ` +
+        "so the honest configuration puts the orchestrator's boundary *before* the irreversible step — " +
+        "it prepares and verifies, a human performs it. Record the boundary that way?",
+    );
+    if (judgment.rollbackMovesBoundary) {
+      judgment.boundary = await ask(
+        ui,
+        "Restate the boundary, ending before the irreversible step",
+        judgment.boundary ?? "",
+      );
+    }
+  }
+  return judgment;
+}
+
+/**
+ * Whether a rollback answer names a human rather than a mechanism.
+ *
+ * Deliberately crude: the point is to *raise* the consequence for the operator to
+ * accept or decline, and a false positive costs one extra question while a false
+ * negative silently records the contradiction the skill warns about.
+ */
+function namesAPerson(answer: string): boolean {
+  const mechanical = ["ci", "workflow", "pipeline", "automation", "the agent", "orchestrator", "nobody", "none", "n/a"];
+  const trimmed = answer.trim().toLowerCase();
+  if (trimmed.length === 0) return false;
+  return !mechanical.some((m) => trimmed === m || trimmed.startsWith(`${m} `));
+}
+
+/**
+ * The mechanical tool gate, one confirm per shape.
+ *
+ * One binary question used to cover all five, which is how #122 happened: an
+ * operator who meant "it may cut a release" also granted "it may deploy to
+ * production", because there was one switch for both. Asking five times is the
+ * point — each answer is a different blast radius.
+ *
+ * No confirm can start on "yes", so a re-run that Enters through the wizard
+ * revokes rather than renews. The current grant is named in the question, so
+ * that revoke is never a surprise.
+ */
+async function askReleaseGrants(
+  ui: WizardUi,
+  prior: ResolvedGrants,
+): Promise<ResolvedGrants> {
+  const grants = { ...prior };
+  for (const shape of RELEASE_SHAPES) {
+    const open = await askYesNo(
+    ui,
+      `Release tool gate — ${shape}`,
+      `Allow the orchestrator session to ${RELEASE_SHAPE_QUESTIONS[shape]}? Grant this only when the ` +
+        "operator brief carries the procedure it must follow. A worker session is refused this " +
+        "whatever you answer. Default: no" +
+        `${prior[shape] === "orchestrator" ? " — currently granted, answer no to take it back" : ""}.`,
+    );
+    grants[shape] = open ? "orchestrator" : "human";
+  }
+  return grants;
+}
+
+/**
+ * Where the session that triages escalations lives. Phrased as a fact about the
+ * host rather than a preference, because that is what it is: answering yes when
+ * no such session exists leaves tier-1 escalations sitting in issue comments
+ * that nobody drains.
+ */
+async function askOrchestratorMode(ui: WizardUi, prior: OrchestratorMode): Promise<OrchestratorMode> {
+  const external = await askYesNo(
+    ui,
+    "Orchestrator session",
+    "Do you already run your own orchestrator session for this project — a visible TUI session, say? " +
+      "Then the daemon starts none of its own, and posts tier-1 escalations as issue comments for yours " +
+      "to drain. Default: no, the daemon runs one" +
+      `${prior === "external" ? " — currently external" : ""}.`,
+  );
+  return external ? "external" : "embedded";
+}
+
+/**
+ * Whether workers get a code graph, and where its clones live.
+ *
+ * One confirm and at most one prompt, asked after the repos are known because
+ * the answer is derived per repo. A declined answer leaves the field off every
+ * repo, which is what keeps an existing fleet's briefs byte-identical.
+ *
+ * The root is validated as absolute here rather than at load time so the
+ * operator learns immediately: a relative path would be resolved against
+ * whichever cwd happened to read the config, and never against the directory
+ * that was indexed.
+ */
+async function askGraphRoot(
+  ui: WizardUi,
+  trackerRepo: string,
+  repoNames: string[],
+  prior: string | undefined,
+): Promise<string | undefined> {
+  const wanted = await askYesNo(
+    ui,
+    "Code-graph discovery",
+    "Set up code-graph discovery for workers? Workers spend most of their turn budget finding code; " +
+      'a graph answers "who calls this" in one call. Conductor keeps one disposable clone per repo, ' +
+      "pinned to the default branch purely for indexing — never your own checkout" +
+      `${prior === undefined ? "" : `. Currently on, under ${prior}`}.`,
+  );
+  if (!wanted) return undefined;
+
+  return await askValid(
+    ui,
+    `Root for those clones — one per repo (${repoNames.join(", ")}) is created under it`,
+    prior ?? defaultGraphRoot(trackerRepo),
+    (v) =>
+      isAbsolute(expandHome(v))
+        ? undefined
+        : `"${v}" is not an absolute path — a worker reads this from its own worktree, so a relative one names the wrong directory.`,
+  );
+}
+
+/**
+ * Whether to render the operator's own brief, and — separately — whether an
+ * existing one may be replaced. Two questions on purpose: that file is where a
+ * fleet's release and reporting policy ends up, so it is never overwritten by
+ * an operator who only meant to re-run setup.
+ */
+async function askOrchestratorBrief(ui: WizardUi, a: SetupAnswers): Promise<boolean> {
+  const path = orchestratorBriefPath(a);
+  const wanted = await askYesNo(
+    ui,
+    `Write ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME} under ${dirname(path)}?`,
+    `Writes composed ${ORCHESTRATOR_BRIEF_NAME} (package floor, refreshed each tick) and ${POLICY_BRIEF_NAME} ` +
+      `(Releases, Project context, Reporting, Amendments — yours to edit via the Learning loop). ` +
+      `The conductor stops at green PRs either way.`,
+  );
+  if (!wanted) return false;
+  if (!existsSync(path)) return true;
+
+  return await askYesNo(
+    ui,
+    `Overwrite existing ${ORCHESTRATOR_BRIEF_NAME} / ${POLICY_BRIEF_NAME}?`,
+    `${path} already exists. Overwriting replaces the composed brief and POLICY.md scaffold — any policy you wrote is lost.`,
+  );
+}
+
+/** The project these answers would replace, so a re-run pre-fills with what is
+ *  already there instead of making the operator retype it. */
+function priorProject(existing: ConductorConfig | undefined, name: string | undefined): ProjectConfig | undefined {
+  if (existing === undefined) return undefined;
+  if (name !== undefined) return existing.projects.find((p) => p.name === name);
+  return existing.projects.length === 1 ? existing.projects[0] : undefined;
+}
+
+/**
+ * One area's questions, over the answers everything else is carried through in.
+ *
+ * Every asker takes the whole answer set and returns the whole answer set with
+ * only its own fields replaced. That is what lets the full interview fold them in
+ * order while an amend applies exactly one, with no second spelling of either the
+ * prompts or the defaults they pre-fill from: the value shown is always the value
+ * that would otherwise be carried through.
+ */
+type AreaAsker = (ui: WizardUi, a: SetupAnswers, probes: SetupProbes) => Promise<SetupAnswers>;
+
+/**
+ * The repo-reading half of onboarding, injected rather than called directly.
+ *
+ * One seam, for three reasons: `--no-ai` becomes a value instead of a branch at
+ * every call site; the wizard's own tests keep running with no model and no clone;
+ * and a probe stays visibly optional — every asker below still works when it
+ * returns nothing, which is the contract that lets setup survive an unreachable
+ * peer, a private repo, or a model that answered in prose.
+ */
+export interface SetupProbes {
+  /** Proposes a repo's pre-push gates by reading its CI. `[]` seeds nothing. */
+  gates(ui: WizardUi, target: ProbeTarget): Promise<ProbedGate[]>;
+  /**
+   * Drafts the brief's prose halves, each previewed and confirmed before it is
+   * kept. `undefined` — declined, unavailable, `--no-ai` — keeps the shipped stub.
+   */
+  prose(ui: WizardUi, a: SetupAnswers): Promise<ProbedProse>;
+}
+
+/** Reads each repo to propose answers. */
+export const DEFAULT_PROBES: SetupProbes = {
+  gates: (ui, target) => probeGates(ui, target),
+  prose: (ui, a) => proseFromRepos(ui, a),
+};
+
+/** `--no-ai`, and every wizard test: nothing is read, nothing is proposed. */
+export const NO_PROBES: SetupProbes = { gates: async () => [], prose: async () => ({}) };
+
+/**
+ * The brief's two prose halves, drafted against **every** configured repo.
+ *
+ * All of them, in one workspace, because both answers are cross-repo by nature and
+ * the skill this ports said so: "read, per routing repo" for the context, "per repo
+ * that can be released" for the procedure. A draft from one repo could not say
+ * which repo owns which concern, which repos ship together, or where the release
+ * machinery actually lives — it would have to guess, and a guess in a file the
+ * orchestrator re-reads every tick is an instruction it follows all week.
+ *
+ * One probe per section rather than per repo: `POLICY.md` has one Project context
+ * and one Releases procedure, and N drafts would have to be merged by hand.
+ */
+async function proseFromRepos(ui: WizardUi, a: SetupAnswers): Promise<ProbedProse> {
+  if (a.targetRepos.length === 0) return {};
+  const targets: ProbeTarget[] = a.targetRepos.map((r) => ({
+    name: r.name,
+    cloneUrl: r.cloneUrl,
+    defaultBranch: r.defaultBranch,
+  }));
+  const j = a.judgment ?? {};
+
+  const context = await probeProse(ui, "project-context", "the project context", targets, {
+    REPOS: probeRepoMap(targets, a.routingLabelPrefix),
+    ROADMAP: j.roadmap ?? "",
+  });
+
+  // Only when the operator actually delegated a release: with no stated intent
+  // there is nothing for the probe to express, and a procedure drafted from a
+  // repo's machinery alone is the invention the template forbids.
+  const delegated = [j.releaseWhat, j.releaseWhen, j.boundary].some(
+    (v) => v !== undefined && v.trim().length > 0,
+  );
+  const procedure = delegated
+    ? await probeProse(ui, "release-procedure", "the release procedure", targets, {
+        // Without this the probe cannot follow its own instruction to name repos by
+        // routing key: the checkouts are generated `repo-N` directories, and an
+        // arbitrary key is not recoverable from one.
+        REPOS: probeRepoMap(targets, a.routingLabelPrefix),
+        BOUNDARY: j.boundary ?? "",
+        WHAT: j.releaseWhat ?? "",
+        WHEN: j.releaseWhen ?? "",
+        PROOF: j.releaseProof ?? "",
+        ASK: j.releaseAsk ?? "",
+        FORBIDDEN: j.releaseForbidden ?? "",
+        WORTH_CUTTING: j.worthCutting ?? "",
+        ROLLBACK_OWNER: j.rollbackOwner ?? "",
+      })
+    : undefined;
+
+  return {
+    ...(context === undefined ? {} : { projectContext: context }),
+    ...(procedure === undefined ? {} : { releaseProcedure: procedure }),
+  };
+}
+
+/**
+ * Where work comes from and where it lands: tracker, labels, routing prefix, and
+ * every repo an issue can be routed to, each with its gates. One area because it
+ * is one fact — the identity of the queue — and changing any part of it without
+ * seeing the rest is how a routing prefix stops matching its labels.
+ */
+const askTrackerAndRepos: AreaAsker = async (ui, a, probes) => {
+  const trackerRepo = await askValid(
+    ui,
+    "Tracker repo (owner/repo) — where ready issues live",
+    a.trackerRepo,
+    (v) => (REPO_RE.test(v) ? undefined : `"${v}" is not owner/repo — e.g. acme/planning.`),
+  );
+
+  const queueLabel = await ask(
+    ui,
+    "Queue label — the human sign-off that makes an issue claimable",
+    a.queueLabel,
+  );
+
+  // One confirm instead of three prompts: the namespaced defaults are right for
+  // almost everyone, and three dialogs of Enter-to-accept is how a wizard earns
+  // its reputation.
+  const stateLabels: SetupAnswers["stateLabels"] = { ...a.stateLabels };
+  const customiseStates = await askYesNo(
+    ui,
+    "State labels",
+    `The conductor writes back "${stateLabels.inProgress}", "${stateLabels.blocked}" and ` +
+      `"${stateLabels.failed}" so the tracker alone shows live state. Rename them?`,
+  );
+  if (customiseStates) {
+    stateLabels.inProgress = await ask(ui, "Label for a run in progress", stateLabels.inProgress);
+    stateLabels.blocked = await ask(ui, "Label for a run parked on a human", stateLabels.blocked);
+    stateLabels.failed = await ask(ui, "Label for a run that gave up", stateLabels.failed);
+  }
+
+  const routingLabelPrefix = await ask(
+    ui,
+    "Routing label prefix — an issue picks its checkout with <prefix><repo>",
+    a.routingLabelPrefix,
+  );
+
+  const targetRepos: SetupAnswers["targetRepos"] = [];
+  for (let i = 0; ; i++) {
+    const seed = a.targetRepos[i];
+    const name = await askValid(
+      ui,
+      `Routing key for repo ${i + 1} — the "${routingLabelPrefix}<key>" label an issue carries`,
+      seed?.name ?? "",
+      (v) => (v.length > 0 ? undefined : "A routing key is required, or no issue can reach this repo."),
+    );
+    const cloneUrl = await askValid(
+      ui,
+      `Clone URL for ${routingLabelPrefix}${name}`,
+      seed?.cloneUrl ?? "",
+      (v) => (v.length > 0 ? undefined : "A clone URL is required — the daemon mirrors it before every run."),
+    );
+    const defaultBranch = await ask(
+      ui,
+      `Default branch for ${name} — worktrees are cut from it and PRs target it`,
+      seed?.defaultBranch ?? SETUP_DEFAULTS.defaultBranch,
+    );
+    // Read before the prompt, so what the probe found is on screen while the
+    // operator reads the default. Skipped when this repo already has gates.
+    const existingGates = seed?.gates ?? [];
+    const probed = existingGates.length > 0 ? [] : await probes.gates(ui, { name, cloneUrl, defaultBranch });
+    targetRepos.push({ name, cloneUrl, defaultBranch, gates: await askGates(ui, name, existingGates, probed) });
+
+    const more = await askYesNo(
+    ui,
+      "Another repo?",
+      `${targetRepos.map((r) => r.name).join(", ")} configured. Add another checkout this project routes to?`,
+    );
+    if (!more) break;
+  }
+
+  return { ...a, trackerRepo, queueLabel, stateLabels, routingLabelPrefix, targetRepos };
+};
+
+/**
+ * The gates alone, repo by repo, with nothing else asked.
+ *
+ * The area that earns amend mode: a CI command changes far more often than a
+ * clone URL does, and re-typing four repos to correct one lint invocation is the
+ * reason an operator edits config.json by hand instead.
+ */
+const askGatesOnly: AreaAsker = async (ui, a, probes) => {
+  if (a.targetRepos.length === 0) {
+    ui.notify("No repos are configured yet — amend \"tracker & repos\" first.", "warning");
+    return a;
+  }
+
+  const targetRepos: SetupAnswers["targetRepos"] = [];
+  for (const r of a.targetRepos) {
+    // Re-read even though gates exist: this is the area an operator opens *because*
+    // CI changed, so a fresh proposal is the whole reason they came. Their current
+    // gates stay the default; the proposal is shown beside it.
+    const probed = await probes.gates(ui, { name: r.name, cloneUrl: r.cloneUrl, defaultBranch: r.defaultBranch });
+    targetRepos.push({ ...r, gates: await askGates(ui, r.name, r.gates, probed) });
+  }
+  return { ...a, targetRepos };
+};
+
+/**
+ * Whether workers get a code graph, and where its clones live. Asked after the
+ * repos in the full interview because the answer is derived per repo.
+ */
+const askGraph: AreaAsker = async (ui, a) => {
+  const graphRoot = await askGraphRoot(
+    ui,
+    a.trackerRepo,
+    a.targetRepos.map((r) => r.name),
+    a.graphRoot,
+  );
+
+  const next: SetupAnswers = { ...a };
+  // Deleted rather than set to `undefined`: the absence of the key is what keeps
+  // a project that declines graphs identical to one written before they existed.
+  if (graphRoot === undefined) delete next.graphRoot;
+  else next.graphRoot = graphRoot;
+  return next;
+};
+
+/** The hard ceilings. One confirm first, because the shipped defaults are the
+ *  answer for anyone who has not measured their own runners. */
+const askCaps: AreaAsker = async (ui, a) => {
+  const caps: Partial<Caps> = { ...a.caps };
+  const spendLabel =
+    DEFAULT_CAPS.dailySpendUsd === null ? "no spend cap" : `$${DEFAULT_CAPS.dailySpendUsd}/day`;
+  // Workers are in-process omp sessions inside the daemon PID. On a host under
+  // 16 GiB the measured shape (2 workers + orchestrator) peaks at 3–4 GB and
+  // swaps on a 7.6 GB shared VPS (#51) — setup therefore defaults to 1 there.
+  const workersDefault =
+    caps.maxConcurrentWorkers ?? recommendedMaxWorkers(hostRamBytes());
+  const smallHostNote =
+    workersDefault < DEFAULT_CAPS.maxConcurrentWorkers
+      ? ` This host looks under 16 GiB RAM, so the worker default is ${workersDefault} instead of ${DEFAULT_CAPS.maxConcurrentWorkers}.`
+      : "";
+  const tuneCaps = await askYesNo(
+    ui,
+    "Caps",
+    `Defaults: ${workersDefault} workers, ` +
+      `${spendLabel}, ${DEFAULT_CAPS.workerMaxTurns} base / ` +
+      `${DEFAULT_CAPS.workerMaxTurnsCeiling} max turns and ` +
+      `${Math.round(DEFAULT_CAPS.workerWallClockMs / 60000)} min per worker, ` +
+      `${DEFAULT_CAPS.maxAttemptsPerIssue} failed attempts and ` +
+      `${DEFAULT_CAPS.maxContinuationsPerIssue} operational continuations per issue.${smallHostNote} Change them?`,
+  );
+  if (!tuneCaps) {
+    if (
+      caps.maxConcurrentWorkers === undefined &&
+      workersDefault !== DEFAULT_CAPS.maxConcurrentWorkers
+    ) {
+      caps.maxConcurrentWorkers = workersDefault;
+    }
+    return { ...a, caps };
+  }
+
+  // Spelled out rather than looped: adding a cap should fail to compile here,
+  // not silently go unasked.
+  caps.maxConcurrentWorkers = await askNumber(
+    ui,
+    "Max concurrent workers",
+    workersDefault,
+  );
+  caps.dailySpendUsd = await askSpendCap(
+    ui,
+    "Spend ceiling per rolling day (USD) — blank = no spend cap",
+    caps.dailySpendUsd !== undefined ? caps.dailySpendUsd : DEFAULT_CAPS.dailySpendUsd,
+  );
+  const workerMaxTurns = await askNumber(
+    ui,
+    "Turn ceiling per worker",
+    caps.workerMaxTurns ?? DEFAULT_CAPS.workerMaxTurns,
+  );
+  caps.workerMaxTurns = workerMaxTurns;
+  const turnCeilingFallback = Math.max(
+    workerMaxTurns,
+    caps.workerMaxTurnsCeiling ??
+      Math.min(workerMaxTurns * 2, Number.MAX_SAFE_INTEGER),
+  );
+  const workerMaxTurnsCeiling = await askNumber(
+    ui,
+    "Maximum turn ceiling for one issue",
+    turnCeilingFallback,
+  );
+  if (workerMaxTurnsCeiling < workerMaxTurns) {
+    ui.notify(
+      `Maximum turn ceiling ${workerMaxTurnsCeiling} cannot be below the ` +
+        `${workerMaxTurns}-turn worker base — keeping ${turnCeilingFallback}.`,
+      "warning",
+    );
+    caps.workerMaxTurnsCeiling = turnCeilingFallback;
+  } else {
+    caps.workerMaxTurnsCeiling = workerMaxTurnsCeiling;
+  }
+  caps.workerWallClockMs = await askNumber(
+    ui,
+    "Wall-clock ceiling per worker (ms)",
+    caps.workerWallClockMs ?? DEFAULT_CAPS.workerWallClockMs,
+  );
+  caps.maxAttemptsPerIssue = await askNumber(
+    ui,
+    "Failed implementation attempts per issue before escalation",
+    caps.maxAttemptsPerIssue ?? DEFAULT_CAPS.maxAttemptsPerIssue,
+  );
+  caps.maxContinuationsPerIssue = await askNumber(
+    ui,
+    "Operational continuations per issue before escalation",
+    caps.maxContinuationsPerIssue ?? DEFAULT_CAPS.maxContinuationsPerIssue,
+  );
+  return { ...a, caps };
+};
+
+/** Outside the caps block: a model is not a ceiling, and an operator who left
+ *  the caps alone may still want workers on a cheaper model. */
+const askWorkerModel: AreaAsker = async (ui, a) => {
+  const answered = await ask(ui, "Worker model pattern (blank = harness default)", a.workerModel ?? "");
+  const next: SetupAnswers = { ...a };
+  if (answered.trim().length === 0) delete next.workerModel;
+  else next.workerModel = answered.trim();
+  return next;
+};
+
+/** The two ownership questions, then the mechanical gate one shape at a time:
+ *  together they are what decides what an unattended fleet may do unasked. */
+const askAuthorityArea: AreaAsker = async (ui, a) => {
+  const authority = await askAuthority(ui, a.authority);
+  const releaseGrants = await askReleaseGrants(ui, a.releaseGrants);
+  // Asked here because it is the same decision one layer down: the grants say
+  // who may act, and these say where that permission stops. Amending authority
+  // therefore re-asks the boundary, which is the point — a grant widened without
+  // restating the boundary is how a delegated release loses its end.
+  const judgment = await askJudgment(ui, releaseGrants, a.judgment ?? {});
+  return { ...a, authority, releaseGrants, judgment };
+};
+
+/** What a merge and a release must satisfy. Asked straight after the grants:
+ *  who may act, then under what conditions (#129). */
+const askPolicy: AreaAsker = async (ui, a) => ({ ...a, policy: await askPolicyPreconditions(ui, a.policy) });
+
+/** How a stuck run reaches a human, and who triages it when it does. */
+const askEscalation: AreaAsker = async (ui, a) => {
+  const telegram = detectTelegram();
+  let telegramChatId = a.telegramChatId;
+  if (telegram.available && telegram.hasToken) {
+    if (telegramChatId === undefined && telegram.pairedOwnerId !== undefined) {
+      const usePaired = await askYesNo(
+        ui,
+        "Tier-2 escalations",
+        `omp-telegram is paired with chat ${telegram.pairedOwnerId}. Page it when a run is stuck?`,
+      );
+      if (usePaired) telegramChatId = telegram.pairedOwnerId;
+    } else {
+      const answered = await ask(ui, "Telegram chat id for tier-2 escalations (blank for none)", telegramChatId ?? "");
+      telegramChatId = answered.length > 0 ? answered : undefined;
+    }
+  } else {
+    // Not an error: tier 2 degrades to a comment, which is the documented fallback.
+    ui.notify(
+      `No usable omp-telegram install at ${telegram.stateDir} — tier-2 escalations will comment on the issue.`,
+      "info",
+    );
+  }
+
+  const telegramTopicId =
+    telegramChatId === undefined
+      ? undefined
+      : await askTelegramTopicId(ui, telegram.stateDir, a.telegramTopicId);
+
+  const fallbackToIssueComment = await askYesNo(
+    ui,
+    "Escalation fallback",
+    "Also comment on the issue when a run escalates? Recommended: a chat message you miss is a run nobody sees.",
+  );
+
+  const orchestratorMode = await askOrchestratorMode(ui, a.orchestratorMode);
+
+  const next: SetupAnswers = { ...a, fallbackToIssueComment, orchestratorMode };
+  if (telegramChatId === undefined) delete next.telegramChatId;
+  else next.telegramChatId = telegramChatId;
+  if (telegramTopicId === undefined) delete next.telegramTopicId;
+  else next.telegramTopicId = telegramTopicId;
+  return next;
+};
+
+/**
+ * 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).
+ */
+async function askTelegramTopicId(
+  ui: WizardUi,
+  stateDir: string,
+  prior: number | undefined,
+): Promise<number | undefined> {
+  const claimed = readClaimedTelegramTopics(stateDir);
+  const manual = "Enter thread id manually";
+  const none = "None — flat chat (0.13 behaviour)";
+  if (claimed.length > 0) {
+    const options = [
+      ...claimed.map((t) => ({
+        label: `${t.name} — ${t.threadId}`,
+        description: `message_thread_id ${t.threadId}`,
+      })),
+      { label: manual, description: "type a numeric forum topic id" },
+      { label: none, description: "send to the chat root, not a topic" },
+    ];
+    const priorIdx = prior === undefined ? -1 : claimed.findIndex((t) => t.threadId === prior);
+    const picked = await ui.select("Telegram forum topic for tier-2 pages", options, {
+      initialIndex: priorIdx >= 0 ? priorIdx : claimed.length + 1,
+    });
+    if (picked === undefined) throw new Cancelled();
+    if (picked === none) return undefined;
+    if (picked !== manual) {
+      const hit = claimed.find((t) => `${t.name} — ${t.threadId}` === picked);
+      if (hit !== undefined) return hit.threadId;
+    }
+  }
+
+  const answered = await ask(
+    ui,
+    "Telegram forum topic id (blank for flat chat)",
+    prior !== undefined ? String(prior) : "",
+  );
+  if (answered.length === 0) return undefined;
+  const n = Number(answered);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n)) {
+    ui.notify(`"${answered}" is not an integer topic id — using flat chat.`, "warning");
+    return undefined;
+  }
+  return n;
+}
+
+function readClaimedTelegramTopics(stateDir: string): Array<{ threadId: number; name: string }> {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(join(stateDir, "threads.json"), "utf8"));
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return [];
+    if (!("threads" in raw)) return [];
+    const threads = raw.threads;
+    if (typeof threads !== "object" || threads === null || Array.isArray(threads)) return [];
+    const out: Array<{ threadId: number; name: string }> = [];
+    for (const [id, entry] of Object.entries(threads)) {
+      const threadId = Number(id);
+      if (!Number.isFinite(threadId) || !Number.isSafeInteger(threadId)) continue;
+      let name = id;
+      if (typeof entry === "object" && entry !== null && "name" in entry) {
+        const candidate = entry.name;
+        if (typeof candidate === "string" && candidate.trim() !== "") name = candidate.trim();
+      }
+      out.push({ threadId, name });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** How loud the orchestrator is and when the operator permits interruptions. */
+const askReporting: AreaAsker = async (ui, a) => {
+  const reportScope = await askReportScope(ui, a.reportScope);
+  const continuous = "Continuous (24-hour interrupts)";
+  const weekly = "Weekly availability window";
+  const mode = await ui.select(
+    "Operator availability",
+    [
+      {
+        label: continuous,
+        description: "preserve legacy behavior: configured interrupt categories may page at any hour",
+      },
+      {
+        label: weekly,
+        description: "hold non-bypass interruptions outside selected local working hours",
+      },
+    ],
+    { initialIndex: a.availability === undefined ? 0 : 1 },
+  );
+  if (mode === undefined) throw new Cancelled();
+
+  const next: SetupAnswers = { ...a, reportScope };
+  delete next.preservedReporting;
+  delete next.availability;
+  const applyDigestSchedule = (raw: string): SetupAnswers => {
+    const updated = { ...next };
+    delete updated.dailyDigestAt;
+    const value = raw.trim().toLowerCase();
+    if (value === "per-tick") {
+      updated.digestCadence = "per-tick";
+    } else if (value === "off" || value === "disabled" || value === "none") {
+      updated.digestCadence = "none";
+    } else if (value === "model-timed" || value === "daily") {
+      updated.digestCadence = "daily";
+    } else {
+      updated.digestCadence = "daily";
+      updated.dailyDigestAt = raw;
+    }
+    return updated;
+  };
+  const askDigestSchedule = async (fallback: string): Promise<SetupAnswers> => {
+    const shown =
+      a.digestCadence === "per-tick"
+        ? "per-tick"
+        : a.digestCadence === "none"
+          ? "off"
+          : a.dailyDigestAt ?? (a.digestCadence === "daily" ? "model-timed" : fallback);
+    const schedule = await askValid(
+      ui,
+      'Daily rollup time in that timezone / digest cadence ("per-tick", "model-timed", "off", or 24h HH:MM)',
+      shown,
+      (value) =>
+        ["per-tick", "model-timed", "daily", "none", "off", "disabled"].includes(
+          value.toLowerCase(),
+        ) || /^([01]\d|2[0-3]):[0-5]\d$/.test(value)
+          ? undefined
+          : 'Use "per-tick", "model-timed", "off", or a 24h HH:MM time.',
+    );
+    return applyDigestSchedule(schedule);
+  };
+
+  if (mode !== weekly) {
+    if (mode !== continuous) {
+      ui.notify(`Unrecognised availability choice "${mode}" — keeping 24-hour interrupts.`, "warning");
+    }
+    if (reportScope !== "quiet") return next;
+    return await askDigestSchedule("model-timed");
+  }
+
+  const defaultZone =
+    a.reportingTimezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  const reportingTimezone = await askValid(
+    ui,
+    "Operator timezone (IANA, for example Europe/London)",
+    defaultZone,
+    (value) => {
+      try {
+        new Intl.DateTimeFormat("en", { timeZone: value }).format();
+        return undefined;
+      } catch {
+        return `"${value}" is not a known IANA timezone.`;
+      }
+    },
+  );
+  const daysText = await askValid(
+    ui,
+    "Working weekdays (comma-separated: mon,tue,wed,thu,fri,sat,sun)",
+    a.availability?.days.join(",") ?? "mon,tue,wed,thu,fri",
+    (value) => {
+      const days = value.split(",").map((day) => day.trim().toLowerCase());
+      if (days.length === 0 || days.some((day) => !WEEKDAYS.includes(day as Weekday))) {
+        return `Use only: ${WEEKDAYS.join(",")}.`;
+      }
+      return new Set(days).size === days.length ? undefined : "List each weekday only once.";
+    },
+  );
+  const days = daysText.split(",").map((day) => day.trim().toLowerCase() as Weekday);
+  const start = await askValid(
+    ui,
+    "Availability starts (24h HH:MM)",
+    a.availability?.start ?? "09:00",
+    (value) => (/^([01]\d|2[0-3]):[0-5]\d$/.test(value) ? undefined : "Use 24h HH:MM."),
+  );
+  const end = await askValid(
+    ui,
+    "Availability ends (24h HH:MM)",
+    a.availability?.end ?? "17:00",
+    (value) =>
+      !/^([01]\d|2[0-3]):[0-5]\d$/.test(value)
+        ? "Use 24h HH:MM."
+        : value === start
+          ? "Start and end must differ."
+          : undefined,
+  );
+  const bypassText = await askValid(
+    ui,
+    `Quiet-hours bypass categories (comma-separated; "none" = none; choices: ${INTERRUPT_CATEGORIES.join(",")})`,
+    a.availability === undefined ? "fleet-stopped" : a.availability.bypass.join(",") || "none",
+    (value) => {
+      if (value.toLowerCase() === "none") return undefined;
+      const categories = value.split(",").map((category) => category.trim().toLowerCase());
+      if (categories.some((category) => !INTERRUPT_CATEGORIES.includes(category as InterruptCategory))) {
+        return `Use only: ${INTERRUPT_CATEGORIES.join(",")}, or "none".`;
+      }
+      return new Set(categories).size === categories.length ? undefined : "List each category only once.";
+    },
+  );
+  const bypass =
+    bypassText.toLowerCase() === "none"
+      ? []
+      : bypassText.split(",").map((category) => category.trim().toLowerCase() as InterruptCategory);
+  const scheduled = await askDigestSchedule(end);
+  return {
+    ...scheduled,
+    reportingTimezone,
+    availability: { days, start, end, bypass },
+  };
+};
+
+/** The operator's own brief. Asked last in the full interview, because the
+ *  question quotes the path the rest of the answers derive. */
+const askBrief: AreaAsker = async (ui, a) => ({ ...a, writeOrchestratorBrief: await askOrchestratorBrief(ui, a) });
+
+/**
+ * One dialog sequence per amend area, keyed so a new area cannot be added to
+ * {@link AMEND_AREA_IDS} without one.
+ */
+const AREA_ASKERS: { readonly [K in AmendAreaId]: AreaAsker } = {
+  tracker: askTrackerAndRepos,
+  gates: askGatesOnly,
+  // The two per-worker knobs the full interview separates with the authority
+  // grants; an amend has no reason to put anything between them.
+  caps: async (ui, a, probes) => await askWorkerModel(ui, await askCaps(ui, a, probes), probes),
+  "code-graph": askGraph,
+  authority: askAuthorityArea,
+  policy: askPolicy,
+  escalation: askEscalation,
+  reporting: askReporting,
+  // `askBrief` alone would be a trap. The floor brief and the unfilled stub both
+  // send an operator here to *fill in* Releases and Project context, and judgment
+  // is deliberately not persisted — so an area that asked only "overwrite it?"
+  // would rewrite POLICY.md from an empty judgment and replace a filled file with
+  // the very stubs they came to remove. The grants are already on disk, so the
+  // boundary questions are asked against the authority this project really has.
+  brief: async (ui, a, probes) =>
+    await askBrief(ui, { ...a, judgment: await askJudgment(ui, a.releaseGrants, a.judgment ?? {}) }, probes),
+};
+
+/** The two ways to answer the first question a configured project gets. Labels,
+ *  because the harness's select resolves to the label it displayed. */
+const AMEND_ONE = "Change one area";
+const REINTERVIEW = "Walk every question again";
+/** Third chooser row when a config already exists: start a full interview for a
+ *  brand-new neighbour rather than amending the one that is already there. */
+const ADD_PROJECT = "Add another project";
+
+/** Outcome of the first chooser on a re-run. */
+type AmendChoice =
+  | { kind: "area"; area: AmendAreaId }
+  | { kind: "reinterview" }
+  | { kind: "add-project" };
+
+/**
+ * The first question a re-run asks, and the reason amend mode exists: adding one
+ * key should not cost twenty prompts. Also the entry for adding a neighbour
+ * project without leaving the wizard (#319).
+ *
+ * Returns the area to amend, a full re-interview of the named project, or the
+ * add-a-project path. Only asked when a project is already configured — a first
+ * run has nothing to amend and is never shown this.
+ */
+async function chooseAmendArea(ui: WizardUi, prior: ProjectConfig): Promise<AmendChoice> {
+  const mode = await ui.select(
+    `"${prior.name}" is already configured — what would you like to do?`,
+    [
+      {
+        label: AMEND_ONE,
+        description: "asks one area's questions; every other answer is carried through from the saved config",
+      },
+      {
+        label: REINTERVIEW,
+        description: "the full interview, every prompt pre-filled with what is configured now",
+      },
+      {
+        label: ADD_PROJECT,
+        description: "full interview for a new project; existing projects stay as they are",
+      },
+    ],
+    { initialIndex: 0 },
+  );
+  if (mode === undefined) throw new Cancelled();
+  if (mode === ADD_PROJECT) return { kind: "add-project" };
+  if (mode !== AMEND_ONE) {
+    // Either the operator chose the full interview, or the dialog answered with
+    // a label we never offered. Both land on today's behaviour, which is the one
+    // that cannot silently skip a question.
+    if (mode !== REINTERVIEW) ui.notify(`Unrecognised choice "${mode}" — asking everything.`, "warning");
+    return { kind: "reinterview" };
+  }
+
+  const choices = amendChoices(prior);
+  const picked = await ui.select(
+    "Which area? Each row shows what it says now",
+    choices.map((c) => ({ label: c.label, description: c.description })),
+    { initialIndex: 0 },
+  );
+  if (picked === undefined) throw new Cancelled();
+
+  const chosen = choices.find((c) => c.label === picked);
+  if (chosen === undefined) {
+    // Guessing an area here would ask the wrong questions and carry the rest
+    // through as if they had been reviewed. Abandoning changes nothing.
+    ui.notify(`Unrecognised choice "${picked}" — nothing was changed.`, "warning");
+    throw new Cancelled();
+  }
+  return { kind: "area", area: chosen.id };
+}
+
+/**
+ * The conversation. Reads only — every answer is collected before anything is
+ * checked against GitHub, and long before anything is written.
+ *
+ * Seeded from one answers object rather than pre-filling each prompt from
+ * `prior?.field ?? default`: that is the same carry-through an amend relies on,
+ * so the two flows cannot disagree about what an unanswered field is.
+ */
+async function collectAnswers(
+  ui: WizardUi,
+  prior: ProjectConfig | undefined,
+  projectArg: string | undefined,
+  probes: SetupProbes,
+  opts: { added?: boolean } = {},
+): Promise<SetupAnswers> {
+  // Added projects seed under projects/<name>/; a first install and a re-interview
+  // of an existing project keep the flat (or already-on-disk) roots.
+  const seed =
+    prior === undefined
+      ? defaultAnswers(projectArg ?? "", { added: opts.added === true })
+      : answersFromProject(prior);
+
+  const projectName = await askValid(
+    ui,
+    "Project name",
+    projectArg ?? seed.projectName,
+    (v) => (v.length > 0 ? undefined : "A name is required — it is how `omp-conductor status --project <name>` finds this project."),
+  );
+
+  // When the operator renames mid-interview on an add, re-seed the scoped roots
+  // so they track the final name rather than the empty/CLI placeholder.
+  let a: SetupAnswers = { ...seed, projectName };
+  if (opts.added === true && prior === undefined) {
+    const scoped = defaultAnswers(projectName, { added: true });
+    a = {
+      ...a,
+      workspaceRoot: scoped.workspaceRoot,
+      mirrorRoot: scoped.mirrorRoot,
+    };
+  }
+  a = await askTrackerAndRepos(ui, a, probes);
+  // Straight after the repos, because it is a fact about them: one clone per
+  // routed repo, under one root.
+  a = await askGraph(ui, a, probes);
+  a = await askCaps(ui, a, probes);
+  a = await askAuthorityArea(ui, a, probes);
+  a = await askPolicy(ui, a, probes);
+  a = await askWorkerModel(ui, a, probes);
+  a = await askEscalation(ui, a, probes);
+  a = await askReporting(ui, a, probes);
+  // Asked last, and asked with the real path in the question — which needs the
+  // rest of the answers to derive.
+  return await askBrief(ui, a, probes);
+}
+
+/** The dry run, rendered. Same routing code the loop uses, so this is what the
+ *  next tick would actually do — not a description of it. */
+function formatPreview(p: QueuePreview): string[] {
+  const lines = [
+    `state        ${p.paused ? "paused" : "armed"}`,
+    p.ready.length === 0
+      ? "Would pick up: nothing — the queue is empty."
+      : `Would pick up ${p.ready.length} issue(s), caps permitting:`,
+  ];
+  for (const r of p.ready) lines.push(`  #${r.number}  → ${r.repo}  ${r.branch}  ${r.title}`);
+
+  if (p.unroutable.length > 0) {
+    lines.push("", `Cannot route ${p.unroutable.length} issue(s) — these escalate instead of running:`);
+    for (const u of p.unroutable) {
+      lines.push(`  #${u.number}  ${u.reason}  [${u.labels.join(", ") || "no labels"}]  ${u.title}`);
+    }
+  }
+  return lines;
+}
+
+
+/** What the whole conversation produced: the answers, and which area an amend
+ *  narrowed it to. `amend` absent means every question was asked. */
+export interface CollectedSetup {
+  answers: SetupAnswers;
+  amend?: { area: AmendAreaId; before: ProjectConfig };
+  /** True when this run is adding a neighbour project (or first-run-for-name). */
+  added?: boolean;
+}
+
+
+export async function ensureSetupArm(
+  projectName: string,
+  arm: typeof armTicks = armTicks,
+): Promise<string> {
+  const armed = await arm(projectName);
+  return armed.alreadyArmed
+    ? `existing heartbeat arm revalidated for owner ${armed.owner} at ${armed.path}`
+    : `heartbeat armed for owner ${armed.owner} at ${armed.path}`;
+}
+
+/**
+ * The whole conversation, from the amend question to the last prompt, and not one
+ * byte further: no `gh`, no dry run, nothing written.
+ *
+ * Exported at exactly that seam so a test can script the dialogs and pin what a
+ * first run asks and what an amend refuses to ask — the two properties amend mode
+ * is judged on — on a host with no `gh` and no config.
+ */
+export async function collectSetup(
+  ui: WizardUi,
+  existing: ConductorConfig | undefined,
+  projectArg: string | undefined,
+  areaArg: AmendAreaId | undefined,
+  probes: SetupProbes,
+): Promise<CollectedSetup> {
+  // Only a project that is already configured can be amended. A first run, or a
+  // name this config has never seen, goes straight into the full interview with
+  // no extra question — which is what it was before amend mode existed.
+  //
+  // When the config already has at least one project and the named (or sole)
+  // target is unknown, this is an add: seed under projects/<name>/ so the new
+  // fleet never shares the first project's flat worktrees/mirrors (#319).
+  const prior = priorProject(existing, projectArg);
+  if (prior === undefined) {
+    const adding = (existing?.projects.length ?? 0) > 0;
+    const answers = await collectAnswers(ui, undefined, projectArg, probes, { added: adding });
+    // An add that typed an already-configured name would silently replace via
+    // buildConfig. Ask first — amend (carry-through full interview of that
+    // project) or replace (answers as collected, roots as answered).
+    const named = existing?.projects.find((p) => p.name === answers.projectName);
+    if (named !== undefined) {
+      const mode = await ui.select(
+        `"${answers.projectName}" is already configured — amend or replace?`,
+        [
+          {
+            label: "Amend (keep existing settings, re-ask everything pre-filled)",
+            description: "full interview seeded from the saved project; other projects untouched",
+          },
+          {
+            label: "Replace with these answers",
+            description: "overwrites this project's config entry on apply; other projects untouched",
+          },
+        ],
+        { initialIndex: 0 },
+      );
+      if (mode === undefined) throw new Cancelled();
+      if (mode.startsWith("Amend")) {
+        return { answers: await collectAnswers(ui, named, answers.projectName, probes) };
+      }
+      // Replace: keep the answers just collected (including any scoped roots the
+      // operator saw). buildConfig replaces by name.
+      return { answers };
+    }
+    return {
+      answers,
+      added: adding || undefined,
+    };
+  }
+
+  // A positional CLI area skips the chooser: the operator already named which
+  // area they came to amend, so the first dialog is that area's first question
+  // rather than a menu of every area.
+  if (areaArg !== undefined) {
+    return {
+      answers: await AREA_ASKERS[areaArg](ui, answersFromProject(prior), probes),
+      amend: { area: areaArg, before: prior },
+    };
+  }
+
+  const choice = await chooseAmendArea(ui, prior);
+  if (choice.kind === "add-project") {
+    // Fresh interview, no pre-fill from the neighbour. CLI --project is ignored
+    // here: the operator just chose to add, so the name comes from the prompt.
+    const answers = await collectAnswers(ui, undefined, undefined, probes, { added: true });
+    const named = existing?.projects.find((p) => p.name === answers.projectName);
+    if (named !== undefined) {
+      const mode = await ui.select(
+        `"${answers.projectName}" is already configured — amend or replace?`,
+        [
+          {
+            label: "Amend (keep existing settings, re-ask everything pre-filled)",
+            description: "full interview seeded from the saved project; other projects untouched",
+          },
+          {
+            label: "Replace with these answers",
+            description: "overwrites this project's config entry on apply; other projects untouched",
+          },
+        ],
+        { initialIndex: 0 },
+      );
+      if (mode === undefined) throw new Cancelled();
+      if (mode.startsWith("Amend")) {
+        return { answers: await collectAnswers(ui, named, answers.projectName, probes) };
+      }
+      return { answers };
+    }
+    return { answers, added: true };
+  }
+  if (choice.kind === "reinterview") {
+    // Full interview of the *existing* name is a replace of that project. Ask
+    // once so a silent overwrite cannot happen from muscle-memory Enter.
+    const replace = await ui.confirm(
+      `Replace existing project "${prior.name}"?`,
+      "Walks every question again and overwrites this project's config entry on apply. " +
+        "Other projects are left alone. Cancel and pick \"Change one area\" to amend without a full replace, " +
+        "or \"Add another project\" to create a neighbour.",
+    );
+    if (replace !== true) throw new Cancelled();
+    return { answers: await collectAnswers(ui, prior, projectArg, probes) };
+  }
+
+  return {
+    answers: await AREA_ASKERS[choice.area](ui, answersFromProject(prior), probes),
+    amend: { area: choice.area, before: prior },
+  };
+}
+
+/**
+ * Operator steps herdr requires for a new fleet pane. Verified against
+ * `herdr workspace create` / `herdr agent start` help and recover.sh bootstrap:
+ * create a workspace at the project's cwd, then start omp *into* that pane with
+ * `--kind omp --pane <id>`. Do **not** invent `agent start --session/--cwd` —
+ * `agent start` requires an existing pane at a shell prompt, and starting into a
+ * live orchestrator pane is refused or worse.
+ */
+export function formatHerdrHandoff(project: ProjectConfig, cfg: ConductorConfig): string {
+  const session = process.env["HERDR_SESSION"] ?? "conductor";
+  const cwds = cfg.projects.map((p) => p.workspaceRoot).join(":");
+  return [
+    "herdr handoff (CLI cannot do these — exact herdr argv):",
+    `  1. In session "${session}", create a workspace for project "${project.name}" at its workspaceRoot:`,
+    `       herdr --session ${session} workspace create --cwd ${project.workspaceRoot} --label ${project.name} --no-focus`,
+    "     Read root_pane.pane_id from the JSON reply (jq -r '((.result // .).root_pane.pane_id) // empty').",
+    `  2. Start omp in that empty pane. The agent NAME must match tick config agentName ("${project.name}"):`,
+    `       herdr --session ${session} agent start ${project.name} --kind omp --pane <pane-id>`,
+    "     The pane must be at a shell prompt with no agent on it. Never agent-start into a live orchestrator pane.",
+    `  3. Point herdr-conductor recovery at every fleet cwd (colon-separated; see #320):`,
+    `       FLEET_CWDS=${cwds}`,
+    `     Legacy single-fleet hosts can keep FLEET_CWD=${project.workspaceRoot} until multi-fleet recovery lands.`,
+    "  4. Reload the daemon so it serves every configured project:",
+    "       omp-conductor restart --now",
+    "     (printed, not auto-run, when workers are live or a neighbour was just added)",
+  ].join("\n");
+}
+
+
+
+export async function setup(
+  ui: WizardUi,
+  projectArg: string | undefined,
+  areaArg?: AmendAreaId,
+  probes: SetupProbes = DEFAULT_PROBES,
+): Promise<void> {
+  const path = configPath();
+  // A config that exists but does not parse is a fault to report, never
+  // something to quietly replace: overwriting it would delete every project it
+  // describes. Absence, by contrast, is just the first run.
+  const existing = existsSync(path) ? loadConfig() : undefined;
+  if (existing === undefined) {
+    ui.notify(`No config at ${path} yet — let's make one. Nothing is written until you confirm.`, "info");
+  }
+
+  let collected: CollectedSetup;
+  try {
+    collected = await collectSetup(ui, existing, projectArg, areaArg, probes);
+  } catch (err) {
+    if (!(err instanceof Cancelled)) throw err;
+    ui.notify("Setup cancelled — nothing was changed.", "info");
+    return;
+  }
+  const { answers, amend, added } = collected;
+
+  const scopes = await checkTokenScopes();
+  if (!scopes.ok) {
+    ui.notify(
+      `Setup stopped before writing anything. The gh token needs repo and project scopes. ` +
+        `Run \`gh auth refresh -s repo,project\`, then run setup again.`,
+      "error",
+    );
+    return;
+  }
+
+  // Drafted here — after the interview, before the plan — because the plan's single
+  // consent gate says "Writes ORCHESTRATOR.md + POLICY.md", and this is what those
+  // files will contain. Each draft carries its own preview and confirm; declining
+  // one keeps the shipped stub, so an operator who wants none reaches the same plan.
+  const prose = answers.writeOrchestratorBrief ? await probes.prose(ui, answers) : {};
+  const labels = await planLabels(answers.trackerRepo, answers);
+  const telegram = detectTelegram();
+  let nextConfig;
+  try {
+    nextConfig = buildConfig(answers, existing);
+  } catch (err) {
+    ui.notify(
+      `Setup stopped before writing anything. ${err instanceof Error ? err.message : String(err)}`,
+      "error",
+    );
+    return;
+  }
+  const project = findProject(nextConfig, answers.projectName);
+  const totalWorkers = totalConfiguredWorkers(nextConfig);
+  const overcommit = workerOvercommit(totalWorkers);
+  // The same project as it is configured right now, so a moved `workspaceRoot`
+  if (
+    project.escalation.orchestrator === "external" &&
+    !answers.writeOrchestratorBrief &&
+    (!existsSync(briefPathForProject(project)) || !existsSync(policyPathForProject(project)))
+  ) {
+    ui.notify(
+      `Setup stopped before writing anything. External orchestration needs ${ORCHESTRATOR_BRIEF_NAME} and ${POLICY_BRIEF_NAME}. ` +
+        `Run setup again and approve the brief write.`,
+      "error",
+    );
+    return;
+  }
+  const runtime = planHostRuntime(
+    project,
+    resolveCaps(project, nextConfig.defaults),
+    telegram.stateDir,
+    undefined,
+    totalWorkers,
+  );
+  let queuePreview: string[];
+  try {
+    queuePreview = formatPreview(await previewProject(project));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    ui.notify(
+      `Setup stopped before writing anything because the proposed queue could not be read: ${message}`,
+      "error",
+    );
+    return;
+  }
+
+  ui.notify(
+    [
+      // The delta first when there is one, then the whole plan: the confirm has
+      // to name every mutation it authorises, and a delta names none of them.
+      ...(amend === undefined ? [] : [summariseAmend(amend.area, amend.before, answers)]),
+      summarisePlan(answers, scopes, labels, telegram),
+      "",
+      formatHostRuntimePlan(runtime),
+      "",
+      ...(overcommit === undefined ? [] : [`WARNING: ${overcommit}`, ""]),
+      "Dry run against the PROPOSED config:",
+      ...queuePreview,
+      "",
+      "Nothing has been changed yet.",
+    ].join("\n"),
+    "info",
+  );
+
+  const toCreate = labels.filter((l) => !l.exists).map((l) => l.name);
+  // Deliberately `ui.confirm` rather than `askYesNo`: this is the one confirm
+  // after the interview, and dismissing it means the same thing as answering no
+  // — do not apply — so it returns through the existing "left untouched" path
+  // instead of raising a `Cancelled` nothing outside `collectSetup` catches.
+  const go = await ui.confirm(
+    amend === undefined ? "Apply this setup?" : `Apply this change to ${AMEND_AREAS[amend.area].name}?`,
+    [
+      toCreate.length > 0
+        ? `Creates ${toCreate.length} label(s) in ${answers.trackerRepo}: ${toCreate.join(", ")}.`
+        : "Creates no labels.",
+      `Writes ${path}, prepares a paused state database, then runs a paused daemon smoke.`,
+      runtime.service.action === "keep"
+        ? `Keeps the staged systemd unit at ${runtime.service.path}.`
+        : `${runtime.service.action === "create" ? "Creates" : "Updates"} the staged systemd unit at ${runtime.service.path}.`,
+      runtime.tick === undefined
+        ? ""
+        : runtime.tick.action === "keep"
+          ? `Keeps the external heartbeat config at ${runtime.tick.path}.`
+          : `${runtime.tick.action === "create" ? "Creates" : "Updates"} the external heartbeat config at ${runtime.tick.path}.`,
+      answers.writeOrchestratorBrief
+        ? `Writes ${orchestratorBriefPath(answers)}, which is then yours to edit.`
+        : "",
+      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.",
+      "Issues are only claimed after every setup gate succeeds.",
+    ]
+      .filter((s) => s.length > 0)
+      .join(" "),
+  );
+  if (!go) {
+    ui.notify("Left untouched — no labels created, no config written, nothing armed.", "info");
+    return;
+  }
+
+  // Hold first. Any later filesystem, tracker, smoke, or channel error leaves a
+  // partially applied setup unable to claim work.
+  prepareConductor(project.name);
+  const created = await createMissingLabels(answers.trackerRepo, labels);
+  saveConfig(nextConfig);
+  const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
+  const runtimeFiles = writeHostRuntime(runtime);
+  const smoke = await runSetupSmoke(project.name);
+  let smokeLine =
+    `paused daemon --once; temporary /healthz on :${smoke.daemon.port}; ` +
+    `stored status for ${smoke.status.project}`;
+  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).
+      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`.",
+          project.escalation.orchestrator === "external"
+            ? `Run \`omp-conductor arm --project ${project.name}\` if ticks are disarmed, then run \`omp-conductor resume --project ${project.name}\`.`
+            : `Then run \`omp-conductor resume --project ${project.name}\`.`,
+        ].join("\n"),
+        "warning",
+      );
+      ui.notify(formatHerdrHandoff(project, nextConfig), "info");
+      return;
+    }
+    // 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) {
+      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",
+      );
+    } else {
+      const restarted = await restartDaemon({ project: project.name });
+      restartVia = restarted.via;
+      smokeLine =
+        `existing /healthz and stored status; restarted through ${restarted.via}; ` +
+        `new /healthz on :${restarted.record.port}`;
+    }
+  }
+
+  let armLine = "embedded orchestrator — no heartbeat arm marker";
+  if (project.escalation.orchestrator === "external") {
+    ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
+    try {
+      armLine = await ensureSetupArm(project.name);
+    } catch (err) {
+      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 ${project.workspaceRoot}, then run \`omp-conductor arm --project ${project.name}\`.`,
+          "After the arm proof succeeds, run `omp-conductor resume`.",
+        ].join("\n"),
+        "warning",
+      );
+      ui.notify(formatHerdrHandoff(project, nextConfig), "info");
+      return;
+    }
+  }
+  setPaused(false, undefined, project.name);
+
+  ui.notify(
+    [
+      created.length > 0 ? `Created label(s): ${created.join(", ")}` : "All required labels already existed.",
+      `Wrote ${path}; dispatch is ready.`,
+      briefPath === undefined
+        ? "Kept the existing orchestrator brief."
+        : `Wrote ${briefPath} + POLICY.md. Edit POLICY.md for Releases and Reporting.`,
+      runtimeFiles.length === 0
+        ? "Host runtime files were already current."
+        : `Wrote host runtime file(s): ${runtimeFiles.join(", ")}`,
+      `Smoke passed: ${smokeLine}.`,
+      `Heartbeat: ${armLine}.`,
+      "",
+      "Use the documented toy-issue drill to prove one complete worker path.",
+    ].join("\n"),
+    "info",
+  );
+
+  // The two installs setup used to only print for the operator to retype.
+  // Offered rather than assumed: each needs root, and an operator who wants to
+  // read the unit before it is enabled must be able to decline and run the verb
+  // later. `undefined` — a dismissed prompt — is a skip, not a cancel: the config
+  // is already written by this point, so there is nothing left to abandon.
+  //
+  // Gated on `installedAction`, never on `service.action`. The staged copy is
+  // written by this very run, so it is always current by now — every fleet
+  // configured before the install was executed would have been told the unit
+  // matched and never offered the install, which is precisely the population that
+  // has never installed one.
+  if (runtime.installedAction === "keep") {
+    ui.notify(`The unit systemd reads (${runtime.installedPath}) already matches this config.`, "info");
+  } else if (platform() !== "linux") {
+    // No systemctl to run. The staged file is real and is what an operator copies
+    // to the box that will run it, so say where it is rather than offer an install
+    // that could only refuse.
+    ui.notify(
+      `Staged the unit at ${runtime.service.path}. systemd install is Linux-only — copy it to the fleet host and run \`omp-conductor setup host\` there.`,
+      "info",
+    );
+  } else {
+    const install = await ui.confirm(
+      "Install and start the supervised daemon now?",
+      `${runtime.installedAction === "create" ? "Installs" : "Updates"} ${runtime.installedPath} from ` +
+        `${runtime.service.path}, then enables and restarts it. Needs root, one step at a time, and shows every ` +
+        "command before it runs. Skipping is fine — `omp-conductor setup host` does exactly this later.",
+    );
+    if (install === true)
+      await runHostInstall(project, resolveCaps(project, nextConfig.defaults), telegram.stateDir, ui);
+    else ui.notify("Left the unit staged. When you want it supervised: omp-conductor setup host", "info");
+  }
+
+  if (graphRepos(project).length > 0) {
+    const wantsGraph = await ui.confirm(
+      "Install the code-graph indexes now?",
+      "Clones each index-only checkout as you, installs and enables the reindex timer as root, then seeds one " +
+        "indexing run so the first fetch happens while you watch. Minutes per repo. " +
+        "`omp-conductor setup graph` does the same later; `--no-seed` skips the seeding run.",
+    );
+    if (wantsGraph === true) await runGraphInstall(project, ui);
+    else
+      ui.notify(
+        "Skipped the code graph — workers grep until it exists. When you want it: omp-conductor setup graph",
+        "info",
+      );
+  }
+
+  // Always print: first install, amend, and add-a-project all need the operator
+  // to create/verify the herdr pane. Added projects especially — the CLI wrote
+  // tick + config but cannot start a herdr agent (#319).
+  ui.notify(formatHerdrHandoff(project, nextConfig), "info");
+}