@runuai/host 0.9.14 → 0.9.43

package/scripts/install/darwin.ts

@@ -7,12 +7,31 @@
  * docker/git resolve); .env.local is loaded by the host process itself.
  */
 
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readlinkSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 
-import type { InstallContext, Installer } from "./types";
-import { escapeXml, printFile, step } from "./util";
+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 = "com.runuai.host";
 
@@ -25,6 +44,10 @@ 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[];
@@ -33,6 +56,7 @@ export interface PlistInputs {
   home: string;
   outLog: string;
   errLog: string;
+  runAtLoad?: boolean;
 }
 
 export function renderPlist(p: PlistInputs): string {
@@ -59,7 +83,7 @@ ${progArgs}
     <string>${escapeXml(p.home)}</string>
   </dict>
   <key>RunAtLoad</key>
-  <true/>
+  <${p.runAtLoad === false ? "false" : "true"}/>
   <key>KeepAlive</key>
   <true/>
   <key>ThrottleInterval</key>
@@ -73,35 +97,106 @@ ${progArgs}
 `;
 }
 
-function inputs(ctx: InstallContext): PlistInputs {
+function inputs(ctx: InstallContext, logs = logDir): PlistInputs {
   return {
     execPath: ctx.execPath,
     args: ctx.args,
     cwd: ctx.cwd,
-    path: process.env.PATH ?? "",
+    path: ctx.envPath ?? process.env.PATH ?? "",
     home: homedir(),
-    outLog: resolve(logDir, "host.out.log"),
-    errLog: resolve(logDir, "host.log"),
+    outLog: resolve(logs, "host.out.log"),
+    errLog: resolve(logs, "host.log"),
+    runAtLoad: ctx.startOnInstall !== false,
   };
 }
 
-async function install(ctx: InstallContext): Promise<void> {
-  const plist = renderPlist(inputs(ctx));
+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(plistPath(), plist);
-    step(true, "mkdir", ["-p", logDir]);
+    printFile(definition, plist);
+    step(true, "mkdir", ["-p", logs]);
     step(true, "launchctl", ["bootout", target]);
-    step(true, "launchctl", ["bootstrap", domain, plistPath()]);
-    step(true, "launchctl", ["enable", target]);
+    if (ctx.startOnInstall !== false) {
+      step(true, "launchctl", ["bootstrap", domain, definition]);
+      await enableDarwinService(true);
+    } else {
+      step(true, "launchctl", ["disable", target]);
+    }
     return;
   }
-  mkdirSync(logDir, { recursive: true });
-  mkdirSync(dirname(plistPath()), { recursive: true });
-  writeFileSync(plistPath(), plist);
-  // Reload cleanly: bootout any prior instance (ignore "not loaded"), bootstrap.
-  step(false, "launchctl", ["bootout", target], { ignoreError: true });
-  await bootstrapWithRetry();
-  step(false, "launchctl", ["enable", target], { ignoreError: true });
+  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;
+  }
 }
 
 /**
@@ -109,44 +204,734 @@ async function install(ctx: InstallContext): Promise<void> {
  * 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(): Promise<void> {
-  let lastErr: unknown;
+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) {
-    try {
-      step(false, "launchctl", ["bootstrap", domain, plistPath()]);
-      return;
-    } catch (err) {
-      lastErr = err;
-      await new Promise((resolve) => setTimeout(resolve, 500));
+    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");
   }
-  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+  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);
 }
 
-async function uninstall(dryRun = false): Promise<void> {
-  step(dryRun, "launchctl", ["bootout", target], { ignoreError: true });
+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(),
+    ".uai-host",
+    "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(),
+    ".uai-host",
+    "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;
   }
-  rmSync(plistPath(), { force: true });
+  (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);
 }
 
-async function start(dryRun = false): Promise<void> {
-  // bootstrap loads + RunAtLoad starts; if already loaded that errors, so also
-  // kickstart to be sure it's running.
-  step(dryRun, "launchctl", ["bootstrap", domain, plistPath()], {
-    ignoreError: true,
-  });
-  step(dryRun, "launchctl", ["kickstart", target], { ignoreError: true });
+export async function stopDarwinService(
+  dryRun = false,
+  deps: DarwinServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileDarwinDefinitionInstall(deps);
+  await assertLaunchdUnloaded(
+    dryRun,
+    deps.execute ?? executeStep,
+    deps.delay ?? defaultDelay,
+  );
 }
 
-async function stop(dryRun = false): Promise<void> {
-  step(dryRun, "launchctl", ["bootout", target], { ignoreError: true });
+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,
+  );
 }
 
-async function restart(dryRun = false): Promise<void> {
-  step(dryRun, "launchctl", ["kickstart", "-k", target], { ignoreError: true });
+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);
+  }
 }
 
 async function status(): Promise<string> {
@@ -158,10 +943,23 @@ async function status(): Promise<string> {
 }
 
 export const installer: Installer = {
-  install,
-  uninstall,
-  start,
-  stop,
-  restart,
+  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,
 };