@homeflare/alchemy 0.8.0 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.8.0",
-  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy.",
+  "version": "0.10.0",
+  "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
   "license": "MIT",
@@ -11,6 +11,9 @@
     "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
     "directory": "packages/alchemy"
   },
+  "bin": {
+    "hf-adopt-verify": "./dist/verify/cli.js"
+  },
   "files": [
     "dist",
     "docs",
@@ -53,6 +56,10 @@
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"
     },
+    "./verify": {
+      "types": "./dist/verify/index.d.ts",
+      "default": "./dist/verify/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/caddy/adopt-scope.test.ts

@@ -5,7 +5,7 @@
  * Caddy the stack declared `.pipe(adopt(false))`.
  * ★ Registered through the REAL `Resource` (caddyWithFile under a Stack), not a hand-built map: the
  *   lookup reads what Alchemy records at registration, so an upgrade that stops recording `Adopt`
- *   in `Stack.resources` fails here (host-effect.ts adoptEnabled).
+ *   in `Stack.resources` fails here (ownership/adopt.ts adoptEnabled).
  */
 import { afterEach, expect, test } from 'bun:test';
 import { push } from 'alchemy';

package/src/caddy/config-lifecycle.ts

@@ -172,7 +172,7 @@ export type Applied = {
  * 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).
+ *     resource's own `adopt(true)` — ownership/adopt.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.
  */

package/src/caddy/config.ts

@@ -27,7 +27,8 @@ import { Unowned } from 'alchemy/AdoptPolicy';
 import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import { adoptEnabled, lift, resolvedString } from '../launchd/host-effect.ts';
+import { lift, resolvedString } from '../launchd/host-effect.ts';
+import { adoptEnabled } from '../ownership/adopt.ts';
 import { CaddyAdminService, CaddyUnreachableError } from './admin.ts';
 import type { CaddyConfigAttributes, CaddyConfigProps } from './config-form.ts';
 import { diffConfig, probeLive, readLive, reconcileConfig } from './config-lifecycle.ts';

package/src/launchd/adopt-apply.test.ts

@@ -0,0 +1,166 @@
+/**
+ * `--adopt` and `adopt(…)` at APPLY, for HostFile and LaunchdJob — the create Alchemy never probed
+ * (a prop still an Output at plan time). Before 2026-09-21 these reconciles refused a foreign file
+ * or job whatever the deploy said, so the flag the refusal told you to use could not work there.
+ * They now resolve adoption the way the planner does (ownership/adopt.ts adoptEnabled), BOTH ways —
+ * for a CREATE only: the row Apply committed for this instance is `creating`. ⛔ A replace's new
+ * generation (a `replacing` row, `output` undefined all the same) is never adoptable at apply.
+ * ★ Registered through the REAL `Resource` under a Stack, as caddy/adopt-scope.test.ts is, over a
+ *   state store holding the row Apply commits before it calls reconcile.
+ */
+import { describe, expect, test } from 'bun:test';
+import { AdoptPolicy, adopt } from 'alchemy/AdoptPolicy';
+import { Artifacts, makeScopedArtifacts } from 'alchemy/Artifacts';
+import { InMemoryService } from 'alchemy/State/InMemoryState';
+import type { ResourceState } from 'alchemy/State/ResourceState';
+import { State } from 'alchemy/State/State';
+import { Stack } from 'alchemy/Stack';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { noteUnfinished } from '../ownership/resume.ts';
+import { fakeRunner } from './fake-runner.ts';
+import { HostFile, HostFileProvider } from './host-file.ts';
+import { LaunchdJob, LaunchdJobProvider } from './job.ts';
+import type { LaunchdJobAttributes } from './job-form.ts';
+import { hostRunnerLayer } from './runner.ts';
+
+type Scope = 'adopt(true)' | 'adopt(false)' | 'none';
+
+const FOREIGN = new TextEncoder().encode('someone else wrote this\n');
+const PATH = '/etc/example/a.conf';
+const PLIST = '/Library/LaunchDaemons/com.example.job.plist';
+const JOB = { domain: 'system', label: 'com.example.job', programArguments: ['/bin/job'] } as const;
+
+const host = () => {
+  const fake = fakeRunner({ dirs: { '/Library/LaunchDaemons': 0, '/etc/example': 0 }, euid: 0 });
+  for (const path of [PATH, PLIST]) {
+    fake.files.set(path, { bytes: FOREIGN, gid: 0, kind: 'file', mode: 0o644, uid: 0 });
+  }
+  return fake;
+};
+
+const scoped = <A extends Effect.Effect<unknown, unknown, unknown>>(declared: A, scope: Scope) =>
+  scope === 'none' ? declared : (declared.pipe(adopt(scope === 'adopt(true)')) as A);
+
+/** The row Apply commits before reconcile: a create's, or a replace's new generation's. */
+type Generation = 'creating' | 'replacing';
+
+/** Register `family` with `scope` under a deploy whose `--adopt` is `flag`; reconcile it statelessly. */
+const firstApply = (
+  family: 'file' | 'job',
+  scope: Scope,
+  flag: boolean,
+  output?: unknown,
+  generation: Generation = 'creating',
+  /** The plan's diff saw this generation's row with no attributes (ownership/resume.ts). */
+  unfinished = false,
+) => {
+  const fake = host();
+  const fqn = family === 'file' ? 'conf' : 'job';
+  const row = { fqn, instanceId: 'i-1', status: generation } as unknown as ResourceState;
+  const spec = { actions: {}, bindings: {}, name: 'test', resources: {}, stage: 'test' };
+  const call = {
+    bindings: [] as never,
+    instanceId: 'i-1',
+    olds: undefined,
+    session: undefined as never,
+  };
+  const program: Effect.Effect<unknown, unknown, AdoptPolicy | Stack> =
+    family === 'file'
+      ? Effect.gen(function* () {
+          yield* scoped(HostFile('conf', { content: 'x', path: PATH }), scope);
+          const provider = yield* HostFile.Provider;
+          const news = { content: 'x', path: PATH };
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'conf',
+            id: 'conf',
+            news,
+            output: undefined,
+          });
+        }).pipe(
+          Effect.provide(HostFileProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        )
+      : Effect.gen(function* () {
+          yield* scoped(LaunchdJob('job', JOB), scope);
+          const provider = yield* LaunchdJob.Provider;
+          const prior = output as LaunchdJobAttributes | undefined;
+          return yield* provider.reconcile({
+            ...call,
+            fqn: 'job',
+            id: 'job',
+            news: JOB,
+            output: prior,
+          });
+        }).pipe(
+          Effect.provide(LaunchdJobProvider().pipe(Layer.provide(hostRunnerLayer(fake.runner)))),
+        );
+  const bag = makeScopedArtifacts(new Map(), fqn);
+  const noted = unfinished ? noteUnfinished('i-1') : Effect.void;
+  const applying = Effect.runPromise(
+    Effect.andThen(noted, program).pipe(
+      Effect.provideService(Artifacts, bag),
+      Effect.provideService(AdoptPolicy, flag),
+      Effect.provideService(State, InMemoryService({ test: { test: { [fqn]: row } } })),
+      Effect.provideService(Stack, spec as never),
+    ),
+  );
+  return { applying, fake };
+};
+
+const REFUSED = /already exists and is not this resource|is already on this host/;
+
+describe.each(['file', 'job'] as const)('%s: a first apply over a foreign object', (family) => {
+  test.each([
+    ['adopt(false) under --adopt', 'adopt(false)', true, false],
+    ['adopt(true) without --adopt', 'adopt(true)', false, true],
+    ['no scope under --adopt', 'none', true, true],
+    ['no scope without --adopt', 'none', false, false],
+  ] as const)('with %s', async (_, scope, flag, takesOver) => {
+    const { applying, fake } = firstApply(family, scope, flag);
+    const path = family === 'file' ? PATH : PLIST;
+    if (takesOver) {
+      await applying;
+      expect(fake.files.get(path)?.bytes).not.toEqual(FOREIGN);
+    } else {
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(path)?.bytes).toEqual(FOREIGN);
+    }
+  });
+});
+
+test('a LaunchdJob rename onto a foreign job stays refused, --adopt or not', async () => {
+  const old = {
+    domain: 'system',
+    label: 'com.example.old',
+    loaded: false,
+    plistPath: '/Library/LaunchDaemons/com.example.old.plist',
+    plistSha256: '',
+    serviceTarget: 'system/com.example.old',
+  };
+  const { applying, fake } = firstApply('job', 'adopt(true)', true, old);
+  await expect(applying).rejects.toThrow(REFUSED);
+  expect(fake.files.get(PLIST)?.bytes).toEqual(FOREIGN);
+});
+
+describe.each(['file', 'job'] as const)('%s: a replace onto a foreign object', (family) => {
+  test.each([
+    ['--adopt', 'none', true],
+    ['adopt(true)', 'adopt(true)', false],
+  ] as const)(
+    'stays refused under %s: the plan never offered its new generation adoption',
+    async (_, scope, flag) => {
+      const { applying, fake } = firstApply(family, scope, flag, undefined, 'replacing');
+      await expect(applying).rejects.toThrow(REFUSED);
+      expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).toEqual(FOREIGN);
+    },
+  );
+
+  test('an UNFINISHED replace (its row seen by the plan) resumes under --adopt, as a create does', async () => {
+    const refused = firstApply(family, 'none', false, undefined, 'replacing', true);
+    await expect(refused.applying).rejects.toThrow(REFUSED);
+    const { applying, fake } = firstApply(family, 'none', true, undefined, 'replacing', true);
+    await applying;
+    expect(fake.files.get(family === 'file' ? PATH : PLIST)?.bytes).not.toEqual(FOREIGN);
+  });
+});

