@homeflare/alchemy 0.7.0 → 0.10.0

package/src/launchd/sudo-runner-files.test.ts

@@ -0,0 +1,240 @@
+/**
+ * sudoRunner's file writes and removes over the fake host (fake-sudo.ts): under a prefix they go
+ * through `install` / `rm` as root; everything a mistaken declaration could turn into a root write
+ * somewhere unintended is refused before anything is staged. No real sudo runs anywhere.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, fakeSudoHost } from './fake-sudo.ts';
+import type { FileStat } from './runner.ts';
+import { INSTALL, RM, SudoRefusedError } from './sudo-allowlist.ts';
+
+const CONF = '/opt/example/app/a.conf';
+const bytes = (text: string) => new TextEncoder().encode(text);
+const plistBytes = bytes('<key>Label</key><string>com.example.a</string>');
+
+describe('writeFileAtomic', () => {
+  test('under a prefix: staged, installed with mode and owner from argv, staged file removed', async () => {
+    const host = fakeSudoHost();
+    await host.runner.writeFileAtomic(CONF, bytes('listen: 127.0.0.1:9100\n'), {
+      gid: 80,
+      mode: 0o640,
+      uid: 0,
+    });
+    const [install] = host.privileged();
+    expect(install).toEqual([
+      INSTALL,
+      '-S',
+      '-m',
+      '0640',
+      '-o',
+      '0',
+      '-g',
+      '80',
+      expect.any(String),
+      CONF,
+    ]);
+    expect(host.state.installedFrom.get(CONF)).toBe('listen: 127.0.0.1:9100\n');
+    expect(host.fake.files.get(CONF)).toMatchObject({ gid: 80, mode: 0o640, uid: 0 });
+    expect(host.staged.size).toBe(0);
+    // ⛔ The log carries the argv, never the content.
+    expect(host.logs.join('\n')).not.toContain('127.0.0.1');
+  });
+
+  test('a failed install throws and still removes the staged file', async () => {
+    const host = fakeSudoHost();
+    host.state.installFailure = { exitCode: 71, stderr: 'install: disk full', stdout: '' };
+    await expect(host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 })).rejects.toThrow(
+      '-> 71: install: disk full',
+    );
+    expect(host.staged.size).toBe(0);
+    expect(host.fake.files.has(CONF)).toBe(false);
+  });
+
+  test("outside every prefix, the operator's own file is written by the operator", async () => {
+    const host = fakeSudoHost();
+    const path = '/Users/someone/Library/LaunchAgents/com.example.a.plist';
+    await host.runner.writeFileAtomic(path, plistBytes, { mode: 0o644, uid: OPERATOR });
+    expect(host.fake.files.get(path)).toMatchObject({ uid: OPERATOR });
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('outside every prefix, a foreign owner is refused and nothing is written', async () => {
+    const host = fakeSudoHost();
+    const path = '/Users/someone/Library/LaunchAgents/x.conf';
+    await expect(
+      host.runner.writeFileAtomic(path, bytes('x'), { mode: 0o644, uid: 502 }),
+    ).rejects.toThrow('owner 502 needs root');
+    expect(host.fake.files.has(path)).toBe(false);
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test.each([
+    ['a directory at the path', '/opt/example/app', 'is a directory'],
+    ['a missing directory on the way', '/opt/example/none/a.conf', '/opt/example/none is missing'],
+  ])('%s is refused before anything is staged', async (_name, path, message) => {
+    const host = fakeSudoHost();
+    await expect(host.runner.writeFileAtomic(path, bytes('x'), { mode: 0o644 })).rejects.toThrow(
+      message,
+    );
+    expect(host.state.stagedCount).toBe(0);
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('a symlinked directory under the prefix is refused', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set('/opt/example/link', {
+      bytes: bytes(''),
+      gid: 0,
+      kind: 'symlink',
+      mode: 0o755,
+      uid: 0,
+    });
+    await expect(
+      host.runner.writeFileAtomic('/opt/example/link/a.conf', bytes('x'), { mode: 0o644 }),
+    ).rejects.toThrow('/opt/example/link is a symlink');
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('a file the operator could not read back is refused before staging', async () => {
+    const host = fakeSudoHost();
+    await expect(
+      host.runner.writeFileAtomic(CONF, bytes('x'), { gid: 0, mode: 0o600, uid: 0 }),
+    ).rejects.toThrow('would hide it from the deploying user');
+    expect(host.state.stagedCount).toBe(0);
+    // Group-readable through one of the operator's groups is fine; so are unknown groups.
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { gid: 80, mode: 0o640, uid: 0 });
+    await fakeSudoHost('unknown').runner.writeFileAtomic(CONF, bytes('x'), {
+      gid: 99,
+      mode: 0o640,
+      uid: 0,
+    });
+  });
+
+  test('an omitted owner is root and an omitted group the directory’s, for the read-back check', async () => {
+    // ⚠️ Omitted owner: root, so 0600 is root-only and refused (not the operator's own 0600).
+    const host = fakeSudoHost();
+    await expect(host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o600 })).rejects.toThrow(
+      'would hide it from the deploying user',
+    );
+    // Omitted group: the parent's (80, one of the operator's), so 0640 is readable and allowed.
+    host.fake.files.set('/opt/example/app', {
+      bytes: bytes(''),
+      gid: 80,
+      kind: 'directory',
+      mode: 0o755,
+      uid: 0,
+    });
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o640 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ gid: 80, mode: 0o640, uid: 0 });
+  });
+
+  test('a mode chmod cannot mean is a refusal, before anything is staged', async () => {
+    const host = fakeSudoHost();
+    await expect(
+      host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o10000 }),
+    ).rejects.toBeInstanceOf(SudoRefusedError);
+    expect(host.state.stagedCount).toBe(0);
+  });
+
+  test('outside every prefix, EACCES names the missing prefix instead of a temp file', async () => {
+    const host = fakeSudoHost();
+    await expect(
+      host.runner.writeFileAtomic('/etc/example/a.conf', bytes('x'), { mode: 0o644 }),
+    ).rejects.toThrow('declare that directory as a prefix');
+    await expect(
+      host.runner.writeFileAtomic('/nowhere/a.conf', bytes('x'), { mode: 0o644 }),
+    ).rejects.toThrow('ENOENT');
+  });
+});
+
+describe('the declared prefix itself is checked at every call', () => {
+  type Host = ReturnType<typeof fakeSudoHost>;
+  const entry = (kind: FileStat['kind'], mode: number) => ({
+    bytes: bytes(''),
+    gid: 0,
+    kind,
+    mode,
+    uid: 0,
+  });
+  test.each([
+    // ⛔ `/opt/example` -> `/etc` would make root write /etc/a.conf, a path the log never names.
+    [
+      'a symlink',
+      (h: Host) => h.fake.files.set('/opt/example', entry('symlink', 0o755)),
+      'is a symlink',
+    ],
+    ['owned by the operator', (h: Host) => h.fake.dirs.set('/opt/example', OPERATOR), 'uid 501'],
+    [
+      'group-writable',
+      (h: Host) => h.fake.files.set('/opt/example', entry('directory', 0o775)),
+      '0775',
+    ],
+    [
+      'world-writable',
+      (h: Host) => h.fake.files.set('/opt/example', entry('directory', 0o757)),
+      '0757',
+    ],
+    ['missing', (h: Host) => h.fake.dirs.delete('/opt/example'), '/opt/example is missing'],
+  ])('%s is refused, before anything is staged or run', async (_name, setup, message) => {
+    const host = fakeSudoHost();
+    setup(host);
+    const write = host.runner.writeFileAtomic('/opt/example/a.conf', bytes('x'), { mode: 0o644 });
+    await expect(write).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(write).rejects.toThrow(message);
+    expect(host.state.stagedCount).toBe(0);
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('a remove under a group-writable prefix is refused too', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set('/opt/example', entry('directory', 0o775));
+    host.fake.files.set('/opt/example/a.conf', entry('file', 0o644));
+    await expect(host.runner.removeFile('/opt/example/a.conf')).rejects.toThrow('0775');
+    expect(host.sudoCalls).toEqual([]);
+  });
+});
+
+describe('removeFile', () => {
+  test('a directory on the way that is already gone: nothing is there, so success, no sudo', async () => {
+    const host = fakeSudoHost();
+    await host.runner.removeFile('/opt/example/gone/a.conf');
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('under a prefix: `rm -f --` through sudo', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set(CONF, { bytes: bytes('x'), gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    await host.runner.removeFile(CONF);
+    expect(host.privileged()).toEqual([[RM, '-f', '--', CONF]]);
+    expect(host.fake.files.has(CONF)).toBe(false);
+  });
+
+  test('nothing there is success with no privileged call and no log line', async () => {
+    const host = fakeSudoHost();
+    await host.runner.removeFile(CONF);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('a directory is refused, not removed', async () => {
+    const host = fakeSudoHost();
+    await expect(host.runner.removeFile('/opt/example/app')).rejects.toThrow('is a directory');
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('outside every prefix it is the operator removing their own file', async () => {
+    const host = fakeSudoHost();
+    const path = '/Users/someone/Library/LaunchAgents/a.plist';
+    host.fake.files.set(path, {
+      bytes: bytes('x'),
+      gid: 20,
+      kind: 'file',
+      mode: 0o644,
+      uid: OPERATOR,
+    });
+    await host.runner.removeFile(path);
+    expect(host.fake.files.has(path)).toBe(false);
+    expect(host.sudoCalls).toEqual([]);
+  });
+});

package/src/launchd/sudo-runner.test.ts

@@ -0,0 +1,126 @@
+/**
+ * sudoRunner over the fake host (fake-sudo.ts): which calls reach sudo, in what exact argv, what
+ * is logged, and what is refused before sudo is ever asked. No real sudo runs anywhere.
+ * File writes and removes are in sudo-runner-files.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, PREFIXES, fakeSudoHost } from './fake-sudo.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+import { RM, SUDO } from './sudo-allowlist.ts';
+import { SudoRefusedError, makeSudoRunner, sudoRunner } from './sudo-runner.ts';
+
+const PLIST = '/Library/LaunchDaemons/com.example.a.plist';
+const plistBytes = new TextEncoder().encode('<key>Label</key><string>com.example.a</string>');
+
+describe('what it claims', () => {
+  test('privileged, as the operator: it elevates calls, it is not root', () => {
+    const { runner } = fakeSudoHost();
+    expect(runner.privileged).toBe(true);
+    expect(runner.effectiveUid()).toBe(OPERATOR);
+  });
+
+  test('prefixes are required and checked when it is built', () => {
+    expect(() => sudoRunner({ prefixes: [] })).toThrow('no prefixes');
+    expect(() => sudoRunner({ prefixes: ['/'] })).toThrow('every path');
+  });
+});
+
+describe('exec', () => {
+  test('a system bootstrap runs as `sudo -n --`, logged once, argv only', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    const result = await host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    expect(result.exitCode).toBe(0);
+    expect(host.sudoCalls).toEqual([[SUDO, '-n', '--', LAUNCHCTL, 'bootstrap', 'system', PLIST]]);
+    expect(host.logs).toEqual([
+      `homeflare/launchd sudo -n ${JSON.stringify([LAUNCHCTL, 'bootstrap', 'system', PLIST])}`,
+    ]);
+  });
+
+  test('bootstrap of a plist that is not a plain file is refused before sudo', async () => {
+    const host = fakeSudoHost();
+    const missing = host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    // ★ The host checks throw the same class as the allowlist: nothing ran as root.
+    await expect(missing).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(missing).rejects.toThrow('is missing, not a file');
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'symlink', mode: 0o755, uid: 0 });
+    await expect(host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST])).rejects.toThrow(
+      'is a symlink',
+    );
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('reads stay unelevated: no sudo, no log line', async () => {
+    const host = fakeSudoHost();
+    const result = await host.runner.exec([LAUNCHCTL, 'print', 'system/com.example.a']);
+    expect(result.exitCode).toBe(113);
+    await host.runner.exec([LAUNCHCTL, 'print-disabled', 'system']);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test.each([
+    ['a bare-domain bootout', [LAUNCHCTL, 'bootout', 'system']],
+    ["another user's gui domain", [LAUNCHCTL, 'bootout', 'gui/502/com.example.a']],
+    ['a sudo argv', [SUDO, '-n', RM, '-rf', '/']],
+  ])('%s is refused before sudo is asked', async (_name, argv) => {
+    const host = fakeSudoHost();
+    await expect(host.runner.exec(argv)).rejects.toBeInstanceOf(SudoRefusedError);
+    expect(host.sudoCalls).toEqual([]);
+    expect(host.logs).toEqual([]);
+  });
+
+  test('a password-required sudo fails at once, saying what to do', async () => {
+    const host = fakeSudoHost();
+    host.state.sudo = 'password';
+    const run = host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+    await expect(run).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(run).rejects.toThrow('a password is required');
+    await expect(run).rejects.toThrow('sudo -v');
+    expect(host.sudoCalls).toHaveLength(1);
+  });
+
+  test.each(['denied', 'not-in-sudoers', 'not-on-host'] as const)(
+    'a sudoers refusal (%s) is named as one',
+    async (refusal) => {
+      const host = fakeSudoHost();
+      host.state.sudo = refusal;
+      const run = host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+      await expect(run).rejects.toBeInstanceOf(SudoRefusedError);
+      await expect(run).rejects.toThrow('sudoers does not let');
+    },
+  );
+
+  test("launchctl's own failure comes back as a result, for the provider to judge", async () => {
+    const host = fakeSudoHost();
+    const result = await host.runner.exec([LAUNCHCTL, 'bootout', 'system/com.example.a']);
+    expect(result.exitCode).toBe(3);
+    expect(host.sudoCalls).toHaveLength(1);
+  });
+
+  test('a launchctl error that says "not allowed" is still launchctl\'s, not sudo\'s', async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set(PLIST, { bytes: plistBytes, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+    // ⚠️ Exit 1 like sudo's own failures; only sudo's message forms may turn it into a refusal.
+    host.fake.state.bootstrapFailure = {
+      exitCode: 1,
+      stderr: 'Bootstrap failed: 1: service is not allowed to execute in this domain',
+      stdout: '',
+    };
+    const result = await host.runner.exec([LAUNCHCTL, 'bootstrap', 'system', PLIST]);
+    expect(result.exitCode).toBe(1);
+  });
+});
+
+test('makeSudoRunner validates prefixes too', () => {
+  const { fake } = fakeSudoHost();
+  const deps = {
+    base: fake.runner,
+    groups: async () => [],
+    log: () => undefined,
+    stage: async () => ({ dispose: async () => undefined, path: '' }),
+  };
+  expect(() => makeSudoRunner([], deps)).toThrow('no prefixes');
+  expect(() => makeSudoRunner(PREFIXES, deps)).not.toThrow();
+});

package/src/launchd/sudo-runner.ts

@@ -0,0 +1,216 @@
+/**
+ * sudoRunner(): the kit's one elevating HostRunner. The deploy runs as the operator, and only the
+ * calls that need root go through `sudo -n`, in the exact shapes sudo-allowlist.ts names:
+ *
+ * - `launchctl bootstrap | bootout | kickstart` in the system domain;
+ * - a file under a prefix the stack declared: staged in a private temp file as the operator, then
+ *   `sudo -n install -S -m <mode> [-o <uid>] [-g <gid>] <staged> <path>`; removed with
+ *   `sudo -n rm -f -- <path>`.
+ *
+ * Everything else (reads, lookups, the operator's own files and gui domain) goes to localRunner().
+ *
+ * ★ DECIDED 2026-09-21. A host stack deploys as the operator rather than as root, so a provider bug
+ *   or a wrong declaration can do no more than this list. It is an explicit opt-in,
+ *   `launchdProviders(sudoRunner({ prefixes }))`, and nothing ever falls back to it: localRunner()
+ *   stays the default and never elevates.
+ * ⛔ `sudo -n`, NEVER A PROMPT. A deploy that stops mid-apply to ask for a password is the failure
+ *   "no silent sudo" exists to prevent. With -n, sudo fails at once, and that failure becomes an
+ *   error saying what to do.
+ * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and it is only ever an argv: a file's bytes
+ *   travel through the staged file, never through argv, so a log line cannot carry content.
+ * ★ `install -S`: install(1) on macOS 27.2 (read 2026-09-21) always writes a temp file in the
+ *   target directory and renames it, so the file is never torn, and -S adds the fsync that
+ *   localRunner's `handle.sync()` does.
+ * ⚠️ REASONED, NOT MEASURED: sudo's failure text (sudo-said.ts has the strings and their sources).
+ * ⛔ EVERY CHECK BEFORE SUDO ALSO RUNS AT PLAN TIME (`checkWrite`, 2026-09-21): the mode, the
+ *   directories from the prefix down, the read-back. Reads only, as the operator — never sudo.
+ */
+import { type LocalRunnerOptions, localRunner } from './local-runner.ts';
+import type { ExecResult, HostRunner, WriteOptions } from './runner.ts';
+import {
+  INSTALL,
+  RM,
+  SUDO,
+  SudoRefusedError,
+  checkPrefixes,
+  octalMode,
+  prefixOf,
+  privilegedProblem,
+  routeExec,
+} from './sudo-allowlist.ts';
+import { assertInstallable, assertPlainPath, operatorGroups } from './sudo-guard.ts';
+import { sudoRefusal, undeclared } from './sudo-said.ts';
+import { type Staged, stageFile } from './sudo-stage.ts';
+
+export { SudoRefusedError };
+
+export type SudoRunnerOptions = LocalRunnerOptions & {
+  /**
+   * The directories root may install into and remove from: `/Library/LaunchDaemons` for system
+   * jobs (bootstrap and bootout are refused without it), plus wherever the stack's root-owned
+   * HostFiles live. ⛔ Required: absolute, normalised, never `/`; and at every privileged call a
+   * real directory that root owns and only root may write (sudo-guard.ts). Outside every prefix a
+   * file is written as the deploying user, or refused when that needs root.
+   */
+  readonly prefixes: readonly string[];
+  /** Receives one line per privileged argv, before it runs. @default a line on stderr */
+  readonly log?: (line: string) => void;
+};
+
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SudoDeps = {
+  /** Runs everything, including `sudo` itself. localRunner() for the real one. */
+  readonly base: HostRunner;
+  readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+  /** The deploying user's groups, for the read-back check; `undefined` when unknown. */
+  readonly groups: () => Promise<readonly number[] | undefined>;
+  readonly log: (line: string) => void;
+};
+
+export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): HostRunner => {
+  const prefixes = checkPrefixes(prefixList);
+  const { base } = deps;
+
+  /**
+   * ⛔ THE ONE PLACE `sudo` IS SPAWNED: allowlist, then any host check (`before`), then the log
+   *   line, then `sudo -n -- argv`.
+   */
+  const elevate = async (
+    argv: readonly string[],
+    { before, staged }: { before?: () => Promise<unknown>; staged?: string } = {},
+  ): Promise<ExecResult> => {
+    const shown = JSON.stringify(argv);
+    const problem = privilegedProblem(argv, {
+      prefixes,
+      ...(staged === undefined ? {} : { staged }),
+    });
+    if (problem !== undefined)
+      throw new SudoRefusedError(`sudoRunner refused ${shown}: ${problem}`);
+    await before?.();
+    deps.log(`homeflare/launchd sudo -n ${shown}`);
+    const result = await base.exec([SUDO, '-n', '--', ...argv]);
+    const refused = sudoRefusal(shown, result);
+    if (refused !== undefined) throw refused;
+    return result;
+  };
+
+  /**
+   * Every refusal a write can meet before sudo is asked — as the deploying user, reading only — so
+   * the same checks run at plan time (`checkWrite`) and at the write. `undefined` outside every
+   * prefix, where the operator writes; else the prefix and the mode as `install -m` takes it.
+   */
+  const vetWrite = async (path: string, options: WriteOptions) => {
+    const prefix = prefixOf(path, prefixes);
+    const operator = base.effectiveUid();
+    if (prefix === undefined) {
+      if (options.uid !== undefined && options.uid !== operator && operator !== 0) {
+        throw new SudoRefusedError(
+          `sudoRunner ${path}: owner ${String(options.uid)} needs root, and the path is under no ` +
+            `declared prefix (${prefixes.join(', ')}). Declare its directory, or deploy as root. ` +
+            'Nothing was written.',
+        );
+      }
+      return undefined;
+    }
+    const mode = octalMode(options.mode);
+    if (mode === undefined) throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
+    await assertInstallable(base, prefix, path, options, await deps.groups());
+    return { mode, prefix };
+  };
+
+  /** A privileged file operation: anything but exit 0 is an error. ⚠️ stderr names paths only. */
+  const mustSucceed = async (argv: readonly string[], staged?: string): Promise<void> => {
+    const result = await elevate(argv, staged === undefined ? {} : { staged });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.trim().slice(0, 300);
+      throw new Error(`sudo -n ${JSON.stringify(argv)} -> ${String(result.exitCode)}: ${stderr}`);
+    }
+  };
+
+  return {
+    // ★ The plan-time half of vetWrite: the providers' diffs call it, and it never elevates.
+    checkWrite: async (path, options) => {
+      await vetWrite(path, options);
+    },
+    effectiveUid: () => base.effectiveUid(),
+    exec: async (argv) => {
+      const route = routeExec(argv, base.effectiveUid());
+      if ('refuse' in route) throw new SudoRefusedError(`sudoRunner: ${route.refuse}`);
+      if (route.as === 'operator') return base.exec(argv);
+      // ⛔ bootstrap makes root read the plist: it must be a plain file exactly where argv says.
+      //   The allowlist has already put it under a prefix by the time `before` runs.
+      const plist = argv[1] === 'bootstrap' ? argv[3] : undefined;
+      const prefix = plist === undefined ? undefined : prefixOf(plist, prefixes);
+      return elevate(argv, {
+        before: async () => {
+          if (plist !== undefined && prefix !== undefined) {
+            await assertPlainPath(base, prefix, plist, 'file');
+          }
+        },
+      });
+    },
+    lookupGroup: (nameOrId) => base.lookupGroup(nameOrId),
+    lookupUser: (nameOrId) => base.lookupUser(nameOrId),
+    // ★ True, so the providers let a system-domain job through to this runner (canActAsRoot).
+    privileged: true,
+    readFile: (path) => base.readFile(path),
+    removeFile: async (path) => {
+      const prefix = prefixOf(path, prefixes);
+      if (prefix === undefined) return base.removeFile(path).catch(undeclared(path, prefixes));
+      /**
+       * ★ Nothing there is success without a privileged call, so an idempotent delete logs nothing.
+       * ⚠️ lstat the path FIRST: a directory on the way that is already gone means nothing is there
+       *   (HostRunner.removeFile is idempotent, and localRunner treats ENOENT/ENOTDIR so), where the
+       *   guard alone would refuse it as a missing directory.
+       */
+      if ((await base.stat(path)) === undefined) return;
+      await assertPlainPath(base, prefix, path, 'file');
+      await mustSucceed([RM, '-f', '--', path]);
+    },
+    sleep: (ms) => base.sleep(ms),
+    stat: (path) => base.stat(path),
+    writeFileAtomic: async (path, bytes, options) => {
+      const vetted = await vetWrite(path, options);
+      if (vetted === undefined) {
+        return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
+      }
+      const { mode } = vetted;
+      const staged = await deps.stage(bytes);
+      try {
+        await mustSucceed(
+          [
+            INSTALL,
+            '-S',
+            '-m',
+            mode,
+            ...(options.uid === undefined ? [] : ['-o', String(options.uid)]),
+            ...(options.gid === undefined ? [] : ['-g', String(options.gid)]),
+            staged.path,
+            path,
+          ],
+          staged.path,
+        );
+      } finally {
+        await staged.dispose();
+      }
+    },
+  };
+};
+
+/**
+ * The real sudo runner: localRunner() for everything, `/usr/bin/sudo -n` for the allowlist.
+ * Pass it explicitly: `launchdProviders(sudoRunner({ prefixes: ['/Library/LaunchDaemons'] }))`.
+ */
+export const sudoRunner = (options: SudoRunnerOptions): HostRunner => {
+  const base = localRunner(options);
+  return makeSudoRunner(options.prefixes, {
+    base,
+    groups: () => operatorGroups(base),
+    log:
+      options.log ??
+      ((line) => {
+        process.stderr.write(`${line}\n`);
+      }),
+    stage: stageFile,
+  });
+};

