@homeflare/alchemy 0.8.0 → 0.10.0

package/src/launchd/runner.ts

@@ -73,6 +73,13 @@ export interface HostRunner {
    * ⚠️ The parent directory must exist; creating it would invent an owner and mode nobody declared.
    */
   writeFileAtomic(path: string, bytes: Uint8Array, options: WriteOptions): Promise<void>;
+  /**
+   * PLAN TIME: refuse, reading only and writing nothing, a write this runner would refuse at
+   * apply — so the plan shows it before any resource is applied. Optional: a runner without it
+   * refuses at the write. ★ sudoRunner implements it with the checks it makes before `sudo -n`;
+   *   ⛔ it never elevates, so a plan still never calls sudo.
+   */
+  checkWrite?(path: string, options: WriteOptions): Promise<void>;
   /** Remove a file. Idempotent: nothing at `path` is success. */
   removeFile(path: string): Promise<void>;
   /** A user by name or numeric id, or `undefined` when the host has none. */

package/src/launchd/sudo-acl.ts

@@ -0,0 +1,68 @@
+/**
+ * The ACL half of sudo-guard.ts: mode bits say a directory is root's alone, and an ACL can say
+ * otherwise. On macOS an `allow add_file,add_subdirectory,delete_child` entry lets its holder swap
+ * what lies under a root-owned `0755` directory — a symlink where the file was — between the
+ * guard's lstat checks and the privileged call, exactly as group write would. An inheritable
+ * `allow write` hands every file root installs there to its holder.
+ *
+ * ★ READ WITH `ls -lden`, AS THE OPERATOR — no sudo, and the same read at plan time and before the
+ *   write. MEASURED 2026-09-21 on macOS 27.2: each entry prints on its own line after the path's,
+ *   as ` 0: <qualifier> [inherited ]allow|deny <perms>`; `-n` makes the qualifier a UUID, never a
+ *   name with a space in it. The `+` flag after the mode is NOT reliable — `@` (extended
+ *   attributes) replaces it in the listing — so the entries are what is read.
+ * ⚠️ A DENY ENTRY GRANTS NOTHING (macOS puts `everyone deny delete` on home folders), and an allow
+ *   of read-only rights (`list`, `search`, `readattr` …) swaps nothing, so neither refuses.
+ */
+import type { HostRunner } from './runner.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+
+export const LS = '/bin/ls';
+
+/** Rights that let the holder add, remove, rename or re-permission what a directory holds. */
+const WRITE_RIGHTS: ReadonlySet<string> = new Set([
+  'add_file',
+  'add_subdirectory',
+  'append',
+  'chown',
+  'delete',
+  'delete_child',
+  'write',
+  'writesecurity',
+]);
+
+const ENTRY = /^\s*\d+:\s+\S+\s+(?:inherited\s+)?allow\s+(\S+)/;
+
+/** The allow entries in `ls -lden` output that grant a write right, as printed. */
+export const aclGrants = (listing: string): string[] =>
+  listing
+    .split('\n')
+    .filter((line) => {
+      const rights = ENTRY.exec(line)?.[1];
+      return rights !== undefined && rights.split(',').some((right) => WRITE_RIGHTS.has(right));
+    })
+    .map((line) => line.trim());
+
+/**
+ * ⛔ Refuse when any directory in `chain` carries an ACL entry that lets someone write it, or when
+ *   the ACLs cannot be read at all (fail closed). `path` names the file in the refusal.
+ */
+export const assertNoAclGrants = async (
+  base: HostRunner,
+  path: string,
+  chain: readonly string[],
+): Promise<void> => {
+  const listed = await base.exec([LS, '-lden', '--', ...chain]);
+  if (listed.exitCode !== 0) {
+    throw new SudoRefusedError(
+      `sudoRunner ${path}: could not read the ACLs of the directories from / down to it ` +
+        `(${LS} -lden exit ${String(listed.exitCode)}). Nothing ran as root.`,
+    );
+  }
+  const grants = aclGrants(listed.stdout);
+  if (grants.length === 0) return;
+  throw new SudoRefusedError(
+    `sudoRunner ${path}: a directory from / down to it carries an ACL that lets someone other ` +
+      `than root change what it holds (${grants.join('; ')}). Remove the entry (chmod -a), or ` +
+      'declare a prefix without one. Nothing ran as root.',
+  );
+};

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

@@ -0,0 +1,121 @@
+/**
+ * sudoRunner's red-team refusals (2026-09-21), over the fake host (fake-sudo.ts): a directory ABOVE
+ * the prefix that someone other than root may change, and an ACL anywhere from / down that grants a
+ * write right. Either lets that someone swap the path between the guard and `sudo -n`. Each is
+ * refused before anything is staged or run as root, and at plan time through `checkWrite`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { OPERATOR, fakeSudoHost } from './fake-sudo.ts';
+import { diffFile, reconcileFile } from './host-file-lifecycle.ts';
+import type { HostRunner } from './runner.ts';
+import { aclGrants, assertNoAclGrants } from './sudo-acl.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { aboveDirs } 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 entry = (kind: 'directory' | 'symlink', mode: number, uid = 0) => ({
+  bytes: bytes(''),
+  gid: 0,
+  kind,
+  mode,
+  uid,
+});
+
+/** As `ls -lden` printed them on macOS 27.2 (sudo-acl.ts): a UUID qualifier, one entry a line. */
+const UUID = 'ABCDEFAB-CDEF-ABCD-EFAB-CDEF00000014';
+
+test('aboveDirs is / down to the parent of the prefix', () => {
+  expect(aboveDirs('/Library/LaunchDaemons')).toEqual(['/', '/Library']);
+  expect(aboveDirs('/opt/example')).toEqual(['/', '/opt']);
+  expect(aboveDirs('/opt')).toEqual(['/']);
+});
+
+describe('aclGrants', () => {
+  test('an allow of a write right counts; deny, and read-only rights, do not', () => {
+    const listing = [
+      `drwxr-xr-x@ 3 0 0 96 Sep 21 19:36 /opt/example`,
+      ` 0: ${UUID} allow add_file,add_subdirectory,delete_child`,
+      ` 1: ${UUID} inherited allow write,file_inherit`,
+      ` 2: ${UUID} deny delete`,
+      ` 3: ${UUID} allow list,search,readattr`,
+    ].join('\n');
+    expect(aclGrants(listing)).toEqual([
+      `0: ${UUID} allow add_file,add_subdirectory,delete_child`,
+      `1: ${UUID} inherited allow write,file_inherit`,
+    ]);
+  });
+
+  test('fails closed when the ACLs cannot be read', async () => {
+    const base = { exec: async () => ({ exitCode: 1, stderr: 'ls: x', stdout: '' }) };
+    const read = assertNoAclGrants(base as unknown as HostRunner, CONF, ['/']);
+    await expect(read).rejects.toThrow('could not read the ACLs');
+  });
+});
+
+const refusedBeforeSudo = async (host: Host, says: string | RegExp) => {
+  const write = host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+  await expect(write).rejects.toBeInstanceOf(SudoRefusedError);
+  await expect(write).rejects.toThrow(says);
+  expect(host.state.stagedCount).toBe(0);
+  expect(host.sudoCalls).toEqual([]);
+};
+
+describe('every directory above the prefix', () => {
+  test.each([
+    ['owned by the operator', (h: Host) => h.fake.dirs.set('/opt', OPERATOR), 'uid 501'],
+    ['group-writable', (h: Host) => h.fake.files.set('/opt', entry('directory', 0o775)), '0775'],
+    [
+      'a symlink the operator owns',
+      (h: Host) => h.fake.files.set('/opt', entry('symlink', 0o755, OPERATOR)),
+      'symlink',
+    ],
+  ] as const)('%s is refused before staging or sudo', async (_n, setup, says) => {
+    const host = fakeSudoHost();
+    setup(host);
+    await refusedBeforeSudo(host, says);
+    await expect(host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 })).rejects.toThrow(
+      /\/opt, above the declared prefix \/opt\/example/,
+    );
+  });
+
+  test("a root-owned symlink (/etc -> private/etc) is root's own, and followed", async () => {
+    const host = fakeSudoHost();
+    host.fake.files.set('/opt', entry('symlink', 0o755));
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ mode: 0o644, uid: 0 });
+  });
+
+  test('a HostFile plan that would write under it fails, still without sudo', async () => {
+    const host = fakeSudoHost();
+    const output = await reconcileFile(host.runner, { content: 'x', path: CONF });
+    host.fake.dirs.set('/opt', OPERATOR);
+    const before = host.sudoCalls.length;
+    await expect(diffFile(host.runner, { content: 'y', path: CONF }, output)).rejects.toThrow(
+      'uid 501',
+    );
+    expect(host.sudoCalls).toHaveLength(before);
+  });
+});
+
+describe('an ACL from / down to the file', () => {
+  test.each(['/', '/opt', '/opt/example', '/opt/example/app'])(
+    'that grants a write right on %s is refused before staging or sudo',
+    async (dir) => {
+      const host = fakeSudoHost();
+      host.fake.acls.set(dir, [` 0: ${UUID} allow add_file,delete_child`]);
+      await refusedBeforeSudo(host, 'carries an ACL');
+      host.fake.files.set(CONF, { bytes: bytes('x'), gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+      await expect(host.runner.removeFile(CONF)).rejects.toThrow('carries an ACL');
+      expect(host.sudoCalls).toEqual([]);
+    },
+  );
+
+  test('a deny-only ACL (as on a home folder) is no refusal', async () => {
+    const host = fakeSudoHost();
+    host.fake.acls.set('/opt/example/app', [` 0: ${UUID} deny delete`]);
+    await host.runner.writeFileAtomic(CONF, bytes('x'), { mode: 0o644 });
+    expect(host.fake.files.get(CONF)).toMatchObject({ uid: 0 });
+  });
+});

package/src/launchd/sudo-guard.ts

@@ -5,12 +5,23 @@
  * ⛔ 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.
- * ⚠️ These checks run before the privileged call, so they guard against a mistaken declaration, not
- *   against someone who can already write inside a prefix and swap a path in between. The prefix
- *   itself is checked to be root-only (prefixProblem); a directory BELOW it that another user owns
- *   is not, and that user could swap what lies under it in that window.
+ * ⛔ 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 =>
@@ -25,6 +36,12 @@ export const betweenDirs = (prefix: string, path: string): string[] => {
   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
@@ -33,17 +50,17 @@ export const betweenDirs = (prefix: string, path: string): string[] => {
 export type Expect = 'file' | 'file-or-absent';
 
 /**
- * ⛔ THE PREFIX ITSELF 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
+ * ⛔ 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. ACLs are not read; mode bits only.
+ *   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 prefixProblem = (stat: FileStat | undefined): string | undefined => {
+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`;
@@ -63,9 +80,20 @@ export const assertPlainPath = async (
   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 = prefixProblem(prefixStat);
+  const bad = rootOnlyProblem(prefixStat);
   if (bad !== undefined) {
     throw refuse(
       path,
@@ -74,20 +102,71 @@ export const assertPlainPath = async (
     );
   }
   for (const [index, stat] of stats.entries()) {
+    const dir = String(dirs[index]);
     if (stat?.kind !== 'directory') {
       throw refuse(
         path,
-        `${String(dirs[index])} is ${stat === undefined ? 'missing' : `a ${stat.kind}`}; root ` +
+        `${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.

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);
+    },
+  );
+});

package/src/launchd/sudo-runner.ts

@@ -21,12 +21,12 @@
  * ★ `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. 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).
+ * ⚠️ 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, errnoCode, localRunner } from './local-runner.ts';
-import type { ExecResult, HostRunner } from './runner.ts';
+import { type LocalRunnerOptions, localRunner } from './local-runner.ts';
+import type { ExecResult, HostRunner, WriteOptions } from './runner.ts';
 import {
   INSTALL,
   RM,
@@ -38,7 +38,8 @@ import {
   privilegedProblem,
   routeExec,
 } from './sudo-allowlist.ts';
-import { assertPlainPath, assertReadableBack, operatorGroups } from './sudo-guard.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 };
@@ -66,31 +67,6 @@ export type SudoDeps = {
   readonly log: (line: string) => void;
 };
 
-/**
- * ⚠️ 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. */
-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 },
-    );
-  };
-
 export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): HostRunner => {
   const prefixes = checkPrefixes(prefixList);
   const { base } = deps;
@@ -113,22 +89,35 @@ export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): H
     await before?.();
     deps.log(`homeflare/launchd sudo -n ${shown}`);
     const result = await base.exec([SUDO, '-n', '--', ...argv]);
-    if (result.exitCode !== 1) return result;
-    if (PASSWORD.test(result.stderr)) {
-      throw 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)) {
-      throw new SudoRefusedError(
-        `sudo -n ${shown}: sudoers does not let the deploying user run this. The command did not run.`,
-      );
-    }
+    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 });
@@ -139,6 +128,10 @@ export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): H
   };
 
   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());
@@ -177,23 +170,11 @@ export const makeSudoRunner = (prefixList: readonly string[], deps: SudoDeps): H
     sleep: (ms) => base.sleep(ms),
     stat: (path) => base.stat(path),
     writeFileAtomic: async (path, bytes, options) => {
-      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.',
-          );
-        }
+      const vetted = await vetWrite(path, options);
+      if (vetted === undefined) {
         return base.writeFileAtomic(path, bytes, options).catch(undeclared(path, prefixes));
       }
-      const mode = octalMode(options.mode);
-      if (mode === undefined)
-        throw new SudoRefusedError(`sudoRunner ${path}: mode must be 0–0o7777`);
-      await assertPlainPath(base, prefix, path, 'file-or-absent');
-      await assertReadableBack(base, path, options, await deps.groups());
+      const { mode } = vetted;
       const staged = await deps.stage(bytes);
       try {
         await mustSucceed(