@homeflare/alchemy 0.5.0 → 0.7.0

package/src/launchd/job-validate.ts

@@ -0,0 +1,134 @@
+/**
+ * Everything LaunchdJob refuses before it touches the host. Run at plan time (diff) and again at
+ * reconcile, so a bad declaration fails the plan instead of half-applying.
+ *
+ * ★ REFUSE WHAT launchd WOULD SILENTLY IGNORE OR MISREAD. launchd loads a plist with an out-of-range
+ *   calendar field or a UserName on an agent without complaint and then simply never does what the
+ *   declaration says; a plan that fails is cheaper than a job that quietly does nothing.
+ */
+import {
+  type CalendarInterval,
+  type LaunchdJobProps,
+  OWNED_KEYS,
+  parseDomain,
+} from './job-form.ts';
+import { jobSecretProblems } from './secret-tripwire.ts';
+
+/** ★ Labels become file names: no `/`, no leading dot, nothing a path could re-interpret. */
+const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+
+/**
+ * ⛔ LABELS OTHER TOOLS OWN ARE NEVER DECLARED HERE. nix-darwin (`org.nixos.*`) rewrites its plists
+ *   on every activation and unloads any it no longer lists; macOS owns `com.apple.*`; `brew
+ *   services` owns `homebrew.mxcl.*`. Declaring one of those makes two tools fight over one file.
+ *   To move a job off such a tool, declare a NEW label and cut over (docs/launchd.md).
+ */
+export const RESERVED_LABEL_PREFIXES: readonly string[] = [
+  'org.nixos.',
+  'com.apple.',
+  'homebrew.mxcl.',
+];
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const RANGES: ReadonlyArray<readonly [keyof CalendarInterval, number, number]> = [
+  ['minute', 0, 59],
+  ['hour', 0, 23],
+  ['day', 1, 31],
+  ['weekday', 0, 7],
+  ['month', 1, 12],
+];
+
+const isInt = (value: number, min: number, max = Number.MAX_SAFE_INTEGER) =>
+  Number.isSafeInteger(value) && value >= min && value <= max;
+
+const calendarProblems = (entries: readonly CalendarInterval[]): string[] => {
+  if (entries.length === 0) return ['startCalendarInterval is an empty list; omit it instead'];
+  const found: string[] = [];
+  for (const [index, entry] of entries.entries()) {
+    for (const [field, min, max] of RANGES) {
+      const value = entry[field];
+      if (value !== undefined && !isInt(value, min, max)) {
+        found.push(
+          `startCalendarInterval[${String(index)}].${field} must be ${String(min)}–${String(max)}`,
+        );
+      }
+    }
+  }
+  return found;
+};
+
+const absolute = (name: string, value: string | undefined): string[] =>
+  value === undefined || value.startsWith('/') ? [] : [`${name} must be an absolute path`];
+
+/**
+ * The label and domain alone — the job's identity. ★ Split out because a rename is a delete-first
+ *   replace, and it must be refusable at plan time even while other props are still unresolved
+ *   Outputs (see job.ts diff): otherwise the old job is deleted and only then is the new label
+ *   found to be invalid.
+ */
+export const identityProblems = (label: string, domainText: string): string[] => {
+  const found: string[] = [];
+  if (!LABEL.test(label)) {
+    found.push('label must be 1–200 of [A-Za-z0-9._-], starting with a letter or digit');
+  }
+  const reserved = RESERVED_LABEL_PREFIXES.find((prefix) => label.startsWith(prefix));
+  if (reserved !== undefined) {
+    found.push(`label ${label} is under ${reserved}, which another tool owns; declare a new label`);
+  }
+  if (parseDomain(domainText) === undefined)
+    found.push(`domain must be 'system' or 'gui/<uid>', not ${domainText}`);
+  return found;
+};
+
+export const jobProblems = (props: LaunchdJobProps): string[] => {
+  const found = identityProblems(props.label, props.domain);
+  const domain = parseDomain(props.domain);
+
+  const [program] = props.programArguments;
+  // ★ Absolute, because launchd's PATH for a job is not the deploying shell's PATH.
+  if (program === undefined) found.push('programArguments must name a program');
+  else if (!program.startsWith('/')) found.push('programArguments[0] must be an absolute path');
+
+  for (const name of Object.keys(props.environment ?? {})) {
+    if (!ENV_NAME.test(name))
+      found.push(`environment name ${JSON.stringify(name)} is not a valid variable name`);
+  }
+  found.push(...jobSecretProblems(props.environment, props.programArguments, props.extraKeys));
+
+  if (props.startInterval !== undefined && !isInt(props.startInterval, 1)) {
+    found.push('startInterval must be a positive whole number of seconds');
+  }
+  if (props.throttleInterval !== undefined && !isInt(props.throttleInterval, 0)) {
+    found.push('throttleInterval must be a non-negative whole number of seconds');
+  }
+  const calendar = props.startCalendarInterval;
+  if (calendar !== undefined) {
+    found.push(
+      ...calendarProblems(Array.isArray(calendar) ? calendar : [calendar as CalendarInterval]),
+    );
+  }
+  const keepAlive = props.keepAlive;
+  if (
+    typeof keepAlive === 'object' &&
+    keepAlive.successfulExit === undefined &&
+    keepAlive.crashed === undefined
+  ) {
+    found.push('keepAlive {} names no condition; use true, false, or a condition');
+  }
+
+  found.push(...absolute('standardOutPath', props.standardOutPath));
+  found.push(...absolute('standardErrorPath', props.standardErrorPath));
+  found.push(...absolute('workingDirectory', props.workingDirectory));
+
+  if (domain?.kind === 'gui' && (props.userName !== undefined || props.groupName !== undefined)) {
+    found.push(
+      'userName/groupName apply only to the system domain; launchd ignores them for agents',
+    );
+  }
+  for (const key of Object.keys(props.extraKeys ?? {})) {
+    if (OWNED_KEYS.includes(key))
+      found.push(`extraKeys.${key} is owned by a typed prop; use that instead`);
+  }
+  return found;
+};