package/src/launchd/fake-runner.ts

@@ -9,6 +9,8 @@
  *   job exits non-zero; a job can linger after bootout (`lingerPrints`); a gui uid with no login
  *   session answers 112 (`loggedOut`); writes into a root-owned directory, or a chown to another
  *   uid, need root.
+ * ★ Every directory ABOVE a declared one exists, root's and `0755`, as `/`, `/Library` and `/opt`
+ *   are on a Mac; `acls` holds the `ls -lden` entry lines a directory prints (sudo-acl.ts).
  */
 import { LAUNCHCTL, NOT_FOUND, NO_DOMAIN } from './launchctl.ts';
 import type { ExecResult, FileStat, HostRunner, HostUser, WriteOptions } from './runner.ts';
@@ -54,6 +56,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
   const root = privileged || euid === 0;
   const dirs = new Map(Object.entries(options.dirs ?? {}));
   const files = new Map<string, Entry>();
+  /** Directory → the ACL entry lines `ls -lden` prints under it. */
+  const acls = new Map<string, string[]>();
+  /** The directories above the declared ones, as the host starts: root's, `0755`. */
+  const above = new Set<string>(['/']);
+  for (const dir of dirs.keys()) {
+    const parts = dir.split('/').slice(1, -1);
+    for (const index of parts.keys()) above.add(`/${parts.slice(0, index + 1).join('/')}`);
+  }
+  for (const dir of dirs.keys()) above.delete(dir);
+  const implied = (path: string) => above.has(path);
   const calls: string[][] = [];
   /** target → pid (undefined = loaded, not running). */
   const loaded = new Map<string, number | undefined>();
