omp-conductor 0.17.0 → 0.18.0

package/src/graph-health.ts

@@ -1,12 +1,21 @@
 import { existsSync } from "node:fs";
-import { graphRepos, REINDEX_UNIT, resolvePrereqs, type GraphPrereqs } from "./graph.ts";
+import { graphRepos, reindexUnitName, resolvePrereqs, type GraphPrereqs } from "./graph.ts";
 import type { ProjectConfig } from "./types.ts";
 
 export const GRAPH_PROBE_TIMEOUT_MS = 1_000;
 export const GRAPH_FRESHNESS_MS = 45 * 60_000;
 
+/** Existence findings: the check observed the host (PATH, a directory, an index). */
 type CheckState = "present" | "missing" | "unknown";
 
+/**
+ * The MCP-mount finding. Its only evidence is the agent's `mcp.json` on disk,
+ * never a live session, so it speaks of configuration rather than presence — a
+ * runtime observation of the mounted toolset must be a *different* state, not
+ * this one relabelled (#738).
+ */
+type McpMountState = "configured" | "unconfigured" | "unknown";
+
 export interface CodeGraphRepoHealth {
   name: string;
   path: string;
@@ -22,7 +31,7 @@ export type CodeGraphHealth =
       checkedAt: string;
       prerequisites: {
         indexer: CheckState;
-        mcpMount: CheckState;
+        mcpMount: McpMountState;
       };
       repos: CodeGraphRepoHealth[];
       timer: {
@@ -228,19 +237,23 @@ export async function probeCodeGraph(
   let uncertain = false;
 
   const indexer: CheckState = prereqs.indexer === null ? "missing" : "present";
-  const mcpMount: CheckState = prereqs.mounted ? "present" : "missing";
+  const mcpMount: McpMountState = prereqs.mounted ? "configured" : "unconfigured";
   if (indexer === "missing") reasons.push("indexer is not present on PATH");
-  if (mcpMount === "missing") reasons.push("worker MCP configuration does not mount the indexer");
+  if (mcpMount === "unconfigured") reasons.push("worker MCP configuration does not mount the indexer");
 
+  // The units are per project (`cbm-reindex-<project>.*`): probing the shared
+  // stem would report project B's health against project A's timer, and with
+  // both installed the answer would be whichever the probe guessed (#720).
+  const stem = reindexUnitName(project);
   const [projectsResult, enabledResult, activeResult, serviceResult] = await Promise.all([
     prereqs.indexer === null
       ? Promise.resolve<ReadOnlyCommandResult>({ kind: "unavailable" })
       : deps.run(prereqs.indexer, ["cli", "list_projects", "{}"]),
-    deps.run("systemctl", ["is-enabled", `${REINDEX_UNIT}.timer`]),
-    deps.run("systemctl", ["is-active", `${REINDEX_UNIT}.timer`]),
+    deps.run("systemctl", ["is-enabled", `${stem}.timer`]),
+    deps.run("systemctl", ["is-active", `${stem}.timer`]),
     deps.run("systemctl", [
       "show",
-      `${REINDEX_UNIT}.service`,
+      `${stem}.service`,
       "--property=Result",
       "--property=ExecMainStatus",
       "--property=ExecMainExitTimestamp",

package/src/graph.ts

@@ -14,9 +14,10 @@
  * - **This package never builds or mutates an index, and never depends on the
  *   indexer for dispatch.** The optional health surface runs the indexer's
  *   read-only `list_projects` query; nothing spawns the graph server or imports
- *   it. `graph-setup` prints commands, and with `--write` writes two systemd
- *   units — it does not enable them, because a package that silently writes
- *   root-level state is not one you can trust with a fleet.
+ *   it. `setup graph` renders a script and two systemd units per project and
+ *   stages them only after its consent prompt — it does not enable them,
+ *   because a package that silently writes root-level state is not one you can
+ *   trust with a fleet.
  * - **A worker never queries its own worktree.** An index is keyed by the
  *   realpath of the directory it was built from, with no git-worktree awareness,
  *   so a run's `worktrees/<issue>` path is always an empty project. Workers are
@@ -37,12 +38,135 @@ import type { ProjectConfig, RepoTarget } from "./types.ts";
  */
 const INDEXER = "codebase-memory-mcp";
 
-/** Both units and the script share this stem; `cbm` is the indexer's own prefix. */
+/** The shared prefix of every reindex artefact; `cbm` is the indexer's own prefix. */
 export const REINDEX_UNIT = "cbm-reindex";
 
 /** Where a system timer has to live to be enabled by `systemctl`. */
 export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";
 
+/**
+ * The filename-safe stem one project's reindex artefacts share:
+ * `cbm-reindex-<slug>`. The slug is the project name folded to `[a-z0-9-]` —
+ * the alphabet systemd unit names tolerate — with a deterministic hash
+ * fallback for a name that folds to nothing, so every configured project gets
+ * its own script, service and timer on the same host and one project's
+ * `setup graph` can never replace another's files. The #720 incident was
+ * exactly one project-less set of names, silently overwritten by the second
+ * project's run.
+ *
+ * Two distinct names can fold to one stem ("My Project" vs "my_project"), so
+ * the write path checks each target's generated-for marker before replacing
+ * it rather than trusting the stem alone.
+ */
+export function reindexUnitName(p: ProjectConfig): string {
+  const name = p.name;
+  const slug = name
+    .normalize("NFKD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (slug !== "") return `${REINDEX_UNIT}-${slug}`;
+  let hash = 2166136261;
+  for (const byte of new TextEncoder().encode(name)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return `${REINDEX_UNIT}-project-${hash.toString(16).padStart(8, "0")}`;
+}
+
+/**
+ * Where this project's generated refresh script lands: conductor state, not a
+ * unit directory, because it is ours to regenerate and needs no root to write.
+ */
+export function reindexScriptPath(p: ProjectConfig): string {
+  return join(stateDir(), `${reindexUnitName(p)}.sh`);
+}
+
+/** Both unit files, from the stem `systemctl enable` will be given. */
+export function unitPaths(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): { service: string; timer: string } {
+  const stem = reindexUnitName(p);
+  return {
+    service: join(unitDir, `${stem}.service`),
+    timer: join(unitDir, `${stem}.timer`),
+  };
+}
+
+/** The `project "<name>"` marker every generated file carries: the script's
+ *  first header line, and both units' Description. */
+const GENERATED_FOR = /omp-conductor project "([^"]+)"/;
+
+/**
+ * The project a generated file at `path` was rendered for, or `undefined`
+ * when the file is absent, unreadable, or does not carry our marker. Any of
+ * the three artefacts can identify its stem's owner, which is what lets a
+ * write refuse to replace another project's files instead of silently doing
+ * it (#720).
+ */
+export function generatedFor(path: string): string | undefined {
+  try {
+    return GENERATED_FOR.exec(readFileSync(path, "utf8"))?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The first of `paths` that already exists and is not this project's own
+ * artefact — another project's generated file, or something `setup graph`
+ * never wrote — or `undefined` when every path is clear. The stem derives
+ * from the project name, and two names can fold to one stem, so an existing
+ * file's marker is checked before it is ever overwritten (#720).
+ */
+export function stagingConflict(
+  p: ProjectConfig,
+  paths: readonly string[],
+): { path: string; owner: string | undefined } | undefined {
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    const owner = generatedFor(path);
+    if (owner !== p.name) return { path, owner };
+  }
+  return undefined;
+}
+
+/** The refusal reason for a conflicting artefact, shared by the pre-consent
+ *  check and the write backstop so both say the same thing. */
+export function graphConflictMessage(conflict: { path: string; owner: string | undefined }): string {
+  return (
+    `${conflict.path} already exists and was ` +
+    (conflict.owner === undefined
+      ? "not generated by `setup graph` — refusing to overwrite it. Delete the file and re-run."
+      : `generated for project "${conflict.owner}" — refusing to overwrite another project's reindex artefacts. Delete it and re-run.`)
+  );
+}
+
+/**
+ * The pre-#720 project-less artefact paths that still exist, in the order a
+ * host that ran the old version has them. `setup graph` no longer writes or
+ * installs these, so a host that upgrades keeps them — and their timer keeps
+ * refreshing whichever project generated it last, forever.
+ */
+export function legacyReindexFiles(): string[] {
+  return [
+    join(stateDir(), `${REINDEX_UNIT}.sh`),
+    join(stateDir(), `${REINDEX_UNIT}.service`),
+    join(stateDir(), `${REINDEX_UNIT}.timer`),
+  ].filter((f) => existsSync(f));
+}
+
+/** What to do with the legacy files, shared by the plan and the install
+ *  warning so both say the same thing. */
+export function legacyReindexNote(files: readonly string[]): string {
+  return [
+    `Legacy project-less reindex files still exist: ${files.join(", ")}.`,
+    "`setup graph` no longer writes or installs them, so their timer refreshes",
+    "whichever project generated it last, forever. Disable and delete them:",
+    "  sudo systemctl disable --now cbm-reindex.timer",
+    `  rm ${files.join(" ")}`,
+  ].join("\n");
+}
+
 /** Where the upstream indexer lives, for an operator who has to go install it. */
 const INDEXER_SOURCE = "https://github.com/DeusData/codebase-memory-mcp";
 
@@ -122,35 +246,111 @@ export function graphRepos(p: ProjectConfig): GraphRepo[] {
 }
 
 /**
- * The paragraph a worker's brief carries about its repo's graph, or `""` when
- * the repo has none — in which case the rendered brief is byte-for-byte the one
- * this package shipped before graphs existed.
+ * The project key the indexer derives from a path — the `project` argument
+ * every code-graph tool takes, and the `<name>` in `<name>.db` under the
+ * indexer's store. This is the mirror of the indexer's own
+ * `cbm_project_name_from_path` (upstream `src/pipeline/fqn.c`):
+ * validator-safe bytes survive, every other byte maps to `-` (non-ASCII
+ * bytes to their two lowercase hex digits), runs of `-` and `.` collapse,
+ * leading `-`/`.` and trailing `-` trim, an all-separator path falls back to
+ * `root`, and a name over 200 bytes is bound with an FNV-1a suffix.
+ *
+ * A brief that named a wrong key would send a worker to a tool that answers
+ * empty and reads as "no graph" — indistinguishable from silence. So this
+ * matches the indexer byte for byte, and graph.test.ts pins it against names
+ * taken from the live indexer store rather than against this function's own
+ * output.
+ */
+export function graphProjectKey(graphProject: string): string {
+  const bytes = new TextEncoder().encode(graphProject);
+  let mapped = "";
+  for (const b of bytes) {
+    const safe =
+      (b >= 0x61 && b <= 0x7a) || (b >= 0x41 && b <= 0x5a) || (b >= 0x30 && b <= 0x39) || b === 0x2e || b === 0x5f || b === 0x2d;
+    if (safe) mapped += String.fromCharCode(b);
+    else if (b >= 0x80) mapped += ((b >> 4) & 0xf).toString(16) + (b & 0xf).toString(16);
+    else mapped += "-";
+  }
+
+  // Collapse consecutive dashes and dots (the validator also rejects "..").
+  let collapsed = "";
+  for (const ch of mapped) {
+    const prev = collapsed[collapsed.length - 1];
+    if ((ch === "-" && prev === "-") || (ch === "." && prev === ".")) continue;
+    collapsed += ch;
+  }
+
+  // Trim leading dashes and dots (the validator rejects a leading dot) and
+  // trailing dashes. A path that maps to nothing but separators is "root".
+  let start = 0;
+  while (start < collapsed.length && (collapsed[start] === "-" || collapsed[start] === ".")) start++;
+  let end = collapsed.length;
+  while (end > start && collapsed[end - 1] === "-") end--;
+  const key = collapsed.slice(start, end);
+  if (key === "") return "root";
+
+  // Bound long names the way the indexer does (#624): first 191 bytes plus an
+  // 8-hex FNV-1a of the full name, so two long paths that share a prefix but
+  // differ later still map to distinct names. The mapped key is pure ASCII, so
+  // per-character iteration is per-byte iteration.
+  if (key.length > 200) {
+    let hash = 2166136261;
+    for (const ch of key) {
+      hash ^= ch.charCodeAt(0);
+      hash = Math.imul(hash, 16777619) >>> 0;
+    }
+    return key.slice(0, 191) + "-" + hash.toString(16).padStart(8, "0");
+  }
+  return key;
+}
+
+/**
+ * The paragraph a worker's brief carries about its repo's graph: the exact
+ * `project` key for a configured repo, or an explicit "no graph" statement for
+ * an unconfigured one — never silence, because a worker that knows there is no
+ * graph stops looking for one.
  *
  * The leading newline and the three-space indent are load-bearing: the
  * placeholder sits immediately before the next numbered item in
- * `briefs/worker.md`, so an empty value leaves no blank line behind and a
- * non-empty one reads as a continuation of the item above it.
+ * `briefs/worker.md`, so the hint reads as a continuation of the item above it
+ * and never leaves a blank line behind.
  *
  * Every sentence here is defending against one specific failure. A worker that
- * passes its own cwd gets an empty answer and concludes there is no graph. A
- * worker that trusts the graph as current edits against a snapshot that predates
- * its own branch. Both end the same way — a confident diff in the wrong place —
- * so the wording says the quiet part out loud rather than describing the tool.
+ * derives the project name from its cwd gets an empty answer and concludes
+ * there is no graph. A worker that indexes its own throwaway worktree writes a
+ * dead index nobody reads — the 9.3 GB of stale worktree-keyed indexes this
+ * fleet pruned. A worker that trusts the graph as current edits against a
+ * snapshot that predates its own branch. All three end the same way — a
+ * confident diff in the wrong place — so the wording says the quiet part out
+ * loud rather than describing the tool.
  */
 export function graphHint(repo: RepoTarget): string {
   const path = repo.graphProject;
-  if (path === undefined) return "";
+  if (path === undefined) {
+    return (
+      "\n" +
+      "   **This repo has no code graph configured.** Do not go looking for one:\n" +
+      "   no index exists for it, so the graph tools answer empty whatever you\n" +
+      "   pass — and indexing your own worktree would build a dead index nobody\n" +
+      "   reads, not a shortcut. Grep is the tool for this run.\n"
+    );
+  }
 
   return (
     "\n" +
     "   **This repo has a code graph, and it was not built from your worktree.**\n" +
-    "   Call `list_projects` first, find the single entry whose `root_path` is\n" +
-    "   exactly\n" +
-    `   \`${path}\`\n` +
-    "   and pass that entry's `name` as the `project` argument to every graph\n" +
-    "   tool. Never pass a path, and never pass your own cwd: that clone is what\n" +
-    "   was indexed, your worktree has no index and never will, so a cwd-based\n" +
-    "   lookup answers nothing and you lose the run to grep.\n" +
+    "   Pass `project: \"" +
+    graphProjectKey(path) +
+    "\"` to every code-graph tool — the index the reindex timer\n" +
+    "   builds for root_path `" +
+    path +
+    "`, shown under that name by\n" +
+    "   `list_projects`. Never pass a path, and never pass your own cwd: that\n" +
+    "   clone is what was indexed, your worktree has no index and never will,\n" +
+    "   so a cwd-based lookup answers nothing and you lose the run to grep.\n" +
+    "   Never run `index_repository` yourself — the refresh that builds this\n" +
+    "   index is conductor's, and indexing your throwaway worktree writes a\n" +
+    "   dead index nobody reads.\n" +
     "\n" +
     "   Read what it tells you as a snapshot of that clone's default branch at\n" +
     "   the last reindex: it does not contain your edits, and it can be hours\n" +
@@ -160,20 +360,6 @@ export function graphHint(repo: RepoTarget): string {
   );
 }
 
-/** Where the generated refresh script lands: conductor state, not a unit
- *  directory, because it is ours to regenerate and needs no root to write. */
-export function reindexScriptPath(): string {
-  return join(stateDir(), `${REINDEX_UNIT}.sh`);
-}
-
-/** Both unit files, from the one stem `systemctl enable` will be given. */
-export function unitPaths(unitDir = SYSTEMD_UNIT_DIR): { service: string; timer: string } {
-  return {
-    service: join(unitDir, `${REINDEX_UNIT}.service`),
-    timer: join(unitDir, `${REINDEX_UNIT}.timer`),
-  };
-}
-
 /**
  * `git clone` for one repo's index-only clone.
  *
@@ -247,7 +433,7 @@ export function reindexScript(p: ProjectConfig): string {
  * its timer, and a service enabled on its own would run once at boot and never
  * again, which looks exactly like a working install.
  */
-export function reindexService(p: ProjectConfig, scriptPath = reindexScriptPath()): string {
+export function reindexService(p: ProjectConfig, scriptPath = reindexScriptPath(p)): string {
   const home = homedir();
   const user = userInfo().username;
   return [
@@ -315,7 +501,7 @@ export function reindexTimer(p: ProjectConfig): string {
     "Persistent=true",
     "RandomizedDelaySec=2m",
     "AccuracySec=1min",
-    `Unit=${REINDEX_UNIT}.service`,
+    `Unit=${reindexUnitName(p)}.service`,
     "",
     "[Install]",
     "WantedBy=timers.target",
@@ -334,11 +520,11 @@ export function reindexTimer(p: ProjectConfig): string {
  * So generation runs unprivileged as the fleet user, and only the copy into
  * the unit directory is elevated.
  */
-export function installCommands(unitDir = SYSTEMD_UNIT_DIR, from = stateDir()): string[] {
-  const { service, timer } = unitPaths(from);
+export function installCommands(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR, from = stateDir()): string[] {
+  const { service, timer } = unitPaths(p, from);
   return [
     `sudo install -m 0644 ${service} ${timer} ${unitDir}/`,
-    `sudo systemctl daemon-reload && sudo systemctl enable --now ${REINDEX_UNIT}.timer`,
+    `sudo systemctl daemon-reload && sudo systemctl enable --now ${reindexUnitName(p)}.timer`,
   ];
 }
 
@@ -347,9 +533,9 @@ function block(title: string, body: string): string[] {
 }
 
 /**
- * The whole plan as text, with nothing done. This is the default mode of
- * `graph-setup`, and it is a plan an operator can read, paste, or ignore —
- * including on a host where they are not root and `--write` would fail.
+ * The whole plan as text, with nothing done. This is the `--print` mode of
+ * `setup graph`, and it is a plan an operator can read, paste, or ignore —
+ * including on a host where they are not root and the install would fail.
  */
 export function formatGraphSetup(
   p: ProjectConfig,
@@ -434,25 +620,63 @@ export function formatGraphSetup(
     "",
   );
 
-  const script = reindexScriptPath();
-  const { service, timer } = unitPaths(stateDir());
+  const script = reindexScriptPath(p);
+  const { service, timer } = unitPaths(p, stateDir());
   lines.push(
     `   \`omp-conductor setup graph\` writes these three files for you, all under`,
-    `   ${stateDir()}. Run it as the account the fleet runs as — never under`,
-    "   sudo, which would resolve the config, the state directory and the unit's",
-    "   own User= as root and quietly build indexes no worker can read.",
+    `   ${stateDir()} — named for this project, so another project's files on the`,
+    "   same host are never touched. Run it as the account the fleet runs as —",
+    "   never under sudo, which would resolve the config, the state directory and",
+    "   the unit's own User= as root and quietly build indexes no worker can read.",
     "",
     ...block(script, reindexScript(p)),
     ...block(service, reindexService(p, script)),
     ...block(timer, reindexTimer(p)),
     `   then install them, which is the only step that needs root:`,
     "",
-    ...installCommands(unitDir).map((c) => `   ${c}`),
+    ...installCommands(p, unitDir).map((c) => `   ${c}`),
   );
 
+  // An artefact another project (or nothing of ours) already owns at this
+  // project's stem: the run would refuse rather than overwrite it, and the
+  // plan must say so before the operator answers a consent prompt they will
+  // not be asked (#720).
+  const conflict = stagingConflict(p, [script, service, timer]);
+  if (conflict !== undefined) {
+    lines.push(
+      "",
+      `   NOTE: ${conflict.path} already exists and was ${
+        conflict.owner === undefined ? "not generated by `setup graph`" : `generated for project "${conflict.owner}"`
+      } —`,
+      "   this run refuses to overwrite it. Delete the file and re-run.",
+    );
+  }
+
+  // A host that ran the pre-#720 project-less version keeps its old files:
+  // their timer refreshes whichever project generated it last, forever. The
+  // plan names the remediation because it is host action this command must
+  // not take for the operator.
+  const legacy = legacyReindexFiles();
+  if (legacy.length > 0) {
+    lines.push("", "   NOTE: " + legacyReindexNote(legacy).replace(/\n/g, "\n   "));
+  }
+
   return lines.join("\n");
 }
 
+/** One rendered artefact: where it lands and exactly what would be written. */
+export interface GraphSetupFile {
+  path: string;
+  content: string;
+}
+
+/** The plan's three artefacts. */
+export interface GraphSetupFiles {
+  script: GraphSetupFile;
+  service: GraphSetupFile;
+  timer: GraphSetupFile;
+}
+
 /** What staging wrote, and the root-only steps it deliberately left. */
 export interface GraphSetupWrite {
   written: string[];
@@ -460,26 +684,20 @@ export interface GraphSetupWrite {
 }
 
 /**
- * Writes the script and both units, and returns what to do next.
- *
- * Deliberately stops there. Running `systemctl` would need root the wizard and
- * the CLI may not have, and a package that enables system timers behind an
- * operator's back is one you cannot audit by reading its output.
+ * Everything `setup graph` would stage, rendered and nothing written: the
+ * three files' paths and bytes, plus the `next` text naming the root-only
+ * steps. The consent prompt prints this, and only the consent-gated step
+ * turns it into files — so the prompt's "stages on confirm" is true of the
+ * staged tree when it is printed, and a declined run leaves every staged
+ * file byte-identical (#720, mirroring #510's deferral for `setup host`).
  */
-export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupWrite {
-  const script = reindexScriptPath();
+export function planGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupFiles & { next: string } {
+  const script = { path: reindexScriptPath(p), content: reindexScript(p) };
   // All three land in the state directory, which this account owns — so the
   // whole command runs unprivileged and there is no sudo path that could
   // resolve HOME, the config or the unit's User= as the wrong account.
-  const { service, timer } = unitPaths(stateDir());
-
-  mkdirSync(dirname(script), { recursive: true });
-  writeFileSync(script, reindexScript(p));
-  // Executable so an operator can run the refresh by hand before trusting a
-  // timer with it; the unit calls bash explicitly either way.
-  chmodSync(script, 0o755);
-  writeFileSync(service, reindexService(p, script));
-  writeFileSync(timer, reindexTimer(p));
+  const service = { path: unitPaths(p, stateDir()).service, content: reindexService(p, script.path) };
+  const timer = { path: unitPaths(p, stateDir()).timer, content: reindexTimer(p) };
 
   const missing = graphRepos(p).filter((r) => !existsSync(r.graphProject));
   const next = [
@@ -488,11 +706,11 @@ export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): G
     "",
     "to install them, which is the only privileged step:",
     "",
-    ...installCommands(unitDir).map((c) => `  ${c}`),
+    ...installCommands(p, unitDir).map((c) => `  ${c}`),
     "",
     "then watch one real run before trusting the schedule (it takes minutes per repo):",
     "",
-    `  sudo systemctl start ${REINDEX_UNIT}.service && systemctl status ${REINDEX_UNIT}.service`,
+    `  sudo systemctl start ${reindexUnitName(p)}.service && systemctl status ${reindexUnitName(p)}.service`,
     ...(missing.length === 0
       ? []
       : [
@@ -504,5 +722,32 @@ export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): G
         ]),
   ].join("\n");
 
-  return { written: [script, service, timer], next };
+  return { script, service, timer, next };
+}
+
+/**
+ * Writes the script and both units, and returns what to do next.
+ *
+ * Deliberately stops there. Running `systemctl` would need root the wizard and
+ * the CLI may not have, and a package that enables system timers behind an
+ * operator's back is one you cannot audit by reading its output.
+ *
+ * Refuses an artefact that already exists and is not this project's own — a
+ * collision between two names that fold to one stem is refused rather than
+ * silently overwritten (#720).
+ */
+export function writeGraphSetup(p: ProjectConfig, unitDir = SYSTEMD_UNIT_DIR): GraphSetupWrite {
+  const plan = planGraphSetup(p, unitDir);
+  const conflict = stagingConflict(p, [plan.script.path, plan.service.path, plan.timer.path]);
+  if (conflict !== undefined) throw new Error(graphConflictMessage(conflict));
+
+  mkdirSync(dirname(plan.script.path), { recursive: true });
+  writeFileSync(plan.script.path, plan.script.content);
+  // Executable so an operator can run the refresh by hand before trusting a
+  // timer with it; the unit calls bash explicitly either way.
+  chmodSync(plan.script.path, 0o755);
+  writeFileSync(plan.service.path, plan.service.content);
+  writeFileSync(plan.timer.path, plan.timer.content);
+
+  return { written: [plan.script.path, plan.service.path, plan.timer.path], next: plan.next };
 }

package/src/lifecycle.ts

@@ -94,7 +94,7 @@ export interface DaemonRecord {
   logFile: string;
 }
 
-function recordPath(): string {
+export function recordPath(): string {
   return join(runtimeDir(), "daemon.json");
 }
 
@@ -340,24 +340,60 @@ export function acquireOnceLease(
   throw new Error("could not acquire the daemon lease — a stale holder kept reappearing");
 }
 
+/**
+ * Why a health probe came back negative. A timeout means the process is up
+ * but not answering (wedged or overloaded); a refusal means nothing is
+ * listening on the port at all. Everything else — a 500, a torn response —
+ * is `other`, a health answer rather than a probe verdict.
+ */
+export type HealthCheckFailure = "timeout" | "refused" | "other";
+
+export type HealthCheckResult =
+  | { ok: true; body?: string }
+  | { ok: false; failure: HealthCheckFailure; body?: string };
+
 /**
  * Probes the daemon's own health endpoint. Never throws: a refused connection,
  * a DNS-less host, a hung socket and a 500 are all just "not healthy", and the
- * callers of this are the ones responsible for saying so nicely.
+ * callers of this are the ones responsible for saying so nicely. The `failure`
+ * kind lets a caller tell "up but slow" (timeout) from "nothing listening"
+ * (refused) instead of collapsing both into `{ ok: false }` (#716).
  */
-export async function healthCheck(port: number): Promise<{ ok: boolean; body?: string }> {
+export async function healthCheck(port: number): Promise<HealthCheckResult> {
   try {
     const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
       signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
     });
     const body = (await res.text()).trim();
-    return { ok: res.ok, ...(body.length > 0 ? { body } : {}) };
-  } catch {
-    return { ok: false };
+    if (!res.ok) {
+      return { ok: false, failure: "other", ...(body.length > 0 ? { body } : {}) };
+    }
+    return { ok: true, ...(body.length > 0 ? { body } : {}) };
+  } catch (err) {
+    return { ok: false, failure: healthFailureKind(err) };
+  }
+}
+
+/**
+ * Classify a fetch rejection: the timeout signal raises `TimeoutError`; a
+ * refused connection is `ConnectionRefused` under Bun and `ECONNREFUSED`
+ * under undici. Anything else is an unclassified probe failure.
+ */
+function healthFailureKind(err: unknown): HealthCheckFailure {
+  if (err instanceof Error && err.name === "TimeoutError") return "timeout";
+  const code = (err as { code?: unknown } | null)?.code;
+  if (code === "ConnectionRefused" || code === "ECONNREFUSED" || code === "ECONNRESET") {
+    return "refused";
   }
+  return "other";
 }
 
-function healthServesProject(body: string | undefined, project: string | undefined): boolean {
+/** Whether a `/healthz` body names `project` as served: the daemon's health
+ *  endpoint lists every project it loaded, as bare strings or `{ project }`
+ *  entries, so callers can prove a runtime generation serves a project —
+ *  the setup rollback's prior-set proof and the restart's owned proof both
+ *  build on it (#650). An unparseable body is a served-nothing answer. */
+export function healthServesProject(body: string | undefined, project: string | undefined): boolean {
   if (project === undefined) return true;
   if (body === undefined) return false;
   try {