package/src/launchd/job.ts

@@ -0,0 +1,96 @@
+/**
+ * `Launchd.Job` — one launchd job (a LaunchDaemon in `system`, a LaunchAgent in `gui/<uid>`),
+ * declared rather than hand-loaded.
+ *
+ * ★ launchd HAS NO SDK. The provider renders the plist (plist.ts), writes it where launchd looks
+ *   (job-form.ts plistPathFor), and drives `launchctl` (launchctl.ts) — all through the HostRunner
+ *   the stack provides (runner.ts), so none of it is reachable except through that seam.
+ *
+ * Lifecycle (job-lifecycle.ts has the reasoning for each step):
+ *   - create / update — write the plist atomically, boot out the old job if loaded, bootstrap.
+ *     An update is therefore a RESTART; a converged job is left alone.
+ *   - read — `launchctl print` (loaded? pid? last exit?) plus the plist's SHA-256.
+ *   - diff — the rendered plist's SHA-256 against the stored AND the on-disk digest.
+ *   - replace — only when `label` or `domain` changes, and DELETE FIRST (labels are unique); so
+ *     everything the new job would be refused for is refused at plan time (job-preflight.ts).
+ *   - delete — boot out, remove the plist.
+ *
+ * ⛔ ENVIRONMENT IS NON-SECRET ONLY — see the ⛔ on LaunchdJobProps.environment.
+ * ⛔ NO SILENT SUDO — see assertMayWrite in job-preflight.ts.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`. A label already loaded, or a plist already on disk, reads
+ *   as `Unowned`, so Alchemy refuses to take it over unless asked. Labels under `org.nixos.`,
+ *   `com.apple.` and `homebrew.mxcl.` are refused outright (job-validate.ts) — declare a new label
+ *   and cut over instead (docs/launchd.md).
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { lift, resolvedString } from './host-effect.ts';
+import type { LaunchdJobAttributes, LaunchdJobProps } from './job-form.ts';
+import { deleteJob, diffJob, readJob, reconcileJob, replaceDiff } from './job-lifecycle.ts';
+import { HostRunnerService } from './runner.ts';
+
+export type {
+  CalendarInterval,
+  KeepAlive,
+  LaunchdDomain,
+  LaunchdJobAttributes,
+  LaunchdJobProps,
+} from './job-form.ts';
+
+export interface LaunchdJob extends Resource<
+  'Launchd.Job',
+  LaunchdJobProps,
+  LaunchdJobAttributes
+> {}
+
+export const LaunchdJob = Resource<LaunchdJob>('Launchd.Job');
+
+export const LaunchdJobProvider = () =>
+  Provider.effect(
+    LaunchdJob,
+    Effect.gen(function* () {
+      const runner = yield* HostRunnerService;
+      return LaunchdJob.Provider.of({
+        /**
+         * ⛔ launchd's job list is not a list of things this stack owns — it is every Apple, Nix
+         *   and hand-loaded job on the host. Returning them would invite a nuke to boot them out.
+         */
+        list: () => Effect.succeed([]),
+
+        read: ({ olds, output }) =>
+          lift(async () => {
+            const found = await readJob(runner, olds);
+            if (found === undefined) return undefined;
+            return output === undefined ? Unowned(found) : found;
+          }),
+
+        diff: ({ news, output }) => {
+          if (output === undefined) return Effect.succeed(undefined);
+          if (isResolved(news)) return lift(() => diffJob(runner, news, output));
+          /**
+           * ⛔ A RENAME MUST BE SEEN EVEN WHILE OTHER PROPS ARE UNRESOLVED. Returning undefined
+           *   hands the call to the engine's default — `update` for any prop change (Plan.ts,
+           *   havePropsChanged) — and an update under a new label bootstraps the new job and
+           *   orphans the old one, still running. `config.path` in programArguments (the pattern
+           *   docs/launchd.md recommends) is unresolved exactly when its HostFile changes in the
+           *   same deploy. reconcileJob also defends against this, for a label that is itself an
+           *   Output; seeing it here is what gets it planned as the replace it is.
+           */
+          const label = resolvedString(news, 'label');
+          const domain = resolvedString(news, 'domain') as LaunchdJobProps['domain'] | undefined;
+          return label !== undefined &&
+            domain !== undefined &&
+            (label !== output.label || domain !== output.domain)
+            ? lift(() => replaceDiff(runner, { domain, label }, undefined, output))
+            : Effect.succeed(undefined);
+        },
+
+        reconcile: ({ news, output }) => lift(() => reconcileJob(runner, news, output)),
+
+        delete: ({ output }) => lift(() => deleteJob(runner, output)),
+      });
+    }),
+  );

