omp-conductor 0.15.9 → 0.15.11

package/src/setup-install.ts

@@ -15,7 +15,7 @@
  * call in here; `privileged.ts` stays the primitive underneath.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { platform } from "node:os";
 import { join } from "node:path";
 import { stateDir } from "./config.ts";
@@ -41,7 +41,9 @@ import {
   STAGED_SERVICE_NAME,
   SYSTEMD_UNIT_DIR,
   type EscalationDeps,
+  type ServiceRuntime,
 } from "./setup-host.ts";
+import { DEFAULT_HERDR_UNIT } from "./fleet.ts";
 import type { WizardUi } from "./wizard-ui.ts";
 import type { Caps, ProjectConfig } from "./types.ts";
 
@@ -62,6 +64,12 @@ export interface InstallDeps {
   /** `"linux"` gates the systemd half. Injectable so the refusal is testable. */
   platform?: () => string;
   unitDir?: string;
+  /**
+   * The runtime the plan derives from. Injectable so tests pin herdr
+   * present/absent deterministically; the default ({@link defaultServiceRuntime})
+   * detects herdr from the host's own PATH.
+   */
+  runtime?: ServiceRuntime;
 }
 
 /**
@@ -75,6 +83,22 @@ function linuxOnly(deps: InstallDeps): string | undefined {
     : "systemd install is Linux-only; staged files are at";
 }
 
+/**
+ * Whether two files hold identical bytes. The "keep" side of setup-host.ts's
+ * `actionFor`: a unit systemd already reads that matches what would be written
+ * needs no reinstall. Reads can fail (permissions, vanished mid-flight) — a
+ * read error is a mismatch, never silently "matches", because the whole point
+ * is to make the plan only claim a unit install is redundant when it can see
+ * the installed copy.
+ */
+function sameFile(a: string, b: string): boolean {
+  try {
+    return readFileSync(a, "utf8") === readFileSync(b, "utf8");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Install the supervised daemon unit: re-render, stage, then run the four steps
  * `planHostRuntime` used to only print.
@@ -92,10 +116,12 @@ export async function runHostInstall(
     return { kind: "refused", reason: verdict.message };
   }
 
-  const plan = planHostRuntime(project, caps, telegramStateDir, undefined, hostInstallWorkers(caps));
-  const wrote = writeHostRuntime(plan);
+  const plan = planHostRuntime(project, caps, telegramStateDir, deps.runtime, hostInstallWorkers(caps));
+  const { wrote, warnings } = writeHostRuntime(plan);
+  for (const warning of warnings) ui.notify(warning, "warning");
   const unitDir = deps.unitDir ?? SYSTEMD_UNIT_DIR;
   const installed = join(unitDir, STAGED_SERVICE_NAME);
+  const installedHerdr = join(unitDir, DEFAULT_HERDR_UNIT);
 
   const blocked = linuxOnly(deps);
   if (blocked !== undefined) {
@@ -111,13 +137,29 @@ export async function runHostInstall(
     { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
     { title: `enable ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "enable", STAGED_SERVICE_NAME] },
     { title: `restart ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "restart", STAGED_SERVICE_NAME] },
+    // The herdr session server, provisioned alongside the daemon (#456). Only
+    // when herdr is installed and the plan therefore staged a unit.
+    ...(plan.herdrUnit === undefined
+      ? []
+      : [
+          { title: `install ${DEFAULT_HERDR_UNIT}`, argv: ["install", "-m", "0644", plan.herdrUnit.path, installedHerdr] },
+          { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+          { title: `enable ${DEFAULT_HERDR_UNIT}`, argv: ["systemctl", "enable", DEFAULT_HERDR_UNIT] },
+          { title: `restart ${DEFAULT_HERDR_UNIT}`, argv: ["systemctl", "restart", DEFAULT_HERDR_UNIT] },
+        ]),
   ];
 
   const outcome = await runPrivileged(steps, ui, {
     ...(deps.privileged === undefined ? {} : { deps: deps.privileged }),
-    title: "Install and start the supervised daemon?",
+    title: "Install and start the supervised session?",
     preamble: [
       `Installs ${plan.service.path} as ${installed}, then enables and restarts it.`,
+      ...(plan.herdrUnit === undefined
+        ? []
+        : [
+            `Also installs the fleet session unit as ${installedHerdr} with the account's login shell so panes`,
+            "run it instead of dash, then enables and restarts it.",
+          ]),
       "The unit runs as the account that staged it; nothing here changes that.",
     ],
   });
@@ -219,6 +261,15 @@ export async function runGraphInstall(
   const blocked = linuxOnly(options);
   const { service, timer } = unitPaths(options.unitDir ?? SYSTEMD_UNIT_DIR);
   const from = unitPaths(stateDir());
+  // The units systemd already reads, compared to what staging just wrote — the
+  // same distinction setup-host.ts draws between `installedAction` and
+  // `service.action` (read the installed file, compare to the fresh content,
+  // "keep" vs "update"). "Installed" is not enough: a green timer serving a
+  // stale unit is the older bug, so when they differ the install runs. Only
+  // when both units already match does the plan omit them — then just the
+  // outstanding clone and seed remain.
+  const unitsCurrent =
+    blocked === undefined && sameFile(service, from.service) && sameFile(timer, from.timer);
   // 3. Install and enable, privileged. 4. Seed, in the SAME batch: the contract is
   //    one preview and one confirm, and a second confirm here also invented a
   //    third outcome — a declined seed — that neither the caller nor the
@@ -230,9 +281,13 @@ export async function runGraphInstall(
   const install: PrivilegedStep[] =
     blocked === undefined
       ? [
-          { title: "install the reindex unit and timer", argv: ["install", "-m", "0644", from.service, from.timer, join(options.unitDir ?? SYSTEMD_UNIT_DIR, "")] },
-          { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
-          { title: `enable ${REINDEX_UNIT}.timer`, argv: ["systemctl", "enable", "--now", `${REINDEX_UNIT}.timer`] },
+          ...(unitsCurrent
+            ? []
+            : [
+                { title: "install the reindex unit and timer", argv: ["install", "-m", "0644", from.service, from.timer, join(options.unitDir ?? SYSTEMD_UNIT_DIR, "")] },
+                { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+                { title: `enable ${REINDEX_UNIT}.timer`, argv: ["systemctl", "enable", "--now", `${REINDEX_UNIT}.timer`] },
+              ]),
           ...seed,
         ]
       : [];
@@ -242,19 +297,19 @@ export async function runGraphInstall(
     return { kind: "staged", wrote: staged.written, reason: `${blocked} ${service}` };
   }
 
-  if (blocked !== undefined) {
-    ui.notify(`${blocked} ${service} and ${timer}`, "warning");
-    return { kind: "staged", wrote: staged.written, reason: `${blocked} ${service}` };
-  }
-
   const outcome = await runPrivileged([...clones, ...install], ui, {
     ...(options.privileged === undefined ? {} : { deps: options.privileged }),
-    title: "Clone, install and enable the code-graph timer?",
+    title: unitsCurrent ? "Clone the code-graph checkouts and seed them?" : "Clone, install and enable the code-graph timer?",
     preamble: [
       `Staged: ${staged.written.join(", ")}.`,
       ...(clones.length === 0
         ? ["Every indexed clone already exists."]
-        : [`${clones.length} clone(s) run as you; the unit install needs root.`]),
+        : [
+            `${clones.length} clone(s) run as you; ${
+              unitsCurrent ? "only the seed needs root — the reindex units already match." : "the unit install needs root."
+            }`,
+          ]),
+      ...(unitsCurrent ? ["The reindex units are already installed and current — nothing to install."] : []),
       `Indexer: ${prereqs.indexer ?? "on PATH"}.`,
     ],
   });

package/src/setup-wizard.ts

@@ -30,7 +30,7 @@ import {
   type QueuePreview,
 } from "./daemon.ts";
 import { armTicks, telegramStateDir } from "./fleet.ts";
-import { restartDaemon } from "./lifecycle.ts";
+import { restartDaemon, type RestartResult } from "./lifecycle.ts";
 import { defaultGraphRoot, graphRepos } from "./graph.ts";
 import {
   formatHostRuntimePlan,
@@ -40,8 +40,9 @@ import {
   SYSTEMD_UNIT_DIR,
   tickCwdForProject,
   writeHostRuntime,
+  type SetupSmokeResult,
 } from "./setup-host.ts";
-import { runGraphInstall, runHostInstall } from "./setup-install.ts";
+import { runGraphInstall, runHostInstall, type GraphInstallOptions, type InstallOutcome } from "./setup-install.ts";
 import { probeGates, probeProse, probeRepoMap, type ProbedGate, type ProbeTarget } from "./setup-probe.ts";
 import {
   discoverFacts,
@@ -74,7 +75,9 @@ import {
   summarisePlan,
   writeOrchestratorBrief,
   type AmendAreaId,
+  type LabelPlan,
   type OperatorJudgment,
+  type ScopeCheck,
   type SetupAnswers,
   type ProbedProse,
 } from "./setup.ts";
@@ -82,11 +85,13 @@ import {
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   DEFAULT_CAPS,
+  DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
   RELEASE_REQUIREMENTS,
   INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
   WEEKDAYS,
+  type AuthorityHolder,
   type Caps,
   type ConductorConfig,
   type OrchestratorMode,
@@ -374,8 +379,18 @@ async function askReleaseRequirements(
  * 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.
+ *
+ * The merge half is always asked — it gates work that lands whatever the
+ * release authority is. The release half only matters when the orchestrator
+ * actually cuts releases: with `release: human` a release verb is refused
+ * before these fields are read (see `verbs/server`), so asking them would be a
+ * dead question. They are skipped, keeping the seed's value.
  */
-async function askPolicyPreconditions(ui: WizardUi, prior: ProjectPolicy): Promise<ProjectPolicy> {
+async function askPolicyPreconditions(
+  ui: WizardUi,
+  prior: ProjectPolicy,
+  releaseAuthority: AuthorityHolder,
+): Promise<ProjectPolicy> {
   const merge = {
     requiredChecks: await askNameList(
       ui,
@@ -405,33 +420,37 @@ async function askPolicyPreconditions(ui: WizardUi, prior: ProjectPolicy): Promi
     ),
   };
 
-  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,
-    ),
-  };
+  const release =
+    releaseAuthority === "orchestrator"
+      ? {
+          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,
+          ),
+        }
+      : prior.release;
 
   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.
+ * Who merges, who releases and who promotes. Three confirms rather than one
+ * four-way list: these are independent grants — delegating merges is routine,
+ * delegating releases and promotion is not — and a menu of combinations frames
+ * them as equally ordinary choices, which is exactly the framing a release or
+ * promotion 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
@@ -456,7 +475,19 @@ async function askAuthority(
       "Default: humans release" +
       `${prior.release === "orchestrator" ? " — currently delegated, answer no to take it back" : ""}.`,
   );
-  return { merge: merge ? "orchestrator" : "human", release: release ? "orchestrator" : "human" };
+  const promotion = await askYesNo(
+    ui,
+    "Promotion authority",
+    "Delegate promotion to the orchestrator session? Promotion is adding the queue label to an " +
+      "issue — the sign-off that lets a worker claim it, and the act that starts spend. " +
+      "Default: the operator promotes" +
+      `${prior.promotion === "orchestrator" ? " — currently delegated, answer no to take it back" : ""}.`,
+  );
+  return {
+    merge: merge ? "orchestrator" : "human",
+    release: release ? "orchestrator" : "human",
+    promotion: promotion ? "orchestrator" : "human",
+  };
 }
 
 /**
@@ -478,6 +509,14 @@ const RELEASE_SHAPE_QUESTIONS: { readonly [K in (typeof RELEASE_SHAPES)[number]]
   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",
+  // #486: the last leg of the loop. Releasing publishes; installing replaces the
+  // running conductor itself, detached from the session, and only the first
+  // tick after the restart proves it. Fund as deliberate as `deploy` is — the
+  // package floor's "nobody patches the running conductor" is this grant's
+  // deny default.
+  install:
+    "install — replace this host's installed conductor: the Bun-global CLI, omp plugin " +
+    "and Herdr plugin pinned to one published release, executed detached from the fleet",
 };
 
 /**
@@ -1137,11 +1176,25 @@ const askWorkerModel: AreaAsker = async (ui, a) => {
   return next;
 };
 
-/** The two ownership questions, then the mechanical gate one shape at a time:
+/** The three 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, _probes, discovered) => {
   const authority = await askAuthority(ui, a.authority);
-  const releaseGrants = await askReleaseGrants(ui, a.releaseGrants);
+  // Declining release authority makes the five per-shape grants moot — they
+  // exist to scope an authority that was just refused, and asking them after
+  // "humans release" teaches the operator that answers do not matter (#368).
+  //
+  // Humans-only authority clears any stale per-shape grant to the fail-closed
+  // baseline rather than offering an individual-tool path: `releaseVerb`
+  // refuses before a shape grant is ever read (see `verbs/server`), so a shape
+  // granted under humans-only authority is a dead prompt that says the opposite
+  // of what the operator answered. Clearing keeps the tick tripwire, which
+  // reads the grant map independently of authority, from enforcing a shape the
+  // operator just revoked.
+  const releaseGrants =
+    authority.release === "human"
+      ? { ...DENIED_RELEASE_GRANTS }
+      : 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
@@ -1151,8 +1204,13 @@ const askAuthorityArea: AreaAsker = async (ui, a, _probes, discovered) => {
 };
 
 /** What a merge and a release must satisfy. Asked straight after the grants:
- *  who may act, then under what conditions (#129). */
-const askPolicy: AreaAsker = async (ui, a) => ({ ...a, policy: await askPolicyPreconditions(ui, a.policy) });
+ *  who may act, then under what conditions. The release half is only asked
+ *  when the orchestrator cuts releases — with humans releasing it has no gates
+ *  to configure, so it would be a dead prompt (#368). */
+const askPolicy: AreaAsker = async (ui, a) => ({
+  ...a,
+  policy: await askPolicyPreconditions(ui, a.policy, a.authority.release),
+});
 
 /** How a stuck run reaches a human, and who triages it when it does. */
 const askEscalation: AreaAsker = async (ui, a) => {
@@ -1216,7 +1274,12 @@ async function askTelegramTopicId(
     const options = [
       ...claimed.map((t) => ({
         label: `${t.name} — ${t.threadId}`,
-        description: `message_thread_id ${t.threadId}`,
+        // Two panes under one state directory claim the same title, so the
+        // herdr space is the only thing that tells the operator which is which.
+        description:
+          t.workspaceLabel === undefined || t.workspaceLabel === t.name
+            ? `message_thread_id ${t.threadId}`
+            : `herdr space ${t.workspaceLabel} · 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" },
@@ -1439,7 +1502,7 @@ type AmendChoice =
  * 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> {
+async function chooseAmendArea(ui: WizardUi, prior: ProjectConfig, defaults: Caps = DEFAULT_CAPS): Promise<AmendChoice> {
   const mode = await ui.select(
     `"${prior.name}" is already configured — what would you like to do?`,
     [
@@ -1468,7 +1531,7 @@ async function chooseAmendArea(ui: WizardUi, prior: ProjectConfig): Promise<Amen
     return { kind: "reinterview" };
   }
 
-  const choices = amendChoices(prior);
+  const choices = amendChoices(prior, defaults);
   const picked = await ui.select(
     "Which area? Each row shows what it says now",
     choices.map((c) => ({ label: c.label, description: c.description })),
@@ -1656,7 +1719,7 @@ export async function collectSetup(
     };
   }
 
-  const choice = await chooseAmendArea(ui, prior);
+  const choice = await chooseAmendArea(ui, prior, existing?.defaults ?? DEFAULT_CAPS);
   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.
@@ -1738,11 +1801,82 @@ export function formatHerdrHandoff(project: ProjectConfig, cfg: ConductorConfig)
 
 
 
+/**
+ * The side-effecting apply tail of {@link setup}, as one injectable object — the
+ * wizard has `collectSetup` fully covered but none of its apply tail today. The
+ * default is the real implementations; a test stubs whichever of gh/daemon/root
+ * it proves, and drives the real tail (including the real `runGraphInstall`
+ * with injected `unitDir`/`privileged`/probe) through the same seam, so a
+ * regression cannot hide behind a rewritten status line.
+ */
+export interface SetupApplyDeps {
+  scopes: () => Promise<ScopeCheck>;
+  labels: (trackerRepo: string, a: SetupAnswers) => Promise<LabelPlan[]>;
+  preview: (project: ProjectConfig) => Promise<QueuePreview>;
+  createLabels: (trackerRepo: string, plan: LabelPlan[]) => Promise<string[]>;
+  smoke: (project: string) => Promise<SetupSmokeResult>;
+  restart: (o: { project?: string }) => Promise<RestartResult>;
+  arm: (project: string) => Promise<string>;
+  resume: (project: string) => void;
+  hostInstall: (
+    project: ProjectConfig,
+    caps: Caps,
+    telegramStateDir: string,
+    ui: WizardUi,
+  ) => Promise<InstallOutcome>;
+  graphInstall: (
+    project: ProjectConfig,
+    ui: WizardUi,
+    options?: GraphInstallOptions,
+  ) => Promise<InstallOutcome>;
+}
+
+export const DEFAULT_APPLY: SetupApplyDeps = {
+  scopes: checkTokenScopes,
+  labels: planLabels,
+  preview: previewProject,
+  createLabels: createMissingLabels,
+  smoke: runSetupSmoke,
+  restart: (o) => restartDaemon(o),
+  arm: (project) => ensureSetupArm(project),
+  resume: (project) => setPaused(false, undefined, project),
+  hostInstall: (project, caps, telegramStateDir, ui) =>
+    runHostInstall(project, caps, telegramStateDir, ui),
+  graphInstall: (project, ui, options) => runGraphInstall(project, ui, options),
+};
+
+/**
+ * The post-apply code-graph offer. Shared by the tail and the live-worker early
+ * return, so neither path can silently leave the graph install unreferenced.
+ * `graphInstall` is injectable: the tail and the CLI both call the real
+ * {@link runGraphInstall}, and a test drives apply through this same seam.
+ */
+async function offerCodeGraph(
+  project: ProjectConfig,
+  ui: WizardUi,
+  graphInstall: SetupApplyDeps["graphInstall"],
+): Promise<void> {
+  if (graphRepos(project).length === 0) return;
+  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 graphInstall(project, ui);
+  else
+    ui.notify(
+      "Skipped the code graph — workers grep until it exists. When you want it: omp-conductor setup graph",
+      "info",
+    );
+}
+
 export async function setup(
   ui: WizardUi,
   projectArg: string | undefined,
   areaArg?: AmendAreaId,
   probes: SetupProbes = DEFAULT_PROBES,
+  apply: SetupApplyDeps = DEFAULT_APPLY,
 ): Promise<void> {
   const path = configPath();
   // A config that exists but does not parse is a fault to report, never
@@ -1763,7 +1897,7 @@ export async function setup(
   }
   const { answers, amend, added } = collected;
 
-  const scopes = await checkTokenScopes();
+  const scopes = await apply.scopes();
   if (!scopes.ok) {
     ui.notify(
       `Setup stopped before writing anything. The gh token needs repo and project scopes. ` +
@@ -1778,7 +1912,7 @@ export async function setup(
   // 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 labels = await apply.labels(answers.trackerRepo, answers);
   const telegram = detectTelegram();
   let nextConfig;
   try {
@@ -1815,7 +1949,7 @@ export async function setup(
   );
   let queuePreview: string[];
   try {
-    queuePreview = formatPreview(await previewProject(project));
+    queuePreview = formatPreview(await apply.preview(project));
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     ui.notify(
@@ -1829,8 +1963,8 @@ export async function setup(
     [
       // 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),
+      ...(amend === undefined ? [] : [summariseAmend(amend.area, amend.before, answers, nextConfig.defaults)]),
+      summarisePlan(answers, scopes, labels, telegram, nextConfig.defaults),
       "",
       formatHostRuntimePlan(runtime),
       "",
@@ -1858,11 +1992,21 @@ export async function setup(
       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.herdrUnit === undefined
+        ? ""
+        : runtime.herdrUnit.action === "keep"
+          ? `Keeps the staged Herdr session unit at ${runtime.herdrUnit.path}.`
+          : `${runtime.herdrUnit.action === "create" ? "Creates" : "Updates"} the staged Herdr session unit at ${runtime.herdrUnit.path} (account's login shell for panes).`,
       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}.`,
+      runtime.briefLink.action === "skip"
+        ? `Leaves the existing file at ${runtime.briefLink.path} alone (an operator's file, not overwritten).`
+        : runtime.briefLink.action === "keep"
+          ? `Keeps the brief link at ${runtime.briefLink.path}.`
+          : `${runtime.briefLink.action === "create" ? "Creates" : "Replaces"} the brief link at ${runtime.briefLink.path} -> ${runtime.briefLink.target}.`,
       answers.writeOrchestratorBrief
         ? `Writes ${orchestratorBriefPath(answers)}, which is then yours to edit.`
         : "",
@@ -1882,11 +2026,12 @@ export async function setup(
   // 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);
+  const created = await apply.createLabels(answers.trackerRepo, labels);
   saveConfig(nextConfig);
   const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
   const runtimeFiles = writeHostRuntime(runtime);
-  const smoke = await runSetupSmoke(project.name);
+  for (const warning of runtimeFiles.warnings) ui.notify(warning, "warning");
+  const smoke = await apply.smoke(project.name);
   let smokeLine =
     `paused daemon --once; temporary /healthz on :${smoke.daemon.port}; ` +
     `stored status for ${smoke.status.project}`;
@@ -1906,6 +2051,12 @@ export async function setup(
         ].join("\n"),
         "warning",
       );
+      // The early return must not swallow the graph offer. This host is the
+      // live reproduction: the shared reindex units were already installed by
+      // the first project, so only the clone+seed are outstanding — and nothing
+      // above names them. Offer regardless of live workers: cloning seeds and
+      // enables the timer, which does not touch the running daemon.
+      await offerCodeGraph(project, ui, apply.graphInstall);
       ui.notify(formatHerdrHandoff(project, nextConfig), "info");
       return;
     }
@@ -1923,7 +2074,7 @@ export async function setup(
         "info",
       );
     } else {
-      const restarted = await restartDaemon({ project: project.name });
+      const restarted = await apply.restart({ project: project.name });
       restartVia = restarted.via;
       smokeLine =
         `existing /healthz and stored status; restarted through ${restarted.via}; ` +
@@ -1935,7 +2086,7 @@ export async function setup(
   if (project.escalation.orchestrator === "external") {
     ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
     try {
-      armLine = await ensureSetupArm(project.name);
+      armLine = await apply.arm(project.name);
     } catch (err) {
       ui.notify(
         [
@@ -1950,7 +2101,7 @@ export async function setup(
       return;
     }
   }
-  setPaused(false, undefined, project.name);
+  apply.resume(project.name);
 
   ui.notify(
     [
@@ -1959,9 +2110,9 @@ export async function setup(
       briefPath === undefined
         ? "Kept the existing orchestrator brief."
         : `Wrote ${briefPath} + POLICY.md. Edit POLICY.md for Releases and Reporting.`,
-      runtimeFiles.length === 0
+      runtimeFiles.wrote.length === 0
         ? "Host runtime files were already current."
-        : `Wrote host runtime file(s): ${runtimeFiles.join(", ")}`,
+        : `Wrote host runtime file(s): ${runtimeFiles.wrote.join(", ")}`,
       `Smoke passed: ${smokeLine}.`,
       `Heartbeat: ${armLine}.`,
       "",
@@ -1999,24 +2150,11 @@ export async function setup(
         "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);
+      await apply.hostInstall(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",
-      );
-  }
+  await offerCodeGraph(project, ui, apply.graphInstall);
 
   // 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