package/src/launchd/sudo-said.ts

@@ -0,0 +1,58 @@
+/**
+ * What sudo's own failure means, for sudo-runner.ts: which exit-1 answers are sudo refusing to run
+ * the command (so NOTHING ran as root), and what an EACCES outside every prefix most likely means.
+ * Split out of sudo-runner.ts, which keeps only the runner.
+ *
+ * ⚠️ REASONED, NOT MEASURED: sudo's failure text. The kit never runs sudo. The strings below follow
+ *   sudoers(5) for sudo 1.9.17p2 on macOS 27.2 ("a password is required": -n was given but a
+ *   password was needed) and sudo(8) (sudo exits 1 when it fails itself).
+ */
+import { errnoCode } from './local-runner.ts';
+import type { ExecResult } from './runner.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+
+/**
+ * ⚠️ ANCHORED TO sudo'S OWN MESSAGE FORMS (`sudo: …` lines, `Sorry, user …`), so a launchctl or
+ *   install error that happens to say "not allowed" is never reported as "the command did not run".
+ *   The refusals are the three a sudoers denial prints: the command not allowed, the user not in
+ *   sudoers, and the user not allowed on this host (`<user> is not allowed to run sudo on <host>.`).
+ *   REASONED from sudo 1.9's sudoers plugin, like the rest (header).
+ */
+const PASSWORD =
+  /^sudo: (?:a password is required|a terminal is required|sorry, you must have a tty)/m;
+const NOT_ALLOWED =
+  /^(?:Sorry, user \S+ (?:is not allowed to execute|may not run sudo)|\S+ is not (?:in the sudoers file|allowed to run sudo on ))/m;
+
+/** ★ An EACCES outside every prefix is almost always a directory the stack forgot to declare. */
+export const undeclared =
+  (path: string, prefixes: readonly string[]) =>
+  (cause: unknown): never => {
+    const code = errnoCode(cause);
+    if (code !== 'EACCES' && code !== 'EPERM') throw cause;
+    throw new Error(
+      `sudoRunner ${path}: ${code} as the deploying user, and the path is under no declared prefix ` +
+        `(${prefixes.join(', ')}). If root owns its directory, declare that directory as a prefix.`,
+      { cause },
+    );
+  };
+
+/**
+ * The refusal sudo itself answered for `shown` (the argv as JSON), or `undefined` when the command
+ * ran — whatever its own exit code. ★ `SudoRefusedError` always means nothing ran as root.
+ */
+export const sudoRefusal = (shown: string, result: ExecResult): SudoRefusedError | undefined => {
+  if (result.exitCode !== 1) return undefined;
+  if (PASSWORD.test(result.stderr)) {
+    return new SudoRefusedError(
+      `sudo -n ${shown}: a password is required, and this runner never prompts. Run \`sudo -v\` ` +
+        'in the deploying terminal just before the deploy, or grant exactly these commands ' +
+        'NOPASSWD (docs/launchd-sudo.md). The command did not run.',
+    );
+  }
+  if (NOT_ALLOWED.test(result.stderr)) {
+    return new SudoRefusedError(
+      `sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`,
+    );
+  }
+  return undefined;
+};

package/src/launchd/sudo-stage.ts

@@ -0,0 +1,28 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into place as root.
+ *
+ * ★ WHY STAGE AT ALL. The deploying user cannot write inside a root-owned directory, and the bytes
+ *   must not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   deploying user, to a private file, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE, O_EXCL: between the write and the install, nobody but the
+ *   deploying user and root can read the bytes or swap the file.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = { readonly path: string; readonly dispose: () => Promise<void> };
+
+export const stageFile = async (bytes: Uint8Array): Promise<Staged> => {
+  const dir = await mkdtemp(join(tmpdir(), 'hf-sudo-'));
+  const dispose = () => rm(dir, { force: true, recursive: true });
+  try {
+    const path = join(dir, 'staged');
+    await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+    return { dispose, path };
+  } catch (cause) {
+    await dispose();
+    throw cause;
+  }
+};