package/src/launchd/launchctl.test.ts

@@ -0,0 +1,181 @@
+/**
+ * The launchctl parsers against the shapes measured on macOS 27.2 (launchctl.ts header), and the
+ * bootout sequence against the fake launchd.
+ *
+ * ★ The fixture keeps the two traps from the real output: a multi-line shell argument that prints
+ *   raw (with a `}` in column 0), and nested blocks that repeat `state = ` two tabs deep.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeRunner } from './fake-runner.ts';
+import {
+  LAUNCHCTL,
+  bootoutIfLoaded,
+  parseDisabled,
+  parsePrint,
+  printFields,
+  printService,
+} from './launchctl.ts';
+
+const RUNNING = [
+  'system/com.example.job = {',
+  '\tactive count = 1',
+  '\tpath = /Library/LaunchDaemons/com.example.job.plist',
+  '\ttype = LaunchDaemon',
+  '\tstate = running',
+  '',
+  '\tprogram = /bin/sh',
+  '\targuments = {',
+  '\t\t/bin/sh',
+  '\t\t-c',
+  '\t\tprog=/opt/example/bin/job',
+  '[ -x "$prog" ] || {',
+  '  pid = 99',
+  '}',
+  'exec "$prog"',
+  '',
+  '\t}',
+  '',
+  '\tstdout path = /var/log/example.log',
+  '\tresource coalition = {',
+  '\t\tID = 777',
+  '\t\ttype = resource',
+  '\t\tstate = active',
+  '\t}',
+  '',
+  '\tdomain = system',
+  '\truns = 1',
+  '\tpid = 1219',
+  '\tlast exit code = (never exited)',
+  '\tspawn type = daemon (3)',
+  '\tjob state = running',
+  '}',
+].join('\n');
+
+describe('printFields / parsePrint', () => {
+  test('reads the job block, not the nested blocks or the raw argument text', () => {
+    const fields = printFields(RUNNING);
+    expect(fields.get('state')).toBe('running');
+    expect(fields.get('pid')).toBe('1219');
+    expect(fields.get('type')).toBe('LaunchDaemon');
+    expect(fields.get('path')).toBe('/Library/LaunchDaemons/com.example.job.plist');
+    expect(fields.has('ID')).toBe(false);
+  });
+
+  test('a running job', () => {
+    expect(parsePrint(RUNNING)).toEqual({ loaded: true, pid: 1219, state: 'running' });
+  });
+
+  test('a stopped job with an exit code, and the newer "78: EX_CONFIG" form', () => {
+    const stopped = RUNNING.replace('\tstate = running', '\tstate = not running')
+      .replace('\tpid = 1219\n', '')
+      .replace('(never exited)', '78: EX_CONFIG');
+    expect(parsePrint(stopped)).toEqual({ lastExitCode: 78, loaded: true, state: 'not running' });
+    expect(parsePrint(stopped.replace('78: EX_CONFIG', '0')).lastExitCode).toBe(0);
+  });
+
+  test('empty output parses to loaded with no details (the caller decides loaded from the exit code)', () => {
+    expect(parsePrint('')).toEqual({ loaded: true });
+  });
+});
+
+describe('parseDisabled', () => {
+  test('the measured `=> enabled|disabled` form, and the older `=> true|false`', () => {
+    const out = [
+      '\tdisabled services = {',
+      '\t\t"com.example.on" => enabled',
+      '\t\t"com.example.off" => disabled',
+      '\t\t"com.example.legacy-off" => true',
+      '\t\t"com.example.legacy-on" => false',
+      '\t}',
+    ].join('\n');
+    expect([...parseDisabled(out)].sort()).toEqual(['com.example.legacy-off', 'com.example.off']);
+  });
+});
+
+describe('printService', () => {
+  test('exit 113 is "not loaded", not an error', async () => {
+    const fake = fakeRunner();
+    expect(await printService(fake.runner, 'system/com.example.none')).toEqual({ loaded: false });
+  });
+
+  test('exit 112 "Could not find domain" (a gui uid with no login session) is "not loaded"', async () => {
+    const fake = fakeRunner();
+    fake.state.loggedOut.add(502);
+    expect(await printService(fake.runner, 'gui/502/com.example.x')).toEqual({
+      domainMissing: true,
+      loaded: false,
+    });
+  });
+
+  test('exit 112 without that text stays an error', async () => {
+    const runner = {
+      ...fakeRunner().runner,
+      exec: async () => ({ exitCode: 112, stderr: 'Bad request.', stdout: '' }),
+    };
+    await expect(printService(runner, 'system/x')).rejects.toThrow('-> 112');
+  });
+
+  test('any other non-zero exit is an error carrying stderr, never stdout', async () => {
+    const runner = {
+      ...fakeRunner().runner,
+      exec: async () => ({ exitCode: 1, stderr: 'Bad request.', stdout: 'SECRET_ENV=leak' }),
+    };
+    const error = await printService(runner, 'system/x').then(
+      () => new Error('expected a rejection'),
+      (cause: unknown) => cause as Error,
+    );
+    expect(error.message).toContain('Bad request.');
+    expect(error.message).not.toContain('leak');
+  });
+});
+
+describe('bootoutIfLoaded', () => {
+  test('does nothing when the job is not loaded (bootout of an absent job exits non-zero)', async () => {
+    const fake = fakeRunner();
+    await bootoutIfLoaded(fake.runner, 'system/com.example.none');
+    expect(fake.calls.map((call) => call[1])).toEqual(['print']);
+  });
+
+  test('boots out, then polls until launchd lets go', async () => {
+    const fake = fakeRunner();
+    fake.loaded.set('system/com.example.job', 1);
+    fake.state.lingerPrints = 3;
+    await bootoutIfLoaded(fake.runner, 'system/com.example.job');
+    expect(fake.loaded.has('system/com.example.job')).toBe(false);
+    const subs = fake.calls.map((call) => call[1]);
+    expect(subs.slice(0, 2)).toEqual(['print', 'bootout']);
+    expect(subs.filter((sub) => sub === 'print').length).toBeGreaterThan(3);
+    expect(fake.calls.every((call) => call[0] === LAUNCHCTL)).toBe(true);
+  });
+
+  test('a non-zero bootout for a job that is still exiting (EINPROGRESS) waits, not fails', async () => {
+    const fake = fakeRunner();
+    fake.loaded.set('system/com.example.slow', 1);
+    fake.state.lingerPrints = 3;
+    fake.state.bootoutFailure = {
+      exitCode: 36,
+      stderr: 'Boot-out failed: 36: Operation now in progress',
+      stdout: '',
+    };
+    await bootoutIfLoaded(fake.runner, 'system/com.example.slow');
+    expect(fake.loaded.has('system/com.example.slow')).toBe(false);
+  });
+
+  test('a non-zero bootout for a job that never leaves fails with bootout’s own error', async () => {
+    const fake = fakeRunner();
+    fake.loaded.set('system/com.example.stuck', 1);
+    fake.state.bootoutKeepsJob = true;
+    await expect(bootoutIfLoaded(fake.runner, 'system/com.example.stuck')).rejects.toThrow(
+      /bootout system\/com\.example\.stuck -> 5: .*still loaded after waiting/,
+    );
+  });
+
+  test('gives up with a clear error when the job never goes away', async () => {
+    const fake = fakeRunner();
+    fake.loaded.set('system/com.example.stuck', 1);
+    fake.state.lingerPrints = 1_000;
+    await expect(bootoutIfLoaded(fake.runner, 'system/com.example.stuck')).rejects.toThrow(
+      'still loaded',
+    );
+  });
+});

package/src/launchd/launchctl.ts

@@ -0,0 +1,188 @@
+/**
+ * The four `launchctl` subcommands LaunchdJob uses — print, print-disabled, bootstrap, bootout —
+ * over a HostRunner, plus the parsers for the two read-only ones.
+ *
+ * ★ MEASURED 2026-09-21 ON macOS 27.2 (read-only `print` / `print-disabled` only; nothing was
+ *   bootstrapped or booted out to write this):
+ *   - `print system/<unknown>` exits **113** with "Could not find service … in domain for system"
+ *     on stderr. 113 is therefore "not loaded", not an error.
+ *   - `print` of a loaded job is a `<target> = {` block. Its own fields sit one tab deep
+ *     (`\tstate = running`, `\tpid = 1219`, `\tlast exit code = 0` or `(never exited)`); nested
+ *     blocks (`resource coalition`, `semaphores`) repeat names like `state` two tabs deep.
+ *   - `print-disabled <domain>` lists `"label" => enabled|disabled`.
+ *   - reading needs no root: a uid-501 shell printed system-domain jobs.
+ *   - `print gui/<uid>/<label>` for a uid with NO LOGIN SESSION exits **112** with "Could not find
+ *     domain for user gui: <uid>" (and so does `print-disabled gui/<uid>`); a malformed target is
+ *     64, a missing service in a live gui domain is 113. So 112 + that text is "the domain does
+ *     not exist", which means the job cannot be loaded — not an error for a read or a delete.
+ * ⚠️ REASONED, NOT MEASURED: bootstrap/bootout exit codes. nix-darwin's own activation script on the
+ *   same host notes "`bootout` on an already-absent job is a no-op that returns non-zero", which is
+ *   why bootout here is always preceded by a print and followed by a poll, never trusted alone.
+ * ⛔ NEVER PUT `print` STDOUT IN AN ERROR. It contains the job's whole environment.
+ */
+import type { HostRunner } from './runner.ts';
+
+export const LAUNCHCTL = '/bin/launchctl';
+/** `launchctl print` of an unknown service — measured, see above. */
+export const NOT_FOUND = 113;
+/** `launchctl print` into a gui domain with no login session — measured, see above. */
+export const NO_DOMAIN = 112;
+const NO_DOMAIN_TEXT = 'Could not find domain';
+
+export class LaunchctlError extends Error {
+  constructor(command: string, exitCode: number, stderr: string) {
+    super(`launchctl ${command} -> ${String(exitCode)}: ${stderr.trim().slice(0, 300)}`);
+    this.name = 'LaunchctlError';
+  }
+}
+
+export type ServiceStatus = {
+  readonly loaded: boolean;
+  /** The domain itself is absent (a gui/<uid> with no login session). Implies `loaded: false`. */
+  readonly domainMissing?: true;
+  readonly state?: string;
+  readonly pid?: number;
+  readonly lastExitCode?: number;
+};
+
+/**
+ * The job block's own `key = value` lines, ignoring nested blocks.
+ * ⚠️ A multi-line ProgramArguments entry is printed raw inside `arguments = {`, so a close is only
+ *   accepted when its indentation matches the open. An argument that itself contains a line of
+ *   exactly one tab and `}` would still desynchronise this; no real job has one.
+ */
+export const printFields = (stdout: string): Map<string, string> => {
+  const fields = new Map<string, string>();
+  const closers: string[] = [];
+  for (const line of stdout.split('\n')) {
+    if (closers.length === 0) {
+      if (fields.size === 0 && line.endsWith(' = {')) closers.push('}');
+      continue;
+    }
+    if (line === closers[closers.length - 1]) {
+      closers.pop();
+      continue;
+    }
+    const opened = /^(\t+)\S.* = \{$/.exec(line);
+    if (opened?.[1] !== undefined && opened[1].length === closers.length) {
+      closers.push(`${opened[1]}}`);
+      continue;
+    }
+    const field = closers.length === 1 ? /^\t([a-z][a-z ]*[a-z]) = (.*)$/.exec(line) : null;
+    if (field?.[1] !== undefined && field[2] !== undefined && !fields.has(field[1])) {
+      fields.set(field[1], field[2]);
+    }
+  }
+  return fields;
+};
+
+const leadingInt = (text: string | undefined): number | undefined => {
+  const match = text === undefined ? null : /^(-?\d+)/.exec(text);
+  return match?.[1] === undefined ? undefined : Number(match[1]);
+};
+
+export const parsePrint = (stdout: string): ServiceStatus => {
+  const fields = printFields(stdout);
+  const state = fields.get('state');
+  const pid = leadingInt(fields.get('pid'));
+  // "(never exited)" parses to undefined; "78: EX_CONFIG" to 78.
+  const lastExitCode = leadingInt(fields.get('last exit code'));
+  return {
+    loaded: true,
+    ...(state === undefined ? {} : { state }),
+    ...(pid === undefined ? {} : { pid }),
+    ...(lastExitCode === undefined ? {} : { lastExitCode }),
+  };
+};
+
+/** Labels `print-disabled` reports as disabled. Older releases printed `=> true` for disabled. */
+export const parseDisabled = (stdout: string): Set<string> => {
+  const disabled = new Set<string>();
+  for (const match of stdout.matchAll(/^\s*"([^"]+)" => (\w+)\s*$/gm)) {
+    if (match[1] !== undefined && (match[2] === 'disabled' || match[2] === 'true')) {
+      disabled.add(match[1]);
+    }
+  }
+  return disabled;
+};
+
+export const printService = async (runner: HostRunner, target: string): Promise<ServiceStatus> => {
+  const result = await runner.exec([LAUNCHCTL, 'print', target]);
+  if (result.exitCode === NOT_FOUND) return { loaded: false };
+  // ⚠️ Without this, deleting an agent while its user is logged out fails on the read, and the
+  //   plist stays in LaunchAgents — where launchd loads it again at that user's next login.
+  if (result.exitCode === NO_DOMAIN && result.stderr.includes(NO_DOMAIN_TEXT)) {
+    return { domainMissing: true, loaded: false };
+  }
+  if (result.exitCode !== 0)
+    throw new LaunchctlError(`print ${target}`, result.exitCode, result.stderr);
+  return parsePrint(result.stdout);
+};
+
+export const isDisabled = async (
+  runner: HostRunner,
+  domain: string,
+  label: string,
+): Promise<boolean> => {
+  const result = await runner.exec([LAUNCHCTL, 'print-disabled', domain]);
+  if (result.exitCode !== 0) {
+    throw new LaunchctlError(`print-disabled ${domain}`, result.exitCode, result.stderr);
+  }
+  return parseDisabled(result.stdout).has(label);
+};
+
+export const bootstrap = async (
+  runner: HostRunner,
+  domain: string,
+  plistPath: string,
+): Promise<void> => {
+  const result = await runner.exec([LAUNCHCTL, 'bootstrap', domain, plistPath]);
+  if (result.exitCode !== 0) {
+    throw new LaunchctlError(`bootstrap ${domain} ${plistPath}`, result.exitCode, result.stderr);
+  }
+};
+
+/**
+ * Poll `print` until the service is gone. ⚠️ bootout can return before launchd lets go of it.
+ * ★ 30 s, because a job gets SIGTERM and then its ExitTimeOut before SIGKILL: launchd.plist(5)
+ *   documents a 20 s default (a macOS 27.2 `print` showed `exit timeout = 5` for a job that sets
+ *   none). Giving up sooner would fail a deploy over a job that was, correctly, still exiting.
+ */
+export const waitUnloaded = async (
+  runner: HostRunner,
+  target: string,
+  attempts = 120,
+  intervalMs = 250,
+): Promise<void> => {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (!(await printService(runner, target)).loaded) return;
+    await runner.sleep(intervalMs);
+  }
+  throw new Error(
+    `${target} is still loaded ${String((attempts * intervalMs) / 1000)}s after bootout`,
+  );
+};
+
+/** Boot a service out if it is loaded, and wait until launchd has let go. Idempotent. */
+export const bootoutIfLoaded = async (runner: HostRunner, target: string): Promise<void> => {
+  if (!(await printService(runner, target)).loaded) return;
+  const result = await runner.exec([LAUNCHCTL, 'bootout', target]);
+  /**
+   * ⚠️ A non-zero bootout is only an error if the service is STILL there after the wait (see
+   *   header) — so wait FIRST, then judge. A job slower to exit than launchctl's own wait is widely
+   *   reported to fail bootout with `36: Operation now in progress` (EINPROGRESS) while it is
+   *   still going away; REASONED from those reports, not measured here. Judging on an immediate
+   *   print would fail the deploy with the new plist written and the old job already exiting —
+   *   the job ends up down either way, and the error would blame the wrong step.
+   */
+  try {
+    await waitUnloaded(runner, target);
+  } catch (cause) {
+    if (result.exitCode === 0) throw cause;
+    throw new LaunchctlError(
+      `bootout ${target}`,
+      result.exitCode,
+      `${result.stderr.trim()} (and still loaded after waiting)`,
+    );
+  }
+};