Skip to content
Python
32.6 KB
Raw Blame
import { spawn } from "node:child_process";
import { randomUUID } from "node:crypto";
import { constants, type Stats } from "node:fs";
import {
  access,
  type FileHandle,
  link,
  lstat,
  mkdir,
  open,
  realpath,
  rename,
  unlink,
} from "node:fs/promises";
import path from "node:path";
import {
  disableRuntimeService,
  enableRuntimeService,
  readRuntimeServiceOwner,
  runtimeServiceEnableMarkerPath,
} from "./service-ownership.js";
import type {
  RuntimeInstallLayout,
  RuntimeServicePlan,
} from "./service-plan.js";
import {
  planUserService,
  priorLaunchAgentDeclarations,
} from "./service-plan.js";

export type ServiceCommandRunner = (
  command: readonly string[],
) => Promise<void>;

/**
 * `disabled` is a distinct, durable OS state: `launchctl disable` records a
 * persistent override, after which `bootstrap` of the same label fails with
 * exit 5 and the job never loads (verified on macOS 15.1). It is NOT `absent`,
 * because installing over it would silently undo the user's or the system's
 * decision. Nothing here ever calls `launchctl enable`.
 */
export type ServiceRegistrationState =
  | "absent"
  | "managed"
  | "conflict"
  | "disabled";

export type ServiceRegistrationInspector = (
  plan: RuntimeServicePlan,
) => Promise<ServiceRegistrationState>;

interface ServiceOptions {
  uid?: number;
  xdgConfigHome?: string;
  runCommand?: ServiceCommandRunner;
  inspectRegistration?: ServiceRegistrationInspector;
  inspectLinuxState?: (
    serviceId: string,
  ) => Promise<{ code: number | null; stdout: string }>;
  platform?: NodeJS.Platform;
}

export async function installUserService(
  layout: RuntimeInstallLayout,
  options: ServiceOptions = {},
): Promise<RuntimeServicePlan> {
  return installUserServiceInternal(layout, options);
}

