@homeflare/alchemy 0.19.1 → 0.21.0

package/src/launchd/runner.ts

@@ -33,10 +33,23 @@ export type FileStat = {
   readonly uid: number;
   readonly gid: number;
   readonly size: number;
+  /**
+   * The entry's identity, device and inode, when the runner can say. ★ Two spellings of ONE file
+   *   (`/tmp/x` and `/private/tmp/x`; `Bin` and `bin` on case-insensitive APFS) differ as strings
+   *   and match here, and a move must not delete its old path when that path IS the new file
+   *   (file-identity.ts). Optional: a runner that leaves them out gets a check after the fact.
+   */
+  readonly dev?: number;
+  readonly ino?: number;
 };
 
 export type WriteOptions = {
-  /** Permission bits for the final file, applied BEFORE it becomes visible at `path`. */
+  /**
+   * Permission bits for the final file. localRunner applies them BEFORE the file is visible at
+   * `path`. ⚠️ sudoRunner's `install -S` does NOT: MEASURED 2026-09-22 on macOS 27.2 (an lstat
+   *   poller racing /usr/bin/install), the new inode appears at `path` as 0600 and is chmodded
+   *   0.2–0.4 ms later. Never torn, never wider than declared, but briefly not executable.
+   */
   readonly mode: number;
   /** Numeric owner; omitted means whoever the runner writes as. */
   readonly uid?: number;
@@ -69,7 +82,9 @@ export interface HostRunner {
   stat(path: string): Promise<FileStat | undefined>;
   /**
    * Write `bytes` so that `path` holds either the old file or the new one, never a torn mix:
-   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`.
+   * a temporary file in the same directory, mode and owner set on it, then rename(2) over `path`
+   * (sudoRunner: the mode just after the rename, measured — see WriteOptions.mode; the owner too,
+   * ⚠️ REASONED NOT MEASURED, since measuring it needs root).
    * ⚠️ The parent directory must exist; creating it would invent an owner and mode nobody declared.
    */
   writeFileAtomic(path: string, bytes: Uint8Array, options: WriteOptions): Promise<void>;

package/src/launchd/sudo-runner.ts

@@ -21,6 +21,17 @@
  * ★ `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.
+ * ⚠️ BUT IT CHMODS AFTER THE RENAME. MEASURED 2026-09-22 (an lstat poller racing
+ *   `/usr/bin/install -S -m 0755`, 300 MB, six runs, target absent and present): the new inode
+ *   is visible at the path as 0600, then 0755 0.2–0.4 ms later. Only ever narrower than declared.
+ *   ⚠️ REASONED NOT MEASURED: a launchd start inside that window gets EACCES and retries after its
+ *   throttle, and an install killed inside it leaves a root-owned 0600 file the operator cannot
+ *   read back. Closing it needs a second privileged step (install to a temp name, then rename),
+ *   which is a change to this allowlist and wants its own red team.
+ * ⚠️ AND IT COPIES XATTRS, com.apple.quarantine included (MEASURED 2026-09-22: a quarantined
+ *   source installed as a quarantined target). The staged file is written by this process, and
+ *   node:fs writes here carried only com.apple.provenance (measured the same day) — so nothing
+ *   is quarantined today, but a quarantined staging file would be installed quarantined.
  * ⚠️ 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.

package/src/linux/region.ts

@@ -34,6 +34,21 @@ const tokens = (spec: RegionSpec) => {
   };
 };
 
+/**
+ * Whether two declarations name the SAME block.
+ *
+ * ⛔ THE COMMENT TOKEN IS PART OF THE IDENTITY, not a formatting preference. The markers are
+ *   matched as literal whole lines, so `# BEGIN pf` and `// BEGIN pf` are two different blocks:
+ *   changing the token leaves the old block invisible to every later read, exactly as renaming
+ *   does. A resource that treated either as a mere content change would splice a second block in
+ *   and never be able to find the first one again.
+ * ★ Whole-file mode is its own identity: `undefined` equals only `undefined`.
+ */
+export const sameRegion = (a: RegionSpec | undefined, b: RegionSpec | undefined): boolean =>
+  a === undefined || b === undefined
+    ? a === undefined && b === undefined
+    : a.name === b.name && (a.comment ?? DEFAULT_COMMENT) === (b.comment ?? DEFAULT_COMMENT);
+
 export const regionProblems = (spec: RegionSpec): string[] => {
   const found: string[] = [];
   const comment = spec.comment ?? DEFAULT_COMMENT;

package/src/linux/remote-file-lifecycle.test.ts

@@ -4,7 +4,6 @@
  */
 import { describe, expect, test } from 'bun:test';
 import { fakeLinuxHost } from './fake-linux-host.ts';
-import { fileProblems } from './remote-file-form.ts';
 import {
   deleteFile,
   diffFile,
@@ -89,93 +88,6 @@ describe('whole-file mode', () => {
   });
 });
 
-describe('region mode', () => {
-  const VENDOR = '# vendor ruleset\nanchor "system"\nrule one\n';
-  const region = { name: 'homeflare' };
-  const block = { content: 'anchor "declared"\n', path: '/etc/vendor.conf', region };
-
-  const withVendor = () => {
-    const fake = host();
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(VENDOR),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    return fake;
-  };
-
-  test('editing the block leaves the rest of the file byte-identical', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
-    expect(after.startsWith(VENDOR)).toBe(true);
-    await reconcileFile(fake.runner, { ...block, content: 'anchor "changed"\n' }, output);
-    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
-  });
-
-  test("the other owner's mode and uid are preserved, never re-declared", async () => {
-    const fake = withVendor();
-    await reconcileFile(fake.runner, block);
-    expect(fake.files.get('/etc/vendor.conf')?.mode).toBe(0o600);
-  });
-
-  test('a change anywhere else in the file is not this resource’s drift', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    const edited = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}rule two\n`;
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(edited),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    expect(await diffFile(fake.runner, block, output)).toEqual({ action: 'noop' });
-  });
-
-  test('delete removes only the block', async () => {
-    const fake = withVendor();
-    const output = await reconcileFile(fake.runner, block);
-    await deleteFile(fake.runner, output);
-    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
-  });
-
-  test('a missing file is a refusal, because a typo is likelier than an intention', async () => {
-    const fake = host();
-    await expect(
-      reconcileFile(fake.runner, { ...block, path: '/etc/example/absent.conf' }),
-    ).rejects.toThrow(/does not create the file it lives in/);
-    const created = await reconcileFile(fake.runner, {
-      ...block,
-      create: true,
-      path: '/etc/example/absent.conf',
-    });
-    expect(created.region).toEqual(region);
-  });
-
-  test('mode and owner without create are refused at validation', () => {
-    expect(fileProblems({ ...block, mode: 0o600 })).toHaveLength(1);
-    expect(fileProblems({ ...block, create: true, mode: 0o600 })).toEqual([]);
-  });
-
-  test('a block already there with other content needs --adopt', async () => {
-    const fake = withVendor();
-    fake.files.set('/etc/vendor.conf', {
-      bytes: new TextEncoder().encode(
-        `${VENDOR}# BEGIN homeflare\nsomething else\n# END homeflare\n`,
-      ),
-      gid: 0,
-      kind: 'file',
-      mode: 0o600,
-      uid: 0,
-    });
-    await expect(reconcileFile(fake.runner, block)).rejects.toThrow(/managed region/);
-    await expect(reconcileFile(fake.runner, block, undefined, true)).resolves.toBeDefined();
-  });
-});
-
 describe('a failed read refuses', () => {
   test('a stat that throws is never read as “nothing is there”', async () => {
     const fake = host();

package/src/linux/remote-file-lifecycle.ts

@@ -28,6 +28,7 @@ import {
   planWrite,
   readFileAttributes,
   refuse,
+  relocation,
 } from './remote-file-plan.ts';
 
 export { readFileAttributes } from './remote-file-plan.ts';
@@ -42,7 +43,8 @@ export const diffFile = async (
   output: RemoteFileAttributes,
 ): Promise<Diff> => {
   const want = await identity(runner, news);
-  if (news.path !== output.path) {
+  // ⛔ A mode flip throws HERE, at plan time, before anything is written (remote-file-plan.ts).
+  if (relocation(news, output) === 'path') {
     // ★ Create-before-delete: two paths hold two files at once, so nothing forces deleteFirst.
     await runner.checkWrite?.(news.path, { mode: news.mode ?? DEFAULT_MODE, ...want });
     return { action: 'replace' };
@@ -80,8 +82,13 @@ export const reconcileFile = async (
         'a root destination or a privileged HostRunner. This provider never calls sudo itself.',
     );
   }
-  const moved = output !== undefined && output.path !== props.path;
-  const prior = moved ? undefined : output;
+  /**
+   * ⛔ WHAT WE OWNED LAST TIME MAY NOT BE WHAT WE OWN NOW. A new path, or a new region name or
+   *   comment token, means the old block or file is still out there and must be taken back — and
+   *   a flip between the two modes is refused outright (remote-file-plan.ts relocation).
+   */
+  const move = output === undefined ? 'none' : relocation(props, output);
+  const prior = move === 'none' ? output : undefined;
   const planned = await planWrite(runner, props, want);
   const live = ownedDigest(planned.before, props.region);
   const declared = digestOf(props.content);
@@ -127,10 +134,21 @@ export const reconcileFile = async (
       'the write returned but the file on disk does not match the declaration',
     );
   }
-  // ★ Create-before-delete, as the replace would have been: the old path goes once the new one is
-  //   written and verified.
-  if (moved && output !== undefined) await deleteFile(runner, output);
-  return after;
+  // ★ Create-before-delete, as the replace would have been: the old path — or, for a rename inside
+  //   one file, the old block — goes once the new one is written and verified.
+  if (move === 'none' || output === undefined) return after;
+  await deleteFile(runner, output);
+  if (move === 'path') return after;
+  /**
+   * ⛔ A REGION RENAME TOOK THE OLD BLOCK OUT OF THIS SAME FILE, so `after` — read before that
+   *   removal — describes bytes that no longer exist. Storing it would make the whole-file digest
+   *   wrong from the moment it was written and every later plan would read it as drift.
+   */
+  const settled = await readFileAttributes(runner, props.path, props.region);
+  if (settled === undefined || settled.contentSha256 !== declared) {
+    throw refuse(props.path, 'removing the previous managed block did not leave ours intact');
+  }
+  return settled;
 };
 
 /**

package/src/linux/remote-file-plan.ts

@@ -8,7 +8,7 @@
  */
 import { sha256Hex } from '../launchd/job-form.ts';
 import type { FileStat, HostRunner, WriteOptions } from '../launchd/runner.ts';
-import { type RegionSpec, readRegion, spliceRegion } from './region.ts';
+import { type RegionSpec, readRegion, sameRegion, spliceRegion } from './region.ts';
 import {
   DEFAULT_MODE,
   type RemoteFileAttributes,
@@ -46,6 +46,42 @@ export const identity = async (runner: HostRunner, props: RemoteFileProps): Prom
 
 export const digestOf = (text: string): string => sha256Hex(encoder.encode(text));
 
+/** What this declaration now owns, compared with what the last deploy owned. */
+export type Move = 'none' | 'path' | 'region';
+
+/**
+ * Has the thing this resource owns MOVED since the last deploy — and if so, how?
+ *
+ * 🔴 WHY THIS EXISTS (found by review, reproduced against the fake host, 2026-09-22). Without it,
+ *   only `path` was identity and both of these read as a routine `update`:
+ *   - RENAMING THE REGION left the old block in the file FOREVER. The new markers were spliced in,
+ *     the old ones were never touched, and `delete` — which can only look for the name in state,
+ *     now the new one — could never remove them. Two `anchor` lines in a packet filter, two
+ *     entries in a host table, and nothing in the stack able to take either back.
+ *   - DROPPING `region` TOOK OVER THE WHOLE FILE. The plan said `update`; the apply replaced every
+ *     byte of a file belonging to a vendor package with this resource's four lines. That is the
+ *     one thing the managed-region design exists to make impossible.
+ * ⛔ A FLIP BETWEEN THE TWO MODES IS A REFUSAL, NOT A MOVE. Neither order is safe: writing the
+ *   whole file first destroys the other owner's bytes before anything can be undone, and removing
+ *   the block first destroys our own claim and then refuses. The operator destroys the resource
+ *   and declares a new one, which is the only sequence with a reviewable diff at each step.
+ * ★ A region-to-region rename IS safe as a move, because both blocks can exist at once: write the
+ *   new one, verify it, then take the old one out (remote-file-lifecycle.ts reconcileFile).
+ */
+export const relocation = (props: RemoteFileProps, output: RemoteFileAttributes): Move => {
+  if (props.path !== output.path) return 'path';
+  if (sameRegion(props.region, output.region)) return 'none';
+  if (props.region === undefined || output.region === undefined) {
+    throw refuse(
+      props.path,
+      `changes between owning the whole file and owning the managed region ` +
+        `${JSON.stringify((props.region ?? output.region)?.name ?? '')} at the same path. Those ` +
+        'are two different claims on one file: destroy this resource and declare a new one.',
+    );
+  }
+  return 'region';
+};
+
 /** The digest of the part this resource owns, or `undefined` when that part is not there. */
 export const ownedDigest = (
   file: string | undefined,

package/src/linux/remote-file-region.test.ts

@@ -0,0 +1,181 @@
+/**
+ * RemoteFile in MANAGED REGION mode against the fake Linux host: the promise that every byte
+ * outside the markers survives, and the identity rules that keep it true when a declaration
+ * changes. Split from remote-file-lifecycle.test.ts, which covers whole-file mode.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { fileProblems } from './remote-file-form.ts';
+import {
+  deleteFile,
+  diffFile,
+  readFileAttributes,
+  reconcileFile,
+} from './remote-file-lifecycle.ts';
+
+const decode = (bytes: Uint8Array | undefined) => new TextDecoder().decode(bytes);
+
+const host = (euid = 0) =>
+  fakeLinuxHost({
+    dirs: { '/etc': 0, '/etc/example': 0, '/home/someone': 1001 },
+    euid,
+    groups: { root: 0, staff: 50 },
+    users: {
+      root: { gid: 0, home: '/root', uid: 0 },
+      someone: { gid: 1001, home: '/home/someone', uid: 1001 },
+    },
+  });
+
+describe('region mode', () => {
+  const VENDOR = '# vendor ruleset\nanchor "system"\nrule one\n';
+  const region = { name: 'homeflare' };
+  const block = { content: 'anchor "declared"\n', path: '/etc/vendor.conf', region };
+
+  const withVendor = () => {
+    const fake = host();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(VENDOR),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    return fake;
+  };
+
+  test('editing the block leaves the rest of the file byte-identical', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after.startsWith(VENDOR)).toBe(true);
+    await reconcileFile(fake.runner, { ...block, content: 'anchor "changed"\n' }, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
+  });
+
+  test("the other owner's mode and uid are preserved, never re-declared", async () => {
+    const fake = withVendor();
+    await reconcileFile(fake.runner, block);
+    expect(fake.files.get('/etc/vendor.conf')?.mode).toBe(0o600);
+  });
+
+  test('a change anywhere else in the file is not this resource’s drift', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const edited = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}rule two\n`;
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(edited),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    expect(await diffFile(fake.runner, block, output)).toEqual({ action: 'noop' });
+  });
+
+  test('delete removes only the block', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    await deleteFile(fake.runner, output);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
+  });
+
+  test('a missing file is a refusal, because a typo is likelier than an intention', async () => {
+    const fake = host();
+    await expect(
+      reconcileFile(fake.runner, { ...block, path: '/etc/example/absent.conf' }),
+    ).rejects.toThrow(/does not create the file it lives in/);
+    const created = await reconcileFile(fake.runner, {
+      ...block,
+      create: true,
+      path: '/etc/example/absent.conf',
+    });
+    expect(created.region).toEqual(region);
+  });
+
+  /**
+   * 🔴 BOTH OF THESE SHIPPED AS `update` AND WERE FOUND BY REVIEW (2026-09-22). They are the two
+   *   ways the region promise could be broken from an ordinary edit to a stack file.
+   */
+  test('renaming the region moves the block; the old markers do not survive', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const renamed = { ...block, region: { name: 'homeflare-mcp' } };
+    // ⛔ An update, not a noop: the new block is not in the file yet.
+    expect(await diffFile(fake.runner, renamed, output)).toEqual({ action: 'update' });
+    const moved = await reconcileFile(fake.runner, renamed, output);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after.startsWith(VENDOR)).toBe(true);
+    expect(after).not.toContain('BEGIN homeflare\n');
+    expect(after).toContain('BEGIN homeflare-mcp');
+    // ⛔ The stored digest must describe the file AFTER the old block was taken out.
+    const live = await readFileAttributes(fake.runner, '/etc/vendor.conf', renamed.region);
+    expect(moved.sha256).toBe(live?.sha256 ?? '');
+    await deleteFile(fake.runner, moved);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes)).toBe(VENDOR);
+  });
+
+  test('changing the comment token is a rename, not a reformat', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const retokened = { ...block, region: { comment: '//', name: 'homeflare' } };
+    await reconcileFile(fake.runner, retokened, output);
+    const after = decode(fake.files.get('/etc/vendor.conf')?.bytes);
+    expect(after).toContain('// BEGIN homeflare');
+    expect(after).not.toContain('# BEGIN homeflare');
+  });
+
+  test('a file this resource borrowed is never taken over by dropping the region', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const whole = { content: block.content, path: block.path };
+    // ⛔ At plan time, before a single byte moves.
+    await expect(diffFile(fake.runner, whole, output)).rejects.toThrow(/two different claims/);
+    await expect(reconcileFile(fake.runner, whole, output)).rejects.toThrow(/two different claims/);
+    expect(decode(fake.files.get('/etc/vendor.conf')?.bytes).startsWith(VENDOR)).toBe(true);
+  });
+
+  test('adding a region to a file this resource owned whole is refused the same way', async () => {
+    const fake = host();
+    const whole = { content: 'a = 1\n', path: '/etc/example/whole.conf' };
+    const output = await reconcileFile(fake.runner, whole);
+    await expect(
+      diffFile(fake.runner, { ...whole, region: { name: 'homeflare' } }, output),
+    ).rejects.toThrow(/two different claims/);
+  });
+
+  test('a rename onto a block someone else already owns is refused', async () => {
+    const fake = withVendor();
+    const output = await reconcileFile(fake.runner, block);
+    const taken = `${decode(fake.files.get('/etc/vendor.conf')?.bytes)}# BEGIN other\nnot ours\n# END other\n`;
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(taken),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(
+      reconcileFile(fake.runner, { ...block, region: { name: 'other' } }, output),
+    ).rejects.toThrow(/already carries that managed region/);
+  });
+
+  test('mode and owner without create are refused at validation', () => {
+    expect(fileProblems({ ...block, mode: 0o600 })).toHaveLength(1);
+    expect(fileProblems({ ...block, create: true, mode: 0o600 })).toEqual([]);
+  });
+
+  test('a block already there with other content needs --adopt', async () => {
+    const fake = withVendor();
+    fake.files.set('/etc/vendor.conf', {
+      bytes: new TextEncoder().encode(
+        `${VENDOR}# BEGIN homeflare\nsomething else\n# END homeflare\n`,
+      ),
+      gid: 0,
+      kind: 'file',
+      mode: 0o600,
+      uid: 0,
+    });
+    await expect(reconcileFile(fake.runner, block)).rejects.toThrow(/managed region/);
+    await expect(reconcileFile(fake.runner, block, undefined, true)).resolves.toBeDefined();
+  });
+});

