omp-conductor 0.14.0 → 0.15.0

package/src/{plugin.ts → setup-wizard.ts}

@@ -1,52 +1,46 @@
 /**
- * The omp plugin surface: one `/conductor` command with four subcommands.
+ * The setup wizard: prompts, per-area amend, and the one-writer apply sequence.
  *
- * `status`, `pause` and `resume` are argument parsing plus printing over
- * ./daemon.ts, so the plugin and the `omp-conductor` CLI can never disagree
- * about what a cap means or where the state lives.
- *
- * `setup` is the exception, and only in volume: it owns the dialogs and nothing
- * else. Every decision it makes lives in ./setup.ts, which is headless and
- * tested; this file turns answers into questions and back again. The invariant
- * worth protecting is on `setup()` below — nothing is written before the confirm.
+ * 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 { dirname, isAbsolute } from "node:path";
+import { platform } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
 import {
-  formatBriefReport,
-  formatMigrateResult,
-  inspectBriefLayout,
-  migrateToPolicy,
-  repairPolicyBannerCrumbs,
-} from "./brief-upgrade.ts";
-import { configPath, expandHome, findProject, loadConfig, resolveCaps, saveConfig } from "./config.ts";
-import { hostRamBytes, recommendedMaxWorkers } from "./host.ts";
+  configPath,
+  expandHome,
+  findProject,
+  loadConfig,
+  resolveCaps,
+  saveConfig,
+} from "./config.ts";
+import { hostRamBytes, recommendedMaxWorkers, workerOvercommit } from "./host.ts";
 import {
-  isPaused,
   prepareConductor,
   previewProject,
   setPaused,
   type QueuePreview,
 } from "./daemon.ts";
-import {
-  armTicks,
-  clearPaneHalt,
-  disarmTicks,
-  halt,
-  haltWithPane,
-  hold,
-  releaseHold,
-  renderStatus,
-} from "./fleet.ts";
+import { armTicks, telegramStateDir } from "./fleet.ts";
 import { restartDaemon } from "./lifecycle.ts";
-
-import { defaultGraphRoot } from "./graph.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,
@@ -61,7 +55,6 @@ import {
   answersFromProject,
   briefPathForProject,
   policyPathForProject,
-  renderFloorForProject,
   buildConfig,
   checkTokenScopes,
   createMissingLabels,
@@ -70,12 +63,13 @@ import {
   formatGates,
   orchestratorBriefPath,
   planLabels,
-  renderBriefForProject,
   summariseAmend,
   summarisePlan,
   writeOrchestratorBrief,
   type AmendAreaId,
+  type OperatorJudgment,
   type SetupAnswers,
+  type ProbedProse,
 } from "./setup.ts";
 import {
   BASE_FRESHNESS,
@@ -94,95 +88,10 @@ import {
   type ProjectConfig,
   type ProjectPolicy,
   type ReleaseRequirement,
-  type ReportScope,
   type ReportScopeChoice,
   type ResolvedGrants,
 } from "./types.ts";
-
-/**
- * The slice of the omp extension API this plugin actually touches, mirroring
- * `RegisteredCommand` / `ExtensionUIContext` from `@oh-my-pi/pi-coding-agent`.
- *
- * Declared here rather than imported because the harness is a peer dependency:
- * the package has to type-check without it installed. Structural typing means
- * the real API object satisfies this on the way in, and narrowing the surface
- * to the five members the wizard uses keeps the coupling visible.
- */
-interface Completion {
-  value: string;
-  label: string;
-  description?: string;
-}
-
-interface CommandContext {
-  ui: {
-    notify(message: string, type?: "info" | "warning" | "error"): void;
-    confirm(title: string, message: string): Promise<boolean>;
-    /**
-     * Single-line text prompt. Resolves `undefined` when the operator dismisses
-     * the dialog, which the wizard treats as "abandon, change nothing".
-     *
-     * The harness has no pre-filled variant, so `placeholder` carries the
-     * default and submitting an empty line accepts it.
-     */
-    input(title: string, placeholder?: string): Promise<string | undefined>;
-    /**
-     * Single-choice list. Resolves the chosen option's **label**, or
-     * `undefined` when the operator dismisses it — so callers map labels back to
-     * their own values rather than trusting the index.
-     */
-    select(
-      title: string,
-      options: { label: string; description?: string }[],
-      dialogOptions?: { initialIndex?: number },
-    ): Promise<string | undefined>;
-  };
-}
-
-interface PluginApi {
-  registerCommand(
-    name: string,
-    options: {
-      description?: string;
-      getArgumentCompletions?: (argumentPrefix: string) => Completion[] | null;
-      handler: (args: string, ctx: CommandContext) => Promise<void>;
-    },
-  ): void;
-}
-
-const SUBCOMMANDS: Completion[] = [
-  {
-    value: "setup",
-    label: "setup",
-    description: "wizard: config, labels, dry run, then arm — or amend one area of a configured project",
-  },
-  { value: "status", label: "status", description: "layered fleet report: dispatch, ticks, pane, herdr, daemon" },
-  { value: "hold", label: "hold", description: "soft stop: pause claiming AND disarm ticks" },
-  { value: "halt", label: "halt", description: "hold + stop dispatch daemon; pass --pane to pin recovery off" },
-  { value: "arm", label: "arm", description: "proof-gated: inbound Telegram round-trip, then write arm marker" },
-  { value: "disarm", label: "disarm", description: "remove arm marker so ticks skip" },
-  { value: "release-pane", label: "release-pane", description: "clear halt --pane recovery pin" },
-  { value: "pause", label: "pause", description: "stop claiming only (ticks keep firing if armed); prefer hold" },
-  { value: "resume", label: "resume", description: "clear pause only — does not re-arm" },
-  {
-    value: "brief-upgrade",
-    label: "brief-upgrade",
-    description: "check ORCHESTRATOR.md against the brief this version ships",
-  },
-];
-
-const USAGE = [
-  "/conductor setup [project]         create a project, or amend one area of one you already have",
-  "/conductor status [project]        layered fleet report (dispatch, ticks, pane, herdr, daemon)",
-  "/conductor hold [project]          soft stop: pause claiming AND disarm ticks",
-  "/conductor halt [--pane] [project] hold + stop daemon; --pane pins conductor recovery off only",
-  "/conductor arm [project]           proof-gated inbound Telegram round-trip, then arm ticks",
-  "/conductor disarm [project]        remove arm marker (ticks skip)",
-  "/conductor release-pane [project]  clear halt --pane recovery pin",
-  "/conductor pause                   stop claiming only (prefer hold)",
-  "/conductor resume                  clear pause only — does not re-arm",
-  "/conductor brief-upgrade [project] check ORCHESTRATOR.md against the shipped brief",
-].join("\n");
+import type { WizardUi } from "./wizard-ui.ts";
 
 /**
  * Dismissing any dialog abandons the whole wizard.
@@ -207,29 +116,43 @@ const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
  * 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(ctx: CommandContext, title: string, fallback: string): Promise<string> {
-  const raw = await ctx.ui.input(title, fallback.length > 0 ? fallback : undefined);
+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(
-  ctx: CommandContext,
+  ui: WizardUi,
   title: string,
   fallback: string,
   check: (value: string) => string | undefined,
 ): Promise<string> {
   for (let attempt = 0; attempt < 3; attempt++) {
-    const value = await ask(ctx, title, fallback);
+    const value = await ask(ui, title, fallback);
     const problem = check(value);
     if (problem === undefined) return value;
-    ctx.ui.notify(problem, "warning");
+    ui.notify(problem, "warning");
   }
   throw new Cancelled();
 }
@@ -237,11 +160,11 @@ async function askValid(
 
 /** 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(ctx: CommandContext, title: string, fallback: number): Promise<number> {
-  const raw = await ask(ctx, title, String(fallback));
+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) {
-    ctx.ui.notify(`"${raw}" is not a non-negative number — keeping ${fallback}.`, "warning");
+    ui.notify(`"${raw}" is not a non-negative number — keeping ${fallback}.`, "warning");
     return fallback;
   }
   return value;
@@ -253,16 +176,16 @@ async function askNumber(ctx: CommandContext, title: string, fallback: number):
  * can turn the money brake off without writing a magic 0 (which is a hard stop).
  */
 async function askSpendCap(
-  ctx: CommandContext,
+  ui: WizardUi,
   title: string,
   fallback: number | null,
 ): Promise<number | null> {
   const seed = fallback === null ? "" : String(fallback);
-  const raw = (await ask(ctx, title, seed)).trim().toLowerCase();
+  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) {
-    ctx.ui.notify(
+    ui.notify(
       `"${raw}" is not a non-negative number or blank — keeping ${fallback === null ? "no cap" : fallback}.`,
       "warning",
     );
@@ -278,18 +201,23 @@ async function askSpendCap(
  *
  * 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 `ctx.ui.editor()`, a real
+ * config file is hand-editable. Upgrade path is `ui.editor()`, a real
  * multi-line buffer, once someone hits it.
  */
 async function askGates(
-  ctx: CommandContext,
+  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(
-    ctx,
+    ui,
     `Pre-push gates for ${repoName} — exactly what CI runs, comma separated`,
-    formatGates(seed),
+    formatGates(seed.length > 0 ? seed : probed),
   );
 
   const gates: { cmd: string; cwd: string }[] = [];
@@ -304,7 +232,7 @@ async function askGates(
   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.
-    ctx.ui.notify(`No gates for ${repoName} — nothing will be verified before a push.`, "warning");
+    ui.notify(`No gates for ${repoName} — nothing will be verified before a push.`, "warning");
   }
   return gates;
 }
@@ -315,10 +243,10 @@ async function askGates(
  * 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(ctx: CommandContext, current: ReportScopeChoice): Promise<ReportScopeChoice> {
+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 ctx.ui.select("What should the orchestrator report unprompted?", options, {
+  const picked = await ui.select("What should the orchestrator report unprompted?", options, {
     initialIndex: at === -1 ? 0 : at,
   });
   if (picked === undefined) throw new Cancelled();
@@ -328,7 +256,7 @@ async function askReportScope(ctx: CommandContext, current: ReportScopeChoice):
     // 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.
-    ctx.ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
+    ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
     return current;
   }
   return choice.scope;
@@ -347,14 +275,14 @@ async function askReportScope(ctx: CommandContext, current: ReportScopeChoice):
  * lookup table that could disagree with the vocabulary it was built from.
  */
 async function askLiteral<T extends string>(
-  ctx: CommandContext,
+  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 ctx.ui.select(
+  const picked = await ui.select(
     title,
     values.map((v) => ({ label: v, description: described[v] })),
     { initialIndex: at === -1 ? 0 : at },
@@ -366,7 +294,7 @@ async function askLiteral<T extends string>(
     // 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.
-    ctx.ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
+    ui.notify(`Unrecognised choice "${picked}" — keeping "${current}".`, "warning");
     return current;
   }
   return hit;
@@ -392,8 +320,8 @@ function parseNameList(answer: string): string[] {
 
 /** Check names, artefacts, environments: open-ended lists this package cannot
  *  enumerate, so the only validation is the shape. */
-async function askNameList(ctx: CommandContext, title: string, seed: readonly string[]): Promise<string[]> {
-  return parseNameList(await ask(ctx, title, formatNameList(seed)));
+async function askNameList(ui: WizardUi, title: string, seed: readonly string[]): Promise<string[]> {
+  return parseNameList(await ask(ui, title, formatNameList(seed)));
 }
 
 /**
@@ -405,19 +333,19 @@ async function askNameList(ctx: CommandContext, title: string, seed: readonly st
  * that went ahead without it.
  */
 async function askReleaseRequirements(
-  ctx: CommandContext,
+  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.
-  ctx.ui.notify(
+  ui.notify(
     RELEASE_REQUIREMENTS.map((r) => `${r} — ${RELEASE_REQUIREMENT_CHOICES[r]}`).join("\n"),
     "info",
   );
   const answered = await askValid(
-    ctx,
+    ui,
     `Release — what must have landed first (any of ${accepted}, comma separated, or "${EMPTY_LIST}")`,
     formatNameList(prior),
     (value) => {
@@ -440,29 +368,29 @@ async function askReleaseRequirements(
  * 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(ctx: CommandContext, prior: ProjectPolicy): Promise<ProjectPolicy> {
+async function askPolicyPreconditions(ui: WizardUi, prior: ProjectPolicy): Promise<ProjectPolicy> {
   const merge = {
     requiredChecks: await askNameList(
-      ctx,
+      ui,
       `Merge — required checks (comma separated, "${EMPTY_LIST}" = every check the PR reports)`,
       prior.merge.requiredChecks,
     ),
     baseFreshness: await askLiteral(
-      ctx,
+      ui,
       "Merge — must the PR be level with its base?",
       BASE_FRESHNESS,
       BASE_FRESHNESS_CHOICES,
       prior.merge.baseFreshness,
     ),
     drafts: await askLiteral(
-      ctx,
+      ui,
       "Merge — draft pull requests",
       DRAFT_POLICIES,
       DRAFT_POLICY_CHOICES,
       prior.merge.drafts,
     ),
     whenBehindBase: await askLiteral(
-      ctx,
+      ui,
       "Merge — a green PR that fell behind its base",
       BEHIND_BASE_ACTIONS,
       BEHIND_BASE_CHOICES,
@@ -471,19 +399,19 @@ async function askPolicyPreconditions(ctx: CommandContext, prior: ProjectPolicy)
   };
 
   const release = {
-    requires: await askReleaseRequirements(ctx, prior.release.requires),
+    requires: await askReleaseRequirements(ui, prior.release.requires),
     requiredChecks: await askNameList(
-      ctx,
+      ui,
       `Release — required checks (comma separated, "${EMPTY_LIST}" = every check the branch reports)`,
       prior.release.requiredChecks,
     ),
     artefacts: await askNameList(
-      ctx,
+      ui,
       `Release — artefacts this project ships (comma separated, or "${EMPTY_LIST}")`,
       prior.release.artefacts,
     ),
     environments: await askNameList(
-      ctx,
+      ui,
       `Release — environments a deploy may target (comma separated, or "${EMPTY_LIST}")`,
       prior.release.environments,
     ),
@@ -503,16 +431,18 @@ async function askPolicyPreconditions(ctx: CommandContext, prior: ProjectPolicy)
  * current grant is named in the question so the revoke is never a surprise.
  */
 async function askAuthority(
-  ctx: CommandContext,
+  ui: WizardUi,
   prior: ProjectConfig["authority"],
 ): Promise<ProjectConfig["authority"]> {
-  const merge = await ctx.ui.confirm(
+  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 ctx.ui.confirm(
+  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. " +
@@ -541,6 +471,139 @@ const RELEASE_SHAPE_QUESTIONS: { readonly [K in (typeof RELEASE_SHAPES)[number]]
     "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.
  *
@@ -554,12 +617,13 @@ const RELEASE_SHAPE_QUESTIONS: { readonly [K in (typeof RELEASE_SHAPES)[number]]
  * that revoke is never a surprise.
  */
 async function askReleaseGrants(
-  ctx: CommandContext,
+  ui: WizardUi,
   prior: ResolvedGrants,
 ): Promise<ResolvedGrants> {
   const grants = { ...prior };
   for (const shape of RELEASE_SHAPES) {
-    const open = await ctx.ui.confirm(
+    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 " +
@@ -577,8 +641,9 @@ async function askReleaseGrants(
  * no such session exists leaves tier-1 escalations sitting in issue comments
  * that nobody drains.
  */
-async function askOrchestratorMode(ctx: CommandContext, prior: OrchestratorMode): Promise<OrchestratorMode> {
-  const external = await ctx.ui.confirm(
+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 " +
@@ -601,12 +666,13 @@ async function askOrchestratorMode(ctx: CommandContext, prior: OrchestratorMode)
  * that was indexed.
  */
 async function askGraphRoot(
-  ctx: CommandContext,
+  ui: WizardUi,
   trackerRepo: string,
   repoNames: string[],
   prior: string | undefined,
 ): Promise<string | undefined> {
-  const wanted = await ctx.ui.confirm(
+  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, ' +
@@ -616,7 +682,7 @@ async function askGraphRoot(
   if (!wanted) return undefined;
 
   return await askValid(
-    ctx,
+    ui,
     `Root for those clones — one per repo (${repoNames.join(", ")}) is created under it`,
     prior ?? defaultGraphRoot(trackerRepo),
     (v) =>
@@ -632,9 +698,10 @@ async function askGraphRoot(
  * 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(ctx: CommandContext, a: SetupAnswers): Promise<boolean> {
+async function askOrchestratorBrief(ui: WizardUi, a: SetupAnswers): Promise<boolean> {
   const path = orchestratorBriefPath(a);
-  const wanted = await ctx.ui.confirm(
+  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). ` +
@@ -643,7 +710,8 @@ async function askOrchestratorBrief(ctx: CommandContext, a: SetupAnswers): Promi
   if (!wanted) return false;
   if (!existsSync(path)) return true;
 
-  return await ctx.ui.confirm(
+  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.`,
   );
@@ -666,7 +734,91 @@ function priorProject(existing: ConductorConfig | undefined, name: string | unde
  * prompts or the defaults they pre-fill from: the value shown is always the value
  * that would otherwise be carried through.
  */
-type AreaAsker = (ctx: CommandContext, a: SetupAnswers) => Promise<SetupAnswers>;
+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
@@ -674,16 +826,16 @@ type AreaAsker = (ctx: CommandContext, a: SetupAnswers) => Promise<SetupAnswers>
  * 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 (ctx, a) => {
+const askTrackerAndRepos: AreaAsker = async (ui, a, probes) => {
   const trackerRepo = await askValid(
-    ctx,
+    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(
-    ctx,
+    ui,
     "Queue label — the human sign-off that makes an issue claimable",
     a.queueLabel,
   );
@@ -692,19 +844,20 @@ const askTrackerAndRepos: AreaAsker = async (ctx, a) => {
   // 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 ctx.ui.confirm(
+  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(ctx, "Label for a run in progress", stateLabels.inProgress);
-    stateLabels.blocked = await ask(ctx, "Label for a run parked on a human", stateLabels.blocked);
-    stateLabels.failed = await ask(ctx, "Label for a run that gave up", stateLabels.failed);
+    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(
-    ctx,
+    ui,
     "Routing label prefix — an issue picks its checkout with <prefix><repo>",
     a.routingLabelPrefix,
   );
@@ -713,25 +866,30 @@ const askTrackerAndRepos: AreaAsker = async (ctx, a) => {
   for (let i = 0; ; i++) {
     const seed = a.targetRepos[i];
     const name = await askValid(
-      ctx,
+      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(
-      ctx,
+      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(
-      ctx,
+      ui,
       `Default branch for ${name} — worktrees are cut from it and PRs target it`,
       seed?.defaultBranch ?? SETUP_DEFAULTS.defaultBranch,
     );
-    targetRepos.push({ name, cloneUrl, defaultBranch, gates: await askGates(ctx, name, seed?.gates ?? []) });
-
-    const more = await ctx.ui.confirm(
+    // 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?`,
     );
@@ -748,15 +906,19 @@ const askTrackerAndRepos: AreaAsker = async (ctx, 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 (ctx, a) => {
+const askGatesOnly: AreaAsker = async (ui, a, probes) => {
   if (a.targetRepos.length === 0) {
-    ctx.ui.notify("No repos are configured yet — amend \"tracker & repos\" first.", "warning");
+    ui.notify("No repos are configured yet — amend \"tracker & repos\" first.", "warning");
     return a;
   }
 
   const targetRepos: SetupAnswers["targetRepos"] = [];
   for (const r of a.targetRepos) {
-    targetRepos.push({ ...r, gates: await askGates(ctx, r.name, r.gates) });
+    // 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 };
 };
@@ -765,9 +927,9 @@ const askGatesOnly: AreaAsker = async (ctx, a) => {
  * 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 (ctx, a) => {
+const askGraph: AreaAsker = async (ui, a) => {
   const graphRoot = await askGraphRoot(
-    ctx,
+    ui,
     a.trackerRepo,
     a.targetRepos.map((r) => r.name),
     a.graphRoot,
@@ -783,7 +945,7 @@ const askGraph: AreaAsker = async (ctx, a) => {
 
 /** 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 (ctx, a) => {
+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`;
@@ -796,7 +958,8 @@ const askCaps: AreaAsker = async (ctx, a) => {
     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 ctx.ui.confirm(
+  const tuneCaps = await askYesNo(
+    ui,
     "Caps",
     `Defaults: ${workersDefault} workers, ` +
       `${spendLabel}, ${DEFAULT_CAPS.workerMaxTurns} base / ` +
@@ -818,17 +981,17 @@ const askCaps: AreaAsker = async (ctx, a) => {
   // Spelled out rather than looped: adding a cap should fail to compile here,
   // not silently go unasked.
   caps.maxConcurrentWorkers = await askNumber(
-    ctx,
+    ui,
     "Max concurrent workers",
     workersDefault,
   );
   caps.dailySpendUsd = await askSpendCap(
-    ctx,
+    ui,
     "Spend ceiling per rolling day (USD) — blank = no spend cap",
     caps.dailySpendUsd !== undefined ? caps.dailySpendUsd : DEFAULT_CAPS.dailySpendUsd,
   );
   const workerMaxTurns = await askNumber(
-    ctx,
+    ui,
     "Turn ceiling per worker",
     caps.workerMaxTurns ?? DEFAULT_CAPS.workerMaxTurns,
   );
@@ -839,12 +1002,12 @@ const askCaps: AreaAsker = async (ctx, a) => {
       Math.min(workerMaxTurns * 2, Number.MAX_SAFE_INTEGER),
   );
   const workerMaxTurnsCeiling = await askNumber(
-    ctx,
+    ui,
     "Maximum turn ceiling for one issue",
     turnCeilingFallback,
   );
   if (workerMaxTurnsCeiling < workerMaxTurns) {
-    ctx.ui.notify(
+    ui.notify(
       `Maximum turn ceiling ${workerMaxTurnsCeiling} cannot be below the ` +
         `${workerMaxTurns}-turn worker base — keeping ${turnCeilingFallback}.`,
       "warning",
@@ -854,17 +1017,17 @@ const askCaps: AreaAsker = async (ctx, a) => {
     caps.workerMaxTurnsCeiling = workerMaxTurnsCeiling;
   }
   caps.workerWallClockMs = await askNumber(
-    ctx,
+    ui,
     "Wall-clock ceiling per worker (ms)",
     caps.workerWallClockMs ?? DEFAULT_CAPS.workerWallClockMs,
   );
   caps.maxAttemptsPerIssue = await askNumber(
-    ctx,
+    ui,
     "Failed implementation attempts per issue before escalation",
     caps.maxAttemptsPerIssue ?? DEFAULT_CAPS.maxAttemptsPerIssue,
   );
   caps.maxContinuationsPerIssue = await askNumber(
-    ctx,
+    ui,
     "Operational continuations per issue before escalation",
     caps.maxContinuationsPerIssue ?? DEFAULT_CAPS.maxContinuationsPerIssue,
   );
@@ -873,8 +1036,8 @@ const askCaps: AreaAsker = async (ctx, a) => {
 
 /** 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 (ctx, a) => {
-  const answered = await ask(ctx, "Worker model pattern (blank = harness default)", a.workerModel ?? "");
+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();
@@ -883,58 +1046,144 @@ const askWorkerModel: AreaAsker = async (ctx, a) => {
 
 /** 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 (ctx, a) => ({
-  ...a,
-  authority: await askAuthority(ctx, a.authority),
-  releaseGrants: await askReleaseGrants(ctx, a.releaseGrants),
-});
+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 (ctx, a) => ({ ...a, policy: await askPolicyPreconditions(ctx, a.policy) });
+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 (ctx, a) => {
+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 ctx.ui.confirm(
+      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(ctx, "Telegram chat id for tier-2 escalations (blank for none)", telegramChatId ?? "");
+      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.
-    ctx.ui.notify(
+    ui.notify(
       `No usable omp-telegram install at ${telegram.stateDir} — tier-2 escalations will comment on the issue.`,
       "info",
     );
   }
 
-  const fallbackToIssueComment = await ctx.ui.confirm(
+  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(ctx, a.orchestratorMode);
+  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 (ctx, a) => {
-  const reportScope = await askReportScope(ctx, a.reportScope);
+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 ctx.ui.select(
+  const mode = await ui.select(
     "Operator availability",
     [
       {
@@ -977,7 +1226,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
           ? "off"
           : a.dailyDigestAt ?? (a.digestCadence === "daily" ? "model-timed" : fallback);
     const schedule = await askValid(
-      ctx,
+      ui,
       'Daily rollup time in that timezone / digest cadence ("per-tick", "model-timed", "off", or 24h HH:MM)',
       shown,
       (value) =>
@@ -992,7 +1241,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
 
   if (mode !== weekly) {
     if (mode !== continuous) {
-      ctx.ui.notify(`Unrecognised availability choice "${mode}" — keeping 24-hour interrupts.`, "warning");
+      ui.notify(`Unrecognised availability choice "${mode}" — keeping 24-hour interrupts.`, "warning");
     }
     if (reportScope !== "quiet") return next;
     return await askDigestSchedule("model-timed");
@@ -1001,7 +1250,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
   const defaultZone =
     a.reportingTimezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
   const reportingTimezone = await askValid(
-    ctx,
+    ui,
     "Operator timezone (IANA, for example Europe/London)",
     defaultZone,
     (value) => {
@@ -1014,7 +1263,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
     },
   );
   const daysText = await askValid(
-    ctx,
+    ui,
     "Working weekdays (comma-separated: mon,tue,wed,thu,fri,sat,sun)",
     a.availability?.days.join(",") ?? "mon,tue,wed,thu,fri",
     (value) => {
@@ -1027,13 +1276,13 @@ const askReporting: AreaAsker = async (ctx, a) => {
   );
   const days = daysText.split(",").map((day) => day.trim().toLowerCase() as Weekday);
   const start = await askValid(
-    ctx,
+    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(
-    ctx,
+    ui,
     "Availability ends (24h HH:MM)",
     a.availability?.end ?? "17:00",
     (value) =>
@@ -1044,7 +1293,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
           : undefined,
   );
   const bypassText = await askValid(
-    ctx,
+    ui,
     `Quiet-hours bypass categories (comma-separated; "none" = none; choices: ${INTERRUPT_CATEGORIES.join(",")})`,
     a.availability === undefined ? "fleet-stopped" : a.availability.bypass.join(",") || "none",
     (value) => {
@@ -1070,7 +1319,7 @@ const askReporting: AreaAsker = async (ctx, a) => {
 
 /** 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 (ctx, a) => ({ ...a, writeOrchestratorBrief: await askOrchestratorBrief(ctx, a) });
+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
@@ -1081,30 +1330,47 @@ const AREA_ASKERS: { readonly [K in AmendAreaId]: AreaAsker } = {
   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 (ctx, a) => await askWorkerModel(ctx, await askCaps(ctx, a)),
-  graph: askGraph,
+  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,
-  brief: askBrief,
+  // `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.
+ * key should not cost twenty prompts. Also the entry for adding a neighbour
+ * project without leaving the wizard (#319).
  *
- * Returns the area to amend, or `undefined` for the full interview. Only asked
- * when the named project is already configured — a first run, or a new project
- * beside an old one, has nothing to amend and is never shown this.
+ * 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(ctx: CommandContext, prior: ProjectConfig): Promise<AmendAreaId | undefined> {
-  const mode = await ctx.ui.select(
+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?`,
     [
       {
@@ -1115,20 +1381,25 @@ async function chooseAmendArea(ctx: CommandContext, prior: ProjectConfig): Promi
         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) ctx.ui.notify(`Unrecognised choice "${mode}" — asking everything.`, "warning");
-    return undefined;
+    if (mode !== REINTERVIEW) ui.notify(`Unrecognised choice "${mode}" — asking everything.`, "warning");
+    return { kind: "reinterview" };
   }
 
   const choices = amendChoices(prior);
-  const picked = await ctx.ui.select(
+  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 },
@@ -1139,10 +1410,10 @@ async function chooseAmendArea(ctx: CommandContext, prior: ProjectConfig): Promi
   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.
-    ctx.ui.notify(`Unrecognised choice "${picked}" — nothing was changed.`, "warning");
+    ui.notify(`Unrecognised choice "${picked}" — nothing was changed.`, "warning");
     throw new Cancelled();
   }
-  return chosen.id;
+  return { kind: "area", area: chosen.id };
 }
 
 /**
@@ -1154,33 +1425,50 @@ async function chooseAmendArea(ctx: CommandContext, prior: ProjectConfig): Promi
  * so the two flows cannot disagree about what an unanswered field is.
  */
 async function collectAnswers(
-  ctx: CommandContext,
+  ui: WizardUi,
   prior: ProjectConfig | undefined,
   projectArg: string | undefined,
+  probes: SetupProbes,
+  opts: { added?: boolean } = {},
 ): Promise<SetupAnswers> {
-  const seed = prior === undefined ? defaultAnswers(projectArg ?? "") : answersFromProject(prior);
+  // 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(
-    ctx,
+    ui,
     "Project name",
     projectArg ?? seed.projectName,
-    (v) => (v.length > 0 ? undefined : "A name is required — it is how `/conductor status <name>` finds this project."),
+    (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 };
-  a = await askTrackerAndRepos(ctx, a);
+  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(ctx, a);
-  a = await askCaps(ctx, a);
-  a = await askAuthorityArea(ctx, a);
-  a = await askPolicy(ctx, a);
-  a = await askWorkerModel(ctx, a);
-  a = await askEscalation(ctx, a);
-  a = await askReporting(ctx, a);
+  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(ctx, a);
+  return await askBrief(ui, a, probes);
 }
 
 /** The dry run, rendered. Same routing code the loop uses, so this is what the
@@ -1209,6 +1497,8 @@ function formatPreview(p: QueuePreview): string[] {
 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;
 }
 
 
@@ -1231,74 +1521,206 @@ export async function ensureSetupArm(
  * is judged on — on a host with no `gh` and no config.
  */
 export async function collectSetup(
-  ctx: CommandContext,
+  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) return { answers: await collectAnswers(ctx, undefined, 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 area = await chooseAmendArea(ctx, prior);
-  if (area === undefined) return { answers: await collectAnswers(ctx, prior, projectArg) };
+  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[area](ctx, answersFromProject(prior)), amend: { area, before: prior } };
+  return {
+    answers: await AREA_ASKERS[choice.area](ui, answersFromProject(prior), probes),
+    amend: { area: choice.area, before: prior },
+  };
 }
 
 /**
- * The onboarding wizard, and — for a project it already knows — the amend.
- *
- * The invariant that makes this safe against a live tracker: no mutation occurs
- * before the consent below. Config, tracker, and host-runtime planning are
- * read-only. The paused state, labels, config, brief, runtime files, smoke, and
- * arm proof all follow the same consent gate.
- *
- * An amend changes which questions are asked and what the summary leads with,
- * and nothing else: the same answers, the same `buildConfig`, the same single
- * confirm, the same dry run. One writer, one consent gate.
+ * 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.
  */
-async function setup(ctx: CommandContext, projectArg: string | undefined): Promise<void> {
+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) {
-    ctx.ui.notify(`No config at ${path} yet — let's make one. Nothing is written until you confirm.`, "info");
+    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(ctx, existing, projectArg);
+    collected = await collectSetup(ui, existing, projectArg, areaArg, probes);
   } catch (err) {
     if (!(err instanceof Cancelled)) throw err;
-    ctx.ui.notify("Setup cancelled — nothing was changed.", "info");
+    ui.notify("Setup cancelled — nothing was changed.", "info");
     return;
   }
-  const { answers, amend } = collected;
+  const { answers, amend, added } = collected;
 
   const scopes = await checkTokenScopes();
   if (!scopes.ok) {
-    ctx.ui.notify(
+    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();
-  const nextConfig = buildConfig(answers, existing);
+  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)))
   ) {
-    ctx.ui.notify(
+    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",
@@ -1309,20 +1731,22 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
     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);
-    ctx.ui.notify(
+    ui.notify(
       `Setup stopped before writing anything because the proposed queue could not be read: ${message}`,
       "error",
     );
     return;
   }
 
-  ctx.ui.notify(
+  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.
@@ -1331,6 +1755,7 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
       "",
       formatHostRuntimePlan(runtime),
       "",
+      ...(overcommit === undefined ? [] : [`WARNING: ${overcommit}`, ""]),
       "Dry run against the PROPOSED config:",
       ...queuePreview,
       "",
@@ -1340,7 +1765,11 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
   );
 
   const toCreate = labels.filter((l) => !l.exists).map((l) => l.name);
-  const go = await ctx.ui.confirm(
+  // 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
@@ -1367,16 +1796,16 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
       .join(" "),
   );
   if (!go) {
-    ctx.ui.notify("Left untouched — no labels created, no config written, nothing armed.", "info");
+    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();
+  prepareConductor(project.name);
   const created = await createMissingLabels(answers.trackerRepo, labels);
   saveConfig(nextConfig);
-  const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers) : undefined;
+  const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
   const runtimeFiles = writeHostRuntime(runtime);
   const smoke = await runSetupSmoke(project.name);
   let smokeLine =
@@ -1385,33 +1814,51 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
   let restartVia: "systemctl" | "cli" | undefined;
   if (smoke.mode === "existing") {
     if (smoke.status.liveWorkers > 0) {
-      ctx.ui.notify(
+      // 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 --project ${project.name}\`.`,
+          "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\`.`
-            : "Then run `omp-conductor resume`.",
+            ? `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;
     }
-    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}`;
+    // 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") {
-    ctx.ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
+    ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
     try {
       armLine = await ensureSetupArm(project.name);
     } catch (err) {
-      ctx.ui.notify(
+      ui.notify(
         [
           "Setup files passed the paused daemon smoke, but the fleet remains held.",
           err instanceof Error ? err.message : String(err),
@@ -1420,12 +1867,13 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
         ].join("\n"),
         "warning",
       );
+      ui.notify(formatHerdrHandoff(project, nextConfig), "info");
       return;
     }
   }
-  setPaused(false);
+  setPaused(false, undefined, project.name);
 
-  ctx.ui.notify(
+  ui.notify(
     [
       created.length > 0 ? `Created label(s): ${created.join(", ")}` : "All required labels already existed.",
       `Wrote ${path}; dispatch is ready.`,
@@ -1438,184 +1886,61 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
       `Smoke passed: ${smokeLine}.`,
       `Heartbeat: ${armLine}.`,
       "",
-      "On a systemd host, install and start the supervised daemon:",
-      ...(restartVia === "cli" ? ["  omp-conductor stop"] : []),
-      ...runtime.installCommands.map((command) => `  ${command}`),
-      "",
-      "Without systemd, run `omp-conductor start`.",
       "Use the documented toy-issue drill to prove one complete worker path.",
     ].join("\n"),
     "info",
   );
-}
 
-export default function conductorPlugin(pi: PluginApi): void {
-  pi.registerCommand("conductor", {
-    description: "Dispatch ready issues to omp coding sessions",
-    getArgumentCompletions: (prefix) => SUBCOMMANDS.filter((s) => s.value.startsWith(prefix.trim())),
+  // 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");
+  }
 
-    handler: async (args, ctx) => {
-      // findProject() throws when the config holds several projects and none is
-      // named, so the project name rides along as an optional second word.
-      const tokens = args.trim().split(/\s+/).filter(Boolean);
-      const sub = tokens[0];
-      const withPane = tokens.includes("--pane");
-      const project = tokens.find((t, i) => i > 0 && t !== "--pane");
+  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",
+      );
+  }
 
-      try {
-        switch (sub) {
-          case "setup":
-            await setup(ctx, project);
-            break;
-
-          case "status":
-            ctx.ui.notify(await renderStatus(project), "info");
-            break;
-
-          case "hold": {
-            const r = hold(project);
-            ctx.ui.notify(
-              `Held — claiming paused; ticks disarmed at ${r.disarmed.path}. Daemon and pane left running.`,
-              "info",
-            );
-            break;
-          }
-
-          case "halt": {
-            if (withPane) {
-              const r = await haltWithPane(project);
-              const stop =
-                r.stop.kind === "not-running"
-                  ? "daemon was not running"
-                  : `daemon stopped (pid ${r.stop.pid})`;
-              ctx.ui.notify(
-                `Halted — ${stop}. Pane: ${r.pane.stopped} (${r.pane.detail}); recovery pinned at ${r.pane.pinPath}.`,
-                "info",
-              );
-            } else {
-              const r = await halt(project);
-              const stop =
-                r.stop.kind === "not-running"
-                  ? "daemon was not running"
-                  : `daemon stopped (pid ${r.stop.pid})`;
-              ctx.ui.notify(`Halted — ${stop}. Pane left running.`, "info");
-            }
-            break;
-          }
-
-          case "arm": {
-            ctx.ui.notify("Arm: sending inbound Telegram challenge — reply in the bot DM…", "info");
-            const r = await armTicks(project);
-            ctx.ui.notify(`ARMED — owner ${r.owner}; marker ${r.path}`, "info");
-            break;
-          }
-
-          case "disarm": {
-            const r = disarmTicks(project);
-            ctx.ui.notify(`Disarmed — ${r.path}`, "info");
-            break;
-          }
-
-          case "release-pane": {
-            const r = clearPaneHalt(project);
-            ctx.ui.notify(
-              r.wasHalted ? `Pane recovery pin cleared (${r.path}).` : `No pane recovery pin at ${r.path}.`,
-              "info",
-            );
-            break;
-          }
-
-          case "pause":
-            setPaused(true, { source: "pause", reason: "via /conductor pause" });
-            ctx.ui.notify("Paused claiming only — ticks keep firing if armed. Prefer /conductor hold.", "info");
-            break;
-
-          case "resume":
-            releaseHold();
-            ctx.ui.notify("Resumed claiming — did NOT re-arm. Run /conductor arm for ticks.", "info");
-            break;
-
-          case "brief-upgrade": {
-            const p = findProject(loadConfig(), project);
-            const path = briefPathForProject(p);
-            const rendered = renderBriefForProject(p);
-            const layout = inspectBriefLayout(p.workspaceRoot, rendered);
-            if (layout.kind === "missing") {
-              ctx.ui.notify(
-                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME}.`,
-                "warning",
-              );
-              break;
-            }
-            if (layout.kind === "overlay") {
-              ctx.ui.notify(
-                formatBriefReport(path, layout, []),
-                "info",
-              );
-              const repair = await ctx.ui.confirm(
-                "Repair POLICY.md banner crumbs and recompose?",
-                "Strips any leading HTML-comment leftovers from a pre-fix migrate, then recomposes ORCHESTRATOR.md from the package floor + POLICY.md.",
-              );
-              if (repair) {
-                const repaired = repairPolicyBannerCrumbs({
-                  orchestratorPath: layout.orchestratorPath,
-                  policyPath: layout.policyPath,
-                  floor: renderFloorForProject(p),
-                });
-                ctx.ui.notify(
-                  repaired === undefined
-                    ? "Recomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip."
-                    : formatMigrateResult(repaired),
-                  "info",
-                );
-              }
-              break;
-            }
-            if (layout.kind === "legacy-bannered") {
-              ctx.ui.notify(
-                [
-                  `Legacy bannered brief at ${layout.orchestratorPath}.`,
-                  "Migrate the owned half into POLICY.md so the package floor refreshes each tick.",
-                ].join("\n"),
-                "warning",
-              );
-              const migrate = await ctx.ui.confirm(
-                "Migrate to POLICY.md overlay?",
-                "Writes POLICY.md from everything below YOURS TO EDIT, recomposes ORCHESTRATOR.md from the package floor + that policy, and keeps backups.",
-              );
-              if (migrate) {
-                const result = migrateToPolicy({
-                  orchestratorPath: layout.orchestratorPath,
-                  policyPath: policyPathForProject(p),
-                  floor: renderFloorForProject(p),
-                  owned: layout.owned,
-                });
-                ctx.ui.notify(formatMigrateResult(result), "info");
-              }
-              break;
-            }
-            // Hand-written: the plugin no longer merges single-file briefs
-            // (#131). There is no banner, so nothing here can tell which lines
-            // are the operator's — a retrofit has to name the cut first.
-            ctx.ui.notify(
-              `Hand-written brief at ${path} — run: omp-conductor brief-upgrade --retrofit (then --migrate). The plugin no longer merges single-file briefs.`,
-              "warning",
-            );
-            break;
-          }
-
-          default:
-            ctx.ui.notify(
-              `${sub ? `Unknown subcommand "${sub}".` : "Pick a subcommand."}\n\n${USAGE}` +
-                (isPaused() ? "\n\nThe conductor is currently paused." : ""),
-              sub ? "warning" : "info",
-            );
-        }
-      } catch (err) {
-        // Config problems arrive as a single readable message listing every
-        // fault, which is more use to the operator than a stack.
-        ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
-      }
-    },
-  });
+  // 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");
 }