/** Internal safety harness for the future managed release implementation. */
export async function installUserServiceInternal(
  layout: RuntimeInstallLayout,
  options: ServiceOptions = {},
): Promise<RuntimeServicePlan> {
  const plan = planUserService(layout, options);
  if (plan.status !== "ready" || plan.service_file === null) {
    throw new Error(plan.blocked_reason ?? "runtime_service_plan_blocked");
  }
  if (layout.platform !== (options.platform ?? process.platform)) {
    throw new Error("runtime_service_platform_mismatch");
  }
  for (const required of [
    layout.nodeCommand,
    layout.runtimeEntry,
    layout.coreCommand,
    layout.mcpEntryPath,
    layout.recallCliPath,
    path.join(layout.syncHookAssetsDirectory, "manifest.json"),
  ]) {
    await access(required).catch(() => {
      throw new Error("runtime_service_install_root_not_ready");
    });
  }
  const target = plan.service_file.path;
  const parent = path.dirname(target);
  await mkdir(parent, { recursive: true, mode: 0o700 });
  const directory = await assertSafeParent(parent);
  const existing = await statIfPresent(target);
  const registration =
    layout.platform === "darwin"
      ? await inspectRegistration(
          plan,
          options.inspectRegistration ?? inspectLaunchAgentRegistration,
        )
      : "absent";
  if (registration === "conflict") {
    throw new Error("runtime_service_label_conflict");
  }
  // A disabled service must not be silently re-enabled. `bootstrap` would fail
  // with exit 5 anyway, but that generic error hides the real cause and invites
  // a caller to "fix" it by re-enabling, which is exactly what the product
  // forbids. Report the durable OS state instead.
  if (registration === "disabled") {
    throw new Error("runtime_service_disabled_by_system");
  }
  // The LaunchAgent redirects stdout/stderr into this directory; launchd will
  // not create it. Only do this once the label is known not to be a foreign
  // registration, so a conflict never leaves new artifacts behind.
  await prepareServiceLogDirectory(plan);
  const markerExisted = await statIfPresent(
    runtimeServiceEnableMarkerPath(layout.dataDir),
  );
  const run = options.runCommand ?? runServiceCommand;
  const content = plan.service_file.content;
  if (existing) {
    if (layout.platform !== "darwin") {
      throw new Error("runtime_service_file_exists");
    }
    if (registration === "absent") {
      const owner = await readRuntimeServiceOwner(layout.dataDir).catch(
        () => null,
      );
      if (owner === null) throw new Error("runtime_service_file_exists");
      await verifyFile(target, content, existing);
      await enableRuntimeService(layout.dataDir);
      try {
        await activateManagedDeclaration(
          target,
          content,
          parent,
          directory,
          run,
          plan.commands.install,
        );
      } catch (error) {
        if (markerExisted === null) {
          await disableRuntimeService(layout.dataDir).catch(() => undefined);
        }
        throw error;
      }
      return plan;
    }
    if (registration !== "managed") {
      throw new Error("runtime_service_file_exists");
    }
    try {
      await verifyFile(target, content, existing);
    } catch (currentError) {
      // A managed registration may still hold an earlier shipped declaration
      // (e.g. the LaunchAgent before stdout/stderr redirects existed). Migrate
      // it exactly; anything else is a user edit and must fail closed.
      const legacy = priorLaunchAgentDeclarations(layout);
      try {
        await verifyFileOneOf(target, legacy, existing);
      } catch {
        throw currentError;
      }
      await rewriteManagedDeclaration(
        target,
        content,
        legacy,
        existing,
        parent,
        directory,
      );
      await enableRuntimeService(layout.dataDir);
      try {
        // launchd keeps serving the declaration it loaded, so a changed plist is
        // only picked up by booting the job out and bootstrapping again.
        // `bootout` is allowed to fail because the label may not be loaded yet.
        // `enable` is deliberately not called: a system or user disable must
        // survive an upgrade instead of being silently undone.
        for (const command of plan.commands.stop) {
          await assertSafeParent(parent, directory);
          await runAllowedToFail(run, command);
          await assertSafeParent(parent, directory);
          await verifyFile(target, content, await lstat(target));
        }
        await activateManagedDeclaration(
          target,
          content,
          parent,
          directory,
          run,
          plan.commands.install,
        );
      } catch (error) {
        if (markerExisted === null) {
          await disableRuntimeService(layout.dataDir).catch(() => undefined);
        }
        throw error;
      }
      return plan;
    }
    await enableRuntimeService(layout.dataDir);
    try {
      for (const command of plan.commands.restart) {
        await assertSafeParent(parent, directory);
        await verifyFile(target, content, existing);
        await runCheckedCommand(run, command);
        await assertSafeParent(parent, directory);
        await verifyFile(target, content, existing);
      }
    } catch (error) {
      if (markerExisted === null) {
        await disableRuntimeService(layout.dataDir).catch(() => undefined);
      }
      throw error;
    }
    return plan;
  }
  const temporary = `${target}.${randomUUID()}.tmp`;
  const commands =
    registration === "managed" ? plan.commands.restart : plan.commands.install;
  let handle: FileHandle | undefined;
  let owned: Stats | undefined;
  let prepared = false;
  let published = false;
  let temporaryPresent = false;
  let markerEnabled = false;
  try {
    await assertSafeParent(parent, directory);
    handle = await open(
      temporary,
      constants.O_CREAT |
        constants.O_EXCL |
        constants.O_WRONLY |
        constants.O_NOFOLLOW,
      0o600,
    );
    temporaryPresent = true;
    await handle.chmod(0o600);
    owned = await handle.stat();
    await handle.writeFile(content, "utf8");
    await handle.sync();
    prepared = true;
    await assertSafeParent(parent, directory);
    await verifyFile(temporary, content, owned, 1);
    // Hard-link publication is atomic NOREPLACE; rename would overwrite a racer.
    await link(temporary, target);
    published = true;
    await assertSafeParent(parent, directory);
    await verifyFile(target, content, owned, 2);
    await verifyFile(temporary, content, owned, 2);
    await unlink(temporary);
    temporaryPresent = false;
    // Keep the post-publication handle state as the stable snapshot. The
    // pre-write/pre-link stat cannot prove that later commands left this exact
    // declaration untouched, while path metadata may still be stale on CephFS.
    owned = await handle.stat();
    await syncDirectory(parent, directory);
    await enableRuntimeService(layout.dataDir);
    markerEnabled = true;
    for (const command of commands) {
      await assertSafeParent(parent, directory);
      await verifyPublishedFile(target, content, handle, owned);
      await runCheckedCommand(run, command);
      await assertSafeParent(parent, directory);
      await verifyPublishedFile(target, content, handle, owned);
    }
    return plan;
  } catch (error) {
    // Unknown directory durability is not rollback success. Never uninstall an
    // OS service here: a failed command may have affected a pre-existing label.
    if (
      error instanceof Error &&
      error.message === "runtime_service_durability_unknown"
    )
      throw error;
    if (owned && prepared && handle) {
      await assertSafeParent(parent, directory);
      if (published) {
        if (temporaryPresent) {
          await verifyFile(target, content, owned, 2);
        } else {
          await verifyPublishedFile(target, content, handle, owned);
        }
        if (temporaryPresent) await verifyFile(temporary, content, owned, 2);
        await unlink(target);
      }
      if (temporaryPresent) {
        await verifyFile(temporary, content, owned);
        await unlink(temporary);
      }
      await syncDirectory(parent, directory);
    }
    if (markerEnabled && markerExisted === null) {
      await disableRuntimeService(layout.dataDir).catch(() => undefined);
    }
    throw error;
  } finally {
    await handle?.close();
  }
}

