@homeflare/alchemy 0.7.0 → 0.10.0

package/src/launchd/host-file-lifecycle.ts

@@ -15,7 +15,7 @@ import {
   fileProblems,
 } from './host-file-form.ts';
 import { sha256Hex } from './job-form.ts';
-import { type HostRunner, canActAsRoot } from './runner.ts';
+import { type HostRunner, type WriteOptions, canActAsRoot } from './runner.ts';
 
 type Desired = {
   readonly bytes: Uint8Array;
@@ -72,29 +72,55 @@ export const readFileAttributes = async (
   };
 };
 
+const writeOptionsOf = (want: Desired): WriteOptions => ({
+  mode: want.mode,
+  ...(want.uid === undefined ? {} : { uid: want.uid }),
+  ...(want.gid === undefined ? {} : { gid: want.gid }),
+});
+
 const matches = (live: HostFileAttributes, want: Desired): boolean =>
   live.sha256 === want.sha256 &&
   live.mode === want.mode &&
   (want.uid === undefined || live.uid === want.uid) &&
   (want.gid === undefined || live.gid === want.gid);
 
+/**
+ * ★ A PLAN THAT WILL WRITE ASKS THE RUNNER FIRST (`checkWrite`, when it has one): sudoRunner's
+ *   refusals — a setuid or group-writable root file, a directory under a prefix another user may
+ *   change — then fail the plan, before any resource is applied, instead of halfway through it.
+ */
 export const diffFile = async (
   runner: HostRunner,
   news: HostFileProps,
   output: HostFileAttributes,
 ): Promise<Diff> => {
-  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
-  if (news.path !== output.path) return { action: 'replace' };
   const want = await desiredFile(runner, news);
-  if (want.sha256 !== output.sha256) return { action: 'update' };
+  const writes = async (diff: Diff): Promise<Diff> => {
+    await runner.checkWrite?.(news.path, writeOptionsOf(want));
+    return diff;
+  };
+  // ★ Create-before-delete: two paths can hold two files at once, so nothing forces deleteFirst.
+  if (news.path !== output.path) return writes({ action: 'replace' });
+  if (want.sha256 !== output.sha256) return writes({ action: 'update' });
   const live = await readFileAttributes(runner, news.path);
-  return live !== undefined && matches(live, want) ? { action: 'noop' } : { action: 'update' };
+  return live !== undefined && matches(live, want)
+    ? { action: 'noop' }
+    : writes({ action: 'update' });
 };
 
