/**
 * Generate and install / uninstall a supervisor unit for the SQLite
 * event-bus dispatcher. Linux gets a systemd unit; macOS gets a
 * launchd plist. The command WRITES the unit file but never touches
 * the supervisor state — the operator (or the celilo-mgmt Ansible
 * role) runs the enable/bootstrap steps themselves so the effect is
 * visible.
 *
 * Two scopes (designs/DISPATCHER_DAEMON_AND_TIMER_EVENTS.md A1):
 *   - `user` (default): per-user unit under $HOME — dev-laptop shape.
 *     Dies with the login session unless lingering is enabled.
 *   - `system`: /etc/systemd/system unit (Linux) or a root-owned
 *     /Library/LaunchDaemons plist (macOS) — the management-plane
 *     shape; survives logout and reboot. The unit pins an explicit
 *     run-as user (the celilo state-dir owner) so every handler
 *     subprocess the dispatcher spawns stays signalable by that user
 *     (ISS-0068 / A1b).
 *
 * Why split write-vs-enable: a celilo command silently flipping
 * systemd state would be hard to reason about during incidents. Pure
 * file-on-disk + printed next-steps keeps the operational surface
 * predictable.
 */

import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
import { homedir, platform as nodePlatform, userInfo } from 'node:os';
import { dirname, join } from 'node:path';
import { getEventBusPath } from '../config/paths';

export type SupervisorPlatform = 'linux' | 'darwin';
export type SupervisorScope = 'user' | 'system';

export interface InstallDaemonOptions {
  celiloPath?: string;
  pollMs?: number;
  concurrency?: number;
  /** Unit scope. Defaults to `user`. */
  scope?: SupervisorScope;
  /**
   * Run-as user for system-scope units. Defaults to the owner of the
   * bus DB's directory (the celilo state dir) — `celilo` on a
   * deb-bootstrapped box, root on a local install. Ignored for user
   * scope (user units already run as their owner).
   */
  runAsUser?: string;
  /** Override platform detection. Mainly for tests. */
  platform?: SupervisorPlatform;
  /** Override the bus DB path. Defaults to celilo's getEventBusPath(). */
  busDbPath?: string;
  /**
   * Override the PATH written into the unit's environment. Defaults to
   * resolveDaemonPathEnv() captured at render time. Test seam — pin it so
   * assertions don't depend on the machine's bun install.
   */
  pathEnv?: 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 {
  platform: SupervisorPlatform;
  scope: SupervisorScope;
  unitPath: string;
  unitContent: string;
  celiloPath: string;
  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;
  unitPath: string;
  removed: boolean;
  nextSteps: string[];
}

const SYSTEMD_UNIT_NAME = 'celilo-events.service';
const LAUNCHD_LABEL = 'com.celilo.events';

/**
 * Map a node `process.platform` to one of the supported supervisor
 * platforms. We don't ship Windows or BSD support for v1.
 */
export function detectPlatform(): SupervisorPlatform {
  const p = nodePlatform();
  if (p === 'linux') return 'linux';
  if (p === 'darwin') return 'darwin';
  throw new Error(
    `celilo events daemon: unsupported platform "${p}". Only linux (systemd) and darwin (launchd) are supported in v1.`,
  );
}

/**
 * Resolve where to write the unit file for a given platform + scope.
 * `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(systemRoot, 'etc/systemd/system', SYSTEMD_UNIT_NAME)
      : join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT_NAME);
  }
  return scope === 'system'
    ? join(systemRoot, 'Library/LaunchDaemons', `${LAUNCHD_LABEL}.plist`)
    : join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
}

export interface LaunchdUnitStatus {
  /** The pid launchd currently runs the unit under, or null when it isn't running. */
  pid: number | null;
  /**
   * The unit's last exit status in wait4 form (256 = exited 1, 15 = killed by
   * SIGTERM), or null when launchd has no record of one.
   */
  lastExitStatus: number | null;
}