export async function uninstallUserService(
  layout: RuntimeInstallLayout,
  options: ServiceOptions = {},
): Promise<"removed" | "not-installed"> {
  const plan = planUserService(layout, options);
  if (plan.status !== "ready" || plan.service_file === null) {
    throw new Error(plan.blocked_reason ?? "runtime_service_plan_blocked");
  }
  if (layout.platform !== (options.platform ?? process.platform)) {
    throw new Error("runtime_service_platform_mismatch");
  }
  const target = plan.service_file.path;
  const info = await statIfPresent(target);
  if (info === null) {
    await disableRuntimeService(layout.dataDir);
    return "not-installed";
  }
  const parent = path.dirname(target);
  const directory = await assertSafeParent(parent);
  await verifyFile(target, plan.service_file.content, info);
  const run = options.runCommand ?? runServiceCommand;
  const marker = runtimeServiceEnableMarkerPath(layout.dataDir);
  const markerExisted = await statIfPresent(marker);
  await disableRuntimeService(layout.dataDir);
  try {
    for (const command of plan.commands.uninstall) {
      await assertSafeParent(parent, directory);
      await verifyFile(target, plan.service_file.content, info);
      // `launchctl bootout` fails with exit 5 for a label that is not currently
      // loaded (e.g. the user disabled the service, or it was already stopped and
      // booted out; verified on macOS 15.1). That is "already stopped", not a
      // failed uninstall. Tolerate it only when the job really is not loaded;
      // otherwise surface the failure instead of silently leaving a live job and
      // deleting its declaration.
      await uninstallBootout(run, command, plan, options.inspectLinuxState);
      await assertSafeParent(parent, directory);
      await verifyFile(target, plan.service_file.content, info);
    }
  } catch (error) {
    if (markerExisted !== null) {
      await enableRuntimeService(layout.dataDir).catch(() => undefined);
    }
    throw error;
  }
  await unlink(target);
  await syncDirectory(parent, directory);
  return "removed";
}

