@celilo/cli 0.18.0 → 0.20.0

package/src/services/bus-interview.ts

@@ -7,13 +7,16 @@
  *
  * No timeouts: the deploy waits indefinitely for a responder. If
  * nothing answers, the operator sees the unanswered query via
- * `celilo events list-pending` and fixes the responder setup.
+ * `celilo events list-unanswered` and answers it with `celilo events
+ * reply <id> <value>`. (NOT `events list-pending` — that reads the
+ * subscriber `deliveries` table and cannot see an unanswered query.)
  *
  * See `infra/openspec/changes/interactive-deploys-via-event-bus/proposal.md`.
  */
 
 import { type Bus, defineEvents, openBus } from '@celilo/event-bus';
 import { getEventBusPath } from '../config/paths';
+import { InterviewAbandonedError } from './interview-errors';
 import { ensureResponderForInterview } from './responder-probe';
 
 const NO_SCHEMAS = defineEvents({});
@@ -239,6 +242,16 @@ export interface InterviewRequiredPayload {
  */
 export interface InterviewReply {
   value: unknown;
+  /**
+   * Set instead of `value` when the question was reaped rather than decided —
+   * a parked session passed its TTL with nobody answering. `askInterview` turns
+   * it into an `InterviewAbandonedError`, which is distinct from both a decline
+   * (someone said no) and an unanswered question (still standing).
+   *
+   * A responder that merely *cannot* decide emits nothing at all: the query
+   * stays unanswered and the asking command stays parked (celilo#609).
+   */
+  abandoned?: { reason: string };
 }
 
 /**
@@ -314,11 +327,9 @@ export async function askInterview(
   payload: InterviewRequiredPayload,
   ownerBus?: Bus,
 ): Promise<unknown> {
-  const reply = await busInterviewGuarded<InterviewReply>(
-    EVENT_TYPES.interviewRequired(payload.scope, payload.key),
-    payload,
-    ownerBus,
-  );
+  const type = EVENT_TYPES.interviewRequired(payload.scope, payload.key);
+  const reply = await busInterviewGuarded<InterviewReply>(type, payload, ownerBus);
+  if (reply.abandoned) throw new InterviewAbandonedError(type, reply.abandoned.reason);
   return reply.value;
 }
 

package/src/services/events-daemon.test.ts

@@ -5,11 +5,17 @@ import { join } from 'node:path';
 import {
   getDaemonUnitPath,
   installDaemon,
+  orphanDispatcherPids,
+  planDaemonInstall,
   readInstalledUnit,
   renderLaunchdPlist,
   renderSystemdUnit,
+  resolveRestartScope,
   resolveRunAsUser,
+  restartDaemon,
+  supervisorCommands,
   uninstallDaemon,
+  unitInstalledInAnyScope,
 } from './events-daemon';
 
 describe('renderSystemdUnit', () => {
@@ -166,6 +172,61 @@ describe('installDaemon / uninstallDaemon roundtrip', () => {
     expect(existsSync(installed.unitPath)).toBe(false);
   });
 
+  // #610 — install-daemon defaults to USER scope, so running it on a box whose
+  // system unit Ansible already installed silently produced a second daemon of
+  // the same name. That is how celilo-mgr ended up with two dispatchers.
+  it('refuses to install when the other scope already has a unit', () => {
+    const home = join(dir, 'home');
+    const systemRoot = join(dir, 'root');
+    installDaemon({
+      platform: 'linux',
+      scope: 'system',
+      home,
+      systemRoot,
+      celiloPath,
+      busDbPath: '/var/lib/celilo/events.db',
+    });
+
+    expect(() =>
+      installDaemon({
+        platform: 'linux',
+        scope: 'user',
+        home,
+        systemRoot,
+        celiloPath,
+        busDbPath: '/var/lib/celilo/events.db',
+      }),
+    ).toThrow(/system-scope unit is already installed/);
+    // Nothing written: refusing must not leave the second unit behind.
+    expect(existsSync(getDaemonUnitPath('linux', home, 'user'))).toBe(false);
+  });
+
+  // --print creates nothing, and the celilo-mgmt Ansible role captures it —
+  // throwing there would wedge the deploy of the tool used to fix the conflict.
+  it('reports the conflict from planDaemonInstall without throwing', () => {
+    const home = join(dir, 'home');
+    const systemRoot = join(dir, 'root');
+    installDaemon({
+      platform: 'linux',
+      scope: 'system',
+      home,
+      systemRoot,
+      celiloPath,
+      busDbPath: '/var/lib/celilo/events.db',
+    });
+
+    const plan = planDaemonInstall({
+      platform: 'linux',
+      scope: 'user',
+      home,
+      systemRoot,
+      celiloPath,
+      busDbPath: '/var/lib/celilo/events.db',
+    });
+    expect(plan.conflict?.scope).toBe('system');
+    expect(plan.unitContent).toContain('ExecStart=');
+  });
+
   it('writes a launchd plist and uninstall removes it', () => {
     const home = join(dir, 'home');
     const installed = installDaemon({
@@ -241,3 +302,186 @@ describe('installDaemon / uninstallDaemon roundtrip', () => {
     ).toThrow(/does not exist/);
   });
 });
+
+// --- restart (celilo#604) ---------------------------------------------
+
+/**
+ * A fake bus + supervisor. `restartUnit()` only produces a new dispatcher if no
+ * live one is left — that IS the one-dispatcher-per-bus guard (#584), and it's
+ * what makes the orphan case fatal rather than merely untidy.
+ */
+function fakeFleet(opts: {
+  initial: Array<{ pid: number; version: string | null; supervised?: boolean }>;
+  newVersion: string;
+}) {
+  let live = opts.initial.map((d) => ({ ...d }));
+  const supervised = opts.initial.find((d) => d.supervised);
+  const killed: number[] = [];
+  let nextPid = 9000;
+  let restarts = 0;
+  return {
+    killed,
+    restarts: () => restarts,
+    deps: {
+      liveDispatchers: () => live.map((d) => ({ pid: d.pid, version: d.version })),
+      supervisorPid: () => supervised?.pid ?? null,
+      kill: (pid: number) => {
+        killed.push(pid);
+        live = live.filter((d) => d.pid !== pid);
+      },
+      restartUnit: () => {
+        restarts++;
+        live = live.filter((d) => d.pid !== supervised?.pid);
+        if (live.length > 0) return; // guard refuses: another dispatcher is live
+        live = [{ pid: nextPid++, version: opts.newVersion }];
+      },
+      sleep: async () => {},
+    },
+  };
+}
+
+describe('orphanDispatcherPids', () => {
+  it('names every live dispatcher the supervisor does not own', () => {
+    expect(orphanDispatcherPids([{ pid: 100 }, { pid: 200 }], 200)).toEqual([100]);
+  });
+
+  it('treats all of them as orphans when the supervisor owns none', () => {
+    expect(orphanDispatcherPids([{ pid: 100 }, { pid: 200 }], null)).toEqual([100, 200]);
+  });
+});
+
+describe('restartDaemon', () => {
+  let dir: string;
+  let home: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-restart-'));
+    home = join(dir, 'home');
+    installDaemon({ platform: 'linux', home, celiloPath: '/bin/sh', busDbPath: '/db' });
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('stops an orphan the supervisor does not own, then brings up new code', async () => {
+    // celilo-mgr exactly: PPID 1, stale v0.1.8, systemd owns nothing.
+    const fleet = fakeFleet({
+      initial: [{ pid: 3639051, version: '0.1.8' }],
+      newVersion: '0.2.0',
+    });
+
+    const result = await restartDaemon(
+      { platform: 'linux', home, expectedVersion: '0.2.0', pollMs: 0 },
+      fleet.deps,
+    );
+
+    expect(fleet.killed).toContain(3639051);
+    expect(result.orphansKilled).toEqual([3639051]);
+    expect(result.dispatcher.version).toBe('0.2.0');
+    expect(result.dispatcher.pid).not.toBe(3639051);
+  });
+
+  it('does not kill the dispatcher the supervisor already owns', async () => {
+    const fleet = fakeFleet({
+      initial: [{ pid: 4242, version: '0.1.8', supervised: true }],
+      newVersion: '0.2.0',
+    });
+
+    const result = await restartDaemon(
+      { platform: 'linux', home, expectedVersion: '0.2.0', pollMs: 0 },
+      fleet.deps,
+    );
+
+    expect(fleet.killed).toEqual([]);
+    expect(result.orphansKilled).toEqual([]);
+    expect(result.dispatcher.version).toBe('0.2.0');
+  });
+
+  it('fails when the restarted dispatcher still reports the OLD version', async () => {
+    // systemctl returned 0, a dispatcher is live — and it is the stale code.
+    // The whole point: never report success off the supervisor's exit code.
+    const fleet = fakeFleet({
+      initial: [{ pid: 3639051, version: '0.1.8' }],
+      newVersion: '0.1.8',
+    });
+
+    await expect(
+      restartDaemon(
+        { platform: 'linux', home, expectedVersion: '0.2.0', pollMs: 0, timeoutMs: 5 },
+        fleet.deps,
+      ),
+    ).rejects.toThrow(/no dispatcher on v0\.2\.0 came up/);
+  });
+
+  it('fails rather than reporting success when nothing comes back at all', async () => {
+    const fleet = fakeFleet({ initial: [], newVersion: '0.2.0' });
+    fleet.deps.restartUnit = () => {}; // unit crash-loops; bus stays empty
+
+    await expect(
+      restartDaemon(
+        { platform: 'linux', home, expectedVersion: '0.2.0', pollMs: 0, timeoutMs: 5 },
+        fleet.deps,
+      ),
+    ).rejects.toThrow(/no dispatcher is live on the bus/);
+  });
+
+  it('refuses when no supervisor unit is installed', () => {
+    expect(() => resolveRestartScope({ platform: 'linux', home: join(dir, 'empty') })).toThrow(
+      /no supervisor unit installed/,
+    );
+  });
+
+  // apt-upgrade runs restart-daemon on every box, including ones that never
+  // installed the daemon. The CLI branches on this so an upgrade with nothing
+  // stale to fix is not failed by a missing unit.
+  it('unitInstalledInAnyScope sees an installed unit, and its absence', () => {
+    expect(unitInstalledInAnyScope('linux', home)).toBe(true);
+    expect(unitInstalledInAnyScope('linux', join(dir, 'empty'))).toBe(false);
+  });
+});
+
+describe('supervisorCommands', () => {
+  it('uses systemctl --user for user scope', () => {
+    expect(supervisorCommands('linux', 'user').restart).toEqual([
+      'systemctl',
+      '--user',
+      'restart',
+      'celilo-events.service',
+    ]);
+  });
+
+  // The system unit is root-owned and celilo is unprivileged. Drop the sudo
+  // and every apt-upgrade on celilo-mgr reports "dispatcher still on old
+  // code" — honest, and never able to do its job. celilo-bootstrap ships the
+  // scoped grant for exactly these two argvs, so they must match it verbatim.
+  it('goes through sudo for system scope, matching the shipped sudoers grant', () => {
+    expect(supervisorCommands('linux', 'system').restart).toEqual([
+      'sudo',
+      'systemctl',
+      'restart',
+      'celilo-events.service',
+    ]);
+    expect(supervisorCommands('linux', 'system').mainPid).toEqual([
+      'sudo',
+      'systemctl',
+      'show',
+      'celilo-events.service',
+      '-p',
+      'MainPID',
+      '--value',
+    ]);
+  });
+
+  it('the shipped sudoers grant covers exactly the argvs used', () => {
+    const grant = readFileSync(
+      join(
+        import.meta.dir,
+        '../../../../packaging/celilo-bootstrap/conffiles/sudoers.d-celilo-events-restart',
+      ),
+      'utf-8',
+    );
+    const cmds = supervisorCommands('linux', 'system');
+    for (const argv of [cmds.restart, cmds.mainPid as string[]]) {
+      // `sudo` itself is the invoker, not part of the granted command.
+      expect(grant).toContain(`/usr/bin/${argv.slice(1).join(' ')}`);
+    }
+  });
+});

package/src/services/events-daemon.ts

@@ -50,6 +50,8 @@ export interface InstallDaemonOptions {
   busDbPath?: string;
   /** Override the home directory used to compute install paths. */
   home?: string;
+  /** Prefix for system-scope paths. Test seam — see getDaemonUnitPath. */
+  systemRoot?: string;
 }
 
 export interface InstallDaemonResult {
@@ -61,9 +63,53 @@ export interface InstallDaemonResult {
   busDbPath: string;
   /** Explicit run-as user for system scope; undefined for user scope. */
   runAsUser?: string;
+  /**
+   * Set when the OTHER scope already has a unit installed. Both scopes use the
+   * same unit name, so installing over that produces two same-named daemons on
+   * one bus — see conflictingScopeError.
+   */
+  conflict?: { scope: SupervisorScope; unitPath: string };
   nextSteps: string[];
 }
 
+export const SUPERVISOR_SCOPES: readonly SupervisorScope[] = ['user', 'system'];
+
+/**
+ * Both scopes name the unit `celilo-events.service`, so `systemctl status
+ * celilo-events.service` and `systemctl --user status celilo-events.service`
+ * are different services that look identical in every operator-facing string.
+ *
+ * That is how celilo-mgr came to run two dispatchers for 40 days (#580, #610):
+ * Ansible installed the system unit, someone later ran `celilo events
+ * install-daemon` — which defaults to USER scope — and got a second daemon with
+ * no warning. `systemctl status celilo-events.service` then reported the dead
+ * system unit while the user-scope one served production.
+ */
+function conflictingScopeError(conflict: { scope: SupervisorScope; unitPath: string }): Error {
+  const flag = conflict.scope === 'system' ? ' --system' : '';
+  return new Error(
+    [
+      `celilo events daemon: a ${conflict.scope}-scope unit is already installed at ${conflict.unitPath}.`,
+      'Both scopes use the same unit name, so installing this one would create a SECOND dispatcher',
+      'on the same bus that `systemctl status` cannot distinguish.',
+      `Remove the other first: \`celilo events uninstall-daemon${flag}\` (and disable it in systemd),`,
+      'or keep the existing one.',
+    ].join(' '),
+  );
+}
+
+/** The other scope's unit, if it exists. */
+function findConflictingScope(
+  platform: SupervisorPlatform,
+  home: string,
+  scope: SupervisorScope,
+  systemRoot?: string,
+): { scope: SupervisorScope; unitPath: string } | undefined {
+  const other = scope === 'user' ? 'system' : 'user';
+  const found = readInstalledUnit({ platform, scope: other, home, systemRoot });
+  return found.exists ? { scope: other, unitPath: found.path } : undefined;
+}
+
 export interface UninstallDaemonResult {
   platform: SupervisorPlatform;
   scope: SupervisorScope;
@@ -90,20 +136,26 @@ export function detectPlatform(): SupervisorPlatform {
 
 /**
  * Resolve where to write the unit file for a given platform + scope.
- * `home` only matters for user scope; system paths are fixed.
+ * `home` only matters for user scope.
+ *
+ * `systemRoot` prefixes the system-scope path. It exists so a test can have
+ * BOTH scopes installed at once without writing to the real /etc — the
+ * two-units-one-name state that produced #610 is otherwise untestable, since
+ * `home` alone can only ever relocate the user unit.
  */
 export function getDaemonUnitPath(
   platform: SupervisorPlatform,
   home: string,
   scope: SupervisorScope = 'user',
+  systemRoot = '/',
 ): string {
   if (platform === 'linux') {
     return scope === 'system'
-      ? join('/etc/systemd/system', SYSTEMD_UNIT_NAME)
+      ? join(systemRoot, 'etc/systemd/system', SYSTEMD_UNIT_NAME)
       : join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT_NAME);
   }
   return scope === 'system'
-    ? join('/Library/LaunchDaemons', `${LAUNCHD_LABEL}.plist`)
+    ? join(systemRoot, 'Library/LaunchDaemons', `${LAUNCHD_LABEL}.plist`)
     : join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
 }
 
@@ -286,7 +338,7 @@ export function planDaemonInstall(opts: InstallDaemonOptions = {}): InstallDaemo
   const concurrency = opts.concurrency ?? 4;
   const runAsUser = scope === 'system' ? resolveRunAsUser(busDbPath, opts.runAsUser) : undefined;
 
-  const unitPath = getDaemonUnitPath(platform, home, scope);
+  const unitPath = getDaemonUnitPath(platform, home, scope, opts.systemRoot);
   const unitInputs: UnitInputs = {
     celiloPath,
     busDbPath,
@@ -307,6 +359,7 @@ export function planDaemonInstall(opts: InstallDaemonOptions = {}): InstallDaemo
     celiloPath,
     busDbPath,
     runAsUser,
+    conflict: findConflictingScope(platform, home, scope, opts.systemRoot),
     nextSteps: nextStepsFor(platform, scope, unitPath),
   };
 }
@@ -320,18 +373,27 @@ export function planDaemonInstall(opts: InstallDaemonOptions = {}): InstallDaemo
  */
 export function installDaemon(opts: InstallDaemonOptions = {}): InstallDaemonResult {
   const plan = planDaemonInstall(opts);
+  // Refuse on the WRITE path only. `--print` renders without creating anything,
+  // and the celilo-mgmt Ansible role captures it — throwing there would wedge
+  // the deploy of the very tool an operator needs to clean the conflict up.
+  if (plan.conflict) throw conflictingScopeError(plan.conflict);
   mkdirSync(dirname(plan.unitPath), { recursive: true });
   writeFileSync(plan.unitPath, plan.unitContent, { mode: 0o644 });
   return plan;
 }
 
 export function uninstallDaemon(
-  opts: { platform?: SupervisorPlatform; scope?: SupervisorScope; home?: string } = {},
+  opts: {
+    platform?: SupervisorPlatform;
+    scope?: SupervisorScope;
+    home?: string;
+    systemRoot?: string;
+  } = {},
 ): UninstallDaemonResult {
   const platform = opts.platform ?? detectPlatform();
   const scope = opts.scope ?? 'user';
   const home = opts.home ?? homedir();
-  const unitPath = getDaemonUnitPath(platform, home, scope);
+  const unitPath = getDaemonUnitPath(platform, home, scope, opts.systemRoot);
 
   let removed = false;
   if (existsSync(unitPath)) {
@@ -366,13 +428,238 @@ export function uninstallDaemon(
   return { platform, scope, unitPath, removed, nextSteps };
 }
 
+// --- restart (celilo#604) ---------------------------------------------
+//
+// `install-daemon` deliberately never touches supervisor state, so the only
+// supported restart was SSH + systemctl — which the "operate celilo through
+// celilo" model forbids. Restart is the one supervisor verb that has to be a
+// celilo command, because the upgrade path needs it.
+//
+// The trap: on celilo-mgr the running dispatcher was an ORPHAN (PPID 1, not the
+// unit's child). `systemctl restart` could not kill it, the unit crash-looped
+// against the one-dispatcher-per-bus guard (#584), and systemctl reported
+// `activating` while the OLD code kept serving. So a restart that shells out and
+// returns is worthless: it must reconcile the orphan and then verify the bus.
+
+export interface RestartDaemonResult {
+  platform: SupervisorPlatform;
+  scope: SupervisorScope;
+  unitPath: string;
+  /** Live dispatchers stopped because the supervisor did not own them. */
+  orphansKilled: number[];
+  /** Version the restarted dispatcher must report (installed @celilo/event-bus). */
+  expectedVersion: string;
+  /** The dispatcher now serving the bus. */
+  dispatcher: { pid: number; version: string | null };
+}
+
+export interface RestartDaemonDeps {
+  /** Live dispatchers on the bus, by pid + the code version each reports. */
+  liveDispatchers: () => Array<{ pid: number; version: string | null }>;
+  /** The pid the supervisor owns for the unit, or null if it owns none. */
+  supervisorPid: () => number | null;
+  /** Stop a process the supervisor does not own. */
+  kill: (pid: number, signal: NodeJS.Signals) => void;
+  /** Ask the supervisor to (re)start the unit. Throws on failure. */
+  restartUnit: () => void;
+  sleep: (ms: number) => Promise<void>;
+}
+
+export interface RestartDaemonOptions {
+  platform?: SupervisorPlatform;
+  scope?: SupervisorScope;
+  home?: string;
+  /** Version the restarted dispatcher must report before we call it a success. */
+  expectedVersion: string;
+  /** How long to wait for the new dispatcher to appear on the bus. */
+  timeoutMs?: number;
+  /** Poll interval while waiting. */
+  pollMs?: number;
+}
+
+/**
+ * Which live dispatchers block the unit from starting: every one whose pid the
+ * supervisor does not own. Pure — the orphan trap is decided here so it can be
+ * tested without a systemd.
+ */
+export function orphanDispatcherPids(
+  live: Array<{ pid: number }>,
+  supervisorPid: number | null,
+): number[] {
+  return live.filter((d) => d.pid !== supervisorPid).map((d) => d.pid);
+}
+
+/**
+ * Pick the scope to act on: whichever scope has a unit installed. Explicit wins;
+ * with units in both scopes, system wins (the management-plane shape).
+ */
+/** Is a supervisor unit present in either scope? */
+export function unitInstalledInAnyScope(platform?: SupervisorPlatform, home?: string): boolean {
+  return (['system', 'user'] as const).some(
+    (scope) => readInstalledUnit({ scope, home, platform }).exists,
+  );
+}
+
+export function resolveRestartScope(
+  opts: { platform?: SupervisorPlatform; home?: string; scope?: SupervisorScope } = {},
+): SupervisorScope {
+  if (opts.scope) return opts.scope;
+  const probe = (scope: SupervisorScope) =>
+    readInstalledUnit({ scope, home: opts.home, platform: opts.platform }).exists;
+  if (probe('system')) return 'system';
+  if (probe('user')) return 'user';
+  throw new Error(
+    'celilo events restart-daemon: no supervisor unit installed (user or system scope). Run `celilo events install-daemon` first.',
+  );
+}
+
+/**
+ * Stop any unmanaged dispatcher, restart the unit, and confirm on the BUS — not
+ * from the supervisor's exit code — that a new process is live on the expected
+ * version. Anything less reports success into the crash loop described above.
+ */
+export async function restartDaemon(
+  opts: RestartDaemonOptions,
+  deps: RestartDaemonDeps,
+): Promise<RestartDaemonResult> {
+  const platform = opts.platform ?? detectPlatform();
+  const scope = resolveRestartScope({ platform, home: opts.home, scope: opts.scope });
+  const unitPath = getDaemonUnitPath(platform, opts.home ?? homedir(), scope);
+  const timeoutMs = opts.timeoutMs ?? 60_000;
+  const pollMs = opts.pollMs ?? 1000;
+
+  const before = deps.liveDispatchers();
+  const orphans = orphanDispatcherPids(before, deps.supervisorPid());
+  for (const pid of orphans) {
+    deps.kill(pid, 'SIGTERM');
+  }
+  // Wait for the guard's view to clear before restarting, else the unit starts
+  // into `another dispatcher is already running` and auto-restart backoff eats
+  // the window. SIGKILL whatever refuses to go.
+  const graceUntil = Date.now() + 10_000;
+  while (orphans.length > 0 && Date.now() < graceUntil) {
+    if (deps.liveDispatchers().every((d) => !orphans.includes(d.pid))) break;
+    await deps.sleep(pollMs);
+  }
+  for (const pid of deps.liveDispatchers().map((d) => d.pid)) {
+    if (orphans.includes(pid)) deps.kill(pid, 'SIGKILL');
+  }
+
+  deps.restartUnit();
+
+  const beforePids = new Set(before.map((d) => d.pid));
+  const deadline = Date.now() + timeoutMs;
+  let last: Array<{ pid: number; version: string | null }> = [];
+  while (Date.now() < deadline) {
+    last = deps.liveDispatchers();
+    const fresh = last.filter((d) => !beforePids.has(d.pid));
+    if (last.length === 1 && fresh.length === 1 && fresh[0]?.version === opts.expectedVersion) {
+      return {
+        platform,
+        scope,
+        unitPath,
+        orphansKilled: orphans,
+        expectedVersion: opts.expectedVersion,
+        dispatcher: fresh[0],
+      };
+    }
+    await deps.sleep(pollMs);
+  }
+
+  const seen =
+    last.length === 0
+      ? 'no dispatcher is live on the bus'
+      : `live: ${last.map((d) => `pid ${d.pid} (v${d.version ?? '?'})`).join(', ')}`;
+  throw new Error(
+    `celilo events restart-daemon: the supervisor was asked to restart ${unitPath}, but no dispatcher on v${opts.expectedVersion} came up within ${Math.round(timeoutMs / 1000)}s — ${seen}. The old code may still be serving. Check \`celilo events status\` and the unit's logs.`,
+  );
+}
+
+/**
+ * systemctl/launchctl argv for this platform+scope — `restart` and MainPID.
+ *
+ * System scope goes through `sudo`, and that is not optional on the box this
+ * exists for: the unit is root-owned and the command runs as the unprivileged
+ * `celilo` user (api-serve's child, the wrapper's sudo-drop target). Without
+ * sudo, every apt-upgrade on celilo-mgr would take the honest-but-useless
+ * branch — "packages upgraded, dispatcher still on old code" — forever.
+ * `celilo-bootstrap` ships the scoped grant (/etc/sudoers.d/celilo-events-restart)
+ * for exactly these two invocations. Same shape as `install-daemon`'s own
+ * printed next-steps, which already say `sudo systemctl` for system scope.
+ */
+export function supervisorCommands(
+  platform: SupervisorPlatform,
+  scope: SupervisorScope,
+): { restart: string[]; mainPid: string[] | null } {
+  if (platform === 'linux') {
+    const sc = scope === 'system' ? ['sudo', 'systemctl'] : ['systemctl', '--user'];
+    return {
+      restart: [...sc, 'restart', SYSTEMD_UNIT_NAME],
+      mainPid: [...sc, 'show', SYSTEMD_UNIT_NAME, '-p', 'MainPID', '--value'],
+    };
+  }
+  const target =
+    scope === 'system'
+      ? `system/${LAUNCHD_LABEL}`
+      : `gui/${process.getuid?.() ?? 501}/${LAUNCHD_LABEL}`;
+  return {
+    // kickstart -k restarts a loaded job; bootstrap first if it was never loaded.
+    restart:
+      scope === 'system'
+        ? ['sudo', 'launchctl', 'kickstart', '-k', target]
+        : ['launchctl', 'kickstart', '-k', target],
+    // launchctl print's pid line is not machine-stable across releases; treat
+    // launchd as "owns nothing we can name" and let the bus decide.
+    // ponytail: no MainPID probe on darwin — celilo-mgr is Linux; add if a mac
+    // ever runs the management plane.
+    mainPid: null,
+  };
+}
+
+/**
+ * The pid the supervisor currently owns for this scope's unit, or null when
+ * that can't be established (launchd, systemd absent, unit inactive, user bus
+ * unreachable). `MainPID=0` means inactive — reported as null, not 0.
+ *
+ * Null is "don't know", never "not supervised": a caller must not accuse a
+ * dispatcher of being an orphan on the strength of a failed probe.
+ *
+ * The argv comes from supervisorCommands (celilo#604) rather than being rebuilt
+ * here — that is where the sudo-for-system-scope decision lives, and two copies
+ * of it would drift.
+ */
+export function unitMainPid(
+  scope: SupervisorScope,
+  platform: SupervisorPlatform = detectPlatform(),
+): number | null {
+  const { mainPid } = supervisorCommands(platform, scope);
+  if (!mainPid) return null;
+  const [cmd, ...args] = mainPid;
+  if (!cmd) return null;
+  try {
+    const out = execFileSync(cmd, args, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const pid = Number(out.trim());
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
 export function readInstalledUnit(
-  opts: { platform?: SupervisorPlatform; scope?: SupervisorScope; home?: string } = {},
+  opts: {
+    platform?: SupervisorPlatform;
+    scope?: SupervisorScope;
+    home?: string;
+    systemRoot?: string;
+  } = {},
 ): { exists: true; path: string; content: string } | { exists: false; path: string } {
   const platform = opts.platform ?? detectPlatform();
   const scope = opts.scope ?? 'user';
   const home = opts.home ?? homedir();
-  const unitPath = getDaemonUnitPath(platform, home, scope);
+  const unitPath = getDaemonUnitPath(platform, home, scope, opts.systemRoot);
   if (!existsSync(unitPath)) return { exists: false, path: unitPath };
   return { exists: true, path: unitPath, content: readFileSync(unitPath, 'utf-8') };
 }