@homeflare/alchemy 0.7.0 → 0.10.0

package/src/launchd/sudo-guard.ts

@@ -0,0 +1,230 @@
+/**
+ * The checks sudo-runner.ts makes against the host, as the deploying user, before it runs anything
+ * as root. sudo-allowlist.ts checks the argv; this checks what the paths in it actually are.
+ *
+ * ⛔ WHAT IS LOGGED IS WHAT IS WRITTEN. A symlinked directory under a prefix would make
+ *   `install` or `rm`, running as root, act on a path the log never named. So every directory
+ *   between the prefix and the file must be a real directory.
+ * ⛔ EVERY DIRECTORY FROM THE PREFIX DOWN IS ROOT'S ALONE (decided 2026-09-21). A directory below
+ *   the prefix that another user owns, or that group or other may write, lets that user swap what
+ *   lies under it — a symlink where the file was — between these checks and the privileged call.
+ *   So each one must be owned by root and not group/other-writable (rootOnlyProblem), exactly as
+ *   the prefix itself must.
+ * ⛔ AND EVERY DIRECTORY ABOVE THE PREFIX (red team, 2026-09-21). Whoever may write the prefix's
+ *   parent may rename the prefix away and put a symlink in its place between these checks and the
+ *   privileged call — the same swap one level up. So `/` down to the prefix's parent must be
+ *   root-only too (a root-owned symlink among them, `/etc` -> `private/etc`, is root's own and is
+ *   followed; its target is root's choice, and not walked).
+ * ⛔ AND NO ACL THAT SAYS OTHERWISE (sudo-acl.ts): mode bits are not the whole answer on macOS.
+ * ⚠️ These checks run before the privileged call, as the deploying user. They guard against a
+ *   mistaken declaration and against every user but root; root itself could still change a path
+ *   in that window.
+ */
+import type { FileStat, HostRunner, WriteOptions } from './runner.ts';
+import { assertNoAclGrants } from './sudo-acl.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+
+const refuse = (path: string, message: string): Error =>
+  new SudoRefusedError(`sudoRunner ${path}: ${message}`);
+
+/** The directories strictly between `prefix` and the file at `path`. */
+export const betweenDirs = (prefix: string, path: string): string[] => {
+  const parts = path
+    .slice(prefix.length + 1)
+    .split('/')
+    .slice(0, -1);
+  return parts.map((_, index) => `${prefix}/${parts.slice(0, index + 1).join('/')}`);
+};
+
+/** The directories strictly above `prefix`: `/`, then each one down to the prefix's parent. */
+export const aboveDirs = (prefix: string): string[] => {
+  const parts = prefix.split('/').slice(1, -1);
+  return ['/', ...parts.map((_, index) => `/${parts.slice(0, index + 1).join('/')}`)];
+};
+
+/**
+ * What must be at `path` itself: a regular file, or (for a write or a remove) nothing yet.
+ * ⚠️ A DIRECTORY AT THE DESTINATION IS THE TRAP: `install src dir` copies INTO the directory
+ *   (install(1)), and install decides that with stat, so a symlink to a directory does the same.
+ */
+export type Expect = 'file' | 'file-or-absent';
+
+/**
+ * ⛔ THE PREFIX, AND EVERY DIRECTORY BELOW IT ON THE WAY TO THE FILE, MUST BE A DIRECTORY ONLY ROOT
+ *   CAN CHANGE, checked at every call rather than trusted from the declaration. A symlinked prefix makes root write wherever it points, which the
+ *   log never names (`/opt/example` -> `/etc` turns a HostFile at `/opt/example/sudoers` into
+ *   `/etc/sudoers`). A prefix another user owns or may write lets that user swap a directory below
+ *   it for a symlink between this check and the privileged call.
+ * ⚠️ lstat of the prefix itself: a symlink ABOVE it (`/etc` -> `/private/etc` on macOS) is the
+ *   system's and is followed, as every path lookup does — when root owns it (aboveDirs).
+ * ★ MEASURED 2026-09-21 on macOS 27.2 (`ls -ldn`): /Library/LaunchDaemons, /private/etc, /opt and
+ *   /usr/local are uid 0, mode 0755, so the prefixes a host stack declares pass as they are.
+ */
+const rootOnlyProblem = (stat: FileStat | undefined): string | undefined => {
+  if (stat === undefined) return 'is missing';
+  if (stat.kind !== 'directory') return `is a ${stat.kind}, not a directory`;
+  if (stat.uid !== 0) return `is owned by uid ${String(stat.uid)}, not root`;
+  if ((stat.mode & 0o022) !== 0) {
+    return `is writable by group or other (mode ${stat.mode.toString(8).padStart(4, '0')})`;
+  }
+  return undefined;
+};
+
+/**
+ * Refuse a prefix that is not a root-only directory, a symlink or a non-directory between the
+ * prefix and `path`, and anything but a file at it.
+ */
+export const assertPlainPath = async (
+  base: HostRunner,
+  prefix: string,
+  path: string,
+  expect: Expect,
+): Promise<'file' | 'absent'> => {
+  const above = aboveDirs(prefix);
+  for (const [index, stat] of (await Promise.all(above.map((dir) => base.stat(dir)))).entries()) {
+    const up = stat?.kind === 'symlink' && stat.uid === 0 ? undefined : rootOnlyProblem(stat);
+    if (up !== undefined) {
+      throw refuse(
+        path,
+        `${String(above[index])}, above the declared prefix ${prefix}, ${up}. Whoever may change it ` +
+          'may swap the prefix itself; every directory from / down must be root-only. Nothing ran as root.',
+      );
+    }
+  }
+  const dirs = betweenDirs(prefix, path);
+  const [prefixStat, ...stats] = await Promise.all([prefix, ...dirs].map((dir) => base.stat(dir)));
+  const bad = rootOnlyProblem(prefixStat);
+  if (bad !== undefined) {
+    throw refuse(
+      path,
+      `the declared prefix ${prefix} ${bad}. Declare only a real directory that root owns and ` +
+        'only root may write. Nothing ran as root.',
+    );
+  }
+  for (const [index, stat] of stats.entries()) {
+    const dir = String(dirs[index]);
+    if (stat?.kind !== 'directory') {
+      throw refuse(
+        path,
+        `${dir} is ${stat === undefined ? 'missing' : `a ${stat.kind}`}; root ` +
+          'writes only through real directories under a declared prefix.',
+      );
+    }
+    const below = rootOnlyProblem(stat);
+    if (below !== undefined) {
+      throw refuse(
+        path,
+        `${dir} ${below}. Every directory from the prefix ${prefix} down to the file must be one ` +
+          'that root owns and only root may write. Nothing ran as root.',
+      );
+    }
+  }
+  await assertNoAclGrants(base, path, [...above, prefix, ...dirs]);
+  const target = await base.stat(path);
+  if (target === undefined && expect === 'file-or-absent') return 'absent';
+  if (target?.kind === 'file') return 'file';
+  throw refuse(path, `is ${target === undefined ? 'missing' : `a ${target.kind}`}, not a file`);
+};
+
+/**
+ * ⛔ A ROOT-OWNED FILE UNDER A PREFIX IS ROOT'S TO CHANGE, AND ONLY ROOT'S (decided 2026-09-21).
+ *   Group- or world-writable, anyone in that class rewrites a file root installed — a daemon's
+ *   config, a script a LaunchDaemon runs as root — which is root by another name. Setuid or setgid,
+ *   it runs as root (or its group) for whoever executes it. install(1) would apply either, as root.
+ * ★ Root-owned is an omitted owner (the runner installs as root under a prefix) or uid 0. A file
+ *   handed to another user is that user's to change; the sticky bit changes nothing on a file.
+ */
+export const modeProblem = (options: WriteOptions): string | undefined => {
+  if (options.uid !== undefined && options.uid !== 0) return undefined;
+  const found: string[] = [];
+  if ((options.mode & 0o6000) !== 0) found.push('setuid/setgid');
+  if ((options.mode & 0o022) !== 0) found.push('writable by group or other');
+  if (found.length === 0) return undefined;
+  return `mode ${options.mode.toString(8).padStart(4, '0')} is ${found.join(' and ')} on a root-owned file`;
+};
+
+/**
+ * Every check a write under `prefix` meets before anything is staged or run as root: the mode, the
+ * path (assertPlainPath) and the read-back (assertReadableBack). ★ Reads only, as the deploying
+ *   user — so sudoRunner's `checkWrite` runs it at PLAN time too, and a plan still never calls sudo.
+ */
+export const assertInstallable = async (
+  base: HostRunner,
+  prefix: string,
+  path: string,
+  options: WriteOptions,
+  groups: readonly number[] | undefined,
+): Promise<void> => {
+  const mode = modeProblem(options);
+  if (mode !== undefined) {
+    throw refuse(
+      path,
+      `${mode}. Declare a mode without those bits (0644, 0640, 0755), or give the file to its ` +
+        'real owner. Nothing ran as root.',
+    );
+  }
+  await assertPlainPath(base, prefix, path, 'file-or-absent');
+  await assertReadableBack(base, path, options, groups);
+};
+
+/**
+ * POSIX read permission for one uid: owner class, else group class, else other. `undefined` when
+ * only group membership could decide and the groups are unknown.
+ * ⚠️ EXACTLY ONE CLASS APPLIES. A group member gets the group bits even when the other bits are
+ *   wider (`0604` hides a file from its group), so "other can read" is not enough on its own.
+ */
+export const canRead = (
+  file: { readonly uid: number; readonly gid: number; readonly mode: number },
+  uid: number,
+  groups: readonly number[] | undefined,
+): boolean | undefined => {
+  if (uid === 0) return true;
+  if (file.uid === uid) return (file.mode & 0o400) !== 0;
+  const groupRead = (file.mode & 0o040) !== 0;
+  const otherRead = (file.mode & 0o004) !== 0;
+  // Membership cannot change the answer when both classes agree.
+  if (groupRead === otherRead) return groupRead;
+  if (groups === undefined) return undefined;
+  return groups.includes(file.gid) ? groupRead : otherRead;
+};
+
+/**
+ * ⛔ REFUSE A FILE THE DEPLOYING USER COULD NOT READ BACK, before writing it. Both providers read
+ *   every write back to verify it (host-file-lifecycle.ts, job-lifecycle.ts) and read it again at
+ *   every plan, as the deploying user; this runner elevates writes, never reads. A root-only
+ *   `0600` would be installed, then fail the read-back with EACCES and stay on disk with no state,
+ *   so every later plan would fail too.
+ * ★ An omitted owner is root (under a prefix the runner writes as root). An omitted group is the
+ *   parent directory's, which is the group a new file gets on macOS.
+ * ⚠️ Unknown groups never refuse: the read-back after the write stays the final judge.
+ */
+export const assertReadableBack = async (
+  base: HostRunner,
+  path: string,
+  options: WriteOptions,
+  groups: readonly number[] | undefined,
+): Promise<void> => {
+  const operator = base.effectiveUid();
+  const parent = path.slice(0, path.lastIndexOf('/')) || '/';
+  const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;
+  const file = { gid, mode: options.mode, uid: options.uid ?? 0 };
+  if (canRead(file, operator, groups) !== false) return;
+  throw refuse(
+    path,
+    `owner ${String(file.uid)}, group ${String(gid)}, mode ${file.mode.toString(8)} would hide it ` +
+      `from the deploying user (uid ${String(operator)}), who reads every file back. Declare a ` +
+      'mode that user can read, or deploy as root. Nothing was written.',
+  );
+};
+
+/**
+ * The deploying user's groups, from `id -G`; `undefined` when that fails.
+ * ⚠️ NOT process.getgroups(). MEASURED 2026-09-21 on macOS 27.2: getgroups() returned 16 groups
+ *   where `id -G` returned 18, because macOS caps a process's own list at 16. A group past the
+ *   16th would read as "not a member" and refuse a file the user can in fact read.
+ */
+export const operatorGroups = async (base: HostRunner): Promise<readonly number[] | undefined> => {
+  const result = await base.exec(['/usr/bin/id', '-G']);
+  const ids = result.stdout.trim().split(/\s+/);
+  return result.exitCode === 0 && ids.every((id) => /^\d+$/.test(id)) ? ids.map(Number) : undefined;
+};

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

