@homeflare/alchemy 0.7.0 → 0.8.0

package/src/caddy/config-lifecycle.ts

@@ -9,9 +9,11 @@
  *   · live ≠ stored — DRIFT: a hand `curl` to the API, or a restart that loaded a different file
  *     (or an `autosave.json` holding someone else's change, under `--resume`).
  *   · declared = live — nothing to load, whatever the state says.
+ * With NO state there is no stored digest, and the question is whose config is running: see
+ * `claimable` below, which both the adoption probe and the apply ask.
  */
 import type { Diff } from 'alchemy/Diff';
-import type { CaddyAdmin } from './admin.ts';
+import { type CaddyAdmin, CaddyUnreachableError } from './admin.ts';
 import {
   CaddyAdminError,
   adaptCaddyfile,
@@ -66,16 +68,75 @@ export const desiredConfig = async (
   return { digest: configDigest(adapted.config), warnings: adapted.warnings };
 };
 
-/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
-export const readLive = async (
+const attributesOf = (
   admin: CaddyAdmin,
+  running: unknown,
   sourceFile?: string,
-): Promise<CaddyConfigAttributes> => ({
-  configSha256: configDigest(await readRunningConfig(admin)),
+): CaddyConfigAttributes => ({
+  configSha256: configDigest(running),
   endpoint: admin.endpoint,
   ...(sourceFile === undefined ? {} : { sourceFile }),
 });
 
+/** What is running now, as attributes. `sourceFile` is carried over, never discovered. */
+export const readLive = async (
+  admin: CaddyAdmin,
+  sourceFile?: string,
+): Promise<CaddyConfigAttributes> =>
+  attributesOf(admin, await readRunningConfig(admin), sourceFile);
+
+/**
+ * ⛔ WITH NO STATE, A RUNNING CONFIG IS THIS STACK'S ONLY IF IT IS THE DECLARED ONE (decision,
+ *   2026-09-21: CaddyConfig must not adopt silently — the house rule HostFile and LaunchdJob keep).
+ *   Anything else was put there by a person, another tool or another stack, and loading over it
+ *   replaces every site it serves. ★ A config that serves nothing (`null`, or no apps) is claimable
+ *   too: there is nothing to take over, as an empty R2 lock rule set reads as no lock.
+ */
+export const claimable = (running: unknown, declaredDigest: string): boolean =>
+  servesNothing(running) || configDigest(running) === declaredDigest;
+
+export type Probe = {
+  readonly attributes: CaddyConfigAttributes;
+  /** The live config IS the declared one: adopting it changes nothing. */
+  readonly ours: boolean;
+  /** Why the declaration could not be compared, when it could not — the Caddy is then not ours. */
+  readonly unchecked?: string;
+};
+
+/**
+ * The adoption probe — `read` with no state: `undefined` when Caddy serves nothing (plan a create),
+ * else the live attributes and whether they are provably ours (the provider brands the rest
+ * `Unowned`, and the plan refuses them without `--adopt`).
+ * ⛔ IT NEVER THROWS OVER THE DECLARATION. The engine also runs this read to recover an interrupted
+ *   create, with THAT deploy's props (Plan.ts, `status: "creating"`) — so a Caddyfile that failed to
+ *   adapt then would fail every later plan, the one carrying the fix included. What cannot be
+ *   compared is "not proven ours", with the reason; the next diff or apply validates the Caddyfile.
+ */
+export const probeLive = async (
+  admin: CaddyAdmin,
+  caddyfile: string | undefined,
+  sourceFile?: string,
+): Promise<Probe | undefined> => {
+  const running = await readRunningConfig(admin);
+  if (servesNothing(running)) return undefined;
+  const attributes = attributesOf(admin, running, sourceFile);
+  if (caddyfile === undefined) {
+    return { attributes, ours: false, unchecked: 'the stored Caddyfile is not plain text' };
+  }
+  try {
+    const want = await desiredConfig(admin, { caddyfile });
+    return { attributes, ours: claimable(running, want.digest) };
+  } catch (cause) {
+    // ⚠️ Unreachable mid-probe is still "no Caddy" (config.ts plans without it), not "not ours".
+    if (cause instanceof CaddyUnreachableError) throw cause;
+    return {
+      attributes,
+      ours: false,
+      unchecked: cause instanceof Error ? cause.message : String(cause),
+    };
+  }
+};
+
 /**
  * ★ NEVER `replace`. Nothing in the props names a different object: a new Caddyfile is a reload of
  *   the same Caddy, and `sourceFile` is a header. (Which Caddy is the transport's business — see
@@ -94,6 +155,7 @@ export const diffConfig = async (
     news.sourceFile === output.sourceFile &&
     // ⚠️ A stack whose transport now reaches ANOTHER Caddy (a new address) must load there; the
     //   old one keeps what it has — the same as a delete, which never unloads (see config.ts).
+    //   Planned as an update, but the state does not vouch for that Caddy: see Authority.
     admin.endpoint === output.endpoint;
   return converged ? { action: 'noop' } : { action: 'update' };
 };
@@ -106,13 +168,42 @@ export type Applied = {
   readonly loaded: boolean;
 };
 
-/** Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches. */
+/**
+ * What this apply may load over — config.ts decides from the state and the adopt setting:
+ *   · `takeOver` — any running config: the state was applied to THIS Caddy (an update, drift
+ *     correction, or a create the engine adopted), or adoption is on (`--adopt`, or the
+ *     resource's own `adopt(true)` — host-effect.ts adoptEnabled).
+ *   · otherwise only a claimable one — plus, as `stored`, the digest the state last recorded: a
+ *     Caddy reached at a NEW endpoint that runs exactly that is the same config under another name.
+ */
+export type Authority = { readonly takeOver: boolean; readonly stored?: string };
+
+/**
+ * Load the Caddyfile unless Caddy already runs it, then read it back and insist it matches.
+ * ⛔ WITHOUT `takeOver`, A CONFIG THE STACK CANNOT CLAIM IS NEVER LOADED OVER. The engine's adoption
+ *   probe cannot guard every create: it is skipped while `news` holds an Output — ALWAYS on
+ *   caddyWithFile's first deploy (`sourceFile` is its HostFile's path) — and a Caddy that was down at
+ *   plan time read as nothing. Nor does state vouch for a Caddy the transport NOW reaches at another
+ *   endpoint (diff plans that as an update). Refused here, before any `/load`, like HostFile's.
+ */
 export const reconcileConfig = async (
   admin: CaddyAdmin,
   props: CaddyConfigProps,
+  authority: Authority,
 ): Promise<Applied> => {
   const want = await desiredConfig(admin, props);
-  const before = configDigest(await readRunningConfig(admin));
+  const running = await readRunningConfig(admin);
+  const before = configDigest(running);
+  const known = before === authority.stored || claimable(running, want.digest);
+  if (!authority.takeOver && !known) {
+    throw refuse(
+      admin,
+      `Caddy runs config ${short(before)}, which this stack did not load, and the Caddyfile adapts ` +
+        `to ${short(want.digest)} — loading it would replace every site that config serves. ` +
+        'Deploy with --adopt (or wrap the resource in adopt(true)) to take this Caddy over, or ' +
+        'point caddyProviders() at the Caddy you meant.',
+    );
+  }
   let warnings = want.warnings;
   const loaded = before !== want.digest;
   if (loaded) {

package/src/caddy/config.ts

@@ -5,8 +5,7 @@
  * - create / update — `POST /adapt` (validate), `POST /load` with `text/caddyfile` (a graceful
  *   reload; Caddy keeps the old config if it refuses the new one, and the error names why), then
  *   `GET /config/` and insist it matches. Skipped when Caddy already runs this config.
- * - read — the digest of `GET /config/`. ★ WITH NO STATE, A RUNNING CADDY IS ADOPTED: its live
- *   config becomes the starting point, and the deploy's forced update loads the declared one.
+ * - read — the digest of `GET /config/`. With no state it is the adoption probe (below).
  * - diff — declared, live and stored digests (config-lifecycle.ts). Never `replace`.
  * - delete — ⛔ NOTHING. See below.
  *
@@ -15,17 +14,23 @@
  *   servers. `retain` is the default (the engine never calls delete); with `destroy` the handler
  *   still only forgets. It never calls `/stop` (which exits the process) or `DELETE /config/`.
  *   To empty a Caddy, do it by hand at its admin API.
+ * ⛔ NOTHING IS ADOPTED SILENTLY (decision, 2026-09-21 — the house rule HostFile and LaunchdJob
+ *   keep). With no state, a running Caddy whose live config IS the declared one reads as ours (the
+ *   adoption changes nothing); any other config reads as `Unowned`, and the plan refuses it unless
+ *   the deploy runs with `--adopt`. A Caddy serving nothing reads as absent: a create. Where the
+ *   engine skips that probe, reconcile refuses the same takeover (config-lifecycle.ts).
  * ⛔ `caddyfile` IS NEVER A SECRET — see config-form.ts; refused before anything is sent.
  * ⚠️ WHICH CADDY is the transport's (providers.ts), not a prop: one CaddyAdmin per stack.
  */
 import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { adoptEnabled, lift, resolvedString } from '../launchd/host-effect.ts';
 import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
-import { diffConfig, readLive, reconcileConfig } from './config-lifecycle.ts';
+import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';
 
 export type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 
@@ -64,17 +69,40 @@ export const CaddyConfigProvider = () =>
     CaddyConfig,
     Effect.gen(function* () {
       const admin = yield* CaddyAdminService;
+      /** The probe, branded for the engine: plain when ours, `Unowned` otherwise. */
+      const probe = (caddyfile: string | undefined, sourceFile: string | undefined) =>
+        Effect.flatMap(
+          lift(() => probeLive(admin, caddyfile, sourceFile)),
+          (found) => {
+            if (found === undefined) return Effect.succeed(undefined);
+            if (found.ours) return Effect.succeed(found.attributes);
+            const unowned = Unowned(found.attributes);
+            return found.unchecked === undefined
+              ? Effect.succeed(unowned)
+              : Effect.as(
+                  Effect.logWarning(
+                    `Caddy.Config at ${admin.endpoint}: the running config could not be compared ` +
+                      `with the declared Caddyfile (${found.unchecked}), so it is not treated as ours`,
+                  ),
+                  unowned,
+                );
+          },
+        );
       return CaddyConfig.Provider.of({
         /** ⛔ A Caddy has one config; there is nothing to enumerate, and nothing for nuke to delete. */
         list: () => Effect.succeed([]),
 
         /**
-         * ★ Plain attributes, never `Unowned`: a Caddy on this host's loopback admin API is the one
-         *   the stack means (the transport refuses anything else), and adopting reads — it changes
-         *   nothing until reconcile loads the declared Caddyfile.
+         * With state: the live attributes, which diff compares. With none, the ADOPTION PROBE —
+         * `olds` is the declaration (Plan.ts passes `news`), and only a live config equal to it is
+         * ours. ⚠️ A running Caddy is still the one the stack means (the transport reaches only
+         * loopback), but WHOSE CONFIG it runs is not: a person, another tool or another stack.
          */
-        read: ({ olds }) =>
-          lift(() => readLive(admin, resolvedString(olds, 'sourceFile'))).pipe(
+        read: ({ olds, output }) =>
+          (output === undefined
+            ? probe(resolvedString(olds, 'caddyfile'), resolvedString(olds, 'sourceFile'))
+            : lift(() => readLive(admin, resolvedString(olds, 'sourceFile')))
+          ).pipe(
             // ★ Nothing to adopt from a Caddy that is down: plan a create, which is the same load.
             Effect.catchIf(unreachable, planWithoutCaddy(admin, undefined)),
           ),
@@ -101,9 +129,18 @@ export const CaddyConfigProvider = () =>
           }).pipe(Effect.catchIf(unreachable, update));
         },
 
-        reconcile: ({ news }) =>
+        reconcile: ({ fqn, news, output }) =>
           Effect.gen(function* () {
-            const applied = yield* lift(() => reconcileConfig(admin, news));
+            // ⛔ State is authority over the Caddy it was applied to, and no other. With none (the
+            //   engine may not have probed: see reconcileConfig), or with the transport now at
+            //   another endpoint, only adoption — `--adopt`, or this resource's own `adopt(…)`,
+            //   as the planner resolves it — loads over a config the stack cannot claim.
+            const sameCaddy = output !== undefined && output.endpoint === admin.endpoint;
+            const takeOver = sameCaddy || (yield* adoptEnabled(fqn));
+            const stored = output === undefined ? {} : { stored: output.configSha256 };
+            const applied = yield* lift(() =>
+              reconcileConfig(admin, news, { takeOver, ...stored }),
+            );
             for (const warning of applied.warnings) {
               yield* Effect.logWarning(`Caddy.Config at ${admin.endpoint}: ${warning}`);
             }

package/src/caddy/fake-caddy.ts

@@ -17,6 +17,9 @@
  * ★ `listenPort` is the port Caddy BELIEVES it listens on — its Host check uses it — while the
  *   fake really listens on an ephemeral one: a Caddy on its default :2019 behind a forward.
  */
+import type { CaddyAdmin } from './admin.ts';
+import { localCaddyAdmin } from './local-admin.ts';
+
 export type Seen = {
   readonly method: string;
   readonly path: string;
@@ -158,3 +161,19 @@ export const fakeCaddy = (
     stop: () => void server.stop(true),
   };
 };
+
+/**
+ * A fake Caddy on its DEFAULT :2019 behind a forward (`hostHeader`), and the transport to it.
+ * ★ Addressed that way so a Caddyfile with no `admin` line — the common case — passes the guard.
+ *   A Caddy reached on any other port needs `admin <address>` declared, or the first load would
+ *   move it (admin-guard.ts).
+ */
+export const fakeDefaultCaddy = (running?: unknown): { admin: CaddyAdmin; caddy: FakeCaddy } => {
+  const caddy = fakeCaddy({ listenPort: 2019, ...(running === undefined ? {} : { running }) });
+  const admin = localCaddyAdmin({
+    address: caddy.address,
+    hostHeader: '127.0.0.1:2019',
+    retries: 0,
+  });
+  return { admin, caddy };
+};

package/src/caddy/index.ts

@@ -6,7 +6,8 @@
  *   the digest, the guards and the admin calls are internals; an `export *` would publish them.
  * ⛔ THE ADMIN API STAYS ON LOOPBACK OR A UNIX SOCKET. It has no authentication; localCaddyAdmin()
  *   refuses any other address, and a Caddyfile that would move or expose it is refused before load.
- * Guide, order of file and load, `--resume` and secrets: docs/caddy.md.
+ * ⛔ NOTHING IS ADOPTED SILENTLY: a running config that is not the declared one needs `--adopt`.
+ * Guide, order of file and load, adoption, `--resume` and secrets: docs/caddy.md.
  */
 export type {
   CaddyAdmin,

package/src/caddy/providers.test.ts

@@ -3,7 +3,6 @@
  * way the engine calls them; caddyWithFile's registration; and the barrel, the public API.
  */
 import { afterEach, describe, expect, test } from 'bun:test';
-import { Unowned } from 'alchemy/AdoptPolicy';
 import * as Output from 'alchemy/Output';
 import { Stack } from 'alchemy/Stack';
 import * as Effect from 'effect/Effect';
@@ -52,37 +51,23 @@ const withProvider = <A>(
 };
 
 describe('CaddyConfigProvider', () => {
-  test('read with no state ADOPTS: plain attributes of the live config, never Unowned', async () => {
-    const probe = await withProvider((provider) =>
-      handler('read', provider.read)({ ...ids, olds: { caddyfile: SITE }, output: undefined }),
-    );
-    expect(Unowned.is(probe)).toBe(false);
-    expect(probe).toMatchObject({ endpoint: fake?.address });
-  });
-
-  test('reconcile applies; delete then sends nothing at all', async () => {
+  test('reconcile applies over its own state; delete then sends nothing at all', async () => {
     await withProvider((provider) =>
       Effect.gen(function* () {
-        yield* provider.reconcile({
+        const output = yield* provider.reconcile({
           ...ids,
           bindings: [] as never,
           news: { caddyfile: SITE },
-          olds: undefined,
-          output: undefined,
+          olds: { caddyfile: SITE },
+          // ★ State from an earlier deploy: the running `legacy` config is this stack's to replace.
+          output: { configSha256: 'earlier', endpoint: fake?.address ?? '' },
           session: undefined as never,
         });
+        expect(fake?.seen.some((call) => call.path === '/load')).toBe(true);
         const before = fake?.seen.length;
-        const output = yield* handler(
-          'read',
-          provider.read,
-        )({
-          ...ids,
-          olds: { caddyfile: SITE },
-          output: undefined,
-        });
         yield* provider.delete({ ...ids, olds: { caddyfile: SITE }, output } as never);
-        // ★ Only the read above talked to Caddy: delete never unloads, never stops.
-        expect(fake?.seen.length).toBe((before ?? 0) + 1);
+        // ★ Delete never unloads, never stops: not one more call reached Caddy.
+        expect(fake?.seen.length).toBe(before);
       }),
     );
   });

package/src/caddy/with-file.ts

@@ -14,9 +14,13 @@
  *     still an Output, Alchemy skips the adoption probe, and the check runs at apply instead.)
  *   · A Caddyfile that adapts but that Caddy then REFUSES (a port in use, a missing cert file) is
  *     on disk when `/load` fails. Caddy keeps serving the old config, the deploy fails with Caddy's
- *     reason — and a RESTART before the fix would load the refused file. Fix and redeploy, or run
- *     Caddy with `--resume` (docs/caddy.md): it restarts from `autosave.json`, the last config Caddy
- *     ACCEPTED, and the file is only the first-boot fallback.
+ *     reason — and a Caddy started without `--resume` would load the refused file on its next
+ *     restart. Managed Caddies run with `--resume` (decision, 2026-09-21; docs/caddy.md): they
+ *     restart from `autosave.json`, the last config Caddy ACCEPTED, and the file is only the
+ *     first-boot fallback.
+ *   · The skipped probe is also why the ADOPTION check of a first deploy happens at apply: a Caddy
+ *     running a config this stack did not load is refused before `/load` unless the deploy runs
+ *     with `--adopt` (config-lifecycle.ts reconcileConfig) — after this file is written.
  * ⛔ SECRETS ARE REFUSED HERE, AT DECLARATION, before the HostFile exists: its `content` is a prop
  *   too, and would carry a literal into state even if the CaddyConfig then refused it.
  * ★ BOTH RETAIN. Removing this from a stack must not delete the file a restart needs.

package/src/launchd/fake-sudo.ts

@@ -0,0 +1,136 @@
+/**
+ * A sudo runner over fake-runner.ts, for the tests beside it: the deploying user is uid 501 and
+ * unprivileged, and `/usr/bin/sudo` is a tiny interpreter that runs the three allowlisted programs
+ * against the same in-memory host, as root.
+ *
+ * ⛔ TEST-ONLY, like fake-runner.ts: no provider imports it, it is not on the barrel, and it never
+ *   runs a real program. No test anywhere runs a real sudo.
+ * ★ THE INTERPRETER READS ONLY WHAT THE ARGV SAYS — mode, owner, group, source, destination — so a
+ *   runner that dropped `-o` or wrote the wrong path shows up as the wrong file, not a passing test.
+ * ★ THE BASE STAYS UNPRIVILEGED, so a write under /Library/LaunchDaemons that skipped sudo fails
+ *   with the fake's EACCES instead of quietly succeeding.
+ * ★ SUDO REFUSES A CALL THAT WAS NOT LOGGED FIRST, so every test holds the runner to "logged
+ *   before it runs", not merely "logged at some point".
+ */
+import { fakeRunner } from './fake-runner.ts';
+import { LAUNCHCTL } from './launchctl.ts';
+import type { ExecResult, HostRunner } from './runner.ts';
+import { INSTALL, RM, SUDO } from './sudo-allowlist.ts';
+import { makeSudoRunner } from './sudo-runner.ts';
+
+export const OPERATOR = 501;
+export const PREFIXES = ['/Library/LaunchDaemons', '/opt/example'];
+
+const ok: ExecResult = { exitCode: 0, stderr: '', stdout: '' };
+
+/** What `sudo -n` prints (exit 1) when it will not run the command. Reasoned; see sudo-runner.ts. */
+export const SUDO_SAYS = {
+  denied:
+    "Sorry, user someone is not allowed to execute '/bin/launchctl bootout system/x' as root on example.\n",
+  'not-in-sudoers': 'someone is not in the sudoers file.\n',
+  'not-on-host': 'someone is not allowed to run sudo on example.\n',
+  password: 'sudo: a password is required\n',
+} as const;
+const fail = (exitCode: number, stderr: string): ExecResult => ({ exitCode, stderr, stdout: '' });
+
+/** Parse `install -S -m MODE [-o UID] [-g GID] SRC DEST` the way install(1) would. */
+const parseInstall = (args: readonly string[]) => {
+  const mode = Number.parseInt(args[2] ?? '', 8);
+  const rest = args.slice(3);
+  const flag = (name: string) => {
+    const at = rest.indexOf(name);
+    return at === -1 ? undefined : Number(rest[at + 1]);
+  };
+  return {
+    dest: rest[rest.length - 1] ?? '',
+    gid: flag('-g'),
+    mode,
+    source: rest[rest.length - 2] ?? '',
+    uid: flag('-o'),
+  };
+};
+
+/** `groups` is the operator's `id -G`; `'unknown'` models that lookup failing. */
+export const fakeSudoHost = (
+  groups: readonly number[] | 'unknown' = [20, 80],
+  prefixes: readonly string[] = PREFIXES,
+) => {
+  const fake = fakeRunner({
+    dirs: {
+      '/Library/LaunchDaemons': 0,
+      '/opt/example': 0,
+      '/opt/example/app': 0,
+      '/Users/someone/Library/LaunchAgents': OPERATOR,
+      '/Users/other/Library/LaunchAgents': 502,
+      // Root-owned, and deliberately NOT a prefix: the forgotten-prefix case.
+      '/etc/example': 0,
+    },
+    euid: OPERATOR,
+    users: {
+      other: { gid: 20, home: '/Users/other', uid: 502 },
+      someone: { gid: 20, home: '/Users/someone', uid: OPERATOR },
+    },
+  });
+  const staged = new Map<string, Uint8Array>();
+  const logs: string[] = [];
+  const sudoCalls: string[][] = [];
+  const state = {
+    /** What sudo itself answers: runs the command, or refuses it with one of SUDO_SAYS. */
+    sudo: 'ok' as 'ok' | keyof typeof SUDO_SAYS,
+    /** Returned by `install` in place of success; nothing is written. */
+    installFailure: undefined as ExecResult | undefined,
+    stagedCount: 0,
+    /** The staged bytes as `install` saw them, by destination. */
+    installedFrom: new Map<string, string>(),
+  };
+
+  const asRoot = async (argv: readonly string[]): Promise<ExecResult> => {
+    const [program, ...args] = argv;
+    if (program === LAUNCHCTL) return fake.runner.exec(argv);
+    if (program === INSTALL) {
+      if (state.installFailure !== undefined) return state.installFailure;
+      const { dest, gid, mode, source, uid } = parseInstall(args);
+      const bytes = staged.get(source);
+      if (bytes === undefined) return fail(71, `install: ${source}: No such file or directory`);
+      state.installedFrom.set(dest, new TextDecoder().decode(bytes));
+      // ★ No -g: the new file takes its directory's group, as a BSD file create does.
+      const dirGid = (await fake.runner.stat(dest.slice(0, dest.lastIndexOf('/'))))?.gid ?? 0;
+      fake.files.set(dest, { bytes, gid: gid ?? dirGid, kind: 'file', mode, uid: uid ?? 0 });
+      return ok;
+    }
+    if (program === RM) {
+      fake.files.delete(args[2] ?? '');
+      return ok;
+    }
+    return fail(1, `sudo: ${String(program)}: command not found`);
+  };
+
+  const base: HostRunner = {
+    ...fake.runner,
+    exec: async (argv) => {
+      if (argv[0] !== SUDO) return fake.runner.exec(argv);
+      sudoCalls.push([...argv]);
+      if (logs[logs.length - 1] !== `homeflare/launchd sudo -n ${JSON.stringify(argv.slice(3))}`) {
+        throw new Error(`fake sudo: ${JSON.stringify(argv)} was not logged before it ran`);
+      }
+      if (state.sudo !== 'ok') return fail(1, SUDO_SAYS[state.sudo]);
+      // argv is [sudo, -n, --, ...command]
+      return asRoot(argv.slice(3));
+    },
+  };
+
+  const runner = makeSudoRunner(prefixes, {
+    base,
+    groups: async () => (groups === 'unknown' ? undefined : groups),
+    log: (line) => logs.push(line),
+    stage: async (bytes) => {
+      state.stagedCount += 1;
+      const path = `/private/tmp/hf-sudo-${String(state.stagedCount)}/staged`;
+      staged.set(path, bytes);
+      return { dispose: async () => void staged.delete(path), path };
+    },
+  });
+  /** The privileged commands run, without the `sudo -n --` in front. */
+  const privileged = () => sudoCalls.map((call) => call.slice(3));
+  return { fake, logs, privileged, runner, staged, state, sudoCalls };
+};

package/src/launchd/host-effect.ts

@@ -1,13 +1,17 @@
 /**
  * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
- * `news` both providers' diffs share.
+ * `news` both providers' diffs share, and the engine's adopt setting for a check at apply.
  *
  * ★ The lifecycle files are plain async functions over a HostRunner (see runner.ts for why the
  *   runner is promise-based), so each provider handler is a single `lift(() => step(runner, …))`.
  * ⚠️ A thrown Error stays that Error — its message is the refusal a deploy prints. Anything else
  *   thrown is wrapped, so the failure channel is always an Error with a readable message.
  */
+import { AdoptPolicy } from 'alchemy/AdoptPolicy';
+import { AlchemyContext } from 'alchemy/AlchemyContext';
+import { Stack } from 'alchemy/Stack';
 import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 
 export const lift = <A>(step: () => Promise<A>): Effect.Effect<A, Error> =>
   Effect.tryPromise({
@@ -26,3 +30,31 @@ export const resolvedString = (news: unknown, key: string): string | undefined =
   const value = (news as Record<string, unknown>)[key];
   return typeof value === 'string' ? value : undefined;
 };
+
+/**
+ * Whether the resource at `fqn` may be adopted, resolved exactly as the planner resolves it (alchemy
+ * beta.79 Plan.ts: `resource.Adopt ?? shouldAdopt`): a resource-scoped `adopt(…)`, else the
+ * `AdoptPolicy` service, else `AlchemyContext.adopt`, else off.
+ * ★ FOR A CREATE THE ENGINE NEVER PROBED. Alchemy skips the adoption probe while `news` holds an
+ *   Output, so an ownership check that must still honour `--adopt` can only run at apply. All three
+ *   reach the apply: Alchemist runs plan AND apply under the session context, which provides the
+ *   services from the CLI flag and the Stack the resources registered on (Alchemist/Session.ts,
+ *   routes/stack.ts; Apply.ts reads the same Stack).
+ * ⛔ THE RESOURCE-SCOPED SETTING WINS, BOTH WAYS. The engine captures `adopt(…)` on the resource at
+ *   registration (Resource.ts `Adopt`, into `Stack.resources[fqn]`) and never hands it to a
+ *   provider. Reading only the deploy-wide flag let `--adopt` take over a resource declared
+ *   `.pipe(adopt(false))` — which the planner refuses — and refused one declared `adopt(true)`.
+ * ⚠️ `resources` carries an `@internal` comment in Alchemy's source, but it is in the published types
+ *   and the planner reads `Adopt` from it. caddy/adopt-scope.test.ts registers through the real
+ *   `Resource`, so an upgrade that stops recording it there fails the suite.
+ */
+export const adoptEnabled = (fqn: string): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    const stack = yield* Effect.serviceOption(Stack);
+    const scoped = Option.isSome(stack) ? stack.value.resources[fqn]?.Adopt : undefined;
+    if (scoped !== undefined) return scoped;
+    const policy = yield* Effect.serviceOption(AdoptPolicy);
+    if (Option.isSome(policy)) return policy.value;
+    const context = yield* Effect.serviceOption(AlchemyContext);
+    return Option.isSome(context) ? context.value.adopt : false;
+  });

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

@@ -46,9 +46,12 @@ const identityProblems = (name: string, value: string | number | undefined): str
     : [`${name} ${JSON.stringify(value)} is not a valid user or group name`];
 };
 
-export const fileProblems = (props: HostFileProps): string[] => {
+/**
+ * An absolute, normalised path, or the reasons it is not. ★ Shared with sudo-allowlist.ts, so a
+ *   path the sudo runner may touch as root obeys exactly the rule a declared file does.
+ */
+export const pathProblems = (path: string): string[] => {
   const found: string[] = [];
-  const { path } = props;
   if (!path.startsWith('/')) found.push('path must be absolute');
   // ★ One spelling per file: `a/./b`, `a//b` and `a/../b` would each be a second resource for the
   //   same inode, and `..` is how a derived path walks out of the directory it was meant for.
@@ -62,6 +65,11 @@ export const fileProblems = (props: HostFileProps): string[] => {
     found.push('path must be normalised (no trailing slash, no empty, "." or ".." segments)');
   }
   if (path.includes('\x00')) found.push('path contains NUL');
+  return found;
+};
+
+export const fileProblems = (props: HostFileProps): string[] => {
+  const found = pathProblems(props.path);
   const mode = props.mode ?? DEFAULT_MODE;
   if (!Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) found.push('mode must be 0–0o7777');
   found.push(...identityProblems('owner', props.owner));

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

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

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-preflight.ts

@@ -61,8 +61,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()) {

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/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) => {