export async function restartUserService(
  layout: RuntimeInstallLayout,
  options: ServiceOptions = {},
): Promise<RuntimeServicePlan> {
  const plan = planUserService(layout, options);
  if (plan.status !== "ready" || plan.service_file === null) {
    throw new Error(plan.blocked_reason ?? "runtime_service_plan_blocked");
  }
  if (layout.platform !== (options.platform ?? process.platform)) {
    throw new Error("runtime_service_platform_mismatch");
  }
  const info = await statIfPresent(plan.service_file.path);
  if (!info?.isFile() || info.isSymbolicLink()) {
    throw new Error("runtime_service_not_installed");
  }
  const parent = path.dirname(plan.service_file.path);
  const directory = await assertSafeParent(parent);
  await verifyFile(plan.service_file.path, plan.service_file.content, info);
  const run = options.runCommand ?? runServiceCommand;
  for (const command of plan.commands.restart) {
    await assertSafeParent(parent, directory);
    await verifyFile(plan.service_file.path, plan.service_file.content, info);
    await runCheckedCommand(run, command);
    await assertSafeParent(parent, directory);
    await verifyFile(plan.service_file.path, plan.service_file.content, info);
  }
  return plan;
}

function sameIdentity(left: Stats, right: Stats): boolean {
  return (
    left.dev === right.dev &&
    left.ino === right.ino &&
    left.mode === right.mode &&
    left.uid === right.uid &&
    left.gid === right.gid
  );
}

async function statIfPresent(target: string): Promise<Stats | null> {
  try {
    return await lstat(target);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw error;
  }
}

/**
 * Atomically replace a managed declaration whose exact prior bytes are already
 * known, then re-check identity. Used only for an in-place migration of the
 * LaunchAgent to the current declaration shape.
 */
async function rewriteManagedDeclaration(
  target: string,
  content: string,
  accepted: readonly string[],
  before: Stats,
  parent: string,
  directory: Stats,
): Promise<void> {
  await assertSafeParent(parent, directory);
  await verifyFileOneOf(target, accepted, before);
  const temporary = `${target}.${randomUUID()}.migrate`;
  const handle = await open(
    temporary,
    constants.O_CREAT |
      constants.O_EXCL |
      constants.O_WRONLY |
      constants.O_NOFOLLOW,
    0o600,
  );
  let owned: Stats | undefined;
  try {
    await handle.chmod(0o600);
    owned = await handle.stat();
    await handle.writeFile(content, "utf8");
    await handle.sync();
  } finally {
    await handle.close();
  }
  try {
    await assertSafeParent(parent, directory);
    await verifyFile(temporary, content, owned, 1);
    await rename(temporary, target);
  } catch (error) {
    await lstat(temporary)
      .then((info) => (info.isFile() ? unlink(temporary) : undefined))
      .catch(() => undefined);
    throw error;
  }
  await assertSafeParent(parent, directory);
  await verifyFile(target, content, owned, 1);
  await syncDirectory(parent, directory);
}

async function activateManagedDeclaration(
  target: string,
  content: string,
  parent: string,
  directory: Stats,
  run: ServiceCommandRunner,
  commands: readonly string[][],
): Promise<void> {
  for (const command of commands) {
    await assertSafeParent(parent, directory);
    const info = await lstat(target);
    await verifyFile(target, content, info);
    await runCheckedCommand(run, command);
    await assertSafeParent(parent, directory);
    const after = await lstat(target);
    await verifyFile(target, content, after);
  }
}

/**
 * launchd refuses to start a LaunchAgent whose StandardOutPath/StandardErrorPath
 * parent does not exist, and it will not create the file itself. Prepare an
 * owner-only directory plus both files so a login start always has somewhere to
 * write, and so the redirect can never downgrade to a world-writable path.
 */