/**
 * Probe launchd for the unit's health. Uses `launchctl list <label>` —
 * on current macOS the richer `launchctl print gui/<uid>/<label>` answers
 * "Domain does not support specified action" for legacy-loaded jobs, while
 * `list <label>` prints a legacy-style dict carrying `PID` (absent when not
 * running) and `LastExitStatus`.
 *
 * Returns null when launchd doesn't answer at all (not loaded, linux, the
 * binary missing) — null is "don't know", never "bad". Only the user scope
 * is probed: the system domain needs root, and a mac running a system-scope
 * celilo daemon is not a supported shape (see supervisorCommands).
 */
export function launchdUnitStatus(scope: SupervisorScope = 'user'): LaunchdUnitStatus | null {
  if (scope !== 'user' || detectPlatform() !== 'darwin') return null;
  let out: string;
  try {
    out = execFileSync('launchctl', ['list', LAUNCHD_LABEL], {
      encoding: 'utf-8',
      stdio: ['ignore', 'pipe', 'ignore'],
    });
  } catch {
    return null;
  }
  const pidMatch = out.match(/"PID" = (\d+)/);
  const exitMatch = out.match(/"LastExitStatus" = (-?\d+)/);
  return {
    pid: pidMatch ? Number(pidMatch[1]) : null,
    lastExitStatus: exitMatch ? Number(exitMatch[1]) : null,
  };
}

/**
 * Find the celilo executable. Priority:
 *   1. Explicit override
 *   2. Bun.which('celilo')
 *   3. error
 *
 * The unit file needs an absolute path because systemd does not resolve
 * PATH for ExecStart and launchd is similarly literal.
 */
export function resolveCeliloPath(override?: string): string {
  if (override) {
    if (!existsSync(override)) {
      throw new Error(`celilo events daemon: --celilo-path "${override}" does not exist`);
    }
    return override;
  }
  // Bun.which returns null when not found.
  const found = (Bun as unknown as { which: (cmd: string) => string | null }).which('celilo');
  if (!found) {
    throw new Error(
      'celilo events daemon: could not find `celilo` on PATH. Install it globally (`bun add -g @celilo/cli`) or pass --celilo-path <path>.',
    );
  }
  return found;
}

/**
 * A PATH that resolves bun, for a supervisor unit's environment.
 *
 * launchd starts jobs with its own default PATH, and systemd runs
 * ExecStart with a similarly minimal one. Neither includes bun, and the
 * global `celilo` entry is a bash wrapper whose first act is
 * `command -v bun` — so a unit without a PATH key crash-loops forever on
 * "Error: celilo requires bun" (celilo#1373: 22680 respawns on one Mac).
 * The PATH is captured at RENDER time — the moment the unit is written —
 * from Bun.which('bun'), falling back to process.execPath, which IS the
 * bun binary under the bun runtime. Standard dirs follow so the
 * dispatcher's own subprocesses keep working.
 */
export function resolveDaemonPathEnv(): string {
  const bun =
    (Bun as unknown as { which: (cmd: string) => string | null }).which('bun') ?? process.execPath;
  return `${dirname(bun)}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`;
}

/**
 * Run-as user for a system-scope unit: the owner of the celilo state
 * dir (the bus DB's directory). Falls back to the current user when
 * the dir doesn't exist yet or the uid can't be resolved to a name —
 * a fresh dev box where nothing has been bootstrapped.
 */
export function resolveRunAsUser(busDbPath: string, override?: string): string {
  if (override) return override;
  try {
    const ownerUid = statSync(dirname(busDbPath)).uid;
    if (ownerUid === process.getuid?.()) return userInfo().username;
    const name = execFileSync('id', ['-nu', String(ownerUid)], { encoding: 'utf-8' }).trim();
    if (name) return name;
  } catch {
    // State dir missing or uid unresolvable — fall through.
  }
  return userInfo().username;
}