+/**
+ * `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 file already at the
+ * path — the takeover the plan's probe would have allowed, had it run. ⛔ A move onto an occupied
+ *   path stays refused, both ways the engine drives one: an `update` across the move (`moved`,
+ *   below), and a fresh replace's new generation, which the caller never marks adoptable (its
+ *   `output` is undefined too, so this function cannot tell it from a create by itself).
+ */
 export const reconcileFile = async (
   runner: HostRunner,
   props: HostFileProps,
   output?: HostFileAttributes,
+  adopt = false,
 ): Promise<HostFileAttributes> => {
   const want = await desiredFile(runner, props);
   // ⛔ NO SILENT SUDO: handing a file to another user is root's call (chown(2)), so say so up front.
@@ -102,7 +128,8 @@ export const reconcileFile = async (
     throw refuse(
       props.path,
       `owner ${String(props.owner)} is not the deploying user; only root may chown. Deploy as root ` +
-        'or through a privileged HostRunner (privileged: true). This provider never calls sudo.',
+        'or through a privileged HostRunner (sudoRunner() with this path under a prefix). This ' +
+        'provider never calls sudo itself.',
     );
   }
   const stat = await runner.stat(props.path);
@@ -119,11 +146,14 @@ export const reconcileFile = async (
   const prior = moved ? undefined : output;
   /**
    * ⛔ A FILE THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. With no prior state for this path,
-   *   the engine's adoption probe has already refused anything it found — except at the new path of
-   *   a replace, where it reads nothing. A path typo there would otherwise overwrite, say, a system
-   *   file that a fresh declaration of the same path would have been refused as `Unowned`.
+   *   the engine's adoption probe has already refused anything it found — except where it never
+   *   looked: the new path of a replace, and a create whose props still held an Output at plan
+   *   time. A path typo there would otherwise overwrite, say, a system file that a fresh
+   *   declaration of the same path would have been refused as `Unowned`. ★ With adoption on, a
+   *   create takes it over, as the probe would have let it (decided 2026-09-21).
    */
-  if (prior === undefined && before !== undefined && !matches(before, want)) {
+  const takeOver = adopt && output === undefined;
+  if (prior === undefined && before !== undefined && !matches(before, want) && !takeOver) {
     throw refuse(
       props.path,
       'already exists and is not this resource. Remove it, or declare it as a new resource and ' +
@@ -131,11 +161,7 @@ export const reconcileFile = async (
     );
   }
   if (before === undefined || !matches(before, want)) {
-    await runner.writeFileAtomic(props.path, want.bytes, {
-      mode: want.mode,
-      ...(want.uid === undefined ? {} : { uid: want.uid }),
-      ...(want.gid === undefined ? {} : { gid: want.gid }),
-    });
+    await runner.writeFileAtomic(props.path, want.bytes, writeOptionsOf(want));
   }
   // ⚠️ READ BACK, never echo the declaration: a umask, an ACL or a runner that ignored `uid` shows
   //   up here as a refusal instead of as a forever-`update`.

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/index.ts

@@ -24,3 +24,5 @@ export { PlistError, renderPlist } from './plist.ts';
 export { launchdProviders } from './providers.ts';
 export type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
 export { HostRunnerService, canActAsRoot, hostRunnerLayer } from './runner.ts';
+export type { SudoRunnerOptions } from './sudo-runner.ts';
+export { SudoRefusedError, sudoRunner } from './sudo-runner.ts';

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}`);
 
@@ -61,8 +77,9 @@ export const assertMayWrite = (runner: HostRunner, label: string, domain: Parsed
   if (domain.kind === 'system') {
     throw refuse(
       label,
-      'the system domain needs root. Run the deploy as root, or provide a HostRunner that is ' +
-        'deliberately privileged (privileged: true). This provider never calls sudo.',
+      'the system domain needs root. Run the deploy as root, or pass a deliberately privileged ' +
+        'HostRunner: sudoRunner() elevates exactly the calls this needs. This provider never ' +
+        'calls sudo itself.',
     );
   }
   if (domain.uid !== runner.effectiveUid()) {
@@ -149,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-validate.ts

@@ -15,7 +15,7 @@ import {
 import { jobSecretProblems } from './secret-tripwire.ts';
 
 /** ★ Labels become file names: no `/`, no leading dot, nothing a path could re-interpret. */
-const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+export const LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
 
 /**
  * ⛔ LABELS OTHER TOOLS OWN ARE NEVER DECLARED HERE. nix-darwin (`org.nixos.*`) rewrites its plists

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/local-runner.ts

@@ -5,7 +5,8 @@
  *   the published dist also loads under node (the package's smoke test and the kit's AGENTS.md:
  *   consumers run dist/, not src/), and both runtimes implement these modules.
  * ⛔ NO ELEVATION, EVER. `privileged` is false; a system-domain write succeeds only when the whole
- *   deploy was started as root. See the ⛔ on HostRunner.privileged for why nothing here calls sudo.
+ *   deploy was started as root. See the ⛔ on HostRunner.privileged for why nothing here calls sudo;
+ *   the opt-in elevating runner is sudo-runner.ts, which wraps this one.
  * ⛔ NO SHELL. `exec` spawns argv directly, so a label, path or argument can never be re-parsed
  *   as shell syntax.
  */
@@ -21,13 +22,15 @@ export type LocalRunnerOptions = {
   readonly execTimeoutMs?: number;
 };
 
-const code = (cause: unknown): string | undefined =>
+/** The errno code of a thrown fs error (`ENOENT`, `EACCES`, …), if it has one. */
+export const errnoCode = (cause: unknown): string | undefined =>
   typeof cause === 'object' && cause !== null && 'code' in cause
     ? String((cause as { code: unknown }).code)
     : undefined;
 
 /** ENOENT and ENOTDIR both mean "nothing is at this path". */
-const absent = (cause: unknown): boolean => code(cause) === 'ENOENT' || code(cause) === 'ENOTDIR';
+const absent = (cause: unknown): boolean =>
+  errnoCode(cause) === 'ENOENT' || errnoCode(cause) === 'ENOTDIR';
 
 const run = (argv: readonly string[], timeoutMs: number): Promise<ExecResult> =>
   new Promise((resolve, reject) => {

package/src/launchd/providers.test.ts

@@ -212,11 +212,14 @@ describe('the barrel', () => {
       'LaunchdJob',
       'LaunchdJobProvider',
       'PlistError',
+      'SudoRefusedError',
       'canActAsRoot',
       'hostRunnerLayer',
       'launchdProviders',
       'localRunner',
       'renderPlist',
+      // ★ The opt-in elevating runner; makeSudoRunner and the allowlist internals stay off.
+      'sudoRunner',
     ]);
   });
 });

package/src/launchd/providers.ts

@@ -7,7 +7,8 @@
  *   written by the same identity on the same host — a stack cannot write the file as one user and
  *   bootstrap the job as another by accident.
  * ⚠️ The default is localRunner(): this process, never elevated. A system-domain job therefore
- *   needs the deploy itself started as root, or a runner passed here with `privileged: true`.
+ *   needs the deploy itself started as root, or a runner passed here with `privileged: true` —
+ *   `launchdProviders(sudoRunner({ prefixes }))` is the kit's own (sudo-runner.ts).
  */
 import * as Layer from 'effect/Layer';
 import { HostFileProvider } from './host-file.ts';

package/src/launchd/runner.ts

@@ -48,13 +48,15 @@ export type HostUser = { readonly uid: number; readonly gid: number; readonly ho
 
 export interface HostRunner {
   /**
-   * ⛔ DECLARED, NEVER INFERRED. `true` only when every call this runner makes already runs with
-   *   root's authority — a runner that talks to a root helper, say. The providers refuse
+   * ⛔ DECLARED, NEVER INFERRED. `true` only when this runner can do every root-needing call the
+   *   providers make of it: every call already runs as root (a runner that talks to a root helper,
+   *   say), or the runner elevates exactly those calls (sudoRunner). The providers refuse
    *   system-domain writes unless `effectiveUid()` is 0 or this is `true`, so claiming it falsely
    *   turns that refusal into an EACCES halfway through a deploy.
-   * ⛔ THE KIT NEVER ELEVATES. No runner here calls `sudo`: a deploy that prompts for a password
-   *   mid-plan, or silently uses a cached sudo ticket, is exactly the "no silent sudo" failure. A
-   *   consumer who wants elevation writes that runner deliberately and sets this flag.
+   * ⛔ THE KIT NEVER ELEVATES SILENTLY. localRunner() never calls `sudo`: a deploy that prompts for
+   *   a password mid-plan, or quietly borrows a cached sudo ticket, is exactly the "no silent sudo"
+   *   failure. sudoRunner() does call `sudo -n`, but only when a stack passes it explicitly, only
+   *   for the argv shapes in sudo-allowlist.ts, and logging each one (decided 2026-09-21).
    */
   readonly privileged: boolean;
   /** The uid file writes and launchctl calls run as. */
@@ -71,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.',
+  );
+};