@homeflare/alchemy 0.8.0 → 0.10.1

package/src/launchd/host-file.ts

@@ -9,7 +9,8 @@
  * - delete — removes the file.
  *
  * ⛔ NEVER A SECRET — see host-file-form.ts. Secret files stay rendered by openbao-agent.
- * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a file already at the path reads as `Unowned`.
+ * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`: a file already at the path reads as `Unowned`, and where
+ *   the plan never asked, reconcile refuses it unless adoption is on (docs/ownership.md).
  * ★ IT LIVES IN THE launchd SUBPATH because the two travel together: a Mac host stack declares a
  *   daemon's config file and the daemon that reads it, through the same HostRunner.
  */
@@ -18,6 +19,8 @@ import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
 import { lift, resolvedString } from './host-effect.ts';
 import type { HostFileAttributes, HostFileProps } from './host-file-form.ts';
 import { deleteFile, diffFile, readFileAttributes, reconcileFile } from './host-file-lifecycle.ts';
@@ -44,8 +47,9 @@ export const HostFileProvider = () =>
             return output === undefined ? Unowned(found) : found;
           }),
 
-        diff: ({ news, output }) => {
-          if (output === undefined) return Effect.succeed(undefined);
+        diff: ({ instanceId, news, output }) => {
+          // ★ An unfinished generation of our own: `--adopt` may resume it (ownership/resume.ts).
+          if (output === undefined) return noteUnfinished(instanceId);
           if (isResolved(news)) return lift(() => diffFile(runner, news, output));
           // ⛔ A new path is a replace even while `content` is unresolved (an Output templated in):
           //   the engine's default would be an update, which writes the new path and never
@@ -56,7 +60,12 @@ export const HostFileProvider = () =>
           );
         },
 
-        reconcile: ({ news, output }) => lift(() => reconcileFile(runner, news, output)),
+        // ★ `--adopt` reaches the apply too: the probe never ran for a create with an Output prop.
+        //   ⛔ A create or an unfinished generation — never a fresh replace's, never offered it.
+        reconcile: ({ fqn, instanceId, news, output }) =>
+          Effect.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) =>
+            lift(() => reconcileFile(runner, news, output, adopt)),
+          ),
 
         delete: ({ output }) => lift(() => deleteFile(runner, output)),
       });

package/src/launchd/job-lifecycle.ts

@@ -28,7 +28,9 @@ import {
   assertReplaceable,
   assertUnclaimed,
   assertValid,
+  checkPlistWrite,
   locate,
+  plistWriteOptions,
   preflight,
   refuse,
 } from './job-preflight.ts';
@@ -94,19 +96,31 @@ export const diffJob = async (
   }
   assertValid(news);
   const desired = renderJob(news).sha256;
+  // ★ A plan that will write the plist asks the runner first (checkPlistWrite, HostRunner.checkWrite).
+  const update = async (): Promise<Diff> => {
+    await checkPlistWrite(runner, await locate(runner, news));
+    return { action: 'update' };
+  };
   // ⛔ BOTH digests: the stored one catches a bootstrap that failed after the write landed, the live
   //   one catches a hand edit. Either alone would report `noop` over a job that is not what we say.
-  if (desired !== output.plistSha256) return { action: 'update' };
+  if (desired !== output.plistSha256) return update();
   const live = await readJob(runner, news);
-  if (live === undefined || !live.loaded || live.plistSha256 !== desired)
-    return { action: 'update' };
+  if (live === undefined || !live.loaded || live.plistSha256 !== desired) return update();
   return { action: 'noop' };
 };
 
+/**
+ * `adopt` is whether adoption is on AND this apply is a create or an unfinished generation of our
+ * own (ownership/adopt.ts adoptsAtApply): it lets such a generation take over a job already on the
+ * host, as the plan's probe would have. A rename onto an occupied label stays refused, as it is at
+ * plan time (assertReplaceable) — including a label taken between that plan and a fresh replace's
+ * new generation, which the caller never marks adoptable.
+ */
 export const reconcileJob = async (
   runner: HostRunner,
   props: LaunchdJobProps,
   output: LaunchdJobAttributes | undefined,
+  adopt = false,
 ): Promise<LaunchdJobAttributes> => {
   assertValid(props);
   const { location, status } = await preflight(runner, props);
@@ -121,8 +135,9 @@ export const reconcileJob = async (
   const renamed =
     output !== undefined && (output.label !== props.label || output.domain !== props.domain);
   const prior = renamed ? undefined : output;
-  // ⛔ No prior state for THIS identity: whatever is there already belongs to someone else.
-  if (prior === undefined) {
+  // ⛔ No prior state for THIS identity: whatever is there already belongs to someone else —
+  //   unless adoption is on for a create, where the probe was skipped (a prop still an Output).
+  if (prior === undefined && !(adopt && output === undefined)) {
     await assertUnclaimed(runner, props.label, location, status, rendered.sha256);
   }
   if (renamed) await deleteJob(runner, output);
@@ -138,18 +153,11 @@ export const reconcileJob = async (
   ) {
     return attributesOf(props, location, rendered.sha256, status);
   }
-  /**
-   * ⚠️ launchd refuses a daemon plist that is not root:wheel or is group/world-writable ("bad
-   *   ownership/permissions"), so the system domain always writes 0644 root:wheel. An agent's plist
-   *   belongs to its user. REASONED from launchd's documented behaviour, not measured here (no
-   *   bootstrap was run to write this); the nix-darwin daemons on the reference host are 0644 root.
-   */
+  // ⚠️ Owner and mode are launchd's rule, not a choice: see plistWriteOptions (job-preflight.ts).
   await runner.writeFileAtomic(
     location.plistPath,
     rendered.bytes,
-    location.domain.kind === 'system'
-      ? { gid: 0, mode: 0o644, uid: 0 }
-      : { mode: 0o644, uid: location.domain.uid },
+    plistWriteOptions(location.domain),
   );
   await bootoutIfLoaded(runner, location.target);
   const failed = async (detail: string): Promise<never> => {

package/src/launchd/job-preflight.ts

@@ -21,7 +21,7 @@ import {
 } from './job-form.ts';
 import { identityProblems, jobProblems } from './job-validate.ts';
 import { type ServiceStatus, isDisabled, printService } from './launchctl.ts';
-import { type HostRunner, canActAsRoot } from './runner.ts';
+import { type HostRunner, type WriteOptions, canActAsRoot } from './runner.ts';
 
 export type Location = {
   readonly domain: ParsedDomain;
@@ -31,6 +31,22 @@ export type Location = {
 
 export type Identity = Pick<LaunchdJobProps, 'label' | 'domain'>;
 
+/**
+ * ⚠️ launchd refuses a daemon plist that is not root:wheel or is group/world-writable ("bad
+ *   ownership/permissions"), so the system domain always writes 0644 root:wheel. An agent's plist
+ *   belongs to its user. REASONED from launchd's documented behaviour, not measured here (no
+ *   bootstrap was run to write this); the nix-darwin daemons on the reference host are 0644 root.
+ */
+export const plistWriteOptions = (domain: ParsedDomain): WriteOptions =>
+  domain.kind === 'system' ? { gid: 0, mode: 0o644, uid: 0 } : { mode: 0o644, uid: domain.uid };
+
+/**
+ * PLAN TIME, for a plan that will write the plist: the runner's own pre-write refusals
+ * (HostRunner.checkWrite — sudoRunner's directory and mode checks), reading only.
+ */
+export const checkPlistWrite = async (runner: HostRunner, location: Location): Promise<void> =>
+  runner.checkWrite?.(location.plistPath, plistWriteOptions(location.domain));
+
 export const refuse = (label: string, message: string): Error =>
   new Error(`Launchd.Job ${label}: ${message}`);
 
@@ -150,4 +166,5 @@ export const assertReplaceable = async (
   assertMayWrite(runner, old.label, oldDomain);
   const { location, status } = await preflight(runner, next);
   await assertUnclaimed(runner, next.label, location, status, renderedSha256);
+  await checkPlistWrite(runner, location);
 };

package/src/launchd/job.ts

@@ -18,7 +18,8 @@
  * ⛔ ENVIRONMENT IS NON-SECRET ONLY — see the ⛔ on LaunchdJobProps.environment.
  * ⛔ NO SILENT SUDO — see assertMayWrite in job-preflight.ts.
  * ⚠️ NOTHING IS ADOPTED WITHOUT `--adopt`. A label already loaded, or a plist already on disk, reads
- *   as `Unowned`, so Alchemy refuses to take it over unless asked. Labels under `org.nixos.`,
+ *   as `Unowned`, so Alchemy refuses to take it over unless asked — and reconcile, where the plan
+ *   never asked, honours the same `--adopt` / `adopt(…)` (docs/ownership.md). Labels under `org.nixos.`,
  *   `com.apple.` and `homebrew.mxcl.` are refused outright (job-validate.ts) — declare a new label
  *   and cut over instead (docs/launchd.md).
  */
@@ -27,6 +28,8 @@ import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
+import { adoptsAtApply } from '../ownership/adopt.ts';
+import { noteUnfinished } from '../ownership/resume.ts';
 import { lift, resolvedString } from './host-effect.ts';
 import type { LaunchdJobAttributes, LaunchdJobProps } from './job-form.ts';
 import { deleteJob, diffJob, readJob, reconcileJob, replaceDiff } from './job-lifecycle.ts';
@@ -67,8 +70,9 @@ export const LaunchdJobProvider = () =>
             return output === undefined ? Unowned(found) : found;
           }),
 
-        diff: ({ news, output }) => {
-          if (output === undefined) return Effect.succeed(undefined);
+        diff: ({ instanceId, news, output }) => {
+          // ★ An unfinished generation of our own: `--adopt` may resume it (ownership/resume.ts).
+          if (output === undefined) return noteUnfinished(instanceId);
           if (isResolved(news)) return lift(() => diffJob(runner, news, output));
           /**
            * ⛔ A RENAME MUST BE SEEN EVEN WHILE OTHER PROPS ARE UNRESOLVED. Returning undefined
@@ -88,7 +92,12 @@ export const LaunchdJobProvider = () =>
             : Effect.succeed(undefined);
         },
 
-        reconcile: ({ news, output }) => lift(() => reconcileJob(runner, news, output)),
+        // ★ `--adopt` reaches the apply too: the probe never ran for a create with an Output prop.
+        //   ⛔ A create or an unfinished generation — never a fresh replace's, never offered it.
+        reconcile: ({ fqn, instanceId, news, output }) =>
+          Effect.flatMap(adoptsAtApply({ fqn, instanceId, output }), (adopt) =>
+            lift(() => reconcileJob(runner, news, output, adopt)),
+          ),
 
         delete: ({ output }) => lift(() => deleteJob(runner, output)),
       });

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.