async function prepareServiceLogDirectory(
  plan: RuntimeServicePlan,
): Promise<void> {
  if (plan.log_directory === null) return;
  await mkdir(plan.log_directory, { recursive: true, mode: 0o700 });
  await assertSafeParent(plan.log_directory);
  for (const name of ["service.log", "service-error.log"]) {
    const target = path.join(plan.log_directory, name);
    try {
      const handle = await open(
        target,
        constants.O_CREAT |
          constants.O_EXCL |
          constants.O_WRONLY |
          constants.O_NOFOLLOW,
        0o600,
      );
      try {
        await handle.chmod(0o600);
      } finally {
        await handle.close();
      }
    } catch (error) {
      // A concurrent install may have created the file between our check and
      // the exclusive open; validate whatever is there instead of failing.
      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
    }
    const info = await statIfPresent(target);
    if (
      info === null ||
      !info.isFile() ||
      info.isSymbolicLink() ||
      (info.mode & 0o7777) !== 0o600 ||
      (typeof process.getuid === "function" && info.uid !== process.getuid())
    ) {
      throw new Error("runtime_service_log_unmanaged");
    }
  }
}

async function assertSafeParent(
  target: string,
  expected?: Stats,
): Promise<Stats> {
  const info = await lstat(target);
  if (
    !info.isDirectory() ||
    info.isSymbolicLink() ||
    (expected !== undefined && !sameIdentity(info, expected)) ||
    (process.platform !== "win32" &&
      ((info.mode & 0o022) !== 0 ||
        (typeof process.getuid === "function" &&
          info.uid !== process.getuid())))
  ) {
    throw new Error("runtime_service_directory_unsafe");
  }
  return info;
}

async function verifyFile(
  target: string,
  content: string,
  expected: Stats,
  links = 1,
): Promise<void> {
  await verifyFileOneOf(target, [content], expected, links);
}

/**
 * Accept any of several exact declarations. Used for the LaunchAgent, where a
 * managed registration may still hold a prior shipped declaration shape; the
 * installer then rewrites it. A declaration matching none of the accepted
 * shapes is a user edit and fails closed.
 */
async function verifyFileOneOf(
  target: string,
  contents: readonly string[],
  expected: Stats,
  links = 1,
): Promise<void> {
  const before = await lstat(target);
  if (
    !before.isFile() ||
    before.isSymbolicLink() ||
    (before.mode & 0o7777) !== 0o600 ||
    before.nlink !== links ||
    !sameIdentity(before, expected) ||
    (process.getuid && before.uid !== process.getuid())
  ) {
    throw new Error("runtime_service_file_unmanaged");
  }
  const file = await open(
    target,
    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
  );
  try {
    const opened = await file.stat();
    if (!opened.isFile() || !sameFileState(opened, before))
      throw new Error("runtime_service_file_unmanaged");
    const expectedBytes = contents.map((content) =>
      Buffer.from(content, "utf8"),
    );
    if (!expectedBytes.some((bytes) => bytes.length === opened.size))
      throw new Error("runtime_service_file_modified");
    const readLimit =
      Math.max(...expectedBytes.map((bytes) => bytes.length)) + 1;
    const bytes = Buffer.alloc(readLimit);
    let total = 0;
    while (total < bytes.length) {
      const { bytesRead } = await file.read({
        buffer: bytes,
        offset: total,
        length: bytes.length - total,
        position: total,
      });
      if (bytesRead === 0) break;
      total += bytesRead;
    }
    const finished = await file.stat();
    const after = await lstat(target);
    if (!sameFileState(finished, opened) || !sameFileState(after, opened))
      throw new Error("runtime_service_file_unmanaged");
    if (
      !expectedBytes.some(
        (candidate) =>
          total === candidate.length &&
          bytes.subarray(0, total).equals(candidate),
      )
    )
      throw new Error("runtime_service_file_modified");
  } finally {
    await file.close();
  }
}

/** Verify a declaration published from a file handle this process still owns.
 *
 * CephFS may briefly return stale link-count and ctime data from `lstat(path)`
 * after the temporary hard link is removed, even though `fstat(handle)` already
 * reports the authoritative single-link state. The open handle is stronger
 * identity evidence than path timestamps: while it remains open, a replacement
 * inode cannot reuse its dev/inode pair. Keep the path checks for type,
 * ownership, permissions and exact bytes, but take identity and link count from
 * the retained handle instead of guessing how quickly path metadata converges.
 */
