omp-conductor 0.15.5 → 0.15.7

package/src/config.ts

@@ -45,6 +45,7 @@ import {
   type MergePreconditions,
   type PlanUsageCap,
   type ProjectConfig,
+  type RecoveryMergeAuthorization,
   type ProjectPolicy,
   type ReleasePreconditions,
   type ReleaseRequirement,
@@ -1044,9 +1045,33 @@ function finalizeProject(
   const escalation = finalizeEscalation(p["escalation"] as Raw | undefined);
   const authority = finalizeAuthority(p["authority"] as Raw | undefined);
   const releasePolicy = finalizeReleasePolicy(p["releasePolicy"], label, problems);
+  const strandedTagRepos =
+    releasePolicy["git-tag"] === "orchestrator" && releasePolicy["version-bump-pr"] !== "orchestrator"
+      ? Object.values(repos).filter((repo) => repo.release !== undefined)
+      : [];
+  if (strandedTagRepos.length > 0) {
+    problems.push(
+      `${label}: releasePolicy delegates git-tag, but ${strandedTagRepos
+        .map((repo) => `${repo.name}.release.versionFile`)
+        .join(", ")} requires a version-change PR and version-bump-pr is not delegated — ` +
+        `grant "version-bump-pr": "orchestrator" or keep git-tag with the human`,
+    );
+  }
   const policy = finalizePolicy(p["policy"], label, problems);
   const caps = reconcileCaps(p["caps"], `${label}: caps`, problems, legacyCaps);
   const reporting = finalizeReporting(p["reporting"], label, problems);
+  const recoveryMerges = (p["recoveryMerges"] as RecoveryMergeAuthorization[] | undefined)?.map(
+    (entry) => ({ ...entry }),
+  );
+  if (recoveryMerges !== undefined) {
+    const seen = new Set<string>();
+    for (const entry of recoveryMerges) {
+      if (seen.has(entry.prUrl)) {
+        problems.push(`${label}: recoveryMerges contains duplicate prUrl ${JSON.stringify(entry.prUrl)}`);
+      }
+      seen.add(entry.prUrl);
+    }
+  }
   const rawWorkerModel = p["workerModel"];
   const workerModel =
     typeof rawWorkerModel === "string" && rawWorkerModel.trim() !== "" ? rawWorkerModel : undefined;
@@ -1070,6 +1095,7 @@ function finalizeProject(
     authority,
     releasePolicy,
     policy,
+    ...(recoveryMerges === undefined ? {} : { recoveryMerges }),
     reporting,
     workspaceRoot: expandHome(pickString(p["workspaceRoot"], defaultWorkspaceRoot())),
     mirrorRoot: expandHome(pickString(p["mirrorRoot"], defaultMirrorRoot())),
@@ -1223,6 +1249,8 @@ function finalizeRepos(parsed: unknown, label: string, problems: string[]): Reco
     if (graph !== undefined) target.graphProject = graph;
     const migrations = finalizeMigrationsDir(value?.["migrations"], `${label}: routing.repos.${key}`, problems);
     if (migrations !== undefined) target.migrations = { dir: migrations };
+    const versionFile = finalizeVersionFile(value?.["release"], `${label}: routing.repos.${key}`, problems);
+    if (versionFile !== undefined) target.release = { versionFile };
     repos[key] = target;
   }
   return repos;
@@ -1262,6 +1290,21 @@ function finalizeMigrationsDir(parsed: unknown, label: string, problems: string[
   return dir;
 }
 
+function finalizeVersionFile(parsed: unknown, label: string, problems: string[]): string | undefined {
+  if (parsed === undefined) return undefined;
+  const raw = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Raw) : undefined;
+  const file = raw?.["versionFile"];
+  if (typeof file !== "string" || file.trim() === "") {
+    problems.push(`${label}.release.versionFile must be a non-empty string`);
+    return undefined;
+  }
+  if (file.startsWith("/") || file.split("/").includes("..")) {
+    problems.push(`${label}.release.versionFile must be a repo-relative file`);
+    return undefined;
+  }
+  return file;
+}
+
 function finalizeGraphProject(parsed: unknown, label: string, problems: string[]): string | undefined {
   if (parsed === undefined) return undefined;
   if (typeof parsed !== "string" || parsed.trim() === "") {

package/src/fleet.ts

@@ -55,8 +55,11 @@ import {
   healthCheck,
   isAlive,
   livingDaemon,
+  probeUnit,
+  runSystemctl,
   stopDaemon,
   type StopResult,
+  type UnitOwnership,
   SYSTEMD_UNIT,
 } from "./lifecycle.ts";
 import { formatRss, rssBytesFromHealthz } from "./host.ts";
@@ -99,7 +102,7 @@ export const ARM_CHALLENGE_TIMEOUT_MS = 300_000;
 const LEGACY_HERDR_SESSION = "fleet";
 
 export const LEGACY_HERDR_SESSION_HINT =
-  'herdr session "fleet" found — rename it to "conductor" or set HERDR_SESSION=fleet (remove this bridge next minor)';
+  'herdr session "fleet" found — rename it to "conductor" or run omp-conductor setup host to pin HERDR_SESSION=fleet (remove this bridge next minor)';
 
 let legacyHerdrSessionHintPrinted = false;
 
@@ -564,21 +567,7 @@ export interface HerdrStartDeps {
  * systemd or without that optional unit keep the standalone daemon behaviour.
  */
 export function startHerdrFleet(projectName?: string, deps: HerdrStartDeps = {}): HerdrStartResult {
-  const run: NonNullable<HerdrStartDeps["systemctl"]> =
-    deps.systemctl ??
-    ((args: string[]) => {
-      const res = spawnSync("systemctl", args, { encoding: "utf8", timeout: 15_000, env: process.env });
-      if (res.error) {
-        const err = res.error as NodeJS.ErrnoException;
-        return {
-          ok: false,
-          stdout: "",
-          stderr: err.message,
-          ...(err.code === "ENOENT" ? { missing: true } : {}),
-        };
-      }
-      return { ok: res.status === 0, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
-    });
+  const run = deps.systemctl ?? runSystemctl;
 
   const shown = run(["show", DEFAULT_HERDR_UNIT, "--property=LoadState", "--value"]);
   if (shown.missing) return { kind: "unmanaged", unit: DEFAULT_HERDR_UNIT, reason: "no systemctl" };
@@ -1270,10 +1259,132 @@ export function formatCodeGraphHealth(graph: CodeGraphHealth, now = Date.now()):
 }
 
 
+/**
+ * Project-scoped reading of a living daemon record + `/healthz` body.
+ *
+ * Board and `status` share this so a host running one daemon for several
+ * projects cannot be called healthy for a project it does not serve (#379).
+ * A third interpretation convention is forbidden.
+ */
+export type DaemonProjectHealth =
+  | { kind: "stopped" }
+  | { kind: "ok" }
+  | { kind: "unreachable" }
+  | { kind: "other-project"; serves?: string };
+
+/**
+ * Facts `formatFleetStatus` needs about the living daemon. Pure input — the
+ * caller probes; the formatter never shells out (#379).
+ */
+export type FleetDaemonProbe = {
+  project: DaemonProjectHealth;
+  /** `/healthz` body when the probe is project-ok (rss / overlays). */
+  body?: string;
+  /** systemd ownership of the living record pid; omit when unprobed. */
+  unit?: UnitOwnership;
+};
+
+/**
+ * Decide whether a living record + optional `/healthz` answer serve `project`.
+ *
+ * Mirrors the board gate: a record pinned to another project is never probed
+ * further; a multi-project payload is ok only when `project` appears in
+ * `projects[]` (or as the top-level single-project `project` field).
+ */
+export function classifyDaemonProjectHealth(
+  record: { project?: string } | undefined,
+  health: { ok: boolean; body?: string } | undefined,
+  project: string,
+): DaemonProjectHealth {
+  if (record === undefined) return { kind: "stopped" };
+  // Record project is authoritative when set — a single-project leftover from
+  // #376 must not be presented as this project's daemon just because its port
+  // still answers.
+  if (record.project !== undefined && record.project !== project) {
+    return { kind: "other-project", serves: record.project };
+  }
+  if (health?.ok !== true) return { kind: "unreachable" };
+  try {
+    const payload = JSON.parse(health.body ?? "null") as unknown;
+    if (payload === null || typeof payload !== "object") {
+      return { kind: "unreachable" };
+    }
+    if (Reflect.get(payload, "project") === project) return { kind: "ok" };
+    const projects = Reflect.get(payload, "projects");
+    if (
+      Array.isArray(projects) &&
+      projects.some(
+        (entry) =>
+          entry !== null &&
+          typeof entry === "object" &&
+          Reflect.get(entry, "project") === project,
+      )
+    ) {
+      return { kind: "ok" };
+    }
+    return { kind: "other-project", serves: servedProjectName(payload) };
+  } catch {
+    return { kind: "unreachable" };
+  }
+}
+
+/** Best-effort name of who a foreign `/healthz` payload is actually serving. */
+function servedProjectName(payload: object): string | undefined {
+  const top = Reflect.get(payload, "project");
+  if (typeof top === "string" && top.length > 0) return top;
+  const projects = Reflect.get(payload, "projects");
+  if (!Array.isArray(projects)) return undefined;
+  for (const entry of projects) {
+    if (entry === null || typeof entry !== "object") continue;
+    const name = Reflect.get(entry, "project");
+    if (typeof name === "string" && name.length > 0) return name;
+  }
+  return undefined;
+}
+
+function formatDaemonHealthz(probe: FleetDaemonProbe | undefined): string {
+  if (probe === undefined) return "unprobed";
+  switch (probe.project.kind) {
+    case "stopped":
+      return "stopped";
+    case "ok":
+      return "ok";
+    case "unreachable":
+      return "unreachable — the process is up but not serving";
+    case "other-project":
+      return probe.project.serves === undefined
+        ? "other-project"
+        : `other-project — serves ${probe.project.serves}`;
+  }
+}
+
+/**
+ * Unit line for a living record. The bare unit name alone used to imply
+ * systemd ownership that was never checked (#379); every branch states the
+ * probe result, and `unknown` is never rendered as owned.
+ */
+function formatDaemonUnit(unit: UnitOwnership | undefined, recordPid: number): string {
+  if (unit === undefined) return `  unit      ${SYSTEMD_UNIT}  unprobed`;
+  switch (unit.kind) {
+    case "active":
+      if (unit.pid === recordPid) {
+        return `  unit      ${SYSTEMD_UNIT}  systemd-owned`;
+      }
+      // Live unit, different MainPID — the record pid is not systemd's.
+      return `  unit      ${SYSTEMD_UNIT}  unmanaged — MainPID ${unit.pid}`;
+    case "failed":
+      return `  unit      ${SYSTEMD_UNIT}  unmanaged — unit failed`;
+    case "inactive":
+      return `  unit      ${SYSTEMD_UNIT}  inactive`;
+    case "unknown":
+      return `  unit      ${SYSTEMD_UNIT}  unknown — ${unit.reason}`;
+  }
+}
+
 export function formatFleetStatus(
   s: StatusSnapshot,
   layers: FleetLayers,
-  daemonHealth?: { ok: boolean; body?: string },
+  daemon: FleetDaemonProbe | undefined = undefined,
   telegram: TelegramHealth = { kind: "unprobed" },
   now = Date.now(),
   codeGraph: CodeGraphHealth = { configured: false },
@@ -1315,20 +1426,17 @@ export function formatFleetStatus(
   if (!layers.daemon.running || layers.daemon.pid === undefined) {
     daemonBlock = "daemon    not running";
   } else {
-    const hz =
-      daemonHealth === undefined
-        ? "unprobed"
-        : daemonHealth.ok
-          ? "ok"
-          : "unreachable — the process is up but not serving";
-    const rss = rssBytesFromHealthz(daemonHealth?.body);
+    // Only trust rss from a project-ok body — a foreign payload's bytes are
+    // not this project's daemon facts (#379).
+    const rss =
+      daemon?.project.kind === "ok" ? rssBytesFromHealthz(daemon.body) : undefined;
     daemonBlock = [
       "daemon",
       `  pid       ${layers.daemon.pid}`,
       `  port      ${layers.daemon.port ?? "?"}`,
       ...(rss === undefined ? [] : [`  rss       ${formatRss(rss)}`]),
-      `  healthz   ${hz}`,
-      `  unit      ${SYSTEMD_UNIT}`,
+      `  healthz   ${formatDaemonHealthz(daemon)}`,
+      formatDaemonUnit(daemon?.unit, layers.daemon.pid),
     ].join("\n");
   }
 
@@ -1504,8 +1612,11 @@ export async function renderStatus(projectName?: string): Promise<string> {
   const layers = fleetLayers(projectName);
   const project = findProject(loadConfig(), projectName);
   const rec = livingDaemon();
-  const [health, telegram, planUsage, github] = await Promise.all([
-    rec === undefined ? undefined : healthCheck(rec.port),
+  // Gate the port probe on record membership first — a leftover single-project
+  // daemon from #376 must not be health-checked as if it served us (#379).
+  const wrongRecord = rec?.project !== undefined && rec.project !== project.name;
+  const [rawHealth, telegram, planUsage, github] = await Promise.all([
+    rec === undefined || wrongRecord ? undefined : healthCheck(rec.port),
     probeTelegramHealth(projectName),
     // Read here rather than in `statusSnapshot`, which is synchronous and used
     // by callers that must not shell out. An unmetered project never spawns
@@ -1516,13 +1627,27 @@ export async function renderStatus(projectName?: string): Promise<string> {
     // broken report (#188).
     fetchRateLimit(),
   ]);
-  const cached = codeGraphFromHealthz(health?.body, project.name);
+  const projectHealth = classifyDaemonProjectHealth(rec, rawHealth, project.name);
+  // Ownership is probed, never assumed from the unit name constant (#379).
+  const unit = rec === undefined ? undefined : probeUnit();
+  const daemon: FleetDaemonProbe | undefined =
+    rec === undefined
+      ? undefined
+      : {
+          project: projectHealth,
+          ...(projectHealth.kind === "ok" && rawHealth?.body !== undefined
+            ? { body: rawHealth.body }
+            : {}),
+          ...(unit === undefined ? {} : { unit }),
+        };
+  const healthBody = projectHealth.kind === "ok" ? rawHealth?.body : undefined;
+  const cached = codeGraphFromHealthz(healthBody, project.name);
   const codeGraph = cached ?? (await probeCodeGraph(project));
-  const workerPhases = workerPhasesFromHealthz(health?.body, project.name);
+  const workerPhases = workerPhasesFromHealthz(healthBody, project.name);
   return formatFleetStatus(
     { ...s, planUsage, github },
     layers,
-    health,
+    daemon,
     telegram,
     Date.now(),
     codeGraph,
@@ -1862,26 +1987,18 @@ export async function transcriptHasUserCode(path: string, code: string): Promise
 // ---------------------------------------------------------------------------
 
 function probeHerdrUnit(unit = DEFAULT_HERDR_UNIT): { kind: HerdrLayer; detail?: string } {
-  try {
-    const res = spawnSync("systemctl", ["is-active", unit], {
-      encoding: "utf8",
-      timeout: 5_000,
-      env: process.env,
-    });
-    if (res.error) {
-      const err = res.error as NodeJS.ErrnoException;
-      if (err.code === "ENOENT") return { kind: "unknown", detail: "no systemctl" };
-      return { kind: "unknown", detail: err.message };
-    }
-    const out = (res.stdout ?? "").trim();
-    if (out === "active") return { kind: "active", detail: unit };
-    if (out === "inactive" || out === "failed" || out === "dead") {
-      return { kind: "inactive", detail: `${unit} ${out}` };
-    }
-    return { kind: "unknown", detail: `${unit} ${out || `exit ${String(res.status)}`}` };
-  } catch (err) {
-    return { kind: "unknown", detail: err instanceof Error ? err.message : String(err) };
-  }
+  const res = runSystemctl(["is-active", unit]);
+  if (res.missing) return { kind: "unknown", detail: "no systemctl" };
+  const out = res.stdout.trim();
+  if (out === "active") return { kind: "active", detail: unit };
+  if (out === "inactive" || out === "failed" || out === "dead") {
+    return { kind: "inactive", detail: `${unit} ${out}` };
+  }
+  const error = res.stderr.trim();
+  return {
+    kind: "unknown",
+    detail: `${unit} ${out || error || "systemctl is-active failed"}`,
+  };
 }
 
 export function paneLayerFromAgents(

package/src/lifecycle.ts

@@ -195,18 +195,34 @@ export async function healthCheck(port: number): Promise<{ ok: boolean; body?: s
   }
 }
 
+function healthServesProject(body: string | undefined, project: string | undefined): boolean {
+  if (project === undefined) return true;
+  if (body === undefined) return false;
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    if (parsed === null || typeof parsed !== "object") return false;
+    const projects = Reflect.get(parsed, "projects");
+    if (!Array.isArray(projects)) return false;
+    return projects.some((entry) => {
+      if (typeof entry === "string") return entry === project;
+      return entry !== null && typeof entry === "object" && Reflect.get(entry, "project") === project;
+    });
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Starts the daemon in the background and does not return until it answers
- * `/healthz`.
+ * Starts the daemon and does not return until it answers `/healthz`.
  *
- * Spawning is not starting. A daemon whose config is broken, whose port is
- * taken or whose database is locked exits within a second of being spawned,
- * and a `start` that printed "started" for it hands the operator a lie they
- * only discover when work silently fails to be picked up. So: spawn, watch
- * both the pid and the endpoint, and fail loudly with the log if either says
- * no.
+ * An installed unit owns the host-wide daemon lifecycle. `start --project X`
+ * may select the project whose health is proved, but it must not turn the unit
+ * into a detached single-project competitor (#400). Only a host proven not to
+ * have the unit keeps the standalone spawn path.
  */
-export async function startDaemon(o: { port?: number; project?: string } = {}): Promise<DaemonRecord> {
+export async function startDaemon(
+  o: { port?: number; project?: string; timeoutMs?: number } = {},
+): Promise<DaemonRecord> {
   const running = livingDaemon();
   if (running !== undefined) {
     throw new Error(
@@ -215,6 +231,28 @@ export async function startDaemon(o: { port?: number; project?: string } = {}):
     );
   }
 
+  const installation = probeUnitInstallation();
+  if (installation.kind === "unknown") {
+    throw new Error(
+      `cannot determine whether ${SYSTEMD_UNIT} is installed (${installation.reason}); ` +
+        "refusing to launch a detached daemon that could compete with the service manager",
+    );
+  }
+  if (installation.kind === "installed") {
+    const ownership = probeUnit();
+    if (ownership.kind === "unknown") {
+      throw new Error(ownershipUnknown("start", ownership.reason));
+    }
+    if (ownership.kind === "failed") {
+      return await restoreFailedUnit(o.timeoutMs, o.project);
+    }
+    const started = systemctl(["start", SYSTEMD_UNIT]);
+    if (!started.ok) {
+      throw new Error(systemctlFailure("start", started));
+    }
+    return await waitForOwnedDaemon("start", o.timeoutMs, o.project);
+  }
+
   const port = o.port ?? DEFAULT_PORT;
   const logFile = join(ensureRuntimeDir(), "daemon.log");
 
@@ -260,7 +298,7 @@ export async function startDaemon(o: { port?: number; project?: string } = {}):
   // rather than nothing at all.
   writeRecord(record);
 
-  const deadline = Date.now() + READY_TIMEOUT_MS;
+  const deadline = Date.now() + (o.timeoutMs ?? READY_TIMEOUT_MS);
   for (;;) {
     // Liveness first. If the child is gone, a healthy answer on that port came
     // from somebody else's server, and reporting it as ours would be worse
@@ -270,7 +308,7 @@ export async function startDaemon(o: { port?: number; project?: string } = {}):
       throw new Error(`daemon exited during startup${tailLog(logFile)}`);
     }
     const health = await healthCheck(port);
-    if (health.ok) return record;
+    if (health.ok && healthServesProject(health.body, o.project)) return record;
     if (Date.now() >= deadline) break;
     await sleep(READY_POLL_MS);
   }
@@ -280,7 +318,7 @@ export async function startDaemon(o: { port?: number; project?: string } = {}):
   await terminate(pid, STOP_TIMEOUT_MS);
   clearRecord();
   throw new Error(
-    `daemon did not answer http://127.0.0.1:${port}/healthz within ${Math.round(READY_TIMEOUT_MS / 1000)}s${tailLog(logFile)}`,
+    `daemon did not answer http://127.0.0.1:${port}/healthz for the requested project within ${Math.round((o.timeoutMs ?? READY_TIMEOUT_MS) / 1000)}s${tailLog(logFile)}`,
   );
 }
 
@@ -395,7 +433,7 @@ export async function restartDaemon(
     // startDaemon() — that leaves the unit failed while handing the operator
     // a healthy-looking but unmanaged pid (the 12:17Z incident in #376).
     // Any manager refusal is terminal; so is unproven ownership afterwards.
-    const record = await restoreFailedUnit(o.timeoutMs);
+    const record = await restoreFailedUnit(o.timeoutMs, o.project);
     return { previous, record, via: "systemctl" };
   }
 
@@ -413,7 +451,7 @@ export async function restartDaemon(
     // systemctl restart returns once the new MainPID is up; the pidfile is
     // written by the daemon itself on boot, so wait for that rather than
     // inventing a record from the unit alone.
-    const record = await waitForOwnedDaemon("restart", o.timeoutMs);
+    const record = await waitForOwnedDaemon("restart", o.timeoutMs, o.project);
     return { previous, record, via: "systemctl" };
   }
 
@@ -430,7 +468,7 @@ export async function restartDaemon(
  * (see {@link waitForOwnedDaemon}). Refusal or unproven ownership is terminal
  * — never a fallthrough to the detached CLI daemon.
  */
-async function restoreFailedUnit(timeoutMs?: number): Promise<DaemonRecord> {
+async function restoreFailedUnit(timeoutMs?: number, project?: string): Promise<DaemonRecord> {
   const reset = systemctl(["reset-failed", SYSTEMD_UNIT]);
   if (!reset.ok) {
     throw new Error(systemctlFailure("reset-failed", reset));
@@ -439,7 +477,7 @@ async function restoreFailedUnit(timeoutMs?: number): Promise<DaemonRecord> {
   if (!started.ok) {
     throw new Error(systemctlFailure("start", started));
   }
-  return await waitForOwnedDaemon("start", timeoutMs);
+  return await waitForOwnedDaemon("start", timeoutMs, project);
 }
 
 /**
@@ -450,7 +488,11 @@ async function restoreFailedUnit(timeoutMs?: number): Promise<DaemonRecord> {
  * cannot un-fail it. Any other unproven state fails at the deadline with a
  * diagnostic that names the mismatch, never a bare "not ready".
  */
-async function waitForOwnedDaemon(verb: "restart" | "start", timeoutMs?: number): Promise<DaemonRecord> {
+async function waitForOwnedDaemon(
+  verb: "restart" | "start",
+  timeoutMs?: number,
+  project?: string,
+): Promise<DaemonRecord> {
   const via = `systemctl ${verb} ${SYSTEMD_UNIT} returned`;
   const inspect = `systemctl status ${SYSTEMD_UNIT}`;
   const deadline = Date.now() + (timeoutMs ?? READY_TIMEOUT_MS);
@@ -459,7 +501,7 @@ async function waitForOwnedDaemon(verb: "restart" | "start", timeoutMs?: number)
     const ownership = probeUnit();
     if (rec !== undefined && ownership.kind === "active" && ownership.pid === rec.pid) {
       const health = await healthCheck(rec.port);
-      if (health.ok) return rec;
+      if (health.ok && healthServesProject(health.body, project)) return rec;
     } else if (ownership.kind === "failed") {
       // A confirmed negative: the start did not take and the unit is failed
       // again. Waiting longer cannot un-fail it.
@@ -482,9 +524,10 @@ async function waitForOwnedDaemon(verb: "restart" | "start", timeoutMs?: number)
   }
   if (ownership.kind === "active") {
     if (ownership.pid === rec.pid) {
+      const projectDetail = project === undefined ? "" : ` for project ${project}`;
       throw new Error(
-        `${via}, but the daemon never answered /healthz on :${rec.port} — ` +
-          `the service manager owns pid ${rec.pid}, but it is not serving; ` +
+        `${via}, but the daemon never answered /healthz${projectDetail} on :${rec.port} — ` +
+          `the service manager owns pid ${rec.pid}, but it is not serving the requested project; ` +
           `check \`${inspect}\` and ${rec.logFile}`,
       );
     }
@@ -579,6 +622,31 @@ export function probeUnit(unit = SYSTEMD_UNIT): UnitOwnership {
   return { kind: "inactive" };
 }
 
+type UnitInstallation =
+  | { kind: "installed" }
+  | { kind: "absent" }
+  | { kind: "unknown"; reason: string };
+
+/**
+ * Installation is separate from ownership: an inactive installed unit and an
+ * absent unit both have MainPID 0, but only the latter permits a detached
+ * fallback.
+ */
+function probeUnitInstallation(unit = SYSTEMD_UNIT): UnitInstallation {
+  const ran = systemctl(["show", unit, "--property=LoadState", "--value"]);
+  if (!ran.ok) {
+    if (ran.missing) return { kind: "absent" };
+    const detail = (ran.stderr.trim() || ran.stdout.trim() || "systemctl show failed").split("\n")[0]!;
+    return { kind: "unknown", reason: detail };
+  }
+  const loadState = ran.stdout.trim();
+  if (loadState === "not-found") return { kind: "absent" };
+  if (loadState.length === 0) return { kind: "unknown", reason: "systemctl returned no LoadState" };
+  // loaded, masked, error and bad-setting all prove a manager-known unit. Let
+  // `systemctl start` provide the actionable refusal for a broken definition.
+  return { kind: "installed" };
+}
+
 /**
  * The MainPID of an *active* {@link SYSTEMD_UNIT}, or `undefined` when the
  * unit is confirmed inactive, failed, or absent, or when ownership could not
@@ -662,7 +730,14 @@ function systemctlFailure(
   );
 }
 
-function ownershipUnknown(verb: "stop" | "restart", reason: string): string {
+function ownershipUnknown(verb: "start" | "stop" | "restart", reason: string): string {
+  if (verb === "start") {
+    return (
+      `cannot determine whether ${SYSTEMD_UNIT} owns the daemon (${reason}) — ` +
+      `refusing to start a detached competitor while ownership is unknown; ` +
+      `retry when systemctl answers, or run \`systemctl start ${SYSTEMD_UNIT}\` yourself`
+    );
+  }
   return (
     `cannot determine whether ${SYSTEMD_UNIT} owns the daemon (${reason}) — ` +
     `refusing to ${verb} via signal while ownership is unknown ` +
@@ -689,7 +764,69 @@ export type SystemctlResult = {
 
 export type SystemctlFn = (args: string[]) => SystemctlResult;
 
+interface TestSystemctlState {
+  installed?: boolean;
+  mainPid?: number;
+  activeState?: string;
+  calls?: string[][];
+  failures?: Record<string, string>;
+}
+
+/**
+ * Child-process CLI tests cannot inject {@link setSystemctlForTest}. Under
+ * NODE_ENV=test they therefore get a file-backed fake manager, or a refusal
+ * when no fixture was supplied. The real binary is never reached from a test
+ * process (#399).
+ */
+function testSystemctl(args: string[]): SystemctlResult {
+  const path = process.env["OMP_CONDUCTOR_TEST_SYSTEMCTL_STATE"];
+  if (path === undefined) {
+    return {
+      ok: false,
+      stdout: "",
+      stderr: "real systemctl is disabled under NODE_ENV=test; no fake manager state was supplied",
+    };
+  }
+  try {
+    const state = JSON.parse(readFileSync(path, "utf8")) as TestSystemctlState;
+    const calls = Array.isArray(state.calls) ? state.calls : [];
+    calls.push(args);
+    state.calls = calls;
+    const verb = args[0] ?? "";
+    const failure = state.failures?.[verb];
+    if (failure !== undefined) {
+      writeFileSync(path, JSON.stringify(state));
+      return { ok: false, stdout: "", stderr: failure };
+    }
+    let stdout = "";
+    if (verb === "show") {
+      stdout = args.includes("--property=LoadState")
+        ? `${state.installed === false ? "not-found" : "loaded"}\n`
+        : `${state.mainPid ?? 0}\n${state.activeState ?? "inactive"}\n`;
+    } else if (verb === "is-active") {
+      const activeState = state.activeState ?? "inactive";
+      stdout = `${activeState}\n`;
+      writeFileSync(path, JSON.stringify(state));
+      return { ok: activeState === "active", stdout, stderr: "" };
+    } else if (verb === "stop") {
+      state.mainPid = 0;
+      state.activeState = "inactive";
+    } else if (verb === "reset-failed") {
+      state.activeState = "inactive";
+    }
+    writeFileSync(path, JSON.stringify(state));
+    return { ok: true, stdout, stderr: "" };
+  } catch (err) {
+    return {
+      ok: false,
+      stdout: "",
+      stderr: `fake systemctl state failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
 function defaultSystemctl(args: string[]): SystemctlResult {
+  if (process.env["NODE_ENV"] === "test") return testSystemctl(args);
   try {
     const res = spawnSync("systemctl", args, {
       encoding: "utf8",
@@ -719,6 +856,12 @@ function defaultSystemctl(args: string[]): SystemctlResult {
 
 let systemctl: SystemctlFn = defaultSystemctl;
 
+/** Shared manager runner. Production reaches the hardcoded binary; test
+ * processes reach only the explicit fake or the fail-closed refusal. */
+export function runSystemctl(args: string[]): SystemctlResult {
+  return systemctl(args);
+}
+
 /** Test-only: replace the `systemctl` runner. Pass `undefined` to restore. */
 export function setSystemctlForTest(fn: SystemctlFn | undefined): void {
   systemctl = fn ?? defaultSystemctl;