@moondeck/station 0.0.1 → 1.0.0

package/scripts/install/darwin.ts

@@ -0,0 +1,1048 @@
+/**
+ * macOS service install via launchd (ADR-028).
+ *
+ * Writes ~/Library/LaunchAgents/io.moondeck.station.plist (KeepAlive +
+ * RunAtLoad), logs to ~/Library/Logs/Moondeck/, loads with `launchctl bootstrap gui/<uid>`.
+ * The service's PATH is the operator's PATH at install time (so node/pnpm/
+ * docker/git resolve); .env.local is loaded by the host process itself.
+ */
+
+import { lstatSync, mkdirSync, readlinkSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+
+import { STATION } from "../../src/station-identity";
+import type {
+  InstallContext,
+  Installer,
+  ServiceDefinitionState,
+  ServiceManagerState,
+} from "./types";
+import {
+  escapeXml,
+  executeStep,
+  printFile,
+  readPrivateJournal,
+  removeFileDurable,
+  restoreDefinitionDurable,
+  snapshotDefinition,
+  step,
+  stepFailure,
+  writeDefinitionDurable,
+  type DirectorySync,
+  type StepExecutor,
+  type StepResult,
+} from "./util";
+
+export const LABEL = STATION.launchdLabel;
+
+/** The per-user launchd domain the LaunchAgent is bootstrapped into. */
+export function launchdDomain(uid: number = process.getuid?.() ?? 0): string {
+  return `gui/${uid}`;
+}
+
+/** The job as `launchctl` addresses it — `gui/<uid>/io.moondeck.station`. The
+ * service's own activation respawn (`src/activation-respawn.ts`) targets the
+ * same string, so the label and domain cannot drift between the CLI and the
+ * running host. */
+export function launchdJobTarget(uid: number = process.getuid?.() ?? 0): string {
+  return `${launchdDomain(uid)}/${LABEL}`;
+}
+
+const domain = launchdDomain();
+const target = launchdJobTarget();
+const logDir = resolve(homedir(), "Library", "Logs", STATION.logDirName);
+
+export function plistPath(): string {
+  return resolve(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+export function darwinInstallJournalPath(definition = plistPath()): string {
+  return resolve(dirname(definition), `.${basename(definition)}.install-journal.json`);
+}
+
+export interface PlistInputs {
+  execPath: string;
+  args: string[];
+  cwd: string;
+  path: string;
+  home: string;
+  outLog: string;
+  errLog: string;
+  runAtLoad?: boolean;
+}
+
+export function renderPlist(p: PlistInputs): string {
+  const progArgs = [p.execPath, ...p.args]
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join("\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>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(p.cwd)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(p.path)}</string>
+    <key>HOME</key>
+    <string>${escapeXml(p.home)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <${p.runAtLoad === false ? "false" : "true"}/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(p.outLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(p.errLog)}</string>
+</dict>
+</plist>
+`;
+}
+
+function inputs(ctx: InstallContext, logs = logDir): PlistInputs {
+  return {
+    execPath: ctx.execPath,
+    args: ctx.args,
+    cwd: ctx.cwd,
+    path: ctx.envPath ?? process.env.PATH ?? "",
+    home: homedir(),
+    outLog: resolve(logs, STATION.logFileName.replace(/\.log$/, ".out.log")),
+    errLog: resolve(logs, STATION.logFileName),
+    runAtLoad: ctx.startOnInstall !== false,
+  };
+}
+
+export interface DarwinInstallDeps extends DarwinServiceDeps {
+  logDirectory?: string;
+}
+
+export async function installDarwinService(
+  ctx: InstallContext,
+  deps: DarwinInstallDeps = {},
+): Promise<void> {
+  const definition = deps.definitionPath ?? plistPath();
+  const logs = deps.logDirectory ?? logDir;
+  const execute = deps.execute ?? executeStep;
+  const delay = deps.delay ?? defaultDelay;
+  const plist = renderPlist(inputs(ctx, logs));
+  if (ctx.dryRun) {
+    printFile(definition, plist);
+    step(true, "mkdir", ["-p", logs]);
+    step(true, "launchctl", ["bootout", target]);
+    if (ctx.startOnInstall !== false) {
+      step(true, "launchctl", ["bootstrap", domain, definition]);
+      await enableDarwinService(true);
+    } else {
+      step(true, "launchctl", ["disable", target]);
+    }
+    return;
+  }
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const installIntent = ctx.definitionInstallIntent;
+  assertDefinitionInstallIntent(installIntent);
+  await reconcileDarwinDefinitionInstall(
+    { ...deps, definitionPath: definition, journalPath },
+    installIntent?.nonce,
+  );
+  mkdirSync(logs, { recursive: true });
+  mkdirSync(dirname(definition), { recursive: true });
+  const previous = snapshotDefinition(definition);
+  const prior = inspectLaunchdJob(execute);
+  if (!previous.exists && prior.loaded) {
+    throw new Error("launchd reports the host job loaded without a recoverable plist");
+  }
+  const journal: DarwinInstallJournal = {
+    schemaVersion: 1,
+    phase: "installed",
+    installIntent: installIntent ?? null,
+    prior: serializeDefinition(previous),
+    manager: { ...prior, enabled: inspectLaunchdEnabled(execute) },
+  };
+  writeDefinitionDurable(journalPath, `${JSON.stringify(journal)}\n`, 0o600);
+  try {
+    writeDefinitionDurable(
+      definition,
+      plist,
+      0o644,
+      deps.definitionDirectorySync,
+    );
+    await assertLaunchdUnloaded(false, execute, delay);
+    if (ctx.startOnInstall === false) {
+      await setDarwinServiceEnabled(false, false, { execute });
+      if (!installIntent) removeFileDurable(journalPath);
+      return;
+    }
+    await enableDarwinService(false, { execute });
+    await bootstrapWithRetry(execute, delay, definition);
+    await kickstartDarwinAndVerify(execute, delay);
+    if (!installIntent) removeFileDurable(journalPath);
+  } catch (error) {
+    try {
+      const rollbackDeps = {
+        ...deps,
+        definitionPath: definition,
+        journalPath,
+      };
+      if (installIntent) {
+        await prepareDarwinDefinitionInstallRollback(
+          rollbackDeps,
+          installIntent.nonce,
+        );
+      } else {
+        await reconcileDarwinDefinitionInstall(rollbackDeps);
+      }
+    } catch (rollbackError) {
+      throw new Error(
+        `${errorMessage(error)}; service-definition rollback failed: ${errorMessage(rollbackError)}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * `bootout` unloads the old job asynchronously, so an immediate `bootstrap`
+ * can race it ("Bootstrap failed: 5: Input/output error"). Retry a few times
+ * so re-running `install` is idempotent instead of leaving nothing loaded.
+ */
+async function bootstrapWithRetry(
+  execute: StepExecutor = executeStep,
+  delay: (milliseconds: number) => Promise<void> = defaultDelay,
+  definition = plistPath(),
+): Promise<void> {
+  let last: StepResult | null = null;
+  const args = ["bootstrap", domain, definition];
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    last = execute(false, "launchctl", args);
+    if (last.status === 0) return;
+    if (attempt < 5) await delay(500);
+  }
+  throw stepFailure("launchctl", args, last!);
+}
+
+export interface DarwinServiceDeps {
+  execute?: StepExecutor;
+  removeFile?: (path: string) => void;
+  delay?: (milliseconds: number) => Promise<void>;
+  definitionPath?: string;
+  journalPath?: string;
+  definitionDirectorySync?: DirectorySync;
+}
+
+const LAUNCHD_ABSENT =
+  /could not find (?:specified )?service|service(?: .+)? not found|no such process/i;
+const defaultDelay = (milliseconds: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+interface DarwinInstallJournal {
+  readonly schemaVersion: 1;
+  readonly phase: "installed" | "definition-restored";
+  readonly installIntent: {
+    readonly nonce: string;
+    readonly ownerPid: number;
+  } | null;
+  readonly prior:
+    | { readonly exists: false }
+    | {
+        readonly exists: true;
+        readonly bytesBase64: string;
+        readonly mode: number;
+      };
+  readonly manager: {
+    readonly loaded: boolean;
+    readonly running: boolean;
+    readonly enabled: boolean;
+  };
+}
+
+function assertDefinitionInstallIntent(
+  intent: InstallContext["definitionInstallIntent"],
+): void {
+  if (
+    intent &&
+    (!/^[a-f0-9]{64}$/.test(intent.nonce) ||
+      !Number.isSafeInteger(intent.ownerPid) ||
+      intent.ownerPid < 1)
+  ) {
+    throw new Error("service definition install intent is invalid");
+  }
+}
+
+function serializeDefinition(
+  snapshot: ReturnType<typeof snapshotDefinition>,
+): DarwinInstallJournal["prior"] {
+  return snapshot.exists
+    ? {
+        exists: true,
+        bytesBase64: snapshot.bytes.toString("base64"),
+        mode: snapshot.mode,
+      }
+    : { exists: false };
+}
+
+function parseDarwinInstallJournal(raw: string): DarwinInstallJournal {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("launchd service install journal is invalid");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("launchd service install journal is invalid");
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    Object.keys(record).sort().join("\0") !==
+      ["installIntent", "manager", "phase", "prior", "schemaVersion"].join(
+        "\0",
+      ) ||
+    record.schemaVersion !== 1 ||
+    (record.phase !== "installed" && record.phase !== "definition-restored") ||
+    !record.manager ||
+    typeof record.manager !== "object" ||
+    Array.isArray(record.manager) ||
+    !record.prior ||
+    typeof record.prior !== "object" ||
+    Array.isArray(record.prior) ||
+    (record.installIntent !== null &&
+      (typeof record.installIntent !== "object" || Array.isArray(record.installIntent)))
+  ) {
+    throw new Error("launchd service install journal is invalid");
+  }
+  const manager = record.manager as Record<string, unknown>;
+  const prior = record.prior as Record<string, unknown>;
+  const installIntent = record.installIntent as Record<string, unknown> | null;
+  if (
+    Object.keys(manager).sort().join("\0") !==
+      ["enabled", "loaded", "running"].join("\0") ||
+    typeof manager.enabled !== "boolean" ||
+    typeof manager.loaded !== "boolean" ||
+    typeof manager.running !== "boolean" ||
+    (manager.running && !manager.loaded) ||
+    typeof prior.exists !== "boolean" ||
+    (installIntent !== null &&
+      (Object.keys(installIntent).sort().join("\0") !== ["nonce", "ownerPid"].join("\0") ||
+        typeof installIntent.nonce !== "string" ||
+        !/^[a-f0-9]{64}$/.test(installIntent.nonce) ||
+        typeof installIntent.ownerPid !== "number" ||
+        !Number.isSafeInteger(installIntent.ownerPid) ||
+        installIntent.ownerPid < 1))
+  ) {
+    throw new Error("launchd service install journal is invalid");
+  }
+  if (prior.exists === false) {
+    if (Object.keys(prior).join("\0") !== "exists" || manager.loaded) {
+      throw new Error("launchd service install journal is invalid");
+    }
+    return {
+      schemaVersion: 1,
+      phase: record.phase,
+      installIntent: installIntent as DarwinInstallJournal["installIntent"],
+      prior: { exists: false },
+      manager: manager as DarwinInstallJournal["manager"],
+    };
+  }
+  if (
+    Object.keys(prior).sort().join("\0") !==
+      ["bytesBase64", "exists", "mode"].join("\0") ||
+    typeof prior.bytesBase64 !== "string" ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+      prior.bytesBase64,
+    ) ||
+    typeof prior.mode !== "number" ||
+    !Number.isInteger(prior.mode) ||
+    prior.mode < 0 ||
+    prior.mode > 0o7777
+  ) {
+    throw new Error("launchd service install journal is invalid");
+  }
+  const bytes = Buffer.from(prior.bytesBase64, "base64");
+  if (bytes.toString("base64") !== prior.bytesBase64) {
+    throw new Error("launchd service install journal is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    phase: record.phase,
+    installIntent: installIntent as DarwinInstallJournal["installIntent"],
+    prior: {
+      exists: true,
+      bytesBase64: prior.bytesBase64,
+      mode: prior.mode,
+    },
+    manager: manager as DarwinInstallJournal["manager"],
+  };
+}
+
+function inspectLaunchdJob(execute: StepExecutor): {
+  loaded: boolean;
+  running: boolean;
+} {
+  const args = ["print", target];
+  const result = execute(false, "launchctl", args);
+  if (result.status === 0) {
+    return { loaded: true, running: launchdReportsRunning(result) };
+  }
+  if (probeConfirmsUnloaded(result)) return { loaded: false, running: false };
+  throw stepFailure("launchctl", args, result, "could not determine prior job state");
+}
+
+function inspectLaunchdEnabled(execute: StepExecutor): boolean {
+  const args = ["print-disabled", domain];
+  const result = execute(false, "launchctl", args);
+  if (result.status !== 0) throw stepFailure("launchctl", args, result);
+  const escaped = LABEL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`"${escaped}"\\s*=>\\s*(true|false)`).exec(result.stdout);
+  return match?.[1] !== "true";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function probeConfirmsUnloaded(result: StepResult): boolean {
+  return (
+    typeof result.status === "number" &&
+    result.status !== 0 &&
+    LAUNCHD_ABSENT.test(`${result.stdout}\n${result.stderr}`)
+  );
+}
+
+function resultDetail(result: StepResult): string {
+  return (
+    result.stderr ||
+    result.stdout ||
+    result.error?.message ||
+    `exit status ${String(result.status)}`
+  ).trim();
+}
+
+async function assertLaunchdUnloaded(
+  dryRun: boolean,
+  execute: StepExecutor,
+  delay: (milliseconds: number) => Promise<void>,
+): Promise<void> {
+  const bootoutArgs = ["bootout", target];
+  const result = execute(dryRun, "launchctl", bootoutArgs);
+  if (dryRun) return;
+
+  const printArgs = ["print", target];
+  let probe = execute(false, "launchctl", printArgs);
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    if (probeConfirmsUnloaded(probe)) return;
+    if (result.status !== 0 || probe.status !== 0 || attempt === 5) break;
+    await delay(500);
+    probe = execute(false, "launchctl", printArgs);
+  }
+
+  const context = `could not verify that the service unloaded: ${resultDetail(probe)}`;
+  if (result.status === 0) {
+    throw new Error(`\`launchctl ${bootoutArgs.join(" ")}\` ${context}`);
+  }
+  throw stepFailure("launchctl", bootoutArgs, result, context);
+}
+
+export async function reconcileDarwinDefinitionInstall(
+  deps: DarwinInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseDarwinInstallJournal(raw);
+  if (journal.installIntent !== null) {
+    assertJournalAccess(journal.installIntent, installIntent);
+    throw new Error(
+      "public service definition rollback requires runtime command restoration between prepare and resume",
+    );
+  }
+  await prepareDarwinDefinitionInstallRollback(deps);
+  await resumeDarwinDefinitionInstallRollback(deps);
+}
+
+export async function prepareDarwinDefinitionInstallRollback(
+  deps: DarwinInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseDarwinInstallJournal(raw);
+  assertJournalAccess(journal.installIntent, installIntent);
+  const execute = deps.execute ?? executeStep;
+  const delay = deps.delay ?? defaultDelay;
+
+  await assertLaunchdUnloaded(false, execute, delay);
+  // Disable while the target definition/command graph is still intact. A
+  // reboot after the following rename must not launch the restored definition
+  // through a not-yet-restored shared shim.
+  await setDarwinServiceEnabled(false, false, { execute });
+  const prior = journal.prior.exists
+    ? {
+        exists: true as const,
+        bytes: Buffer.from(journal.prior.bytesBase64, "base64"),
+        mode: journal.prior.mode,
+      }
+    : ({ exists: false } as const);
+  restoreDefinitionDurable(definition, prior, deps.definitionDirectorySync);
+
+  if (journal.phase !== "definition-restored") {
+    writeDefinitionDurable(
+      journalPath,
+      `${JSON.stringify({ ...journal, phase: "definition-restored" })}\n`,
+      0o600,
+    );
+  }
+}
+
+export async function resumeDarwinDefinitionInstallRollback(
+  deps: DarwinInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseDarwinInstallJournal(raw);
+  assertJournalAccess(journal.installIntent, installIntent);
+  if (journal.phase !== "definition-restored") {
+    throw new Error("launchd service definition rollback has not been prepared");
+  }
+  const execute = deps.execute ?? executeStep;
+  const delay = deps.delay ?? defaultDelay;
+
+  // Reassert the no-daemon boundary in case a supervisor raced the command
+  // restoration between prepare and resume.
+  await assertLaunchdUnloaded(false, execute, delay);
+  const prior = journal.prior.exists
+    ? {
+        exists: true as const,
+        bytes: Buffer.from(journal.prior.bytesBase64, "base64"),
+        mode: journal.prior.mode,
+      }
+    : ({ exists: false } as const);
+  restoreDefinitionDurable(definition, prior, deps.definitionDirectorySync);
+
+  if (prior.exists) {
+    const enabledArgs = [journal.manager.enabled ? "enable" : "disable", target];
+    const enabled = execute(false, "launchctl", enabledArgs);
+    if (enabled.status !== 0) throw stepFailure("launchctl", enabledArgs, enabled);
+  }
+
+  if (journal.manager.loaded) {
+    await bootstrapWithRetry(execute, delay, definition);
+    if (journal.manager.running) {
+      const kickstartArgs = ["kickstart", target];
+      const kickstart = execute(false, "launchctl", kickstartArgs);
+      if (kickstart.status !== 0) {
+        throw stepFailure("launchctl", kickstartArgs, kickstart);
+      }
+      const printArgs = ["print", target];
+      let probe = execute(false, "launchctl", printArgs);
+      for (let attempt = 0; attempt < 6; attempt += 1) {
+        if (launchdReportsRunning(probe)) break;
+        if (attempt === 5) {
+          throw new Error(
+            `\`launchctl ${kickstartArgs.join(" ")}\` did not restore the prior service: ${resultDetail(probe)}`,
+          );
+        }
+        await delay(500);
+        probe = execute(false, "launchctl", printArgs);
+      }
+    }
+  }
+  removeFileDurable(journalPath);
+}
+
+export async function completeDarwinDefinitionInstall(
+  deps: DarwinInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseDarwinInstallJournal(raw);
+  assertJournalAccess(journal.installIntent, installIntent);
+  if (journal.phase !== "installed") {
+    throw new Error("cannot commit a service definition whose rollback was prepared");
+  }
+  removeFileDurable(journalPath);
+}
+
+function assertJournalAccess(
+  owner: DarwinInstallJournal["installIntent"],
+  installIntent?: string,
+): void {
+  if (owner === null) {
+    if (installIntent) {
+      throw new Error("service definition journal does not belong to this install intent");
+    }
+    return;
+  }
+  if (owner.nonce !== installIntent) {
+    throw new Error(
+      `service definition update is owned by managed installer PID ${owner.ownerPid}`,
+    );
+  }
+}
+
+export async function darwinDefinitionState(
+  managedCommand: string,
+  definition = plistPath(),
+  expectedManagedTarget = resolve(
+    homedir(),
+    STATION.runtimeDirName,
+    "runtime",
+    "current",
+    "bin",
+    "uai-host",
+  ),
+  execute: StepExecutor = executeStep,
+): Promise<ServiceDefinitionState> {
+  const snapshot = snapshotDefinition(definition);
+  const loadedCommand = inspectLaunchdLoadedCommand(execute, managedCommand);
+  if (!snapshot.exists && loadedCommand.loaded) {
+    throw new Error(
+      "launchd reports the host job loaded without a recoverable plist",
+    );
+  }
+  if (!snapshot.exists) {
+    // launchd's print-disabled map treats an absent label as enabled by
+    // default. There is no definition to enable, so normalize a truly missing
+    // service to the all-false lifecycle state expected by install admission.
+    return {
+      ownership: "missing",
+      manager: { loaded: false, active: false, enabled: false },
+    };
+  }
+  const manager: ServiceManagerState = {
+    loaded: loadedCommand.loaded,
+    // This LaunchAgent is KeepAlive+RunAtLoad. A loaded-but-currently-waiting
+    // job is launchd restart/throttle pending and must be quiesced/preserved as
+    // active even when no daemon answers at the instant of inspection.
+    active: loadedCommand.loaded,
+    enabled: inspectLaunchdEnabled(execute),
+  };
+  const args = parsePlistProgramArguments(snapshot.bytes.toString("utf8"));
+  if (
+    args?.length === 2 &&
+    args[0] === managedCommand &&
+    args[1] === "run" &&
+    managedCommandIsOwned(managedCommand, expectedManagedTarget) &&
+    loadedCommand.matches !== false
+  ) {
+    return { ownership: "managed", manager };
+  }
+  return { ownership: "legacy", manager };
+}
+
+export async function darwinDefinitionOwnership(
+  managedCommand: string,
+  definition = plistPath(),
+  expectedManagedTarget = resolve(
+    homedir(),
+    STATION.runtimeDirName,
+    "runtime",
+    "current",
+    "bin",
+    "uai-host",
+  ),
+  execute: StepExecutor = executeStep,
+): Promise<"missing" | "managed" | "legacy"> {
+  return (
+    await darwinDefinitionState(
+      managedCommand,
+      definition,
+      expectedManagedTarget,
+      execute,
+    )
+  ).ownership;
+}
+
+function inspectLaunchdLoadedCommand(
+  execute: StepExecutor,
+  managedCommand: string,
+): { loaded: boolean; matches: boolean | null } {
+  const args = ["print", target];
+  const result = execute(false, "launchctl", args);
+  if (probeConfirmsUnloaded(result)) {
+    return { loaded: false, matches: null };
+  }
+  if (result.status !== 0) {
+    throw stepFailure(
+      "launchctl",
+      args,
+      result,
+      "could not determine the loaded host command",
+    );
+  }
+  const programLines = result.stdout
+    .split(/\r?\n/)
+    .map((line) => /^\s*program = (.*)$/.exec(line)?.[1])
+    .filter((value): value is string => value !== undefined);
+  const argumentBlocks = [
+    ...result.stdout.matchAll(/^\s*arguments = \{\s*$([\s\S]*?)^\s*\}\s*$/gm),
+  ];
+  if (programLines.length !== 1 || argumentBlocks.length !== 1) {
+    return {
+      loaded: true,
+      matches: false,
+    };
+  }
+  const loadedArgs = (argumentBlocks[0]?.[1] ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return {
+    loaded: true,
+    matches:
+      programLines[0] === managedCommand &&
+      loadedArgs.length === 2 &&
+      loadedArgs[0] === managedCommand &&
+      loadedArgs[1] === "run",
+  };
+}
+
+function parsePlistProgramArguments(contents: string): string[] | null {
+  const matches = [
+    ...contents.matchAll(
+      /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/g,
+    ),
+  ];
+  if (matches.length !== 1) return null;
+  const body = matches[0]?.[1] ?? "";
+  const args: string[] = [];
+  const strings = /<string>([\s\S]*?)<\/string>/g;
+  let cursor = 0;
+  for (const match of body.matchAll(strings)) {
+    const index = match.index ?? 0;
+    if (body.slice(cursor, index).trim() !== "") return null;
+    const decoded = decodeXmlString(match[1] ?? "");
+    if (decoded === null) return null;
+    args.push(decoded);
+    cursor = index + match[0].length;
+  }
+  return body.slice(cursor).trim() === "" ? args : null;
+}
+
+function decodeXmlString(value: string): string | null {
+  const decoded = value.replace(
+    /&(amp|lt|gt|quot|apos);/g,
+    (_entity, name: string) =>
+      ({ amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" })[name] ?? "",
+  );
+  return /&(?:#\d+|#x[0-9a-f]+|[a-z][a-z0-9]*);/i.test(decoded)
+    ? null
+    : decoded;
+}
+
+function managedCommandIsOwned(command: string, expectedTarget: string): boolean {
+  try {
+    const stat = lstatSync(command);
+    if (!stat.isSymbolicLink()) return false;
+    const actual = resolve(dirname(command), readlinkSync(command));
+    return actual === expectedTarget;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function uninstallDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileDarwinDefinitionInstall(deps);
+  await assertLaunchdUnloaded(
+    dryRun,
+    deps.execute ?? executeStep,
+    deps.delay ?? defaultDelay,
+  );
+  if (dryRun) {
+    console.log(`$ rm -f ${plistPath()}`);
+    return;
+  }
+  (deps.removeFile ?? ((path) => rmSync(path, { force: true })))(
+    deps.definitionPath ?? plistPath(),
+  );
+}
+
+export async function enableDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  await setDarwinServiceEnabled(true, dryRun, deps);
+}
+
+async function setDarwinServiceEnabled(
+  enabled: boolean,
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  const args = [enabled ? "enable" : "disable", target];
+  const result = (deps.execute ?? executeStep)(dryRun, "launchctl", args);
+  if (result.status !== 0) {
+    throw stepFailure("launchctl", args, result);
+  }
+}
+
+function launchdReportsRunning(result: StepResult): boolean {
+  return (
+    result.status === 0 &&
+    /(?:^|\n)\s*state = running(?:\s|$)/.test(result.stdout)
+  );
+}
+
+async function kickstartDarwinAndVerify(
+  execute: StepExecutor,
+  delay: (milliseconds: number) => Promise<void>,
+): Promise<void> {
+  const kickstartArgs = ["kickstart", target];
+  const kickstart = execute(false, "launchctl", kickstartArgs);
+  if (kickstart.status !== 0) {
+    throw stepFailure("launchctl", kickstartArgs, kickstart);
+  }
+
+  const printArgs = ["print", target];
+  let probe = execute(false, "launchctl", printArgs);
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    if (launchdReportsRunning(probe)) return;
+    if (attempt === 5) break;
+    await delay(500);
+    probe = execute(false, "launchctl", printArgs);
+  }
+  throw new Error(
+    `\`launchctl ${kickstartArgs.join(" ")}\` did not leave the service running: ${resultDetail(probe)}`,
+  );
+}
+
+export async function startDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileDarwinDefinitionInstall(deps);
+  const execute = deps.execute ?? executeStep;
+  await enableDarwinService(dryRun, deps);
+
+  const bootstrapArgs = ["bootstrap", domain, deps.definitionPath ?? plistPath()];
+  const bootstrap = execute(dryRun, "launchctl", bootstrapArgs);
+  if (dryRun) {
+    execute(true, "launchctl", ["kickstart", target]);
+    execute(true, "launchctl", ["print", target]);
+    return;
+  }
+  if (bootstrap.status !== 0) {
+    const loaded = execute(false, "launchctl", ["print", target]);
+    if (loaded.status !== 0) {
+      throw stepFailure(
+        "launchctl",
+        bootstrapArgs,
+        bootstrap,
+        `service is not already loaded: ${resultDetail(loaded)}`,
+      );
+    }
+  }
+
+  await kickstartDarwinAndVerify(execute, deps.delay ?? defaultDelay);
+}
+
+export async function stopDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileDarwinDefinitionInstall(deps);
+  await assertLaunchdUnloaded(
+    dryRun,
+    deps.execute ?? executeStep,
+    deps.delay ?? defaultDelay,
+  );
+}
+
+export async function stopDarwinServiceForInstall(
+  installIntent: string,
+  priorManager: ServiceManagerState,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  assertServiceManagerState(priorManager);
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw !== null) {
+    const journal = parseDarwinInstallJournal(raw);
+    assertJournalAccess(journal.installIntent, installIntent);
+  }
+  // Disable first so launchd cannot relaunch a waiting/KeepAlive predecessor
+  // between a successful unload and the runtime's durable stopped marker.
+  await setDarwinServiceEnabled(false, false, deps);
+  await assertLaunchdUnloaded(
+    false,
+    deps.execute ?? executeStep,
+    deps.delay ?? defaultDelay,
+  );
+}
+
+export async function resumeDarwinServiceForInstall(
+  installIntent: string,
+  priorManager: ServiceManagerState,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  assertServiceManagerState(priorManager);
+  const definition = deps.definitionPath ?? plistPath();
+  const journalPath = deps.journalPath ?? darwinInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw !== null) {
+    const journal = parseDarwinInstallJournal(raw);
+    assertJournalAccess(journal.installIntent, installIntent);
+    if (journal.phase === "installed") {
+      throw new Error("cannot resume the prior service before definition rollback");
+    }
+    await resumeDarwinDefinitionInstallRollback(deps, installIntent);
+  }
+  const execute = deps.execute ?? executeStep;
+  const delay = deps.delay ?? defaultDelay;
+  const definitionPath = deps.definitionPath ?? plistPath();
+  await setDarwinServiceEnabled(priorManager.enabled, false, { execute });
+  if (priorManager.loaded) {
+    await bootstrapWithRetry(execute, delay, definitionPath);
+  }
+  if (priorManager.active) {
+    await kickstartDarwinAndVerify(execute, delay);
+  }
+}
+
+function assertServiceManagerState(state: ServiceManagerState): void {
+  if (
+    typeof state.loaded !== "boolean" ||
+    typeof state.active !== "boolean" ||
+    typeof state.enabled !== "boolean" ||
+    (state.active && !state.loaded)
+  ) {
+    throw new Error("managed service lifecycle snapshot is invalid");
+  }
+}
+
+export async function restartDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileDarwinDefinitionInstall(deps);
+  const args = ["kickstart", "-k", target];
+  const result = (deps.execute ?? executeStep)(dryRun, "launchctl", args);
+  if (result.status !== 0) {
+    throw stepFailure("launchctl", args, result);
+  }
+}
+
+/** What `launchctl print gui/<uid>/com.runuai.host` says about the job. */
+export interface LaunchdJobState {
+  readonly loaded: boolean;
+  /** `state = …` verbatim: `running`, `not running`, `waiting`, … */
+  readonly state: string | null;
+  readonly pid: number | null;
+  /** `last exit code = …` verbatim, e.g. `75: EX_TEMPFAIL` or `(never exited)`. */
+  readonly lastExitCode: string | null;
+  /** `pended nondemand spawn = …` — launchd holds a spawn it has not executed
+   * (live 2026-09-06: `inefficient`, with the job `not running` after an
+   * exit-75 activation restart that KeepAlive never honoured). */
+  readonly pendedNondemandSpawn: string | null;
+  /** Why the probe failed, when it did not confirm a loaded job. */
+  readonly detail: string | null;
+}
+
+function launchdPrintField(stdout: string, name: string): string | null {
+  // Top-level keys are indented by exactly one tab; nested dicts (endpoints,
+  // event triggers) reuse names like `state = active` two tabs deep, so the
+  // job's own key is preferred and the loose match is only a fallback. The
+  // whitespace class is horizontal only, so `state` never matches the tail
+  // of `spawn type` or another longer key.
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const value = `(.+?)[ \\t]*(?:\\r?\\n|$)`;
+  return (
+    new RegExp(`(?:^|\\n)\\t${escaped} = ${value}`).exec(stdout)?.[1] ??
+    new RegExp(`(?:^|\\n)[ \\t]*${escaped} = ${value}`).exec(stdout)?.[1] ??
+    null
+  );
+}
+
+export function parseLaunchdJobPrint(stdout: string): LaunchdJobState {
+  const pid = launchdPrintField(stdout, "pid");
+  return {
+    loaded: true,
+    state: launchdPrintField(stdout, "state"),
+    pid: pid !== null && /^\d+$/.test(pid) ? Number(pid) : null,
+    lastExitCode: launchdPrintField(stdout, "last exit code"),
+    pendedNondemandSpawn: launchdPrintField(stdout, "pended nondemand spawn"),
+    detail: null,
+  };
+}
+
+/** One `launchctl print` of the host job, parsed. Read-only: safe to call
+ * from the running service (a boot after an activation logs it so a pended
+ * respawn is visible in the service log rather than only in `launchctl`). */
+export function describeLaunchdJob(execute: StepExecutor = executeStep): LaunchdJobState {
+  const result = execute(false, "launchctl", ["print", target]);
+  if (result.status !== 0) {
+    return {
+      loaded: false,
+      state: null,
+      pid: null,
+      lastExitCode: null,
+      pendedNondemandSpawn: null,
+      detail: resultDetail(result) || null,
+    };
+  }
+  return parseLaunchdJobPrint(result.stdout);
+}
+
+export function formatLaunchdJobState(job: LaunchdJobState): string {
+  if (!job.loaded) return `not loaded${job.detail ? ` (${job.detail})` : ""}`;
+  const parts = [`state = ${job.state ?? "unknown"}`];
+  if (job.pid !== null) parts.push(`pid = ${job.pid}`);
+  if (job.lastExitCode !== null) parts.push(`last exit code = ${job.lastExitCode}`);
+  if (job.pendedNondemandSpawn !== null) {
+    parts.push(`pended nondemand spawn = ${job.pendedNondemandSpawn}`);
+  }
+  return parts.join(", ");
+}
+
+async function status(): Promise<string> {
+  const job = describeLaunchdJob();
+  if (!job.loaded) return "not installed / not loaded";
+  return `${job.state ?? "unknown"}${job.pid !== null ? ` (pid ${job.pid})` : ""}`;
+}
+
+export const installer: Installer = {
+  install: installDarwinService,
+  uninstall: uninstallDarwinService,
+  start: startDarwinService,
+  stop: stopDarwinService,
+  stopForInstall: (installIntent, priorManager) =>
+    stopDarwinServiceForInstall(installIntent, priorManager),
+  resumeServiceForInstall: (installIntent, priorManager) =>
+    resumeDarwinServiceForInstall(installIntent, priorManager),
+  restart: restartDarwinService,
+  status,
+  reconcileDefinitionInstall: (installIntent) =>
+    reconcileDarwinDefinitionInstall({}, installIntent),
+  prepareDefinitionInstallRollback: (installIntent) =>
+    prepareDarwinDefinitionInstallRollback({}, installIntent),
+  resumeDefinitionInstallRollback: (installIntent) =>
+    resumeDarwinDefinitionInstallRollback({}, installIntent),
+  completeDefinitionInstall: (installIntent) =>
+    completeDarwinDefinitionInstall({}, installIntent),
+  definitionState: darwinDefinitionState,
+};