async function verifyPublishedFile(
  target: string,
  content: string,
  ownedHandle: FileHandle,
  expected: Stats,
): Promise<void> {
  const authoritative = await ownedHandle.stat();
  if (
    !authoritative.isFile() ||
    authoritative.nlink !== 1 ||
    !sameFileState(authoritative, expected) ||
    (authoritative.mode & 0o7777) !== 0o600 ||
    (process.getuid && authoritative.uid !== process.getuid())
  ) {
    throw new Error("runtime_service_file_unmanaged");
  }
  const before = await lstat(target);
  if (
    !before.isFile() ||
    before.isSymbolicLink() ||
    !sameIdentity(before, authoritative) ||
    (before.mode & 0o7777) !== 0o600 ||
    (process.getuid && before.uid !== process.getuid())
  ) {
    throw new Error("runtime_service_file_unmanaged");
  }
  const file = await open(
    target,
    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
  );
  try {
    const opened = await file.stat();
    if (!opened.isFile() || !sameIdentity(opened, authoritative)) {
      throw new Error("runtime_service_file_unmanaged");
    }
    const expectedBytes = Buffer.from(content, "utf8");
    if (opened.size !== expectedBytes.length) {
      throw new Error("runtime_service_file_modified");
    }
    const bytes = Buffer.alloc(expectedBytes.length + 1);
    let total = 0;
    while (total < bytes.length) {
      const { bytesRead } = await file.read({
        buffer: bytes,
        offset: total,
        length: bytes.length - total,
        position: total,
      });
      if (bytesRead === 0) break;
      total += bytesRead;
    }
    const finished = await file.stat();
    const after = await lstat(target);
    const finalAuthoritative = await ownedHandle.stat();
    if (
      !sameIdentity(finished, authoritative) ||
      !sameIdentity(after, authoritative) ||
      !sameFileState(finalAuthoritative, authoritative) ||
      finalAuthoritative.nlink !== 1
    ) {
      throw new Error("runtime_service_file_unmanaged");
    }
    if (
      total !== expectedBytes.length ||
      !bytes.subarray(0, total).equals(expectedBytes)
    ) {
      throw new Error("runtime_service_file_modified");
    }
  } finally {
    await file.close();
  }
}

function sameFileState(left: Stats, right: Stats): boolean {
  return (
    sameIdentity(left, right) &&
    left.nlink === right.nlink &&
    left.size === right.size &&
    left.mtimeMs === right.mtimeMs &&
    left.ctimeMs === right.ctimeMs
  );
}

async function runCheckedCommand(
  run: ServiceCommandRunner,
  command: readonly string[],
): Promise<void> {
  try {
    await run(command);
  } catch {
    throw new Error("runtime_service_command_failed");
  }
}

/**
 * A bootout for a label that is not currently loaded is a no-op failure, not a
 * lost update. Callers must have already verified the declaration on disk.
 */
async function runAllowedToFail(
  run: ServiceCommandRunner,
  command: readonly string[],
): Promise<void> {
  try {
    await run(command);
  } catch {
    // Intentionally ignored: absence of the label is acceptable here.
  }
}

/** Run `bootout`, treating "not currently loaded" as success but never a
 * genuine failure. Only the exact managed declaration reaches this point.
 *
 * The re-probe asks the OS directly whether the job is loaded. A job that is
 * `disable`d but not loaded is the common case here (the user turned the
 * service off), and `bootout` reports that as exit 5. A job that is still
 * loaded after a failed `bootout` is a real failure and must surface.
 */
async function uninstallBootout(
  run: ServiceCommandRunner,
  command: readonly string[],
  plan: RuntimeServicePlan,
  inspectLinuxState?: (
    serviceId: string,
  ) => Promise<{ code: number | null; stdout: string }>,
): Promise<void> {
  try {
    await run(command);
    return;
  } catch (error) {
    if (
      plan.platform === "linux" &&
      command[0] === "systemctl" &&
      command.includes("disable") &&
      (await linuxServiceDisabledAndStopped(
        plan.service_id,
        inspectLinuxState ?? inspectLinuxServiceState,
      ))
    ) {
      return;
    }
    const domain = plan.commands.install[0]?.[2];
    if (plan.platform !== "darwin" || !domain) throw error;
    const probe = await runServiceProbe([
      "launchctl",
      "print",
      `${domain}/${plan.service_id}`,
    ]).catch(() => null);
    // 113 means the label is not loaded: nothing left to stop.
    if (probe?.code === 113) return;
    throw error;
  }
}