interface UnitInputs {
  celiloPath: string;
  busDbPath: string;
  pollMs: number;
  concurrency: number;
  home: string;
  scope: SupervisorScope;
  /**
   * PATH injected into the unit's environment (celilo#1373). Required:
   * a unit without it cannot resolve bun and crash-loops.
   */
  pathEnv: string;
  /** Required for system scope; ignored for user scope. */
  runAsUser?: string;
}

export function renderSystemdUnit(input: UnitInputs): string {
  const userLine = input.scope === 'system' && input.runAsUser ? `User=${input.runAsUser}\n` : '';
  const journalHint =
    input.scope === 'system'
      ? `journalctl -u ${SYSTEMD_UNIT_NAME}`
      : `journalctl --user -u ${SYSTEMD_UNIT_NAME}`;
  return `[Unit]
Description=Celilo SQLite Event Bus Dispatcher
Documentation=https://github.com/psbanka/infra/blob/main/openspec/specs/event-bus/spec.md
After=network.target

[Service]
Type=simple
${userLine}ExecStart=${input.celiloPath} events run --poll-ms ${input.pollMs} --concurrency ${input.concurrency}
Restart=on-failure
RestartSec=10s
Environment=EVENT_BUS_DB=${input.busDbPath}
Environment=PATH=${input.pathEnv}
# stdout/stderr are captured by ${journalHint}.
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=${input.scope === 'system' ? 'multi-user.target' : 'default.target'}
`;
}

export function renderLaunchdPlist(input: UnitInputs): string {
  // System daemons log under /Library/Logs (no $HOME at boot); user
  // agents under the user's Library/Logs. Indentation matters very
  // little to launchd but we want it readable when an operator opens
  // the file manually to debug.
  const logDir = input.scope === 'system' ? '/Library/Logs' : join(input.home, 'Library', 'Logs');
  const userNameBlock =
    input.scope === 'system' && input.runAsUser
      ? `  <key>UserName</key>\n  <string>${input.runAsUser}</string>\n`
      : '';
  return `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>${LAUNCHD_LABEL}</string>
${userNameBlock}  <key>ProgramArguments</key>
  <array>
    <string>${input.celiloPath}</string>
    <string>events</string>
    <string>run</string>
    <string>--poll-ms</string>
    <string>${input.pollMs}</string>
    <string>--concurrency</string>
    <string>${input.concurrency}</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>EVENT_BUS_DB</key>
    <string>${input.busDbPath}</string>
    <key>PATH</key>
    <string>${input.pathEnv}</string>
  </dict>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>${join(logDir, 'celilo-events.out.log')}</string>
  <key>StandardErrorPath</key>
  <string>${join(logDir, 'celilo-events.err.log')}</string>
</dict>
</plist>
`;
}

function nextStepsFor(
  platform: SupervisorPlatform,
  scope: SupervisorScope,
  unitPath: string,
): string[] {
  if (platform === 'linux') {
    return scope === 'system'
      ? [
          'Reload systemd:  sudo systemctl daemon-reload',
          `Enable + start:  sudo systemctl enable --now ${SYSTEMD_UNIT_NAME}`,
          `Tail logs:       journalctl -u ${SYSTEMD_UNIT_NAME} -f`,
          `Status:          systemctl status ${SYSTEMD_UNIT_NAME}`,
        ]
      : [
          'Reload systemd:  systemctl --user daemon-reload',
          `Enable + start:  systemctl --user enable --now ${SYSTEMD_UNIT_NAME}`,
          `Tail logs:       journalctl --user -u ${SYSTEMD_UNIT_NAME} -f`,
          `Status:          systemctl --user status ${SYSTEMD_UNIT_NAME}`,
        ];
  }
  return scope === 'system'
    ? [
        `Load + start:    sudo launchctl bootstrap system ${unitPath}`,
        'Tail stdout:     tail -f /Library/Logs/celilo-events.out.log',
        'Tail stderr:     tail -f /Library/Logs/celilo-events.err.log',
        `Status:          sudo launchctl print system/${LAUNCHD_LABEL}`,
      ]
    : [
        `Load + start:    launchctl load -w ${unitPath}`,
        'Tail stdout:     tail -f ~/Library/Logs/celilo-events.out.log',
        'Tail stderr:     tail -f ~/Library/Logs/celilo-events.err.log',
        `Status:          launchctl list | grep ${LAUNCHD_LABEL}`,
      ];
}

