omp-conductor 0.17.1 → 0.18.1

package/src/setup-install.ts

@@ -30,12 +30,17 @@ import {
   type UpgradeScope,
 } from "./upgrade.ts";
 import {
+  graphConflictMessage,
   graphRepos,
   formatGraphSetup,
+  legacyReindexFiles,
+  legacyReindexNote,
   mcpEntry,
+  planGraphSetup,
   reindexScriptPath,
+  reindexUnitName,
   resolvePrereqs,
-  REINDEX_UNIT,
+  stagingConflict,
   unitPaths,
   writeGraphSetup,
   type GraphPrereqs,
@@ -47,6 +52,8 @@ import {
   agentRenameVerdict,
   checkEscalation,
   DEFAULT_AGENT_RENAME_DEPS,
+  defaultIdentityProbes,
+  defaultServiceRuntime,
   planHostRuntime,
   totalConfiguredWorkers,
   writeHostRuntime,
@@ -56,6 +63,7 @@ import {
   type AgentRenameDeps,
   type EscalationDeps,
   type ServiceRuntime,
+  type WorkerIdentityProbes,
 } from "./setup-host.ts";
 import type { WizardUi } from "./wizard-ui.ts";
 import type { Caps, ProjectConfig, Store } from "./types.ts";
@@ -76,6 +84,14 @@ export interface InstallDeps {
   escalation?: EscalationDeps;
   /** `"linux"` gates the systemd half. Injectable so the refusal is testable. */
   platform?: () => string;
+  /**
+   * The worker identity plan's probes (#798). `undefined` means the real
+   * host's read-only facts — production: every `setup host` installs and
+   * grants the dedicated worker account. `null` disables the identity plan
+   * entirely (the historical step list, for tests pinning it), and an object
+   * is used as given (tests pinning a specific host state).
+   */
+  workerIdentityProbes?: WorkerIdentityProbes | null;
   unitDir?: string;
   /**
    * Where the recovery playbook installs. Injectable so the idempotency gate
@@ -131,16 +147,18 @@ function linuxOnly(deps: InstallDeps): string | undefined {
 }
 
 /**
- * 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.
+ * Whether a file holds exactly the rendered 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. Comparing against the rendered content
+ * rather than the staged file keeps the comparison read-only: staging now
+ * happens only after consent (#720), so nothing may be written to compare.
  */
-function sameFile(a: string, b: string): boolean {
+function sameContent(path: string, content: string): boolean {
   try {
-    return readFileSync(a, "utf8") === readFileSync(b, "utf8");
+    return readFileSync(path, "utf8") === content;
   } catch {
     return false;
   }
@@ -181,6 +199,13 @@ export async function runHostInstall(
   // happens only after consent (#510), so the prompt's "Nothing has been run
   // yet" is true of the staged tree when it is printed, and a declined run
   // leaves every staged file byte-identical.
+  // The worker identity plan rides the same consent (#798): production probes
+  // the real host (account present? grants current?); a test may pass its own
+  // probes, or `null` to plan the historical step list only.
+  const identityProbes: WorkerIdentityProbes | null =
+    deps.workerIdentityProbes === null
+      ? null
+      : deps.workerIdentityProbes ?? defaultIdentityProbes(deps.runtime ?? defaultServiceRuntime(telegramStateDir));
   const plan = planHostRuntime(
     project,
     caps,
@@ -190,6 +215,7 @@ export async function runHostInstall(
     unitDir,
     deps.recoverScriptInstallPath ?? RECOVER_SCRIPT_INSTALL_PATH,
     deps.multiProject ?? hostMultiProject(),
+    identityProbes,
   );
   // No pane-shell key is planned (unusable login shell, unparseable config):
   // the operator hears why before the consent prompt, not after an install
@@ -291,6 +317,15 @@ export async function runHostInstall(
                 ]),
           ]),
       "The unit runs as the account that staged it; nothing here changes that.",
+      ...(plan.workerIdentity === undefined
+        ? []
+        : [
+            `Establishes the dedicated worker identity ${plan.workerIdentity.account}: every worker session runs under it, ` +
+              "never under the daemon's account, and it is granted search/read access to exactly the fleet paths a worker needs.",
+            ...(plan.workerIdentity.current
+              ? ["The worker identity is already in place — nothing to change."]
+              : plan.workerIdentity.pending),
+          ]),
       "",
       liveWorkers === 0
         ? "No workers are live — nothing to drain before the restart."
@@ -450,9 +485,10 @@ export interface GraphInstallOptions extends InstallDeps {
  * Staging and enabling alone installs a service that fails on every run: the
  * generated script runs under `set -euo pipefail` and `cd "<graphProject>"` as
  * its first act per repo, so a missing clone is a `cd` failure at 03:00 rather
- * than a graph. That is why `writeGraphSetup` already refused to call the old
- * install a finished job. So: prerequisites, then clones, then install, then
- * seed and verify — one preview, one confirm.
+ * than a graph. That is why staging was never allowed to call the install a
+ * finished job. So: prerequisites, then a conflict check, then clones, then
+ * install, then seed and verify — one preview, one confirm, and nothing
+ * staged before the confirm (#720).
  */
 export async function runGraphInstall(
   project: ProjectConfig,
@@ -494,7 +530,38 @@ export async function runGraphInstall(
     return { kind: "refused", reason: missing };
   }
 
-  const staged = writeGraphSetup(project, options.unitDir ?? SYSTEMD_UNIT_DIR);
+  const unitDir = options.unitDir ?? SYSTEMD_UNIT_DIR;
+  // The plan is computed eagerly — `planGraphSetup` renders every byte, so the
+  // prompt can print exactly what would be written and the unitsCurrent gate
+  // below can decide a re-run installs nothing. But rendering is read-only: no
+  // file is written here. Staging happens only after consent (#720), so the
+  // prompt's "stages once you confirm" is true of the staged tree when it is
+  // printed, and a declined run leaves every staged file byte-identical.
+  const plan = planGraphSetup(project, unitDir);
+  // Never overwrite another project's staged artefact: the stems derive from
+  // the project name, and two names can fold to one stem ("My Project" vs
+  // "my_project"), so an existing file's generated-for marker is checked
+  // before the consent prompt — a collision is refused before anything is
+  // asked, let alone written (#720).
+  const conflict = stagingConflict(project, [
+    plan.script.path,
+    plan.service.path,
+    plan.timer.path,
+    ...Object.values(unitPaths(project, unitDir)),
+  ]);
+  if (conflict !== undefined) {
+    const message = graphConflictMessage(conflict);
+    ui.notify(message, "error");
+    return { kind: "refused", reason: message };
+  }
+  // A host that ran the pre-#720 project-less version keeps its old files:
+  // their timer refreshes whichever project generated it last, forever. Name
+  // the remediation before the consent prompt — deleting files outside this
+  // command's own names is exactly how the overwrite happened in the first
+  // place, so it is host action, not install action.
+  const legacy = legacyReindexFiles();
+  if (legacy.length > 0) ui.notify(legacyReindexNote(legacy), "warning");
+
   const absent = repos.filter((r) => !existsSync(r.graphProject));
 
   // 2. Missing clones, as the operator. A root-owned index-only clone under the
@@ -507,17 +574,18 @@ 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
+  const stem = reindexUnitName(project);
+  const { service, timer } = unitPaths(project, unitDir);
+  // The units systemd already reads, compared to the rendered content — 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.
+  // outstanding clone and seed remain. Nothing is written to compare: staging
+  // is post-consent now, so the comparison is against the rendered bytes.
   const unitsCurrent =
-    blocked === undefined && sameFile(service, from.service) && sameFile(timer, from.timer);
+    blocked === undefined && sameContent(service, plan.service.content) && sameContent(timer, plan.timer.content);
   // 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
@@ -525,32 +593,52 @@ export async function runGraphInstall(
   const seed: PrivilegedStep[] =
     options.noSeed === true
       ? []
-      : [{ title: `seed the indexes (runs ${REINDEX_UNIT}.service once, minutes per repo)`, argv: ["systemctl", "start", `${REINDEX_UNIT}.service`] }];
+      : [{ title: `seed the indexes (runs ${stem}.service once, minutes per repo)`, argv: ["systemctl", "start", `${stem}.service`] }];
   const install: PrivilegedStep[] =
     blocked === undefined
       ? [
           ...(unitsCurrent
             ? []
             : [
-                { title: "install the reindex unit and timer", argv: ["install", "-m", "0644", from.service, from.timer, join(options.unitDir ?? SYSTEMD_UNIT_DIR, "")] },
+                { title: "install the reindex unit and timer", argv: ["install", "-m", "0644", plan.service.path, plan.timer.path, join(unitDir, "")] },
                 { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
-                { title: `enable ${REINDEX_UNIT}.timer`, argv: ["systemctl", "enable", "--now", `${REINDEX_UNIT}.timer`] },
+                { title: `enable ${stem}.timer`, argv: ["systemctl", "enable", "--now", `${stem}.timer`] },
               ]),
           ...seed,
         ]
       : [];
 
   if (blocked !== undefined) {
+    // A non-Linux host cannot run systemd, so staging IS the deliverable: the
+    // rendered files are written for the operator to copy to the box that will
+    // run them, and only the systemctl half is refused. There is no consent
+    // prompt on this path — nothing privileged to approve — so the write lands
+    // here, not in the (never reached) post-consent hook (#720, as #510).
+    const staged = writeGraphSetup(project, unitDir);
     ui.notify(`${blocked} ${service} and ${timer}`, "warning");
     return { kind: "staged", wrote: staged.written, reason: `${blocked} ${service}` };
   }
 
+  // What the post-consent staging actually wrote, surfaced by the outcomes
+  // that report it. Empty on a decline — the hook never ran.
+  let wrote: readonly string[] = [];
+  const beforeRun = async (): Promise<void> => {
+    // Consent has been given; this project's files may now land. Staging here —
+    // post-confirm, pre-step, under the same confirm that authorised the batch
+    // — is what makes the prompt's plan true of the staged tree when it is
+    // printed: a declined prompt never reaches this hook, so nothing is staged
+    // and a re-run still plans an install (#720). `writeGraphSetup`'s ownership
+    // backstop throws here with nothing written if a collision raced the
+    // pre-consent check.
+    wrote = writeGraphSetup(project, unitDir).written;
+  };
+
   const outcome = await runPrivileged([...clones, ...install], ui, {
     ...(options.privileged === undefined ? {} : { deps: options.privileged }),
     title: unitsCurrent ? "Clone the code-graph checkouts and seed them?" : "Clone, install and enable the code-graph timer?",
     answerKey: `install-code-graph.${project.name}`,
     preamble: [
-      `Staged: ${staged.written.join(", ")}.`,
+      `Stages ${[plan.script.path, plan.service.path, plan.timer.path].join(", ")} once you confirm — nothing is written before that.`,
       ...(clones.length === 0
         ? ["Every indexed clone already exists."]
         : [
@@ -561,8 +649,9 @@ export async function runGraphInstall(
       ...(unitsCurrent ? ["The reindex units are already installed and current — nothing to install."] : []),
       `Indexer: ${prereqs.indexer ?? "on PATH"}.`,
     ],
+    beforeRun,
   });
-  if (outcome.kind === "declined") return { kind: "declined", wrote: staged.written };
+  if (outcome.kind === "declined") return { kind: "declined", wrote };
   if (outcome.kind === "failed") {
     return { kind: "failed", reason: `${outcome.step.title} exited ${outcome.exitCode}` };
   }
@@ -571,10 +660,10 @@ export async function runGraphInstall(
   // answer: an unseeded graph is not usable until the timer first fires.
   if (options.noSeed === true) {
     ui.notify(
-      `Timer enabled; skipped the seeding run. The graph is NOT usable until ${REINDEX_UNIT}.timer first fires.`,
+      `Timer enabled; skipped the seeding run. The graph is NOT usable until ${stem}.timer first fires.`,
       "warning",
     );
-    return { kind: "installed", wrote: staged.written };
+    return { kind: "installed", wrote };
   }
 
   const health = await (options.probe ?? probeCodeGraph)(project);
@@ -583,13 +672,13 @@ export async function runGraphInstall(
     // Staged but not trusted. Reporting success here is how an operator learns
     // months later that no worker ever read an index.
     ui.notify(
-      [`Installed, but ${unhealthy.length} repo(s) did not verify: ${unhealthy.join(", ")}.`, "", staged.next].join("\n"),
+      [`Installed, but ${unhealthy.length} repo(s) did not verify: ${unhealthy.join(", ")}.`, "", plan.next].join("\n"),
       "error",
     );
     return { kind: "failed", reason: `unverified: ${unhealthy.join(", ")}` };
   }
   ui.notify(`Code graph installed and verified for ${repos.map((r) => r.name).join(", ")}.`, "info");
-  return { kind: "installed", wrote: staged.written };
+  return { kind: "installed", wrote };
 }
 
 /** The two prerequisites that make an enabled timer meaningful, or `undefined`. */
@@ -618,7 +707,7 @@ export function graphInstallable(project: ProjectConfig): GraphRepo[] {
   return graphRepos(project);
 }
 
-/** Where the reindex script lands, for the wizard's tail to name. */
-export function reindexScriptLocation(): string {
-  return reindexScriptPath();
+/** Where this project's reindex script lands, for the wizard's tail to name. */
+export function reindexScriptLocation(project: ProjectConfig): string {
+  return reindexScriptPath(project);
 }

package/src/setup-wizard.ts

@@ -93,6 +93,7 @@ import {
   POLICY_BRIEF_NAME,
   RELEASE_REQUIREMENT_CHOICES,
   REPORT_SCOPE_CHOICES,
+  REVIEW_STRICTNESS_CHOICES,
   SETUP_DEFAULTS,
   amendChoices,
   answersFromProject,
@@ -125,11 +126,16 @@ import {
   BASE_FRESHNESS,
   BEHIND_BASE_ACTIONS,
   DEFAULT_CAPS,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
   RELEASE_REQUIREMENTS,
   INTERRUPT_CATEGORIES,
   RELEASE_SHAPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   WEEKDAYS,
   type AuthorityHolder,
   type Caps,
@@ -142,6 +148,7 @@ import {
   type ReleaseRequirement,
   type ReportScopeChoice,
   type ResolvedGrants,
+  type ReviewPolicy,
 } from "./types.ts";
 import { withProgress } from "./ui/progress.ts";
 import type { WizardUi } from "./wizard-ui.ts";
@@ -972,6 +979,7 @@ function seedFromDiscovery(seed: SetupAnswers, found: DiscoveredFacts): SetupAns
       inProgress: labels.get(seed.stateLabels.inProgress.toLowerCase()) ?? seed.stateLabels.inProgress,
       blocked: labels.get(seed.stateLabels.blocked.toLowerCase()) ?? seed.stateLabels.blocked,
       failed: labels.get(seed.stateLabels.failed.toLowerCase()) ?? seed.stateLabels.failed,
+      backlog: labels.get(seed.stateLabels.backlog.toLowerCase()) ?? seed.stateLabels.backlog,
     },
     targetRepos,
     policy: {
@@ -1087,19 +1095,28 @@ const askTrackerAndRepos: AreaAsker = async (ui, a, probes) => {
 
   // One confirm instead of three prompts: the namespaced defaults are right for
   // almost everyone, and three dialogs of Enter-to-accept is how a wizard earns
-  // its reputation.
+  // its reputation. The park label is in the same confirm, with its ownership
+  // stated — it is not conductor-written, but it has to exist for the operator
+  // to have the gesture (#507).
   const stateLabels: SetupAnswers["stateLabels"] = { ...a.stateLabels };
   const customiseStates = await askYesNo(
     ui,
     "customise-state-labels",
     "State labels",
     `The conductor writes back "${stateLabels.inProgress}", "${stateLabels.blocked}" and ` +
-      `"${stateLabels.failed}" so the tracker alone shows live state. Rename them?`,
+      `"${stateLabels.failed}" so the tracker alone shows live state; "${stateLabels.backlog}" is ` +
+      `yours — the conductor never writes it, but an issue carrying it is never claimed. Rename them?`,
   );
   if (customiseStates) {
     stateLabels.inProgress = await ask(ui, "state-label-in-progress", "Label for a run in progress", stateLabels.inProgress);
     stateLabels.blocked = await ask(ui, "state-label-blocked", "Label for a run parked on a human", stateLabels.blocked);
     stateLabels.failed = await ask(ui, "state-label-failed", "Label for a run that gave up", stateLabels.failed);
+    stateLabels.backlog = await ask(
+      ui,
+      "state-label-backlog",
+      "Label the operator applies to park an issue (the conductor never writes it)",
+      stateLabels.backlog,
+    );
   }
 
   const routingLabelPrefix = await ask(
@@ -1379,6 +1396,73 @@ const askAuthorityArea: AreaAsker = async (ui, a, _probes, discovered) => {
  * and `claim-only` means anything that can invoke it can start dispatch once
  * the live claim and poller pass.
  */
+/**
+ * How many review rounds one PR lifecycle may be returned at most — the hard
+ * bound against endless polishing (#678). Validated in the dialog against the
+ * same integer range the loader validates against, so an out-of-range answer
+ * is re-asked rather than written for the daemon to reject. The consequence of
+ * the ceiling is stated in the title: at it, the PR is left open and escalated
+ * once, never returned again.
+ */
+async function askReviewRounds(ui: WizardUi, current: number): Promise<number> {
+  // Bounded like askValid above: a dialog that cannot be escaped is worse than
+  // one that gives up and leaves the config alone. The `--answers` path
+  // matters here specifically — answersUi is a map, not a consumer, so every
+  // retry reads the same value and an out-of-range file used to recurse
+  // forever instead of failing closed (#678).
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const raw = await ask(
+      ui,
+      "review-max-rounds",
+      `Review rounds per PR lifecycle — an integer ${REVIEW_MAX_ROUNDS_MIN} to ${REVIEW_MAX_ROUNDS_MAX}; ` +
+        `at the ceiling the PR is left open and escalated once`,
+      String(current),
+    );
+    const value = Number(raw);
+    if (Number.isInteger(value) && value >= REVIEW_MAX_ROUNDS_MIN && value <= REVIEW_MAX_ROUNDS_MAX) {
+      return value;
+    }
+    ui.notify(
+      `Review rounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX} ` +
+        `— shown the current value again.`,
+      "warning",
+    );
+  }
+  throw new Cancelled();
+}
+
+/**
+ * How green PRs are reviewed (#678), asked with the merge preconditions and
+ * the arming proof: they are the same kind of declared policy — a typed,
+ * mechanical boundary on what may happen to a PR — so they ride the same area.
+ *
+ * The three levels and their bars are shown before the select, with the
+ * recommended level marked, so an operator chooses between named thresholds
+ * rather than between three words. The select cursor opens on the current
+ * answer (the configured level on a re-run, the recommended default on a
+ * first run); the rounds are a validated integer within the same range the
+ * loader enforces.
+ */
+async function askReviewPolicy(ui: WizardUi, a: SetupAnswers): Promise<ReviewPolicy> {
+  ui.notify(
+    REVIEW_STRICTNESS.map((level) => `${level}${level === DEFAULT_REVIEW_STRICTNESS ? " (recommended)" : ""} — ${REVIEW_STRICTNESS_CHOICES[level]}`).join(
+      "\n",
+    ),
+    "info",
+  );
+  return {
+    strictness: await askLiteral(
+      ui,
+      "review-strictness",
+      "Review strictness for green PRs",
+      REVIEW_STRICTNESS,
+      REVIEW_STRICTNESS_CHOICES,
+      a.review.strictness,
+    ),
+    maxRounds: await askReviewRounds(ui, a.review.maxRounds),
+  };
+}
+
 const askPolicy: AreaAsker = async (ui, a) => ({
   ...a,
   policy: await askPolicyPreconditions(ui, a.policy, a.authority.release),
@@ -1390,6 +1474,7 @@ const askPolicy: AreaAsker = async (ui, a) => ({
     ARM_PROOF_CHOICES,
     a.armProof,
   ),
+  review: await askReviewPolicy(ui, a),
 });
 
 /** How a stuck run reaches a human, and who triages it when it does. */
@@ -2441,6 +2526,7 @@ function captureInventory(
   };
   captureIfWritten(plan.runtime.service);
   captureIfWritten(plan.runtime.herdrUnit);
+  captureIfWritten(plan.runtime.harnessMount);
   captureIfWritten(plan.runtime.herdrConfig);
   captureIfWritten(plan.runtime.herdrEnv);
   captureIfWritten(plan.runtime.recoverUnit);