/** A failed `systemctl disable --now` may still have reached its exact target.
 *
 * systemd returns non-zero when the unit became absent while the command was
 * stopping/disabling it. Treat that as idempotent success only after two
 * independent probes agree that the unit is no longer enabled and no process
 * is active. Any enabled/active/unparseable state remains a hard failure, so a
 * live service declaration is never deleted on the strength of an exit code.
 */
async function linuxServiceDisabledAndStopped(
  serviceId: string,
  inspect: (
    serviceId: string,
  ) => Promise<{ code: number | null; stdout: string }>,
): Promise<boolean> {
  const state = await inspect(serviceId).catch(() => null);
  if (state?.code !== 0) return false;
  const properties = Object.fromEntries(
    state.stdout
      .split(/\r?\n/)
      .map((line) => line.split("=", 2))
      .filter((entry) => entry.length === 2),
  );
  const load = properties.LoadState?.toLowerCase();
  const unitFile = properties.UnitFileState?.toLowerCase();
  const active = properties.ActiveState?.toLowerCase();
  const disabled =
    load === "not-found" ||
    ["disabled", "masked", "not-found"].includes(unitFile ?? "");
  const stopped = ["inactive", "failed"].includes(active ?? "");
  return disabled && stopped;
}

async function inspectLinuxServiceState(
  serviceId: string,
): Promise<{ code: number | null; stdout: string }> {
  return runServiceProbe([
    "systemctl",
    "--user",
    "show",
    serviceId,
    "--property=LoadState",
    "--property=UnitFileState",
    "--property=ActiveState",
    "--no-pager",
  ]);
}

async function inspectLaunchAgentRegistration(
  plan: RuntimeServicePlan,
): Promise<ServiceRegistrationState> {
  if (plan.platform !== "darwin" || plan.service_file === null) return "absent";
  const domain = plan.commands.install[0]?.[2];
  if (!domain) throw new Error("runtime_service_inspection_failed");
  // A persistent `launchctl disable` override must be detected before we treat
  // the label as installable. `print` returns 113 for a disabled-but-unloaded
  // job, which would otherwise look exactly like `absent`; bootstrapping it
  // then fails with exit 5. Read the override table first so a disabled service
  // is never silently re-enabled or misreported as a fresh install.
  if (await launchAgentIsDisabled(domain, plan.service_id)) return "disabled";
  const result = await runServiceProbe([
    "launchctl",
    "print",
    `${domain}/${plan.service_id}`,
  ]);
  if (result.code === 113) return "absent";
  if (result.code !== 0) throw new Error("runtime_service_inspection_failed");
  // launchd reports the resolved plist path, which can differ textually from
  // the user-facing one (e.g. /private/var vs /var, symlinked HOME). Compare
  // real paths so a genuine managed registration is never misread as conflict.
  const wanted = await resolvedPath(plan.service_file.path);
  const declared = parseLaunchctlPlistPath(result.stdout);
  if (declared === null) return "conflict";
  return (await resolvedPath(declared)) === wanted ? "managed" : "conflict";
}

/** True when launchd currently records a `disable` override for this label.
 *
 * `launchctl print-disabled <domain>` exits 0 and lists every override as
 * `"<label>" => disabled|enabled`. Any failure to read the table is reported as
 * "not disabled" so the caller keeps its existing fail-closed behavior on the
 * subsequent `print`/`bootstrap` rather than inventing a state.
 */
async function launchAgentIsDisabled(
  domain: string,
  serviceId: string,
): Promise<boolean> {
  const result = await runServiceProbe(["launchctl", "print-disabled", domain]);
  if (result.code !== 0) return false;
  return parseDisabledOverride(result.stdout, serviceId);
}

