omp-conductor 0.17.1 → 0.18.1

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
@@ -28,7 +29,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 import { expandHome, stateDir } from "./config.ts";
-import type { ProjectConfig, RepoTarget } from "./types.ts";
+import type { GraphToolsObservation, ProjectConfig, RepoTarget } from "./types.ts";
 
 /**
  * The indexer's own CLI, invoked by name rather than by path so the generated
@@ -37,12 +38,200 @@ 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 MCP server name the graph tools arrive under in a session's registry,
+ * in the spellings the harness prefixes tools with (#726). `graphToolsPresent`
+ * matches against these, so the runtime observation and `resolvePrereqs`'s
+ * config check share one identity and cannot drift apart. The underscore form
+ * is the harness's normalised spelling for a server name; the verbatim form
+ * covers servers that keep their hyphens.
+ */
+export const GRAPH_MCP_SERVER_NAMES: readonly string[] = [INDEXER, INDEXER.replace(/-/g, "_")];
+
+/**
+ * Whether the code-graph tools are in a live session's registry (#726).
+ *
+ * Takes the session's own enabled tool names and matches the harness's MCP
+ * mounting convention (`mcp__<server>_<tool>`). This is the runtime
+ * observation: unlike {@link resolvePrereqs}'s `mounted` (which reads
+ * `mcp.json` and can only say what a session should mount), it answers what
+ * the session actually had, so "the model ignored a tool it had" and "the
+ * tool was missing" stop looking identical from outside the session.
+ */
+export function graphToolsPresent(toolNames: readonly string[]): boolean {
+  return toolNames.some(
+    (name) =>
+      name.startsWith("mcp__") &&
+      GRAPH_MCP_SERVER_NAMES.some((server) => name.startsWith(`mcp__${server}_`)),
+  );
+}
+
+/**
+ * Poll a session's registry for the code-graph observation (#726).
+ *
+ * Measured against the real harness rather than assumed: MCP wiring finalises
+ * after `createAgentSession` resolves (a deferred discovery pass), so the
+ * registry read can throw in the window right after session creation, and the
+ * graph tools surface under the *enabled* names — the active names stop at
+ * the core tools. This therefore polls the enabled surface until the read
+ * stops throwing, bounded by `deadlineMs`; a surface that never becomes
+ * readable (or a build that does not expose one — `getEnabledToolNames` is
+ * `undefined`) records *no* observation — never "graph tools absent", which
+ * is the `present: false` truth value of a surface that was read.
+ *
+ * @param getEnabledToolNames the session's `getEnabledToolNames` read, already
+ *   bound to its session (the SDK method dereferences private state), or
+ *   `undefined` when the harness surface is absent
+ */
+export async function observeGraphTools(
+  getEnabledToolNames: (() => string[]) | undefined,
+  options: { intervalMs?: number; deadlineMs?: number } = {},
+): Promise<GraphToolsObservation | undefined> {
+  if (getEnabledToolNames === undefined) return undefined;
+  const intervalMs = options.intervalMs ?? 250;
+  const deadlineMs = options.deadlineMs ?? 15_000;
+  const start = Date.now();
+  for (;;) {
+    try {
+      return { present: graphToolsPresent(getEnabledToolNames()), at: Date.now() };
+    } catch {
+      if (Date.now() - start >= deadlineMs) return undefined;
+      const { promise, resolve } = Promise.withResolvers<void>();
+      setTimeout(resolve, intervalMs);
+      await promise;
+    }
+  }
+}
+
+/** 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 +311,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 +425,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 +498,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 +566,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 +585,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 +598,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 +685,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 +749,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 +771,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 +787,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/harness-loader.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import {
+  OMP_HARNESS_PACKAGE,
+  OMP_NATIVES_PACKAGE,
+  packageNodeModulesRoot,
+} from "./host.ts";
+
+export interface HarnessAttestation {
+  path: string;
+  version: string;
+  nativePath: string;
+}
+
+/** Resolve the installed peer from this package's directory, never Bun's ambient cache. */
+export function resolveHarnessEntry(moduleDir: string = import.meta.dir): string {
+  return Bun.resolveSync(OMP_HARNESS_PACKAGE, moduleDir);
+}
+
+/** The installed peer version belonging to a resolved harness entry. */
+export function harnessVersion(entry: string): string | undefined {
+  const root = packageNodeModulesRoot(entry);
+  if (root === undefined) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(
+      readFileSync(join(root, OMP_HARNESS_PACKAGE, "package.json"), "utf8"),
+    );
+    if (parsed === null || typeof parsed !== "object") return undefined;
+    const version = Reflect.get(parsed, "version");
+    return typeof version === "string" && version !== "" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Exercise the worker's real import contract: explicitly anchored peer and
+ * native-addon resolution, with the caller responsible for passing
+ * `--no-install` so neither import can fall through to Bun's package cache.
+ */
+export async function probeHarness(moduleDir: string = import.meta.dir): Promise<HarnessAttestation> {
+  const path = resolveHarnessEntry(moduleDir);
+  await import(path);
+  const version = harnessVersion(path);
+  if (version === undefined) throw new Error(`cannot read the harness version for ${path}`);
+  const nativePath = Bun.resolveSync(OMP_NATIVES_PACKAGE, dirname(path));
+  await import(nativePath);
+  return { path, version, nativePath };
+}
+
+if (import.meta.main) {
+  try {
+    process.stdout.write(`${JSON.stringify(await probeHarness())}\n`);
+  } catch (cause) {
+    process.stderr.write(`${cause instanceof Error ? cause.stack ?? cause.message : String(cause)}\n`);
+    process.exitCode = 1;
+  }
+}