omp-conductor 0.15.6 → 0.15.8

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/escalate.ts

@@ -269,7 +269,7 @@ export function createEscalator(
           // the tick re-raises it. A *report* has no such source — it exists
           // once, in the model's head, and nothing regenerates it — which is
           // why that one needed a ledger and this one does not.
-          await sendTelegram(token, chatId, text, { topicId: p.escalation.telegramTopicId });
+          await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
           store.markNotified(key);
           return;
         }
@@ -350,6 +350,74 @@ export function readTelegramToken(): string | undefined {
   return undefined;
 }
 
+/**
+ * The forum topic a project's Telegram actually lives in *now*.
+ *
+ * `escalation.telegramTopicId` is pinned by the wizard from the topics
+ * omp-telegram had claimed at setup time — but the bridge re-claims a pane's
+ * topic across restarts, and conductor restarts that service itself during
+ * `upgrade` and `restart`. The pinned id therefore goes stale on the fleet's
+ * own maintenance, and every topic-addressed send silently degrades to the main
+ * chat: tier-2 pages, reports, digests, arm challenges, direct messages (#407).
+ *
+ * The operator's pin still wins whenever it is live. Only a pin that is
+ * *provably* absent from the current claims is replaced, and only by the claim
+ * whose name is this project's — so a deliberately separate alerts topic is
+ * never hijacked by the pane's own thread. Unreadable bridge state changes
+ * nothing, and #318's stale-topic retry remains the last line of defence.
+ *
+ * The substitution is logged, naming the project and the claim's name. Never an
+ * id: a log line is a place these leak from.
+ */
+export function resolveProjectTopicId(project: ProjectConfig): number | undefined {
+  const pinned = project.escalation.telegramTopicId;
+  if (pinned === undefined) return undefined;
+  const claims = claimedTelegramTopics();
+  if (claims.length === 0) return pinned;
+  if (claims.some((claim) => claim.threadId === pinned)) return pinned;
+  const named = claims.find((claim) => claim.name === project.name);
+  if (named === undefined) return pinned;
+  warn(
+    `escalation.telegramTopicId for ${project.name} is no longer a claimed topic; ` +
+      `following omp-telegram's current "${named.name}" claim instead`,
+  );
+  return named.threadId;
+}
+
+/**
+ * omp-telegram's live topic claims: `{ threads: { "<threadId>": { name } } }`.
+ * Borrowed exactly as the token is, and tolerant of every shape it might not
+ * be — a bridge that has never run a forum pane has no file at all.
+ *
+ * `stateDir` is passed by the setup wizard, which has already probed for the
+ * bridge; send-time callers let it resolve the same way the token does.
+ */
+export function claimedTelegramTopics(stateDir?: string): Array<{ threadId: number; name: string }> {
+  const override = stateDir?.trim() ?? process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(join(dir, "threads.json"), "utf8"));
+  } catch {
+    return [];
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) || !("threads" in raw)) return [];
+  const threads = raw.threads;
+  if (typeof threads !== "object" || threads === null || Array.isArray(threads)) return [];
+  const out: Array<{ threadId: number; name: string }> = [];
+  for (const [id, entry] of Object.entries(threads)) {
+    const threadId = Number(id);
+    if (!Number.isFinite(threadId) || !Number.isSafeInteger(threadId)) continue;
+    let name = id;
+    if (typeof entry === "object" && entry !== null && "name" in entry) {
+      const candidate = entry.name;
+      if (typeof candidate === "string" && candidate.trim() !== "") name = candidate.trim();
+    }
+    out.push({ threadId, name });
+  }
+  return out;
+}
+
 /**
  * The one Telegram send in this package. Exported so the report outbox (#123)
  * reuses it rather than forking it: the response handling below is load-bearing

package/src/fleet.ts

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { formatZonedMinute } from "./availability.ts";
 import { findProject, loadConfig, stateDir } from "./config.ts";
-import { sendTelegram } from "./escalate.ts";
+import { resolveProjectTopicId, sendTelegram } from "./escalate.ts";
 import { planUsageLine, readPlanUsage, sharedUsageSource } from "./usage.ts";
 import { readApprovalSurface, readDaemonProfile } from "./approval-surface.ts";
 import { inspectBriefLayout } from "./brief-upgrade.ts";
@@ -56,6 +56,7 @@ import {
   isAlive,
   livingDaemon,
   probeUnit,
+  runSystemctl,
   stopDaemon,
   type StopResult,
   type UnitOwnership,
@@ -348,12 +349,13 @@ export async function armTicks(projectName?: string, deps: ArmDeps = {}): Promis
     `Reply to this chat with exactly:\n${code}\n` +
     `Nothing will be dispatched until that reply is seen in the orchestrator session.`;
 
-  // Prefer the project's configured forum topic so arm challenges land where
-  // escalations already do (#318). Missing project config keeps flat-chat 0.13.
+  // Prefer the project's live forum topic so arm challenges land where
+  // escalations already do (#318), following the bridge's current claim when the
+  // pinned id has gone stale (#407). Missing project config keeps flat-chat 0.13.
   let topicId: number | undefined;
   if (named !== undefined) {
     try {
-      topicId = findProject(loadConfig(), named).escalation.telegramTopicId;
+      topicId = resolveProjectTopicId(findProject(loadConfig(), named));
     } catch {
       /* no project config */
     }
@@ -566,21 +568,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" };
@@ -2000,26 +1988,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;