package/src/linux/remote-file.ts

@@ -6,10 +6,13 @@
  *   the host already says what we declare; then read back and compared.
  * - read — lstat plus the SHA-256 of the file and of the part this resource owns.
  * - diff — the declared digest against the stored AND the on-disk one, plus mode and owner.
- * - replace — only when `path` changes; create-before-delete.
+ * - replace — only when `path` changes; create-before-delete. A region renamed inside one file
+ *   is an update that writes the new block, verifies it, then takes the old one out.
  * - delete — removes the file, or in region mode only the block.
  *
  * ⛔ NEVER A SECRET — see remote-file-form.ts.
+ * ⛔ THE REGION IS PART OF THE IDENTITY. Renaming it, or changing its comment token, moves the block;
+ *   swapping between owning the whole file and owning a block is refused (remote-file-plan.ts).
  * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt` (docs/ownership.md): a file already at the path, or a
  *   block already carrying the markers, reads as `Unowned`.
  * ★ IT IS A SEPARATE RESOURCE FROM `Host.File`, not a flag on it: the two have different attributes

package/src/linux/sudo-listing.ts

@@ -0,0 +1,122 @@
+/**
+ * ONE READ OF `ls -ldn --` FOR A WHOLE LIST OF PATHS, parsed into the same FileStat the seam uses
+ * plus the one thing `stat` cannot say on Linux: whether the path carries a POSIX ACL.
+ *
+ * ★ WHY `ls` AND NOT `stat`, AND WHY ONE CALL. The Mac guard lstats every directory from `/` down
+ *   with a local syscall each; over ssh each of those is a TCP connection with no multiplexing
+ *   (ssh-runner.ts), so a five-deep chain would be five handshakes per check and per plan. `ls -ldn`
+ *   takes every path as an operand and answers in one connection, and its mode column carries the
+ *   ACL flag the chain check needs anyway.
+ * ★ MEASURED 2026-09-22, read-only over ssh, on two host classes — an unprivileged LXC container
+ *   and a Proxmox VE node, both Debian 13 / coreutils 9.7, LANG=C, ssh user uid 1001 and 1000:
+ *     $ ls -ldn / /etc /etc/systemd /etc/systemd/system /usr /usr/lib /usr/lib/systemd …
+ *       drwxr-xr-x 18 0 0 4096 Sep 22 10:12 /etc          (all ten root:root 0755, no flag)
+ *     $ ls -ld /var/log/journal
+ *       drwxr-sr-x+ 3 root systemd-journal …              (the `+` IS the POSIX ACL flag here)
+ *     $ ls -lden …  →  ls: invalid option -- 'e'          (the Mac's spelling does not exist)
+ *     $ command -v getfacl  →  absent on both Debian classes (present on the NixOS class)
+ *   ⛔ SO THE ACL SIGNAL IS THE `+` FLAG, NOT `getfacl`: the tool that would enumerate the entries
+ *     is not installed on the hosts this runner is for, and a guard that shells out to a missing
+ *     program and fails closed would refuse every write on them. `ls` is coreutils, always there.
+ *   ⚠️ THE PRICE, STATED: we learn THAT a directory has an ACL, never WHAT it grants, so any ACL on
+ *     the chain is a refusal — including a read-only one the Mac guard would allow. Fail closed and
+ *     say so; the remedy is a prefix without one.
+ * ⚠️ `.` in that column is an SELinux context, not an ACL, and is not a grant. `@` is macOS's.
+ * ⛔ FAIL CLOSED ON ANYTHING WE DO NOT UNDERSTAND. A line that does not parse, a path that no line
+ *   named, two lines for one path, or a non-zero exit is an error — never "nothing is there".
+ */
+import type { FileStat, HostRunner } from '../launchd/runner.ts';
+import { SudoRefusedError } from '../launchd/sudo-allowlist.ts';
+
+/** What one `ls -ldn` line says: the lstat fields, plus whether the path carries an ACL. */
+export type Listed = FileStat & { readonly acl: boolean };
+
+const KINDS = new Map<string, FileStat['kind']>([
+  ['-', 'file'],
+  ['d', 'directory'],
+  ['l', 'symlink'],
+]);
+
+/**
+ * `rwxr-x---` → 0o750, with the three special bits `ls` hides in the execute columns:
+ * `s`/`S` = setuid (user) or setgid (group), `t`/`T` = sticky; the capital is the bit without
+ * execute. ⚠️ Anything else in a column is a shape we do not know, and returns undefined.
+ */
+export const permBits = (perms: string): number | undefined => {
+  if (perms.length !== 9) return undefined;
+  let mode = 0;
+  for (const index of [0, 1, 2]) {
+    const at = index * 3;
+    const shift = 6 - at;
+    const [read, write, exec] = [perms[at], perms[at + 1], perms[at + 2]];
+    if ((read !== 'r' && read !== '-') || (write !== 'w' && write !== '-')) return undefined;
+    if (read === 'r') mode |= 0o4 << shift;
+    if (write === 'w') mode |= 0o2 << shift;
+    const [set, unset] = index === 2 ? ['t', 'T'] : ['s', 'S'];
+    if (exec === 'x' || exec === set) mode |= 0o1 << shift;
+    else if (exec !== '-' && exec !== unset) return undefined;
+    if (exec === set || exec === unset) mode |= 0o4000 >> index;
+  }
+  return mode;
+};
+
+/** `drwxr-xr-x+ 4 0 0 4096 Sep 22 10:12 /etc/systemd` — the tail holds the date and the name. */
+const LINE = /^([-dlbcps])(\S{9})([+.@]?)\s+\d+\s+(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/;
+
+/**
+ * Match each line to the path that asked for it, by NAME rather than by position.
+ * ⚠️ `ls` SORTS ITS OPERANDS, so the answers do not come back in the order they were asked; and a
+ *   symlink's line ends `<path> -> <target>`, so it is not a suffix match either. The longest
+ *   candidate wins, so a path that is a tail of another cannot steal its line.
+ */
+const nameOf = (tail: string, paths: readonly string[]): string | undefined =>
+  [...paths]
+    .sort((left, right) => right.length - left.length)
+    .find((path) => tail.endsWith(` ${path}`) || tail.includes(` ${path} -> `));
+
+/** Every requested path's entry, or `undefined` when the listing is not exactly that. */
+export const parseListing = (
+  stdout: string,
+  paths: readonly string[],
+): Map<string, Listed> | undefined => {
+  const entries = new Map<string, Listed>();
+  for (const line of stdout.split('\n').filter((text) => text.trim() !== '')) {
+    const match = LINE.exec(line);
+    if (match === null) return undefined;
+    const [, type, perms, flag, uid, gid, size, tail] = match;
+    const mode = permBits(perms ?? '');
+    const path = nameOf(tail ?? '', paths);
+    if (mode === undefined || path === undefined || entries.has(path)) return undefined;
+    entries.set(path, {
+      acl: flag === '+',
+      gid: Number(gid),
+      kind: KINDS.get(type ?? '') ?? 'other',
+      mode,
+      size: Number(size),
+      uid: Number(uid),
+    });
+  }
+  return entries.size === paths.length ? entries : undefined;
+};
+
+/**
+ * Read every path in one call, as the deploying user — no sudo, the same read at plan time and
+ * before the write. ⛔ Anything but a complete, understood listing is a SudoRefusedError: a chain
+ *   we could not read is a chain we cannot say is root's alone.
+ */
+export const readListing = async (
+  base: HostRunner,
+  ls: string,
+  what: string,
+  paths: readonly string[],
+): Promise<Map<string, Listed>> => {
+  const result = await base.exec([ls, '-ldn', '--', ...paths]);
+  const entries = result.exitCode === 0 ? parseListing(result.stdout, paths) : undefined;
+  if (entries === undefined) {
+    throw new SudoRefusedError(
+      `sudoRunner ${what}: could not read ${paths.join(', ')} (${ls} -ldn exit ` +
+        `${String(result.exitCode)}: ${result.stderr.trim().slice(0, 200)}). Nothing ran as root.`,
+    );
+  }
+  return entries;
+};

package/src/linux/unit-handlers.ts

@@ -17,6 +17,7 @@ import { adoptsAtApply } from '../ownership/adopt.ts';
 import { noteUnfinished } from '../ownership/resume.ts';
 import type { SystemdUnitAttributes, SystemdUnitProps } from './unit-form.ts';
 import { deleteUnit, diffUnit, readUnit, reconcileUnit } from './unit-lifecycle.ts';
+import { assertRenameTarget } from './unit-preflight.ts';
 
 export const readHandler = (
   runner: HostRunner,
@@ -46,11 +47,17 @@ export const diffHandler = (
    *   when a rendered config file's digest is templated into the same deploy.
    */
   const name = resolvedString(news, 'name');
-  return Effect.succeed(
-    name !== undefined && name !== output.name
-      ? { action: 'replace' as const, deleteFirst: true }
-      : undefined,
-  );
+  if (name === undefined || name === output.name) return Effect.succeed(undefined);
+  /**
+   * ⛔ THE NAME IS ENOUGH TO REFUSE A MASKED TARGET, and the refusal has to happen here: the old
+   *   unit is removed before the new one is reconciled. The unit file cannot be compared while
+   *   `content` is still an Output, so this is the name-only half of assertReplaceable
+   *   (unit-preflight.ts).
+   */
+  return lift(async () => {
+    await assertRenameTarget(runner, output, name);
+    return { action: 'replace' as const, deleteFirst: true };
+  });
 };
 
 export const reconcileHandler = (