@@ -128,6 +140,16 @@ export const fakeRunner = (options: FakeOptions = {}) => {
     exec: async (argv) => {
       calls.push([...argv]);
       if (argv[0] === LAUNCHCTL) return launchctl(argv.slice(1));
+      if (argv[0] === '/bin/ls' && argv[1] === '-lden' && argv[2] === '--') {
+        const paths = argv.slice(3);
+        if (paths.some((path) => !dirs.has(path) && !files.has(path) && !implied(path)))
+          return fail(1, 'ls: No such file or directory');
+        const lines = paths.flatMap((path) => [
+          `drwxr-xr-x  2 0  0  64 Sep 21 10:00 ${path}`,
+          ...(acls.get(path) ?? []),
+        ]);
+        return ok(lines.join('\n'));
+      }
       return fail(127, `fake: no program ${String(argv[0])}`);
     },
     lookupGroup: async (nameOrId) => options.groups?.[nameOrId],
@@ -153,9 +175,9 @@ export const fakeRunner = (options: FakeOptions = {}) => {
           size: entry.bytes.length,
           uid: entry.uid,
         };
-      return dirs.has(path)
-        ? { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 }
-        : undefined;
+      if (dirs.has(path) || implied(path))
+        return { gid: 0, kind: 'directory', mode: 0o755, size: 0, uid: dirs.get(path) ?? 0 };
+      return undefined;
     },
     writeFileAtomic: async (path: string, bytes: Uint8Array, write: WriteOptions) => {
       calls.push(['write', path]);
@@ -172,5 +194,5 @@ export const fakeRunner = (options: FakeOptions = {}) => {
       });
     },
   };
-  return { calls, disabled, dirs, files, loaded, runner, state };
+  return { acls, calls, disabled, dirs, files, loaded, runner, state };
 };

package/src/launchd/host-effect.ts

@@ -1,17 +1,13 @@
 /**
  * The one place a HostRunner's promises become Effects — plus the one probe of an unresolved
- * `news` both providers' diffs share, and the engine's adopt setting for a check at apply.
+ * `news` both providers' diffs share. (The engine's adopt setting lives in ownership/adopt.ts.)
  *
  * ★ 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({
@@ -30,31 +26,3 @@ 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-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.
@@ -120,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 ' +
@@ -132,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/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)),
       });