@runuai/host 0.9.13 → 0.9.42

package/scripts/install/linux.ts

@@ -10,12 +10,30 @@
  * dedicated headless server a system unit + service user would be the move.
  */
 
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { lstatSync, mkdirSync, readlinkSync, rmSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { basename, dirname, resolve } from "node:path";
 
-import type { InstallContext, Installer } from "./types";
-import { printFile, step } from "./util";
+import type {
+  InstallContext,
+  Installer,
+  ServiceDefinitionState,
+  ServiceManagerState,
+} from "./types";
+import {
+  executeStep,
+  printFile,
+  readPrivateJournal,
+  removeFileDurable,
+  restoreDefinitionDurable,
+  snapshotDefinition,
+  step,
+  stepFailure,
+  writeDefinitionDurable,
+  type DirectorySync,
+  type StepExecutor,
+  type StepResult,
+} from "./util";
 
 export const UNIT = "uai-host.service";
 
@@ -23,6 +41,10 @@ export function unitPath(): string {
   return resolve(homedir(), ".config", "systemd", "user", UNIT);
 }
 
+export function linuxInstallJournalPath(definition = unitPath()): string {
+  return resolve(dirname(definition), `.${basename(definition)}.install-journal.json`);
+}
+
 export interface UnitInputs {
   execPath: string;
   args: string[];
@@ -30,8 +52,18 @@ export interface UnitInputs {
   path: string;
 }
 
+function systemdQuote(value: string): string {
+  if (/[\n\r\0]/.test(value)) {
+    throw new Error("systemd service values must not contain control characters");
+  }
+  return `"${value
+    .replace(/%/g, "%%")
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')}"`;
+}
+
 export function renderUnit(p: UnitInputs): string {
-  const exec = [p.execPath, ...p.args].join(" ");
+  const exec = [p.execPath, ...p.args].map(systemdQuote).join(" ");
   return `[Unit]
 Description=Uai host service (ADR-028)
 After=network-online.target
@@ -39,8 +71,8 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=${p.cwd}
-Environment=PATH=${p.path}
+WorkingDirectory=${systemdQuote(p.cwd)}
+Environment=${systemdQuote(`PATH=${p.path}`)}
 ExecStart=${exec}
 Restart=on-failure
 RestartSec=10
@@ -55,47 +87,805 @@ function inputs(ctx: InstallContext): UnitInputs {
     execPath: ctx.execPath,
     args: ctx.args,
     cwd: ctx.cwd,
-    path: process.env.PATH ?? "",
+    path: ctx.envPath ?? process.env.PATH ?? "",
   };
 }
 
-async function install(ctx: InstallContext): Promise<void> {
+export interface LinuxInstallDeps extends LinuxServiceDeps {
+}
+
+export async function installLinuxService(
+  ctx: InstallContext,
+  deps: LinuxInstallDeps = {},
+): Promise<void> {
+  const execute = deps.execute ?? executeStep;
   const unit = renderUnit(inputs(ctx));
+  const definition = deps.definitionPath ?? unitPath();
   if (ctx.dryRun) {
-    printFile(unitPath(), unit);
-    step(true, "systemctl", ["--user", "daemon-reload"]);
-    step(true, "systemctl", ["--user", "enable", "--now", UNIT]);
+    await ensureLinuxLinger(true, deps);
+    printFile(definition, unit);
+    execute(true, "systemctl", ["--user", "daemon-reload"]);
+    execute(
+      true,
+      "systemctl",
+      ctx.startOnInstall === false
+        ? ["--user", "disable", "--now", UNIT]
+        : ["--user", "enable", "--now", UNIT],
+    );
     return;
   }
-  mkdirSync(dirname(unitPath()), { recursive: true });
-  writeFileSync(unitPath(), unit);
-  step(false, "systemctl", ["--user", "daemon-reload"]);
-  step(false, "systemctl", ["--user", "enable", "--now", UNIT]);
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const installIntent = ctx.definitionInstallIntent;
+  assertDefinitionInstallIntent(installIntent);
+  await reconcileLinuxDefinitionInstall(
+    { ...deps, definitionPath: definition, journalPath },
+    installIntent?.nonce,
+  );
+  await ensureLinuxLinger(false, deps);
+  mkdirSync(dirname(definition), { recursive: true });
+  const previous = snapshotDefinition(definition);
+  const manager = inspectSystemdState(execute);
+  if (!previous.exists && (manager.active || manager.enabled)) {
+    throw new Error("systemd reports the host unit active/enabled without a recoverable unit file");
+  }
+  const journal: LinuxInstallJournal = {
+    schemaVersion: 1,
+    phase: "installed",
+    installIntent: installIntent ?? null,
+    prior: serializeDefinition(previous),
+    manager,
+  };
+  writeDefinitionDurable(journalPath, `${JSON.stringify(journal)}\n`, 0o600);
+  try {
+    writeDefinitionDurable(
+      definition,
+      unit,
+      0o644,
+      deps.definitionDirectorySync,
+    );
+    strictStep(execute, "systemctl", ["--user", "daemon-reload"]);
+    strictStep(
+      execute,
+      "systemctl",
+      ctx.startOnInstall === false
+        ? ["--user", "disable", "--now", UNIT]
+        : ["--user", "enable", "--now", UNIT],
+    );
+    if (!installIntent) removeFileDurable(journalPath);
+  } catch (error) {
+    try {
+      const rollbackDeps = {
+        ...deps,
+        definitionPath: definition,
+        journalPath,
+      };
+      if (installIntent) {
+        await prepareLinuxDefinitionInstallRollback(
+          rollbackDeps,
+          installIntent.nonce,
+        );
+      } else {
+        await reconcileLinuxDefinitionInstall(rollbackDeps);
+      }
+    } catch (rollbackError) {
+      throw new Error(
+        `${errorMessage(error)}; service-definition rollback failed: ${errorMessage(rollbackError)}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
 }
 
-async function uninstall(dryRun = false): Promise<void> {
-  step(dryRun, "systemctl", ["--user", "disable", "--now", UNIT], {
-    ignoreError: true,
-  });
+export interface LinuxServiceDeps {
+  execute?: StepExecutor;
+  removeFile?: (path: string) => void;
+  username?: string;
+  definitionPath?: string;
+  journalPath?: string;
+  definitionDirectorySync?: DirectorySync;
+}
+
+const STOPPED_SYSTEMD_STATES = new Set(["inactive", "failed", "unknown"]);
+const ACTIVE_SYSTEMD_STATES = new Set([
+  "active",
+  "activating",
+  "reloading",
+  "deactivating",
+]);
+const DISABLED_SYSTEMD_STATES = new Set([
+  "disabled",
+  "static",
+  "indirect",
+  "generated",
+  "transient",
+  "not-found",
+  "masked",
+]);
+
+interface LinuxInstallJournal {
+  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 active: 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>,
+): LinuxInstallJournal["prior"] {
+  return snapshot.exists
+    ? {
+        exists: true,
+        bytesBase64: snapshot.bytes.toString("base64"),
+        mode: snapshot.mode,
+      }
+    : { exists: false };
+}
+
+function parseLinuxInstallJournal(raw: string): LinuxInstallJournal {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("systemd service install journal is invalid");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("systemd 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("systemd 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") !== ["active", "enabled"].join("\0") ||
+    typeof manager.active !== "boolean" ||
+    typeof manager.enabled !== "boolean" ||
+    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("systemd service install journal is invalid");
+  }
+  if (prior.exists === false) {
+    if (
+      Object.keys(prior).join("\0") !== "exists" ||
+      manager.active ||
+      manager.enabled
+    ) {
+      throw new Error("systemd service install journal is invalid");
+    }
+    return {
+      schemaVersion: 1,
+      phase: record.phase,
+      installIntent: installIntent as LinuxInstallJournal["installIntent"],
+      prior: { exists: false },
+      manager: manager as LinuxInstallJournal["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("systemd service install journal is invalid");
+  }
+  const bytes = Buffer.from(prior.bytesBase64, "base64");
+  if (bytes.toString("base64") !== prior.bytesBase64) {
+    throw new Error("systemd service install journal is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    phase: record.phase,
+    installIntent: installIntent as LinuxInstallJournal["installIntent"],
+    prior: {
+      exists: true,
+      bytesBase64: prior.bytesBase64,
+      mode: prior.mode,
+    },
+    manager: manager as LinuxInstallJournal["manager"],
+  };
+}
+
+function inspectSystemdState(execute: StepExecutor): {
+  active: boolean;
+  enabled: boolean;
+} {
+  const activeArgs = ["--user", "is-active", UNIT];
+  const activeResult = execute(false, "systemctl", activeArgs);
+  const activeState = activeResult.stdout.trim();
+  if (typeof activeResult.status !== "number") {
+    throw stepFailure(
+      "systemctl",
+      activeArgs,
+      activeResult,
+      "could not determine prior unit activity",
+    );
+  }
+  const active = ACTIVE_SYSTEMD_STATES.has(activeState);
+  if (!active && !STOPPED_SYSTEMD_STATES.has(activeState)) {
+    throw stepFailure(
+      "systemctl",
+      activeArgs,
+      activeResult,
+      "could not determine prior unit activity",
+    );
+  }
+
+  const enabledArgs = ["--user", "is-enabled", UNIT];
+  const enabledResult = execute(false, "systemctl", enabledArgs);
+  const enabledState = enabledResult.stdout.trim();
+  if (typeof enabledResult.status !== "number") {
+    throw stepFailure(
+      "systemctl",
+      enabledArgs,
+      enabledResult,
+      "could not determine prior unit enablement",
+    );
+  }
+  const enabled = enabledResult.status === 0 && enabledState === "enabled";
+  if (!enabled && !DISABLED_SYSTEMD_STATES.has(enabledState)) {
+    throw stepFailure(
+      "systemctl",
+      enabledArgs,
+      enabledResult,
+      "could not determine prior unit enablement",
+    );
+  }
+  return { active, enabled };
+}
+
+function strictStep(execute: StepExecutor, command: string, args: string[]): void {
+  const result = execute(false, command, args);
+  if (result.status !== 0) throw stepFailure(command, args, result);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function lingerIsEnabled(result: StepResult): boolean {
+  return result.status === 0 && result.stdout.trim().toLowerCase() === "yes";
+}
+
+export async function ensureLinuxLinger(
+  dryRun = false,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  const execute = deps.execute ?? executeStep;
+  const username = deps.username ?? userInfo().username;
+  const showArgs = ["show-user", username, "-p", "Linger", "--value"];
+  const initial = execute(dryRun, "loginctl", showArgs);
+  if (dryRun) {
+    execute(true, "loginctl", ["enable-linger", username]);
+    execute(true, "loginctl", showArgs);
+    return;
+  }
+  if (lingerIsEnabled(initial)) return;
+
+  const enableArgs = ["enable-linger", username];
+  const enabled = execute(false, "loginctl", enableArgs);
+  const adminGuidance =
+    `ask an administrator to run: sudo loginctl enable-linger ${username}`;
+  if (enabled.status !== 0) {
+    throw stepFailure("loginctl", enableArgs, enabled, adminGuidance);
+  }
+
+  const verified = execute(false, "loginctl", showArgs);
+  if (!lingerIsEnabled(verified)) {
+    throw new Error(
+      `loginctl did not confirm reboot persistence for uai-host; ${adminGuidance}`,
+    );
+  }
+}
+
+function probeConfirmsStopped(result: StepResult): boolean {
+  return (
+    typeof result.status === "number" &&
+    result.status !== 0 &&
+    STOPPED_SYSTEMD_STATES.has(result.stdout.trim())
+  );
+}
+
+function assertSystemdStopped(
+  dryRun: boolean,
+  actionArgs: string[],
+  execute: StepExecutor,
+): void {
+  const result = execute(dryRun, "systemctl", actionArgs);
+  if (result.status === 0 || dryRun) return;
+
+  const probeArgs = ["--user", "is-active", UNIT];
+  const probe = execute(false, "systemctl", probeArgs);
+  if (probeConfirmsStopped(probe)) return;
+
+  const probeDetail = (
+    probe.stderr ||
+    probe.stdout ||
+    probe.error?.message ||
+    `exit status ${String(probe.status)}`
+  ).trim();
+  throw stepFailure(
+    "systemctl",
+    actionArgs,
+    result,
+    `could not verify that the service stopped: ${probeDetail}`,
+  );
+}
+
+export async function reconcileLinuxDefinitionInstall(
+  deps: LinuxInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseLinuxInstallJournal(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 prepareLinuxDefinitionInstallRollback(deps);
+  await resumeLinuxDefinitionInstallRollback(deps);
+}
+
+export async function prepareLinuxDefinitionInstallRollback(
+  deps: LinuxInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseLinuxInstallJournal(raw);
+  assertJournalAccess(journal.installIntent, installIntent);
+  const execute = deps.execute ?? executeStep;
+
+  assertSystemdStopped(false, ["--user", "stop", UNIT], 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);
+  // Persist the disabled state before restoring a definition which may still
+  // point through a shared shim. A reboot in the restore/fsync window cannot
+  // launch it until runtime-command rollback has completed.
+  assertSystemdDisabledForRollback(execute, !prior.exists);
+  restoreDefinitionDurable(definition, prior, deps.definitionDirectorySync);
+  strictStep(execute, "systemctl", ["--user", "daemon-reload"]);
+
+  if (journal.phase !== "definition-restored") {
+    writeDefinitionDurable(
+      journalPath,
+      `${JSON.stringify({ ...journal, phase: "definition-restored" })}\n`,
+      0o600,
+    );
+  }
+}
+
+function assertSystemdDisabledForRollback(
+  execute: StepExecutor,
+  allowMissing: boolean,
+): void {
+  const disableArgs = ["--user", "disable", UNIT];
+  const disabled = execute(false, "systemctl", disableArgs);
+  if (disabled.status === 0) return;
+  if (allowMissing) {
+    const probeArgs = ["--user", "is-enabled", UNIT];
+    const probe = execute(false, "systemctl", probeArgs);
+    if (
+      probe.status !== 0 &&
+      DISABLED_SYSTEMD_STATES.has(probe.stdout.trim())
+    ) {
+      return;
+    }
+  }
+  throw stepFailure(
+    "systemctl",
+    disableArgs,
+    disabled,
+    "could not durably disable the replacement service before rollback",
+  );
+}
+
+export async function resumeLinuxDefinitionInstallRollback(
+  deps: LinuxInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseLinuxInstallJournal(raw);
+  assertJournalAccess(journal.installIntent, installIntent);
+  if (journal.phase !== "definition-restored") {
+    throw new Error("systemd service definition rollback has not been prepared");
+  }
+  const execute = deps.execute ?? executeStep;
+
+  // Nothing may launch between restoring the command graph and resuming the
+  // recorded predecessor, so reassert the stopped boundary first.
+  assertSystemdStopped(false, ["--user", "stop", UNIT], 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);
+  strictStep(execute, "systemctl", ["--user", "daemon-reload"]);
+  if (prior.exists) {
+    strictStep(execute, "systemctl", [
+      "--user",
+      journal.manager.enabled ? "enable" : "disable",
+      UNIT,
+    ]);
+  }
+  if (journal.manager.active) {
+    strictStep(execute, "systemctl", ["--user", "start", UNIT]);
+  }
+  removeFileDurable(journalPath);
+}
+
+export async function completeLinuxDefinitionInstall(
+  deps: LinuxInstallDeps = {},
+  installIntent?: string,
+): Promise<void> {
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw === null) return;
+  const journal = parseLinuxInstallJournal(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: LinuxInstallJournal["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 linuxDefinitionState(
+  managedCommand: string,
+  definition = unitPath(),
+  expectedManagedTarget = resolve(
+    homedir(),
+    ".uai-host",
+    "runtime",
+    "current",
+    "bin",
+    "uai-host",
+  ),
+  execute: StepExecutor = executeStep,
+): Promise<ServiceDefinitionState> {
+  const snapshot = snapshotDefinition(definition);
+  const loadedCommand = inspectSystemdLoadedCommand(execute, managedCommand);
+  if (!snapshot.exists && loadedCommand.loaded) {
+    throw new Error(
+      "systemd reports the host unit loaded without a recoverable unit file",
+    );
+  }
+  if (!snapshot.exists) {
+    return {
+      ownership: "missing",
+      manager: { loaded: false, active: false, enabled: false },
+    };
+  }
+  const managerState = inspectSystemdState(execute);
+  const manager: ServiceManagerState = {
+    loaded: loadedCommand.loaded,
+    active: managerState.active,
+    enabled: managerState.enabled,
+  };
+  const execStarts = snapshot.bytes
+    .toString("utf8")
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("ExecStart="));
+  const expected = `ExecStart=${[managedCommand, "run"].map(systemdQuote).join(" ")}`;
+  if (
+    execStarts.length === 1 &&
+    execStarts[0] === expected &&
+    managedCommandIsOwned(managedCommand, expectedManagedTarget) &&
+    loadedCommand.matches !== false
+  ) {
+    return { ownership: "managed", manager };
+  }
+  return { ownership: "legacy", manager };
+}
+
+export async function linuxDefinitionOwnership(
+  managedCommand: string,
+  definition = unitPath(),
+  expectedManagedTarget = resolve(
+    homedir(),
+    ".uai-host",
+    "runtime",
+    "current",
+    "bin",
+    "uai-host",
+  ),
+  execute: StepExecutor = executeStep,
+): Promise<"missing" | "managed" | "legacy"> {
+  return (
+    await linuxDefinitionState(
+      managedCommand,
+      definition,
+      expectedManagedTarget,
+      execute,
+    )
+  ).ownership;
+}
+
+function inspectSystemdLoadedCommand(
+  execute: StepExecutor,
+  managedCommand: string,
+): { loaded: boolean; matches: boolean | null } {
+  const loadArgs = ["--user", "show", UNIT, "--property=LoadState", "--value"];
+  const load = execute(false, "systemctl", loadArgs);
+  const loadState = load.stdout.trim();
+  if (typeof load.status !== "number") {
+    throw stepFailure(
+      "systemctl",
+      loadArgs,
+      load,
+      "could not determine the loaded host command",
+    );
+  }
+  if (load.status !== 0) {
+    if (/not[- ]found|could not be found|no such (?:file|unit)/i.test(
+      `${load.stdout}\n${load.stderr}`,
+    )) {
+      return { loaded: false, matches: null };
+    }
+    throw stepFailure(
+      "systemctl",
+      loadArgs,
+      load,
+      "could not determine the loaded host command",
+    );
+  }
+  if (loadState === "not-found") return { loaded: false, matches: null };
+  if (loadState !== "loaded") return { loaded: false, matches: false };
+
+  const execArgs = ["--user", "show", UNIT, "--property=ExecStart", "--value"];
+  const result = execute(false, "systemctl", execArgs);
+  if (typeof result.status !== "number") {
+    throw stepFailure(
+      "systemctl",
+      execArgs,
+      result,
+      "could not determine the loaded host command",
+    );
+  }
+  if (result.status !== 0) {
+    throw stepFailure(
+      "systemctl",
+      execArgs,
+      result,
+      "could not determine the loaded host command",
+    );
+  }
+  const records = [
+    ...result.stdout.matchAll(
+      /\{\s*path=([^;]*?)\s*;\s*argv\[\]=([^;]*?)\s*;/g,
+    ),
+  ];
+  return {
+    loaded: true,
+    matches:
+      records.length === 1 &&
+      records[0]?.[1] === managedCommand &&
+      records[0]?.[2] === `${managedCommand} run`,
+  };
+}
+
+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 uninstallLinuxService(
+  dryRun = false,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileLinuxDefinitionInstall(deps);
+  const execute = deps.execute ?? executeStep;
+  assertSystemdStopped(
+    dryRun,
+    ["--user", "disable", "--now", UNIT],
+    execute,
+  );
   if (dryRun) {
     console.log(`$ rm -f ${unitPath()}`);
-    step(true, "systemctl", ["--user", "daemon-reload"]);
+    execute(true, "systemctl", ["--user", "daemon-reload"]);
     return;
   }
-  rmSync(unitPath(), { force: true });
-  step(false, "systemctl", ["--user", "daemon-reload"], { ignoreError: true });
+  (deps.removeFile ?? ((path) => rmSync(path, { force: true })))(
+    deps.definitionPath ?? unitPath(),
+  );
+  const reloadArgs = ["--user", "daemon-reload"];
+  const reload = execute(false, "systemctl", reloadArgs);
+  if (reload.status !== 0) {
+    throw stepFailure("systemctl", reloadArgs, reload);
+  }
+}
+
+export async function startLinuxService(
+  dryRun = false,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileLinuxDefinitionInstall(deps);
+  const args = ["--user", "enable", "--now", UNIT];
+  const result = (deps.execute ?? executeStep)(dryRun, "systemctl", args);
+  if (result.status !== 0) throw stepFailure("systemctl", args, result);
+}
+
+export async function stopLinuxService(
+  dryRun = false,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileLinuxDefinitionInstall(deps);
+  assertSystemdStopped(
+    dryRun,
+    ["--user", "stop", UNIT],
+    deps.execute ?? executeStep,
+  );
+}
+
+export async function stopLinuxServiceForInstall(
+  installIntent: string,
+  priorManager: ServiceManagerState,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  assertServiceManagerState(priorManager);
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw !== null) {
+    const journal = parseLinuxInstallJournal(raw);
+    assertJournalAccess(journal.installIntent, installIntent);
+  }
+  // Disable before stopping so a pending automatic restart or reboot cannot
+  // relaunch the legacy definition after quiescence is durably acknowledged.
+  strictStep(deps.execute ?? executeStep, "systemctl", [
+    "--user",
+    "disable",
+    UNIT,
+  ]);
+  assertSystemdStopped(
+    false,
+    ["--user", "stop", UNIT],
+    deps.execute ?? executeStep,
+  );
 }
 
-async function start(dryRun = false): Promise<void> {
-  step(dryRun, "systemctl", ["--user", "start", UNIT]);
+export async function resumeLinuxServiceForInstall(
+  installIntent: string,
+  priorManager: ServiceManagerState,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  assertServiceManagerState(priorManager);
+  const definition = deps.definitionPath ?? unitPath();
+  const journalPath = deps.journalPath ?? linuxInstallJournalPath(definition);
+  const raw = readPrivateJournal(journalPath);
+  if (raw !== null) {
+    const journal = parseLinuxInstallJournal(raw);
+    assertJournalAccess(journal.installIntent, installIntent);
+    if (journal.phase === "installed") {
+      throw new Error("cannot resume the prior service before definition rollback");
+    }
+    await resumeLinuxDefinitionInstallRollback(deps, installIntent);
+  }
+  const execute = deps.execute ?? executeStep;
+  strictStep(execute, "systemctl", [
+    "--user",
+    priorManager.enabled ? "enable" : "disable",
+    UNIT,
+  ]);
+  if (priorManager.active) {
+    strictStep(execute, "systemctl", ["--user", "start", UNIT]);
+  }
 }
 
-async function stop(dryRun = false): Promise<void> {
-  step(dryRun, "systemctl", ["--user", "stop", UNIT], { ignoreError: true });
+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");
+  }
 }
 
-async function restart(dryRun = false): Promise<void> {
-  step(dryRun, "systemctl", ["--user", "restart", UNIT]);
+export async function restartLinuxService(
+  dryRun = false,
+  deps: LinuxServiceDeps = {},
+): Promise<void> {
+  if (!dryRun) await reconcileLinuxDefinitionInstall(deps);
+  const args = ["--user", "restart", UNIT];
+  const result = (deps.execute ?? executeStep)(dryRun, "systemctl", args);
+  if (result.status !== 0) throw stepFailure("systemctl", args, result);
 }
 
 async function status(): Promise<string> {
@@ -106,10 +896,23 @@ async function status(): Promise<string> {
 }
 
 export const installer: Installer = {
-  install,
-  uninstall,
-  start,
-  stop,
-  restart,
+  install: installLinuxService,
+  uninstall: uninstallLinuxService,
+  start: startLinuxService,
+  stop: stopLinuxService,
+  stopForInstall: (installIntent, priorManager) =>
+    stopLinuxServiceForInstall(installIntent, priorManager),
+  resumeServiceForInstall: (installIntent, priorManager) =>
+    resumeLinuxServiceForInstall(installIntent, priorManager),
+  restart: restartLinuxService,
   status,
+  reconcileDefinitionInstall: (installIntent) =>
+    reconcileLinuxDefinitionInstall({}, installIntent),
+  prepareDefinitionInstallRollback: (installIntent) =>
+    prepareLinuxDefinitionInstallRollback({}, installIntent),
+  resumeDefinitionInstallRollback: (installIntent) =>
+    resumeLinuxDefinitionInstallRollback({}, installIntent),
+  completeDefinitionInstall: (installIntent) =>
+    completeLinuxDefinitionInstall({}, installIntent),
+  definitionState: linuxDefinitionState,
 };