/**
 * Resolve everything an install would do — platform, paths, run-as
 * user, rendered unit content — WITHOUT writing anything. This is the
 * single renderer behind both `installDaemon` and the CLI's `--print`
 * mode, which the celilo-mgmt Ansible role uses: the deb wrapper drops
 * to the unprivileged celilo user, so the role renders via `--print`
 * and performs the root-owned write itself with `copy:`.
 */
export function planDaemonInstall(opts: InstallDaemonOptions = {}): InstallDaemonResult {
  const platform = opts.platform ?? detectPlatform();
  const scope = opts.scope ?? 'user';
  const home = opts.home ?? homedir();
  const celiloPath = resolveCeliloPath(opts.celiloPath);
  const busDbPath = opts.busDbPath ?? getEventBusPath();
  const pathEnv = opts.pathEnv ?? resolveDaemonPathEnv();
  const pollMs = opts.pollMs ?? 1000;
  const concurrency = opts.concurrency ?? 4;
  const runAsUser = scope === 'system' ? resolveRunAsUser(busDbPath, opts.runAsUser) : undefined;

  const unitPath = getDaemonUnitPath(platform, home, scope, opts.systemRoot);
  const unitInputs: UnitInputs = {
    celiloPath,
    busDbPath,
    pollMs,
    concurrency,
    home,
    scope,
    pathEnv,
    runAsUser,
  };
  const unitContent =
    platform === 'linux' ? renderSystemdUnit(unitInputs) : renderLaunchdPlist(unitInputs);

  return {
    platform,
    scope,
    unitPath,
    unitContent,
    celiloPath,
    busDbPath,
    runAsUser,
    conflict: findConflictingScope(platform, home, scope, opts.systemRoot),
    nextSteps: nextStepsFor(platform, scope, unitPath),
  };
}

/**
 * Write the supervisor unit file. Idempotent: rewrites if present.
 * Returns the path written + the operator-facing next steps.
 *
 * System scope writes root-owned paths (/etc/systemd/system,
 * /Library/LaunchDaemons) — run as root or the write fails loudly.
 */
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;
    systemRoot?: string;
  } = {},
): UninstallDaemonResult {
  const platform = opts.platform ?? detectPlatform();
  const scope = opts.scope ?? 'user';
  const home = opts.home ?? homedir();
  const unitPath = getDaemonUnitPath(platform, home, scope, opts.systemRoot);

  let removed = false;
  if (existsSync(unitPath)) {
    unlinkSync(unitPath);
    removed = true;
  }

  let nextSteps: string[];
  if (!removed) {
    nextSteps =
      platform === 'linux'
        ? ['No unit file present; nothing to clean up.']
        : ['No plist present; nothing to clean up.'];
  } else if (platform === 'linux') {
    nextSteps =
      scope === 'system'
        ? [
            `Disable + stop:  sudo systemctl disable --now ${SYSTEMD_UNIT_NAME}`,
            'Reload systemd:  sudo systemctl daemon-reload',
          ]
        : [
            `Disable + stop:  systemctl --user disable --now ${SYSTEMD_UNIT_NAME}`,
            'Reload systemd:  systemctl --user daemon-reload',
          ];
  } else {
    nextSteps =
      scope === 'system'
        ? [`Unload:          sudo launchctl bootout system/${LAUNCHD_LABEL}`]
        : [`Unload:          launchctl unload ${unitPath}`];
  }

  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;
    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, opts.systemRoot);
  if (!existsSync(unitPath)) return { exists: false, path: unitPath };
  return { exists: true, path: unitPath, content: readFileSync(unitPath, 'utf-8') };
}