omp-conductor 0.15.12 → 0.15.13

package/src/setup-wizard.ts

@@ -40,6 +40,7 @@ import {
   SYSTEMD_UNIT_DIR,
   tickCwdForProject,
   writeHostRuntime,
+  type HostRuntimePlan,
   type SetupSmokeResult,
 } from "./setup-host.ts";
 import { runGraphInstall, runHostInstall, type GraphInstallOptions, type InstallOutcome } from "./setup-install.ts";
@@ -70,9 +71,11 @@ import {
   detectTelegram,
   formatGates,
   orchestratorBriefPath,
+  planAgainstLabels,
   planLabels,
   summariseAmend,
   summarisePlan,
+  wantedLabels,
   writeOrchestratorBrief,
   type AmendAreaId,
   type LabelPlan,
@@ -1538,6 +1541,31 @@ const REINTERVIEW = "Walk every question again";
  *  brand-new neighbour rather than amending the one that is already there. */
 const ADD_PROJECT = "Add another project";
 
+/**
+ * The consent gate's four choices, in the order the contract names them: the
+ * old yes/no "apply?" is now a menu whose decline loops back instead of
+ * dropping the interview (#417). The plan is recomputed from the answers
+ * (including the predictive queue preview) before every row is offered again.
+ */
+const REVIEW_APPLY = "Apply";
+const REVIEW_EDIT = "Edit an area";
+const REVIEW_REVIEW = "Review the plan";
+const REVIEW_EXIT = "Exit";
+/** A bare Enter lands on Review — the one row with no effect, so neither
+ *  applying nor discarding can happen by accident. */
+const REVIEW_CHOICES: { label: string; description: string }[] = [
+  {
+    label: REVIEW_APPLY,
+    description: "run the apply sequence once: labels, config, briefs, staged host files, paused-daemon smoke",
+  },
+  {
+    label: REVIEW_EDIT,
+    description: "re-ask one interview area; the plan re-derives from the new answers",
+  },
+  { label: REVIEW_REVIEW, description: "show the current plan again — nothing applies" },
+  { label: REVIEW_EXIT, description: "discard these answers; nothing is written or changed" },
+];
+
 /** Outcome of the first chooser on a re-run. */
 type AmendChoice =
   | { kind: "area"; area: AmendAreaId }
@@ -1685,6 +1713,24 @@ export interface CollectedSetup {
   added?: boolean;
 }
 
+/**
+ * The consent gate's re-derivable view of the *current* answers: everything the
+ * plan shows and the apply tail writes. The review loop rebuilds it after every
+ * edit — config, project, runtime plan, caps, and the predictive queue preview
+ * all re-derive from the answers, so the operator can only approve a diff that
+ * matches them (#417).
+ */
+interface DerivedPlan {
+  nextConfig: ConductorConfig;
+  project: ProjectConfig;
+  runtime: HostRuntimePlan;
+  /** Re-derived from the *cached* label listing: one `gh` read per run. */
+  labels: LabelPlan[];
+  toCreate: string[];
+  totalWorkers: number;
+  overcommit: string | undefined;
+  queuePreview: string[];
+}
 
 export async function ensureSetupArm(
   projectName: string,
@@ -1941,7 +1987,10 @@ export async function setup(
     ui.notify("Setup cancelled — nothing was changed.", "info");
     return;
   }
-  const { answers, amend, added } = collected;
+  // `answers` is mutable below: the review loop re-asks one area at a time and
+  // replaces only the fields that area owns, so everything else carries across.
+  const { amend, added } = collected;
+  let answers = collected.answers;
 
   const scopes = await apply.scopes();
   if (!scopes.ok) {
@@ -1957,129 +2006,240 @@ export async function setup(
   // 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 apply.labels(answers.trackerRepo, answers);
+  // Everything below the interview is *derived* from `answers`, so an edit in
+  // the review loop re-derives it all — including the predictive queue preview,
+  // which is part of the diff the operator approves (#417). The one-time reads
+  // (scope check, label listing, Telegram state, the prose draft) run once and
+  // are cached: a decline followed by a dozen edits must not re-probe GitHub or
+  // the daemon on every pass.
   const telegram = detectTelegram();
-  let nextConfig;
-  try {
-    nextConfig = buildConfig(answers, existing);
-  } catch (err) {
-    ui.notify(
-      `Setup stopped before writing anything. ${err instanceof Error ? err.message : String(err)}`,
-      "error",
-    );
-    return;
-  }
-  const project = findProject(nextConfig, answers.projectName);
-  const totalWorkers = totalConfiguredWorkers(nextConfig);
-  const overcommit = workerOvercommit(totalWorkers);
-  // The same project as it is configured right now, so a moved `workspaceRoot`
-  if (
-    project.escalation.orchestrator === "external" &&
-    !answers.writeOrchestratorBrief &&
-    (!existsSync(briefPathForProject(project)) || !existsSync(policyPathForProject(project)))
-  ) {
-    ui.notify(
-      `Setup stopped before writing anything. External orchestration needs ${ORCHESTRATOR_BRIEF_NAME} and ${POLICY_BRIEF_NAME}. ` +
-        `Run setup again and approve the brief write.`,
-      "error",
-    );
-    return;
+  let prose: ProbedProse = {};
+  let proseDrafted = false;
+  if (answers.writeOrchestratorBrief) {
+    prose = await probes.prose(ui, answers);
+    proseDrafted = true;
   }
-  const runtime = planHostRuntime(
-    project,
-    resolveCaps(project, nextConfig.defaults),
-    telegram.stateDir,
-    undefined,
-    totalWorkers,
-  );
-  let queuePreview: string[];
-  try {
-    queuePreview = formatPreview(await apply.preview(project));
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    ui.notify(
-      `Setup stopped before writing anything because the proposed queue could not be read: ${message}`,
-      "error",
+  // The single label listing, cached for the whole review loop. The plan
+  // re-derives existence against this set after an edit, so a new queue label
+  // or routing key is planned on the same tracker read the first pass used —
+  // a label that in fact already exists is skipped idempotently at apply.
+  const labelListing = await apply.labels(answers.trackerRepo, answers);
+  const knownLabelNames = new Set(labelListing.filter((l) => l.exists).map((l) => l.name));
+
+  /** Re-builds everything the plan shows and apply writes from the answers as
+   *  they stand right now. Returns `undefined` when a guard aborted (the error
+   *  is already shown) — either way, nothing has been written. */
+  const derive = async (): Promise<DerivedPlan | undefined> => {
+    let nextConfig: ConductorConfig;
+    try {
+      nextConfig = buildConfig(answers, existing);
+    } catch (err) {
+      ui.notify(
+        `Setup stopped before writing anything. ${err instanceof Error ? err.message : String(err)}`,
+        "error",
+      );
+      return undefined;
+    }
+    const project = findProject(nextConfig, answers.projectName);
+    const totalWorkers = totalConfiguredWorkers(nextConfig);
+    const overcommit = workerOvercommit(totalWorkers);
+    // The same project as it is configured right now, so a moved `workspaceRoot`
+    if (
+      project.escalation.orchestrator === "external" &&
+      !answers.writeOrchestratorBrief &&
+      (!existsSync(briefPathForProject(project)) || !existsSync(policyPathForProject(project)))
+    ) {
+      ui.notify(
+        `Setup stopped before writing anything. External orchestration needs ${ORCHESTRATOR_BRIEF_NAME} and ${POLICY_BRIEF_NAME}. ` +
+          `Run setup again and approve the brief write.`,
+        "error",
+      );
+      return undefined;
+    }
+    const runtime = planHostRuntime(
+      project,
+      resolveCaps(project, nextConfig.defaults),
+      telegram.stateDir,
+      undefined,
+      totalWorkers,
     );
-    return;
-  }
+    let queuePreview: string[];
+    try {
+      // The predictive diff: the same routing code the loop runs, re-run on
+      // every pass back so the dry run can only ever describe the answers it
+      // was just asked about (#417).
+      queuePreview = formatPreview(await apply.preview(project));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ui.notify(
+        `Setup stopped before writing anything because the proposed queue could not be read: ${message}`,
+        "error",
+      );
+      return undefined;
+    }
+    const labels = planAgainstLabels(wantedLabels(answers), knownLabelNames);
+    return {
+      nextConfig,
+      project,
+      runtime,
+      labels,
+      toCreate: labels.filter((l) => !l.exists).map((l) => l.name),
+      totalWorkers,
+      overcommit,
+      queuePreview,
+    };
+  };
 
-  ui.notify(
+  /** The plan screen, exactly as the consent gate shows it after every re-derive:
+   *  the delta first when there is one, then the whole plan — the confirm has to
+   *  name every mutation it makes, and a delta names none of them. */
+  const planBlock = (d: DerivedPlan): string =>
     [
-      // 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, nextConfig.defaults)]),
-      summarisePlan(answers, scopes, labels, telegram, nextConfig.defaults),
+      ...(amend === undefined ? [] : [summariseAmend(amend.area, amend.before, answers, d.nextConfig.defaults)]),
+      summarisePlan(answers, scopes, d.labels, telegram, d.nextConfig.defaults),
       "",
-      formatHostRuntimePlan(runtime),
+      formatHostRuntimePlan(d.runtime),
       "",
-      ...(overcommit === undefined ? [] : [`WARNING: ${overcommit}`, ""]),
+      ...(d.overcommit === undefined ? [] : [`WARNING: ${d.overcommit}`, ""]),
       "Dry run against the PROPOSED config:",
-      ...queuePreview,
+      ...d.queuePreview,
       "",
       "Nothing has been changed yet.",
-    ].join("\n"),
-    "info",
-  );
+    ].join("\n");
 
-  const toCreate = labels.filter((l) => !l.exists).map((l) => l.name);
-  // Deliberately `ui.confirm` rather than `askYesNo`: this is the one confirm
-  // after the interview, and dismissing it means the same thing as answering no
-  // — do not apply — so it returns through the existing "left untouched" path
-  // instead of raising a `Cancelled` nothing outside `collectSetup` catches.
-  const go = await ui.confirm(
-    amend === undefined ? "Apply this setup?" : `Apply this change to ${AMEND_AREAS[amend.area].name}?`,
+  /** The consent recap, unchanged from the confirm it replaces: picking "Apply"
+   *  is an agreement to exactly the mutations named here. */
+  const consentRecap = (d: DerivedPlan): string =>
     [
-      toCreate.length > 0
-        ? `Creates ${toCreate.length} label(s) in ${answers.trackerRepo}: ${toCreate.join(", ")}.`
+      d.toCreate.length > 0
+        ? `Creates ${d.toCreate.length} label(s) in ${answers.trackerRepo}: ${d.toCreate.join(", ")}.`
         : "Creates no labels.",
       `Writes ${path}, prepares a paused state database, then runs a paused daemon smoke.`,
-      runtime.service.action === "keep"
-        ? `Keeps the staged systemd unit at ${runtime.service.path}.`
-        : `${runtime.service.action === "create" ? "Creates" : "Updates"} the staged systemd unit at ${runtime.service.path}.`,
-      runtime.herdrUnit === undefined
+      d.runtime.service.action === "keep"
+        ? `Keeps the staged systemd unit at ${d.runtime.service.path}.`
+        : `${d.runtime.service.action === "create" ? "Creates" : "Updates"} the staged systemd unit at ${d.runtime.service.path}.`,
+      d.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
+        : d.runtime.herdrUnit.action === "keep"
+          ? `Keeps the staged Herdr session unit at ${d.runtime.herdrUnit.path}.`
+          : `${d.runtime.herdrUnit.action === "create" ? "Creates" : "Updates"} the staged Herdr session unit at ${d.runtime.herdrUnit.path} (account's login shell for panes).`,
+      d.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 === undefined
+        : d.runtime.tick.action === "keep"
+          ? `Keeps the external heartbeat config at ${d.runtime.tick.path}.`
+          : `${d.runtime.tick.action === "create" ? "Creates" : "Updates"} the external heartbeat config at ${d.runtime.tick.path}.`,
+      d.runtime.briefLink === undefined
         ? ""
-        : 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}.`,
+        : d.runtime.briefLink.action === "skip"
+          ? `Leaves the existing file at ${d.runtime.briefLink.path} alone (an operator's file, not overwritten).`
+          : d.runtime.briefLink.action === "keep"
+            ? `Keeps the brief link at ${d.runtime.briefLink.path}.`
+            : `${d.runtime.briefLink.action === "create" ? "Creates" : "Replaces"} the brief link at ${d.runtime.briefLink.path} -> ${d.runtime.briefLink.target}.`,
       answers.writeOrchestratorBrief
         ? `Writes ${orchestratorBriefPath(answers)}, which is then yours to edit.`
         : "",
-      project.escalation.orchestrator === "external"
+      d.project.escalation.orchestrator === "external"
         ? "Dispatch stays paused until the existing arm marker or a new inbound Telegram proof makes the heartbeat live."
         : "Dispatch resumes after the smoke succeeds.",
       "Issues are only claimed after every setup gate succeeds.",
     ]
       .filter((s) => s.length > 0)
-      .join(" "),
-  );
-  if (!go) {
-    ui.notify("Left untouched — no labels created, no config written, nothing armed.", "info");
-    return;
+      .join(" ");
+
+  let plan = await derive();
+  if (plan === undefined) return;
+  ui.notify(planBlock(plan), "info");
+  // -------- the consent gate (#417): a review loop, not a yes/no --------
+  //
+  // Declining the old "Apply this setup?" confirm dropped every collected
+  // answer on the floor. Now the decline is a loop: edit a named area (through
+  // the same INTERVIEW_AREAS list the interview walks, so the menu's area names
+  // cannot drift from the questions), re-review the resulting plan, or exit
+  // explicitly — and every pass back re-derives the whole plan including the
+  // predictive diff. Nothing is touched before the loop ends on "Apply", which
+  // runs the one-writer sequence below exactly once. A dismissed menu (Ctrl-C /
+  // EOF) is an explicit exit: the old confirm treated dismissal as decline, and
+  // that is the path whose dropped answers must be seen to be dropped.
+  for (;;) {
+    ui.notify(consentRecap(plan), "info");
+    const choice = await ui.select(
+      amend === undefined ? "Apply this setup?" : `Apply this change to ${AMEND_AREAS[amend.area].name}?`,
+      REVIEW_CHOICES,
+      // Bare Enter lands on Review — the one row with no effect.
+      { initialIndex: 2 },
+    );
+    if (choice === undefined) {
+      ui.notify("Setup cancelled — nothing was changed, and the answers were discarded.", "info");
+      return;
+    }
+    if (choice === REVIEW_APPLY) break;
+    if (choice === REVIEW_EXIT) {
+      ui.notify("Setup exited without applying — the answers were discarded and nothing was changed.", "info");
+      return;
+    }
+    if (choice === REVIEW_REVIEW) {
+      ui.notify(planBlock(plan), "info");
+      continue;
+    }
+    if (choice !== REVIEW_EDIT) {
+      // An option this wizard never offered; do not guess. Mirrors
+      // chooseAmendArea's refusal: nothing was changed.
+      ui.notify(`Unrecognised choice "${choice}" — nothing was changed.`, "warning");
+      continue;
+    }
+
+    // Edit: re-enter through the interview's own area list, never a parallel
+    // vocabulary — the review menu's names are the interview's names (#416/#417).
+    const pickedArea = await ui.select(
+      "Edit which area?",
+      INTERVIEW_AREAS.map((area) => ({ label: area.label })),
+      { initialIndex: 0 },
+    );
+    if (pickedArea === undefined) {
+      ui.notify("Editing cancelled — the answers stand as they were.", "info");
+      continue;
+    }
+    const area = INTERVIEW_AREAS.find((a) => a.label === pickedArea);
+    if (area === undefined) {
+      // Guessing an area here would ask the wrong questions and carry the rest
+      // through as if it had been reviewed.
+      ui.notify(`Unrecognised choice "${pickedArea}" — nothing was changed.`, "warning");
+      continue;
+    }
+    let edited: SetupAnswers;
+    try {
+      edited = await area.asker(ui, answers, probes);
+    } catch (err) {
+      if (!(err instanceof Cancelled)) throw err;
+      ui.notify(`Editing "${area.label}" was cancelled — the answers stand as they were.`, "info");
+      continue;
+    }
+    answers = edited;
+    // The prose draft is the one probe an edit can legitimately make necessary:
+    // flipping the brief on after a first pass had it off (the interview ran
+    // once, not per loop). Still one draft per run.
+    if (answers.writeOrchestratorBrief && !proseDrafted) {
+      prose = await probes.prose(ui, answers);
+      proseDrafted = true;
+    }
+    const redrafted = await derive();
+    if (redrafted === undefined) return;
+    plan = redrafted;
+    ui.notify(`Edited "${area.label}" — the plan below is recomputed from the new answers.`, "info");
+    ui.notify(planBlock(plan), "info");
   }
 
   // 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 apply.createLabels(answers.trackerRepo, labels);
-  saveConfig(nextConfig);
+  // partially applied setup unable to claim work. Everything below reads the
+  // last re-derivation: the loop above can only break here on a final "Apply",
+  // so this one-writer sequence runs exactly once per setup run.
+  prepareConductor(plan.project.name);
+  const created = await apply.createLabels(answers.trackerRepo, plan.labels);
+  saveConfig(plan.nextConfig);
   const briefPath = answers.writeOrchestratorBrief ? writeOrchestratorBrief(answers, prose) : undefined;
-  const runtimeFiles = writeHostRuntime(runtime);
+  const runtimeFiles = writeHostRuntime(plan.runtime);
   for (const warning of runtimeFiles.warnings) ui.notify(warning, "warning");
-  const smoke = await apply.smoke(project.name);
+  const smoke = await apply.smoke(plan.project.name);
   let smokeLine =
     `paused daemon --once; temporary /healthz on :${smoke.daemon.port}; ` +
     `stored status for ${smoke.status.project}`;
@@ -2093,9 +2253,9 @@ export async function setup(
           `Setup files are updated, but ${smoke.status.liveWorkers} live worker(s) still use the old daemon config.`,
           "Dispatch remains paused. Let those workers finish.",
           "Then run `omp-conductor restart --now`.",
-          project.escalation.orchestrator === "external"
-            ? `Run \`omp-conductor arm --project ${project.name}\` if ticks are disarmed, then run \`omp-conductor resume --project ${project.name}\`.`
-            : `Then run \`omp-conductor resume --project ${project.name}\`.`,
+          plan.project.escalation.orchestrator === "external"
+            ? `Run \`omp-conductor arm --project ${plan.project.name}\` if ticks are disarmed, then run \`omp-conductor resume --project ${plan.project.name}\`.`
+            : `Then run \`omp-conductor resume --project ${plan.project.name}\`.`,
         ].join("\n"),
         "warning",
       );
@@ -2104,8 +2264,8 @@ export async function setup(
       // 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");
+      await offerCodeGraph(plan.project, ui, apply.graphInstall);
+      ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
       return;
     }
     // No live workers: still prefer an explicit reload when this run *added* a
@@ -2122,7 +2282,7 @@ export async function setup(
         "info",
       );
     } else {
-      const restarted = await apply.restart({ project: project.name });
+      const restarted = await apply.restart({ project: plan.project.name });
       restartVia = restarted.via;
       smokeLine =
         `existing /healthz and stored status; restarted through ${restarted.via}; ` +
@@ -2131,25 +2291,25 @@ export async function setup(
   }
 
   let armLine = "embedded orchestrator — no heartbeat arm marker";
-  if (project.escalation.orchestrator === "external") {
+  if (plan.project.escalation.orchestrator === "external") {
     ui.notify("Setup smoke passed. Proving the external heartbeat channel…", "info");
     try {
-      armLine = await apply.arm(project.name);
+      armLine = await apply.arm(plan.project.name);
     } catch (err) {
       ui.notify(
         [
           "Setup files passed the paused daemon smoke, but the fleet remains held.",
           err instanceof Error ? err.message : String(err),
-          `Start the external orchestrator in ${project.workspaceRoot}, then run \`omp-conductor arm --project ${project.name}\`.`,
+          `Start the external orchestrator in ${plan.project.workspaceRoot}, then run \`omp-conductor arm --project ${plan.project.name}\`.`,
           "After the arm proof succeeds, run `omp-conductor resume`.",
         ].join("\n"),
         "warning",
       );
-      ui.notify(formatHerdrHandoff(project, nextConfig), "info");
+      ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
       return;
     }
   }
-  apply.resume(project.name);
+  apply.resume(plan.project.name);
 
   ui.notify(
     [
@@ -2180,32 +2340,37 @@ export async function setup(
   // 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");
+  if (plan.runtime.installedAction === "keep") {
+    ui.notify(`The unit systemd reads (${plan.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.`,
+      `Staged the unit at ${plan.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 ` +
+      `${plan.runtime.installedAction === "create" ? "Installs" : "Updates"} ${plan.runtime.installedPath} from ` +
+        `${plan.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 apply.hostInstall(project, resolveCaps(project, nextConfig.defaults), telegram.stateDir, ui);
+      await apply.hostInstall(
+        plan.project,
+        resolveCaps(plan.project, plan.nextConfig.defaults),
+        telegram.stateDir,
+        ui,
+      );
     else ui.notify("Left the unit staged. When you want it supervised: omp-conductor setup host", "info");
   }
 
-  await offerCodeGraph(project, ui, apply.graphInstall);
+  await offerCodeGraph(plan.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
   // tick + config but cannot start a herdr agent (#319).
-  ui.notify(formatHerdrHandoff(project, nextConfig), "info");
+  ui.notify(formatHerdrHandoff(plan.project, plan.nextConfig), "info");
 }

package/src/stop-provenance.ts

@@ -0,0 +1,66 @@
+/**
+ * Provenance for stop/restart requests (#378): who asked, from which project,
+ * for which daemon, naming every affected project and its live-run count.
+ *
+ * Shared by the `stop` and `restart` verbs so a second convention cannot
+ * drift beside the first. Explicit facts only — caller pid/uid and session
+ * role, scope, control path, timestamp, reason — and specifically never raw
+ * argv, environment values or credentials: the incident this exists for was
+ * a stop nobody could attribute, and a "just serialise the command line"
+ * implementation would leak tokens into the audit trail.
+ */
+
+import { loadConfig } from "./config.ts";
+import { openStore, dbPath } from "./store.ts";
+import { SESSION_ROLE_ENV, type DaemonStopDraft } from "./types.ts";
+
+export interface StopProvenanceSpec {
+  /** The operator-visible control path: "cli stop", "cli restart", … */
+  controlPath: string;
+  /** Non-secret reason; a generated default is fine, never credentials. */
+  reason: string;
+  /** "global" when the request covered every project ("--all"); otherwise "project". */
+  scope: "global" | "project";
+  /** The originating project, when project-scoped. */
+  project?: string;
+}
+
+/**
+ * Build the provenance draft for one stop/restart request.
+ *
+ * `affected` is every configured project with its live-run count at request
+ * time, not just the targeted one: the shared daemon serves all of them, and
+ * a project-scoped stop still stops the siblings — the record names them
+ * instead of silently interrupting them.
+ *
+ * Pure: nothing is written. The command decides when to persist (at request
+ * entry for drain-style restarts whose signal may never arrive, and at the
+ * lifecycle chokepoint immediately before signalling for every mediated stop).
+ */
+export function buildStopProvenance(spec: StopProvenanceSpec): DaemonStopDraft {
+  const cfg = loadConfig();
+  const store = openStore(dbPath());
+  try {
+    const affected = cfg.projects.map((project) => ({
+      project: project.name,
+      live: store.liveRuns(project.name).length,
+    }));
+    return {
+      controlPath: spec.controlPath,
+      callerPid: process.pid,
+      ...(typeof process.getuid === "function" ? { callerUid: process.getuid() } : {}),
+      // The daemon stamps SESSION_ROLE_ENV on every session it spawns, so a
+      // stop that a worker session's tools trigger names itself as a worker;
+      // everything else — the operator's shell, a systemd unit, a script — is
+      // the orchestrator surface (same convention as the reporting CLI).
+      role: process.env[SESSION_ROLE_ENV] === "worker" ? "worker" : "orchestrator",
+      scope: spec.scope,
+      ...(spec.project === undefined ? {} : { project: spec.project }),
+      affected,
+      reason: spec.reason,
+      unattributed: false,
+    };
+  } finally {
+    store.close();
+  }
+}