/** Parse `launchctl print-disabled <domain>` output for one label.
 * A label absent from the table has no override and is treated as not disabled.
 */
export function parseDisabledOverride(
  stdout: string,
  serviceId: string,
): boolean {
  const quoted = `"${serviceId}"`;
  for (const line of stdout.split(/\r?\n/)) {
    const trimmed = line.trim();
    if (!trimmed.startsWith(quoted)) continue;
    const value = trimmed
      .slice(quoted.length)
      .replace(/^\s*=>\s*/, "")
      .trim();
    return value === "disabled";
  }
  return false;
}

/** Extract the `path = ...` line launchctl prints for a loaded job. */
export function parseLaunchctlPlistPath(stdout: string): string | null {
  for (const line of stdout.split(/\r?\n/)) {
    const trimmed = line.trim();
    if (!trimmed.startsWith("path = ")) continue;
    const value = trimmed.slice("path = ".length).trim();
    const unquoted =
      value.length >= 2 && value.startsWith('"') && value.endsWith('"')
        ? value.slice(1, -1)
        : value;
    if (unquoted.startsWith("/")) return unquoted;
  }
  return null;
}

async function resolvedPath(target: string): Promise<string> {
  return realpath(target).catch(() => target);
}

async function inspectRegistration(
  plan: RuntimeServicePlan,
  inspect: ServiceRegistrationInspector,
): Promise<ServiceRegistrationState> {
  try {
    const state = await inspect(plan);
    if (
      state === "absent" ||
      state === "managed" ||
      state === "conflict" ||
      state === "disabled"
    ) {
      return state;
    }
  } catch {
    // Registration probing is a trust boundary; never expose launchctl output.
  }
  throw new Error("runtime_service_inspection_failed");
}

async function runServiceProbe(
  command: readonly string[],
): Promise<{ code: number | null; stdout: string }> {
  const [program, ...args] = command;
  if (!program) throw new Error("runtime_service_inspection_failed");
  return new Promise((resolve, reject) => {
    const child = spawn(program, args, {
      shell: false,
      windowsHide: true,
      stdio: ["ignore", "pipe", "ignore"],
    });
    const chunks: Buffer[] = [];
    let size = 0;
    child.stdout.on("data", (chunk: Buffer) => {
      size += chunk.length;
      if (size > 64 * 1024) {
        child.kill();
        return;
      }
      chunks.push(chunk);
    });
    child.once("error", () =>
      reject(new Error("runtime_service_inspection_failed")),
    );
    child.once("close", (code) => {
      if (size > 64 * 1024) {
        reject(new Error("runtime_service_inspection_failed"));
        return;
      }
      resolve({ code, stdout: Buffer.concat(chunks).toString("utf8") });
    });
  });
}

async function syncDirectory(target: string, expected: Stats): Promise<void> {
  await assertSafeParent(target, expected);
  let directory: FileHandle;
  try {
    directory = await open(
      target,
      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
    );
  } catch {
    throw new Error("runtime_service_durability_unknown");
  }
  try {
    if (!sameIdentity(await directory.stat(), expected))
      throw new Error("runtime_service_directory_unsafe");
    try {
      await directory.sync();
    } catch {
      throw new Error("runtime_service_durability_unknown");
    }
    await assertSafeParent(target, expected);
  } finally {
    await directory.close();
  }
}

async function runServiceCommand(command: readonly string[]): Promise<void> {
  const [program, ...args] = command;
  if (!program) throw new Error("runtime_service_command_invalid");
  await new Promise<void>((resolve, reject) => {
    const child = spawn(program, args, {
      shell: false,
      windowsHide: true,
      stdio: "ignore",
    });
    child.once("error", () =>
      reject(new Error("runtime_service_command_failed")),
    );
    child.once("exit", (code) => {
      if (code === 0) resolve();
      else reject(new Error("runtime_service_command_failed"));
    });
  });
}