omp-conductor 0.13.0 → 0.15.0

package/src/setup-host.ts

@@ -1,7 +1,8 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
-import { configPath, stateDir } from "./config.ts";
+import { configPath, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { isPaused, runDaemon, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import { DEFAULT_FLEET_AGENT_NAME } from "./fleet.ts";
 import {
@@ -14,11 +15,13 @@ import {
   type StopResult,
 } from "./lifecycle.ts";
 import {
+  legacyArmedMarkerPath,
   readTickConfig,
   TICK_CONFIG_FILE,
+  tickConfigMatchesProject,
   type TickConfig,
 } from "./orchestrator-tick.ts";
-import type { Caps, ProjectConfig } from "./types.ts";
+import type { Caps, ConductorConfig, ProjectConfig } from "./types.ts";
 
 export const DEFAULT_TICK_INTERVAL_SECONDS = 900;
 export const STAGED_SERVICE_NAME = "omp-conductor.service";
@@ -36,6 +39,21 @@ export interface HostRuntimePlan {
   tick?: PlannedWrite<TickConfig>;
   installCommands: readonly string[];
   cliSource: "global" | "plugin";
+  /** Absolute path of the unit systemd actually reads. */
+  installedPath: string;
+  /**
+   * What installing would do to the unit **systemd reads**, which is a different
+   * question from {@link HostRuntimePlan.service}'s action — that one compares the
+   * staged copy under the state directory.
+   *
+   * The distinction is load-bearing: staging has always happened during setup,
+   * so on any fleet configured before the install was executed the staged file is
+   * already current (`service.action === "keep"`) while `/etc/systemd/system`
+   * holds nothing at all. Gating the install offer on the staged action therefore
+   * skipped exactly the fleets that had never installed the unit, and told them
+   * the installed unit matched.
+   */
+  installedAction: PlannedWrite<string>["action"];
 }
 
 export interface ServiceRuntime {
@@ -66,6 +84,143 @@ function actionFor(path: string, content: string): PlannedWrite<string>["action"
     return "update";
   }
 }
+/**
+ * Which account this host's fleet belongs to, and how we know.
+ *
+ * Two sources, in order of authority: the installed unit's own `User=` is what
+ * systemd will actually run as, and the owner of `$OMP_CONDUCTOR_HOME` is what
+ * owns the config, the store and the state directory. Either one disagreeing
+ * with the invoking account means staging would write the wrong identity.
+ */
+export interface FleetAccount {
+  name: string | undefined;
+  source: "installed unit" | "$OMP_CONDUCTOR_HOME owner" | "nothing on this host";
+}
+
+export interface EscalationDeps {
+  invokingUser(): string;
+  /** `$SUDO_USER`, which `sudo` sets and `sudo -i` / `su -` clear. */
+  sudoUser(): string | undefined;
+  /** `User=` from the installed unit, or `undefined` when there is no unit. */
+  unitUser(): string | undefined;
+  /** Owner of `$OMP_CONDUCTOR_HOME`, or `undefined` when it does not exist. */
+  homeOwner(): string | undefined;
+  conductorHome(): string;
+}
+
+/** uid → account name. `id -un` because no Node builtin maps a foreign uid. */
+function accountName(uid: number): string {
+  const ran = spawnSync("id", ["-un", String(uid)], { encoding: "utf8" });
+  const name = ran.status === 0 ? (ran.stdout ?? "").trim() : "";
+  return name === "" ? `uid ${uid}` : name;
+}
+
+function installedUnitUser(): string | undefined {
+  try {
+    const unit = readFileSync(join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME), "utf8");
+    const match = /^User=(.*)$/m.exec(unit);
+    if (match === null) return undefined;
+    // Unquoted in what we generate, but systemd accepts quotes and a
+    // hand-edited unit is exactly the case this guard has to read correctly.
+    const value = match[1]?.trim().replace(/^"(.*)"$/, "$1") ?? "";
+    return value === "" ? undefined : value;
+  } catch {
+    return undefined;
+  }
+}
+
+export const DEFAULT_ESCALATION_DEPS: EscalationDeps = {
+  invokingUser: () => userInfo().username,
+  sudoUser: () => process.env["SUDO_USER"],
+  unitUser: installedUnitUser,
+  homeOwner: () => {
+    try {
+      return accountName(statSync(dirname(configPath())).uid);
+    } catch {
+      return undefined;
+    }
+  },
+  conductorHome: () => dirname(configPath()),
+};
+
+/** The account this host's fleet runs as, from whichever source knows. */
+export function resolveFleetAccount(deps: EscalationDeps = DEFAULT_ESCALATION_DEPS): FleetAccount {
+  const fromUnit = deps.unitUser();
+  if (fromUnit !== undefined) return { name: fromUnit, source: "installed unit" };
+  const fromHome = deps.homeOwner();
+  if (fromHome !== undefined) return { name: fromHome, source: "$OMP_CONDUCTOR_HOME owner" };
+  return { name: undefined, source: "nothing on this host" };
+}
+
+export type EscalationVerdict = { kind: "ok" } | { kind: "refuse"; message: string };
+
+/**
+ * Refuses an *escalated* invocation of any setup path — and only that.
+ *
+ * The distinction is the whole point. Staging derives the unit's `User=` and
+ * `HOME=` from the invoking account ({@link defaultServiceRuntime}), so a
+ * `sudo omp-conductor setup host` writes `User=root` + `HOME=/root` into a unit
+ * for a fleet that runs as somebody else, and the config it loads, the state
+ * directory it writes and the indexes it points at all resolve as root too.
+ * Nothing about that announces itself: the unit starts, the timer goes green,
+ * and the fleet reads none of it. So it is refused rather than accommodated.
+ *
+ * `uid 0` is *not* the test. A fleet that legitimately runs as root — root owns
+ * `$OMP_CONDUCTOR_HOME` and the unit says `User=root` — is the case this verb
+ * exists for on single-tenant boxes, and refusing there would break exactly the
+ * hosts it targets. Two checks instead:
+ *
+ *   - `$SUDO_USER` is set, which is `sudo` announcing the escalation itself;
+ *   - the invoking account disagrees with the fleet account, which is what
+ *     catches `sudo -i` and `su -` — both clear `$SUDO_USER`, so the
+ *     environment check alone is not sufficient.
+ */
+export function checkEscalation(
+  verb: string,
+  deps: EscalationDeps = DEFAULT_ESCALATION_DEPS,
+): EscalationVerdict {
+  const invoking = deps.invokingUser();
+  const sudoUser = deps.sudoUser();
+  const fleet = resolveFleetAccount(deps);
+
+  if (sudoUser !== undefined && sudoUser !== "") {
+    return {
+      kind: "refuse",
+      message: refusal(verb, invoking, sudoUser, fleet, deps.conductorHome()),
+    };
+  }
+  if (fleet.name !== undefined && fleet.name !== invoking) {
+    return {
+      kind: "refuse",
+      message: refusal(verb, invoking, undefined, fleet, deps.conductorHome()),
+    };
+  }
+  return { kind: "ok" };
+}
+
+function refusal(
+  verb: string,
+  invoking: string,
+  sudoUser: string | undefined,
+  fleet: FleetAccount,
+  home: string,
+): string {
+  const fleetName = fleet.name ?? sudoUser ?? "the fleet's own account";
+  return [
+    `omp-conductor: run ${verb} as the account the fleet runs as, not escalated.`,
+    sudoUser === undefined
+      ? `This is running as "${invoking}", but the fleet runs as "${fleetName}" (${fleet.source}).`
+      : `This is running as "${invoking}" under sudo from "${sudoUser}"` +
+        (fleet.name === undefined ? "." : `, and the fleet runs as "${fleet.name}" (${fleet.source}).`),
+    `As "${invoking}" the config, ${home}, ~/.cache and the unit's own User= all resolve`,
+    `as "${invoking}" instead, and the result is a unit that starts and a fleet that reads`,
+    "none of it. Nothing has been written.",
+    "",
+    `Run it as "${fleetName}". Only the individual install steps need root, and`,
+    `${verb} runs those for you with sudo after showing you each one.`,
+  ].join("\n");
+}
+
 
 function defaultServiceRuntime(telegramStateDir: string): ServiceRuntime {
   const home = homedir();
@@ -86,16 +241,19 @@ function defaultServiceRuntime(telegramStateDir: string): ServiceRuntime {
   };
 }
 
-export function renderDaemonService(
-  project: ProjectConfig,
-  caps: Caps,
-  runtime: ServiceRuntime,
-): string {
+export function totalConfiguredWorkers(cfg: ConductorConfig = loadConfig()): number {
+  return cfg.projects.reduce(
+    (total, project) => total + resolveCaps(project, cfg.defaults).maxConcurrentWorkers,
+    0,
+  );
+}
+
+export function renderDaemonService(runtime: ServiceRuntime, totalWorkers: number): string {
   const command =
     runtime.cli === undefined
-      ? [runtime.bun, runtime.packageCli, "daemon", "--project", project.name, "--port", String(DEFAULT_PORT)]
-      : [runtime.cli, "daemon", "--project", project.name, "--port", String(DEFAULT_PORT)];
-  const memoryMax = caps.maxConcurrentWorkers <= 1 ? "3G" : "5G";
+      ? [runtime.bun, runtime.packageCli, "daemon", "--port", String(DEFAULT_PORT)]
+      : [runtime.cli, "daemon", "--port", String(DEFAULT_PORT)];
+  const memoryMax = totalWorkers <= 1 ? "3G" : "5G";
   return [
     "[Unit]",
     "Description=omp-conductor dispatch daemon",
@@ -128,6 +286,19 @@ function tickSearchRoots(project: ProjectConfig): string[] {
   return roots.filter((root, index) => roots.indexOf(root) === index);
 }
 
+/**
+ * The tick config for one project's fleet cwd.
+ *
+ * Everything per-project here used to be shared, and that was two bugs: one
+ * `<stateDir>/armed` marker meant arming project A armed B as well, and one
+ * `agentName` meant every pane claimed the identity `fleet`, so herdr recovery
+ * and tick ownership could not tell two fleets apart.
+ *
+ * An existing config keeps an explicit `armedFile`/`agentName` only when it
+ * differs from those shared defaults. A value equal to a shared default cannot
+ * have been a deliberate per-project choice — it *is* the collision — so it is
+ * rewritten; anything else is operator intent and survives untouched.
+ */
 function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrite<TickConfig> {
   let existing: { path: string; config: TickConfig } | undefined;
   for (const root of tickSearchRoots(project)) {
@@ -135,24 +306,37 @@ function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrit
     if (result.kind === "invalid") {
       throw new Error(`tick config invalid at ${result.path}: ${result.problem}; fix or remove it before setup`);
     }
-    if (result.kind === "ok") {
+    // A config stamped for another project is that project's file: the search
+    // roots overlap, and restamping it here would hand this project's identity
+    // to the other fleet's cwd.
+    if (result.kind === "ok" && tickConfigMatchesProject(result.config, project.name)) {
       existing = { path: result.path, config: result.config };
       break;
     }
   }
 
+  const armedFile = join(stateDir(), `armed-${project.name}`);
   const path = existing?.path ?? join(project.workspaceRoot, TICK_CONFIG_FILE);
   const config: TickConfig = existing === undefined
     ? {
         intervalSeconds: DEFAULT_TICK_INTERVAL_SECONDS,
-        armedFile: join(stateDir(), "armed"),
+        project: project.name,
+        armedFile,
         accessFile: join(telegramStateDir, "access.json"),
-        agentName: DEFAULT_FLEET_AGENT_NAME,
+        agentName: project.name,
       }
     : {
         ...existing.config,
-        armedFile: existing.config.armedFile ?? join(stateDir(), "armed"),
+        project: project.name,
+        armedFile:
+          existing.config.armedFile === undefined || existing.config.armedFile === legacyArmedMarkerPath()
+            ? armedFile
+            : existing.config.armedFile,
         accessFile: existing.config.accessFile ?? join(telegramStateDir, "access.json"),
+        agentName:
+          existing.config.agentName === undefined || existing.config.agentName === DEFAULT_FLEET_AGENT_NAME
+            ? project.name
+            : existing.config.agentName,
       };
   const content = `${JSON.stringify(config, null, 2)}\n`;
   return { path, action: actionFor(path, content), content, value: config };
@@ -160,12 +344,16 @@ function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrit
 
 export function planHostRuntime(
   project: ProjectConfig,
-  caps: Caps,
+  _caps: Caps,
   telegramStateDir: string,
   runtime: ServiceRuntime = defaultServiceRuntime(telegramStateDir),
+  // Callers that know the fleet pass the sum of resolved maxConcurrentWorkers.
+  // Defaulting through loadConfig() would throw in install tests that stage
+  // files before a config exists, and would hide a missing total at the call site.
+  totalWorkers: number = 1,
 ): HostRuntimePlan {
   const servicePath = join(stateDir(), STAGED_SERVICE_NAME);
-  const serviceContent = renderDaemonService(project, caps, runtime);
+  const serviceContent = renderDaemonService(runtime, totalWorkers);
   const service: PlannedWrite<string> = {
     path: servicePath,
     action: actionFor(servicePath, serviceContent),
@@ -185,6 +373,8 @@ export function planHostRuntime(
       `sudo systemctl restart ${STAGED_SERVICE_NAME}`,
     ],
     cliSource: runtime.cli === undefined ? "plugin" : "global",
+    installedPath,
+    installedAction: actionFor(installedPath, serviceContent),
   };
 }
 
@@ -242,7 +432,7 @@ export interface SetupSmokeResult {
 }
 
 export interface SetupSmokeDeps {
-  paused(): boolean;
+  paused(project: string): boolean;
   runOnce(project: string): Promise<void>;
   living(): DaemonRecord | undefined;
   health(port: number): Promise<{ ok: boolean; body?: string }>;
@@ -265,7 +455,7 @@ export async function runSetupSmoke(
   project: string,
   deps: SetupSmokeDeps = DEFAULT_SMOKE_DEPS,
 ): Promise<SetupSmokeResult> {
-  if (!deps.paused()) throw new Error("setup smoke requires paused dispatch");
+  if (!deps.paused(project)) throw new Error("setup smoke requires paused dispatch");
   await deps.runOnce(project);
   const existing = deps.living();
   if (existing !== undefined) {
@@ -283,8 +473,3 @@ export async function runSetupSmoke(
     await deps.stop();
   }
 }
-
-/** Absolute path of the unit systemd actually reads. */
-export function installedUnitPath(): string {
-  return join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME);
-}

package/src/setup-install.ts

@@ -0,0 +1,320 @@
+/**
+ * The two executed install paths: the supervised daemon unit, and the code-graph
+ * timer.
+ *
+ * Both used to end at a printed list the operator retyped — `setup-host.ts`
+ * composed the exact `sudo` lines and showed them, and `graph-setup --write`
+ * staged its files and said it "never runs `systemctl` itself". Retyping is not
+ * a safety property: it is the same commands with a chance of a typo, and it is
+ * why a fleet sits half-installed. These run them, behind one confirm each.
+ *
+ * Why this module exists rather than the code living where its pieces do:
+ * `graph-health.ts` already imports `graph.ts`, so orchestration that verifies
+ * with `probeCodeGraph()` cannot sit in `graph.ts` without a cycle — and `cli.ts`
+ * is argument parsing, not sequencing. Both the CLI verbs and the wizard's tail
+ * call in here; `privileged.ts` stays the primitive underneath.
+ */
+
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { stateDir } from "./config.ts";
+import {
+  graphRepos,
+  formatGraphSetup,
+  mcpEntry,
+  reindexScriptPath,
+  resolvePrereqs,
+  REINDEX_UNIT,
+  unitPaths,
+  writeGraphSetup,
+  type GraphPrereqs,
+  type GraphRepo,
+} from "./graph.ts";
+import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
+import { runPrivileged, type PrivilegedDeps, type PrivilegedStep } from "./privileged.ts";
+import {
+  checkEscalation,
+  planHostRuntime,
+  totalConfiguredWorkers,
+  writeHostRuntime,
+  STAGED_SERVICE_NAME,
+  SYSTEMD_UNIT_DIR,
+  type EscalationDeps,
+} from "./setup-host.ts";
+import type { WizardUi } from "./wizard-ui.ts";
+import type { Caps, ProjectConfig } from "./types.ts";
+
+/**
+ * Every outcome a caller has to tell apart. `staged` is the non-Linux answer:
+ * the files are real and correct, only the `systemctl` half is impossible.
+ */
+export type InstallOutcome =
+  | { kind: "installed"; wrote: readonly string[] }
+  | { kind: "staged"; wrote: readonly string[]; reason: string }
+  | { kind: "declined"; wrote: readonly string[] }
+  | { kind: "refused"; reason: string }
+  | { kind: "failed"; reason: string };
+
+export interface InstallDeps {
+  privileged?: PrivilegedDeps;
+  escalation?: EscalationDeps;
+  /** `"linux"` gates the systemd half. Injectable so the refusal is testable. */
+  platform?: () => string;
+  unitDir?: string;
+}
+
+/**
+ * `systemctl` exists only on Linux, and staging is still worth doing everywhere:
+ * a macOS operator reading the plan wants the rendered unit on disk to copy to
+ * the box that will run it. So this is checked *after* the files are written.
+ */
+function linuxOnly(deps: InstallDeps): string | undefined {
+  return (deps.platform ?? platform)() === "linux"
+    ? undefined
+    : "systemd install is Linux-only; staged files are at";
+}
+
+/**
+ * Install the supervised daemon unit: re-render, stage, then run the four steps
+ * `planHostRuntime` used to only print.
+ */
+export async function runHostInstall(
+  project: ProjectConfig,
+  caps: Caps,
+  telegramStateDir: string,
+  ui: WizardUi,
+  deps: InstallDeps = {},
+): Promise<InstallOutcome> {
+  const verdict = checkEscalation("setup host", deps.escalation);
+  if (verdict.kind === "refuse") {
+    ui.notify(verdict.message, "error");
+    return { kind: "refused", reason: verdict.message };
+  }
+
+  const plan = planHostRuntime(project, caps, telegramStateDir, undefined, hostInstallWorkers(caps));
+  const wrote = writeHostRuntime(plan);
+  const unitDir = deps.unitDir ?? SYSTEMD_UNIT_DIR;
+  const installed = join(unitDir, STAGED_SERVICE_NAME);
+
+  const blocked = linuxOnly(deps);
+  if (blocked !== undefined) {
+    ui.notify(`${blocked} ${plan.service.path}`, "warning");
+    return { kind: "staged", wrote, reason: `${blocked} ${plan.service.path}` };
+  }
+
+  // argv, not shell: `installCommands` renders `sudo …` strings for humans to
+  // read, and re-parsing those into an argv is how a path with a space becomes
+  // two arguments. The steps are built from the same values instead.
+  const steps: PrivilegedStep[] = [
+    { title: `install ${STAGED_SERVICE_NAME}`, argv: ["install", "-m", "0644", plan.service.path, installed] },
+    { 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] },
+  ];
+
+  const outcome = await runPrivileged(steps, ui, {
+    ...(deps.privileged === undefined ? {} : { deps: deps.privileged }),
+    title: "Install and start the supervised daemon?",
+    preamble: [
+      `Installs ${plan.service.path} as ${installed}, then enables and restarts it.`,
+      "The unit runs as the account that staged it; nothing here changes that.",
+    ],
+  });
+  if (outcome.kind === "declined") return { kind: "declined", wrote };
+  if (outcome.kind === "failed") {
+    return { kind: "failed", reason: `${outcome.step.title} exited ${outcome.exitCode}` };
+  }
+  ui.notify(`Installed and started ${STAGED_SERVICE_NAME}.`, "info");
+  return { kind: "installed", wrote };
+}
+
+/** Fleet-wide worker sum when config is loadable; otherwise this project's caps. */
+function hostInstallWorkers(caps: Caps): number {
+  try {
+    return totalConfiguredWorkers();
+  } catch {
+    return caps.maxConcurrentWorkers;
+  }
+}
+
+export interface GraphInstallOptions extends InstallDeps {
+  /**
+   * Skip the seeding step. The timer is still installed and enabled, and the
+   * graph is plainly unusable until its first scheduled run finishes. Never
+   * skips the prerequisite or clone steps: those are what make the installed
+   * unit runnable at all.
+   */
+  noSeed?: boolean;
+  /** Print the plan and change nothing — today's `graph-setup` behaviour. */
+  print?: boolean;
+  /** Injected so the prerequisite gate is testable without touching PATH. */
+  prereqs?: GraphPrereqs;
+  /** Injected so verification is deterministic without a live indexer. */
+  probe?: (project: ProjectConfig) => Promise<CodeGraphHealth>;
+}
+
+/**
+ * The code-graph install, end to end.
+ *
+ * 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.
+ */
+export async function runGraphInstall(
+  project: ProjectConfig,
+  ui: WizardUi,
+  options: GraphInstallOptions = {},
+): Promise<InstallOutcome> {
+  const repos = graphRepos(project);
+  if (repos.length === 0) {
+    const reason = `no repo in ${project.name} has graphProject — nothing to install`;
+    ui.notify(reason, "error");
+    return { kind: "refused", reason };
+  }
+
+  const prereqs = options.prereqs ?? resolvePrereqs();
+
+  // `--print` is today's `graph-setup`: read-only, writes nothing, runs nothing.
+  // It comes first — before the escalation guard and before the prerequisite
+  // refusal — because the host that most needs the plan is exactly the fresh one
+  // missing the indexer, and refusing there would withhold the remediation the
+  // operator ran the command to get. `formatGraphSetup` is that renderer, and it
+  // already reports the prerequisites as step 0.
+  if (options.print === true) {
+    ui.notify(formatGraphSetup(project, options.unitDir ?? SYSTEMD_UNIT_DIR, prereqs), "info");
+    return { kind: "staged", wrote: [], reason: "print-only" };
+  }
+
+  const verdict = checkEscalation("setup graph", options.escalation);
+  if (verdict.kind === "refuse") {
+    ui.notify(verdict.message, "error");
+    return { kind: "refused", reason: verdict.message };
+  }
+
+  // 1. Prerequisites. With no indexer on PATH every timer run fails, and with no
+  //    MCP entry no worker can read what it indexed — so this stops before
+  //    installing anything rather than enabling a timer that cannot work.
+  const missing = prerequisiteProblem(prereqs);
+  if (missing !== undefined) {
+    ui.notify([missing, "", mcpEntry(prereqs)].join("\n"), "error");
+    return { kind: "refused", reason: missing };
+  }
+
+  const staged = writeGraphSetup(project, options.unitDir ?? SYSTEMD_UNIT_DIR);
+  const absent = repos.filter((r) => !existsSync(r.graphProject));
+
+  // 2. Missing clones, as the operator. A root-owned index-only clone under the
+  //    fleet user's cache is exactly the failure the escalation guard exists to
+  //    prevent — but it belongs in the same plan under the same confirm.
+  const clones: PrivilegedStep[] = absent.map((r) => ({
+    title: `clone ${r.name} for indexing (as you, not root)`,
+    argv: ["git", "clone", "--single-branch", "--branch", r.defaultBranch, r.cloneUrl, r.graphProject],
+    unprivileged: true,
+  }));
+
+  const blocked = linuxOnly(options);
+  const { service, timer } = unitPaths(options.unitDir ?? SYSTEMD_UNIT_DIR);
+  const from = unitPaths(stateDir());
+  // 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
+  //    verification below could interpret.
+  const seed: PrivilegedStep[] =
+    options.noSeed === true
+      ? []
+      : [{ title: `seed the indexes (runs ${REINDEX_UNIT}.service once, minutes per repo)`, argv: ["systemctl", "start", `${REINDEX_UNIT}.service`] }];
+  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`] },
+          ...seed,
+        ]
+      : [];
+
+  if (blocked !== undefined) {
+    ui.notify(`${blocked} ${service} and ${timer}`, "warning");
+    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?",
+    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.`]),
+      `Indexer: ${prereqs.indexer ?? "on PATH"}.`,
+    ],
+  });
+  if (outcome.kind === "declined") return { kind: "declined", wrote: staged.written };
+  if (outcome.kind === "failed") {
+    return { kind: "failed", reason: `${outcome.step.title} exited ${outcome.exitCode}` };
+  }
+
+  // Verify. `--no-seed` has nothing to verify yet, and saying so is the honest
+  // 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.`,
+      "warning",
+    );
+    return { kind: "installed", wrote: staged.written };
+  }
+
+  const health = await (options.probe ?? probeCodeGraph)(project);
+  const unhealthy = unverifiedRepos(health);
+  if (unhealthy.length > 0) {
+    // 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"),
+      "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 };
+}
+
+/** The two prerequisites that make an enabled timer meaningful, or `undefined`. */
+function prerequisiteProblem(prereqs: GraphPrereqs): string | undefined {
+  if (prereqs.indexer === null) {
+    return "codebase-memory-mcp is not on PATH — every timer run would fail, so nothing was installed.";
+  }
+  if (!prereqs.mounted) {
+    return "no codebase-memory MCP entry — no worker could read the indexes, so nothing was installed.";
+  }
+  return undefined;
+}
+
+/**
+ * Repos whose index the probe could not vouch for: a missing clone, or an
+ * indexed project path that never appeared in `list_projects`. Either one means
+ * staged-but-not-trusted, which must not be reported as success.
+ */
+function unverifiedRepos(health: CodeGraphHealth): string[] {
+  if (!health.configured) return [];
+  return health.repos.filter((r) => r.clone !== "present" || r.index !== "present").map((r) => r.name);
+}
+
+/** The repos `setup graph` would act on, for a caller deciding whether to offer it. */
+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();
+}