@@ -0,0 +1,172 @@
+/**
+ * The real LaunchdJob and HostFile lifecycles, driven through sudoRunner over the fake host: the
+ * deploying user is uid 501, and the only way anything root-owned changes is an allowlisted
+ * `sudo -n` call. No real sudo, launchctl or /Library write happens.
+ *
+ * ★ The assertions are on the PRIVILEGED SEQUENCE, because that list is the whole point: a plan
+ *   needs none, a create is install + bootstrap, a delete is bootout + rm.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeSudoHost } from './fake-sudo.ts';
+import { deleteFile, reconcileFile } from './host-file-lifecycle.ts';
+import type { LaunchdJobAttributes, LaunchdJobProps } from './job-form.ts';
+import { deleteJob, diffJob, readJob, reconcileJob } from './job-lifecycle.ts';
+import { INSTALL, RM } from './sudo-allowlist.ts';
+
+const DAEMON = '/Library/LaunchDaemons/com.example.job.plist';
+const job: LaunchdJobProps = {
+  domain: 'system',
+  keepAlive: true,
+  label: 'com.example.job',
+  programArguments: ['/usr/local/bin/job'],
+};
+
+/** Each privileged call as its program and first operand, e.g. `launchctl bootout`. */
+const fail = (): never => {
+  throw new Error('the deployed plist is missing');
+};
+
+const verbs = (privileged: string[][]) =>
+  privileged.map(([program, first]) =>
+    program === INSTALL ? 'install' : program === RM ? 'rm' : `launchctl ${String(first)}`,
+  );
+
+describe('a system daemon, deployed as the operator', () => {
+  test('create is install then bootstrap; the plist lands root:wheel 0644', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileJob(host.runner, job, undefined);
+    expect(verbs(host.privileged())).toEqual(['install', 'launchctl bootstrap']);
+    expect(host.fake.files.get(DAEMON)).toMatchObject({ gid: 0, mode: 0o644, uid: 0 });
+    expect(attrs).toMatchObject({ loaded: true, plistPath: DAEMON });
+    expect(host.logs).toHaveLength(2);
+  });
+
+  test('a plan (read, diff) needs no sudo at all', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileJob(host.runner, job, undefined);
+    const before = host.sudoCalls.length;
+    expect(await readJob(host.runner, job)).toMatchObject({ loaded: true });
+    expect(await diffJob(host.runner, job, attrs)).toEqual({ action: 'noop' });
+    expect(await diffJob(host.runner, { ...job, runAtLoad: true }, attrs)).toEqual({
+      action: 'update',
+    });
+    expect(host.sudoCalls).toHaveLength(before);
+  });
+
+  test('update is install, bootout, bootstrap — in that order', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileJob(host.runner, job, undefined);
+    await reconcileJob(host.runner, { ...job, runAtLoad: true }, attrs);
+    expect(verbs(host.privileged())).toEqual([
+      'install',
+      'launchctl bootstrap',
+      'install',
+      'launchctl bootout',
+      'launchctl bootstrap',
+    ]);
+  });
+
+  test('delete is bootout then rm', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileJob(host.runner, job, undefined);
+    await deleteJob(host.runner, attrs);
+    expect(verbs(host.privileged()).slice(2)).toEqual(['launchctl bootout', 'rm']);
+    expect(host.fake.files.has(DAEMON)).toBe(false);
+    expect(host.fake.loaded.has('system/com.example.job')).toBe(false);
+  });
+
+  test('sudo wanting a password on an update leaves the old job running, untouched', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileJob(host.runner, job, undefined);
+    const pid = host.fake.loaded.get('system/com.example.job');
+    const before = host.fake.files.get(DAEMON)?.bytes;
+    host.state.sudo = 'password';
+    await expect(reconcileJob(host.runner, { ...job, runAtLoad: true }, attrs)).rejects.toThrow(
+      'a password is required',
+    );
+    expect(host.fake.loaded.get('system/com.example.job')).toBe(pid);
+    expect(host.fake.files.get(DAEMON)?.bytes).toBe(before);
+  });
+});
+
+test('without /Library/LaunchDaemons declared, a delete is refused before the bootout', async () => {
+  const deployed = fakeSudoHost();
+  const attrs = await reconcileJob(deployed.runner, job, undefined);
+  // The same host, now driven by a runner that declares only /opt/example.
+  const narrow = fakeSudoHost([20, 80], ['/opt/example']);
+  narrow.fake.files.set(DAEMON, deployed.fake.files.get(DAEMON) ?? fail());
+  narrow.fake.loaded.set('system/com.example.job', 4242);
+  await expect(deleteJob(narrow.runner, attrs)).rejects.toThrow('/Library/LaunchDaemons');
+  // ⚠️ Not half a delete: the job still runs and its plist is still there, both or neither.
+  expect(narrow.fake.loaded.get('system/com.example.job')).toBe(4242);
+  expect(narrow.fake.files.has(DAEMON)).toBe(true);
+  expect(narrow.sudoCalls).toEqual([]);
+});
+
+describe("another user's gui domain is not elevated", () => {
+  const theirs: LaunchdJobProps = { ...job, domain: 'gui/502' };
+
+  test('create is refused at the write, with nothing written or loaded', async () => {
+    const host = fakeSudoHost();
+    await expect(reconcileJob(host.runner, theirs, undefined)).rejects.toThrow(
+      'owner 502 needs root',
+    );
+    expect(host.fake.files.size).toBe(0);
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test('delete is refused at the bootout, and their job keeps running', async () => {
+    const host = fakeSudoHost();
+    host.fake.loaded.set('gui/502/com.example.job', 4242);
+    const output: LaunchdJobAttributes = {
+      domain: 'gui/502',
+      label: 'com.example.job',
+      loaded: true,
+      plistPath: '/Users/other/Library/LaunchAgents/com.example.job.plist',
+      plistSha256: '',
+      serviceTarget: 'gui/502/com.example.job',
+    };
+    await expect(deleteJob(host.runner, output)).rejects.toThrow('elevates only the system domain');
+    expect(host.fake.loaded.get('gui/502/com.example.job')).toBe(4242);
+    expect(host.sudoCalls).toEqual([]);
+  });
+});
+
+describe('a root-owned HostFile under a declared prefix', () => {
+  const PATH = '/opt/example/app/exporter.yml';
+  const file = {
+    content: 'listen: 127.0.0.1:9100\n',
+    group: 80,
+    mode: 0o640,
+    owner: 0,
+    path: PATH,
+  };
+
+  test('is installed with its owner, group and mode, verified by the read-back', async () => {
+    const host = fakeSudoHost();
+    const attrs = await reconcileFile(host.runner, file);
+    expect(attrs).toMatchObject({ gid: 80, mode: 0o640, uid: 0 });
+    expect(host.privileged()[0]?.slice(0, 8)).toEqual([
+      INSTALL,
+      '-S',
+      '-m',
+      '0640',
+      '-o',
+      '0',
+      '-g',
+      '80',
+    ]);
+    await deleteFile(host.runner, attrs);
+    expect(verbs(host.privileged())).toEqual(['install', 'rm']);
+    expect(host.fake.files.has(PATH)).toBe(false);
+  });
+
+  test('a mode the operator could not read back is refused with nothing written', async () => {
+    const host = fakeSudoHost();
+    await expect(reconcileFile(host.runner, { ...file, group: 0, mode: 0o600 })).rejects.toThrow(
+      'Nothing was written',
+    );
+    expect(host.fake.files.has(PATH)).toBe(false);
+    expect(host.sudoCalls).toEqual([]);
+  });
+});

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

@@ -0,0 +1,135 @@
+/**
+ * sudoRunner's 2026-09-21 refusals, over the fake host (fake-sudo.ts): no group/world-writable,
+ * setuid or setgid root-owned file under a prefix, and no directory from the prefix down that root
+ * does not own alone. Each is refused before anything is staged or run as root — and, through
+ * `checkWrite`, at PLAN time, still without sudo.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, fakeSudoHost } from './fake-sudo.ts';
+import { diffFile, reconcileFile } from './host-file-lifecycle.ts';
+import type { LaunchdJobProps } from './job-form.ts';
+import { diffJob, reconcileJob } from './job-lifecycle.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { modeProblem } from './sudo-guard.ts';
+
+const CONF = '/opt/example/app/a.conf';
+const bytes = (text: string) => new TextEncoder().encode(text);
+type Host = ReturnType<typeof fakeSudoHost>;
+const dir = (mode: number, uid = 0) => ({
+  bytes: bytes(''),
+  gid: 0,
+  kind: 'directory' as const,
+  mode,
+  uid,
+});
+
+describe('modeProblem', () => {
+  test.each([
+    ['0644 root', { mode: 0o644, uid: 0 }, undefined],
+    ['0755 with the owner omitted (root under a prefix)', { mode: 0o755 }, undefined],
+    ['0640 root', { mode: 0o640, uid: 0 }, undefined],
+    ['sticky 1755 changes nothing on a file', { mode: 0o1755 }, undefined],
+    ['0664 root is group-writable', { mode: 0o664 }, 'writable by group or other'],
+    ['0646 root is world-writable', { mode: 0o646, uid: 0 }, 'writable by group or other'],
+    ['4755 root is setuid', { mode: 0o4755 }, 'setuid/setgid'],
+    ['2755 root is setgid', { mode: 0o2755, uid: 0 }, 'setuid/setgid'],
+    ['6777 root is both', { mode: 0o6777 }, 'setuid/setgid and writable by group or other'],
+    ['0664 handed to another user is theirs to change', { mode: 0o664, uid: OPERATOR }, undefined],
+  ] as const)('%s', (_name, options, found) => {
+    const problem = modeProblem(options);
+    if (found === undefined) expect(problem).toBeUndefined();
+    else expect(problem).toContain(found);
+  });
+});
+
+describe('a root-owned install under a prefix', () => {
+  test.each([0o664, 0o646, 0o4755, 0o2755])(
+    'mode %o is refused before staging or sudo',
+    async (mode) => {
+      const host = fakeSudoHost();
+      const write = host.runner.writeFileAtomic(CONF, bytes('x'), { mode });
+      await expect(write).rejects.toBeInstanceOf(SudoRefusedError);
+      await expect(write).rejects.toThrow('on a root-owned file');
+      expect(host.state.stagedCount).toBe(0);
+      expect(host.sudoCalls).toEqual([]);
+    },
+  );
+
+  test('an omitted-owner 0644 still installs, as root', async () => {
+    const host = fakeSudoHost();
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ mode: 0o644, uid: 0 });
+  });
+});
+
+describe('every directory from the prefix down to the file', () => {
+  const below: [string, (h: Host) => void, string][] = [
+    ['owned by the operator', (h) => h.fake.dirs.set('/opt/example/app', OPERATOR), 'uid 501'],
+    ['group-writable', (h) => h.fake.files.set('/opt/example/app', dir(0o775)), '0775'],
+    ['world-writable', (h) => h.fake.files.set('/opt/example/app', dir(0o757)), '0757'],
+  ];
+
+  test.each(below)('%s is refused for a write, before staging or sudo', async (_n, setup, says) => {
+    const host = fakeSudoHost();
+    setup(host);
+    const write = host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    await expect(write).rejects.toBeInstanceOf(SudoRefusedError);
+    await expect(write).rejects.toThrow(
+      /\/opt\/example\/app is .*(uid 501|0775|0757).*Every directory from the prefix/s,
+    );
+    await expect(write).rejects.toThrow(says);
+    expect(host.state.stagedCount).toBe(0);
+    expect(host.sudoCalls).toEqual([]);
+  });
+
+  test.each(below)('%s is refused for a remove too', async (_n, setup, says) => {
+    const host = fakeSudoHost();
+    host.fake.files.set(CONF, { ...dir(0o644), kind: 'file' });
+    setup(host);
+    await expect(host.runner.removeFile(CONF)).rejects.toThrow(says);
+    expect(host.sudoCalls).toEqual([]);
+  });
+});
+
+describe('at plan time, through checkWrite — reads only, never sudo', () => {
+  test('HostFile: a diff that would write a setuid root file fails the plan', async () => {
+    const host = fakeSudoHost();
+    const output = await reconcileFile(host.runner, { content: 'x', mode: 0o755, path: CONF });
+    const before = host.sudoCalls.length;
+    const plan = diffFile(host.runner, { content: 'x', mode: 0o4755, path: CONF }, output);
+    await expect(plan).rejects.toThrow('setuid/setgid');
+    expect(host.sudoCalls).toHaveLength(before);
+    // ★ A converged file plans noop and asks nothing, so an unrelated plan is never blocked by it.
+    expect(await diffFile(host.runner, { content: 'x', mode: 0o755, path: CONF }, output)).toEqual({
+      action: 'noop',
+    });
+  });
+
+  test('HostFile: a new path under a directory another user may write fails the plan', async () => {
+    const host = fakeSudoHost();
+    const output = await reconcileFile(host.runner, { content: 'x', path: CONF });
+    host.fake.dirs.set('/opt/example/other', OPERATOR);
+    const moved = { content: 'x', path: '/opt/example/other/a.conf' };
+    await expect(diffFile(host.runner, moved, output)).rejects.toThrow('uid 501');
+  });
+
+  test.each([
+    ['an update', { runAtLoad: true }],
+    ['a rename (the delete-first replace)', { label: 'com.example.renamed' }],
+  ] as const)(
+    'LaunchdJob: %s into a group-writable LaunchDaemons fails the plan',
+    async (_n, change) => {
+      const job: LaunchdJobProps = {
+        domain: 'system',
+        label: 'com.example.job',
+        programArguments: ['/usr/local/bin/job'],
+      };
+      const host = fakeSudoHost();
+      const attrs = await reconcileJob(host.runner, job, undefined);
+      host.fake.files.set('/Library/LaunchDaemons', dir(0o775));
+      const before = host.sudoCalls.length;
+      await expect(diffJob(host.runner, { ...job, ...change }, attrs)).rejects.toThrow('0775');
+      expect(host.sudoCalls).toHaveLength(before);
+    },
+  );
+});