@homeflare/alchemy 0.19.0 → 0.20.0

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

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

package/src/linux/remote-file.ts

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

package/src/linux/unit-handlers.ts

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

package/src/linux/unit-lifecycle.ts

@@ -19,7 +19,8 @@
  *   start fail; unmasking here would silently overrule whoever masked it.
  */
 import type { Diff } from 'alchemy/Diff';
-import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import type { HostRunner } from '../launchd/runner.ts';
+import { daemonReload, disableUnit, showUnit, stopUnit } from './systemctl.ts';
 import {
   type SystemdUnitAttributes,
   type SystemdUnitProps,
@@ -27,21 +28,14 @@ import {
   configDigest,
   digestOf,
   unitPathFor,
-  unitProblems,
   unitText,
 } from './unit-form.ts';
-import { type UnitStatus, daemonReload, disableUnit, showUnit, stopUnit } from './systemctl.ts';
+import { assertMayWrite, assertReplaceable, assertUsable, assertValid } from './unit-preflight.ts';
 import { attributesOf, refuse, settle } from './unit-settle.ts';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-/** Throw every refusal at once, so one plan shows the whole list. */
-export const assertValid = (props: SystemdUnitProps, expect?: string): void => {
-  const found = unitProblems(props, expect);
-  if (found.length > 0) throw refuse(props.name, found.join('; '));
-};
-
 /** What is on the host now: the unit file's digest and systemd's view. `undefined` when neither. */
 export const readUnit = async (
   runner: HostRunner,
@@ -53,26 +47,6 @@ export const readUnit = async (
   return attributesOf(props, bytes === undefined ? '' : digestOf(decoder.decode(bytes)), status);
 };
 
-/** ⛔ Writing a unit file and driving systemd are root's, so refuse up front rather than mid-apply. */
-export const assertMayWrite = (runner: HostRunner, name: string): void => {
-  if (canActAsRoot(runner)) return;
-  throw refuse(
-    name,
-    'a systemd unit is root-owned and systemctl needs root. Point the runner at a destination ' +
-      'whose ssh user is root, or provide a privileged HostRunner. This provider never calls sudo.',
-  );
-};
-
-const assertUsable = (props: SystemdUnitProps, status: UnitStatus): void => {
-  if (status.loadState === 'masked' || status.unitFileState === 'masked') {
-    throw refuse(
-      props.name,
-      'is masked. If that is stale, `systemctl unmask` it deliberately, then redeploy. Nothing ' +
-        'was written.',
-    );
-  }
-};
-
 export const diffUnit = async (
   runner: HostRunner,
   news: SystemdUnitProps,
@@ -82,8 +56,10 @@ export const diffUnit = async (
   assertValid(news, expect);
   // ★ The unit's name or its directory is its identity on the host: a change is a replace, and
   //   delete-first, because two unit files for one name cannot both be the one systemd reads.
+  // ⛔ Which is why everything the new unit's reconcile would refuse is refused HERE, at plan
+  //   time (unit-preflight.ts): after the delete it would be too late.
   if (news.name !== output.name || unitPathFor(news) !== output.unitPath) {
-    assertMayWrite(runner, news.name);
+    await assertReplaceable(runner, news, output, expect);
     return { action: 'replace', deleteFirst: true };
   }
   const desired = digestOf(unitText(news));
@@ -129,6 +105,12 @@ export const reconcileUnit = async (
   const before = await runner.readFile(path);
   const liveSha = before === undefined ? undefined : digestOf(decoder.decode(before));
   const moved = output !== undefined && (output.name !== props.name || output.unitPath !== path);
+  /**
+   * ★ A rename the diff could not see — a name that was still an unresolved Output at plan time
+   *   (unit-handlers.ts diffHandler) — arrives here as an update. Run the same read-only checks a
+   *   plan-time replace runs, BEFORE deleteUnit, or the old unit is already gone when we refuse.
+   */
+  if (moved && output !== undefined) await assertReplaceable(runner, props, output, expect);
   const prior = moved ? undefined : output;
   /**
    * ⛔ A UNIT THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. Where the engine's probe never

package/src/linux/unit-preflight.test.ts

@@ -0,0 +1,128 @@
+/**
+ * A systemd rename is a delete-first replace, so every refusal has to fire at PLAN time. Caught
+ * only in reconcile, Alchemy has already stopped and removed the old unit (Apply.ts,
+ * deleteOldGenerations under `node.deleteFirst`).
+ *
+ * ★ The last case is the one the diff cannot see: a name that was still an Output at plan time
+ *   arrives at reconcile as an update (unit-handlers.ts). The same refusals have to fire there,
+ *   before deleteUnit.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { renderUnit } from './unit-form.ts';
+import { deleteUnit, diffUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-example.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+const RENAMED = 'hf-renamed.service';
+const RENAMED_PATH = `/etc/systemd/system/${RENAMED}`;
+
+const body = (exec: string) =>
+  renderUnit([
+    { lines: [['Description', 'an example']], name: 'Unit' },
+    {
+      lines: [
+        ['ExecStart', exec],
+        ['Restart', 'on-failure'],
+      ],
+      name: 'Service',
+    },
+    { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+  ]);
+
+const props = { content: body('/usr/bin/example'), name: NAME };
+const renamed = { ...props, name: RENAMED };
+const host = () => fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+
+const running = async () => {
+  const fake = host();
+  const output = await reconcileUnit(fake.runner, props, undefined);
+  return { fake, output };
+};
+
+describe('a rename is refused at plan time, and the old unit is still running', () => {
+  test('a masked new name', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { masked: true });
+    await expect(diffUnit(fake.runner, renamed, output)).rejects.toThrow(/is masked/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+
+  test('a new name whose file belongs to someone else', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { active: true, enabled: true });
+    await expect(diffUnit(fake.runner, renamed, output)).rejects.toThrow(/not this resource/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.units.get(RENAMED)?.active).toBe(true);
+  });
+
+  test('a file byte-identical to our render is our own leftover, not a claim', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, props.content);
+    expect(await diffUnit(fake.runner, renamed, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+  });
+
+  test('a runner that will not write the new path', async () => {
+    const { fake, output } = await running();
+    const refusing = {
+      ...fake.runner,
+      checkWrite: async () => {
+        throw new Error('HostRunner.checkWrite refused');
+      },
+    };
+    await expect(diffUnit(refusing, renamed, output)).rejects.toThrow(/checkWrite/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+  });
+
+  test('the old unit must be deletable before a delete-first replace is promised', async () => {
+    const { fake, output } = await running();
+    const unprivileged = { ...fake.runner, effectiveUid: () => 1001, privileged: false };
+    await expect(diffUnit(unprivileged, renamed, output)).rejects.toThrow(/never calls sudo/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+});
+
+describe('a free name', () => {
+  test('plans a delete-first replace, and delete-then-reconcile leaves only the new unit', async () => {
+    const { fake, output } = await running();
+    expect(await diffUnit(fake.runner, renamed, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+    await deleteUnit(fake.runner, output);
+    const next = await reconcileUnit(fake.runner, renamed, output);
+    expect(next).toMatchObject({
+      active: true,
+      enabled: true,
+      name: RENAMED,
+      unitPath: RENAMED_PATH,
+    });
+    expect(fake.files.has(PATH)).toBe(false);
+    expect(fake.files.has(RENAMED_PATH)).toBe(true);
+    expect(fake.units.get(NAME)?.active ?? false).toBe(false);
+  });
+});
+
+describe('a rename the diff could not see is refused at apply, before the old unit stops', () => {
+  test('a masked new name', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { masked: true });
+    await expect(reconcileUnit(fake.runner, renamed, output)).rejects.toThrow(/is masked/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+
+  test('a new name whose file belongs to someone else', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { active: true, enabled: true });
+    await expect(reconcileUnit(fake.runner, renamed, output)).rejects.toThrow(/not this resource/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+    expect(fake.units.get(RENAMED)?.active).toBe(true);
+  });
+});

package/src/linux/unit-preflight.ts

@@ -0,0 +1,116 @@
+/**
+ * Everything Systemd.Unit checks before it touches the host — split from unit-lifecycle.ts so that
+ * a reconcile and a plan-time REPLACE run the very same checks.
+ *
+ * ★ WHY A REPLACE IS CHECKED AT PLAN TIME. A name or directory change is a delete-first replace,
+ *   and Alchemy runs `delete` on the old unit BEFORE `reconcile` on the new one (Apply.ts,
+ *   deleteOldGenerations under `node.deleteFirst`). A refusal that fired only in reconcile would
+ *   therefore arrive after the old unit was already stopped and its file removed: nothing running,
+ *   and a plan that had promised a clean swap.
+ * ★ EVERY CHECK HERE IS READ-ONLY. systemd has no `print-disabled` equivalent in this family —
+ *   masking is `systemctl show`'s LoadState / UnitFileState, which `showUnit` already returns.
+ *   Validation, that show, a file read and `HostRunner.checkWrite` write nothing. `systemctl
+ *   enable` itself stays an apply step; the ways it is known to fail (no `[Install]`, a directory
+ *   systemd does not search) are `unitProblems`, checked here before the plan may promise a swap.
+ */
+import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
+import { type UnitStatus, showUnit } from './systemctl.ts';
+import {
+  type SystemdUnitAttributes,
+  type SystemdUnitProps,
+  UNIT_WRITE,
+  digestOf,
+  unitPathFor,
+  unitProblems,
+  unitText,
+} from './unit-form.ts';
+import { refuse } from './unit-settle.ts';
+
+const decoder = new TextDecoder();
+
+/** Throw every refusal at once, so one plan shows the whole list. */
+export const assertValid = (props: SystemdUnitProps, expect?: string): void => {
+  const found = unitProblems(props, expect);
+  if (found.length > 0) throw refuse(props.name, found.join('; '));
+};
+
+/** ⛔ Writing a unit file and driving systemd are root's, so refuse up front rather than mid-apply. */
+export const assertMayWrite = (runner: HostRunner, name: string): void => {
+  if (canActAsRoot(runner)) return;
+  throw refuse(
+    name,
+    'a systemd unit is root-owned and systemctl needs root. Point the runner at a destination ' +
+      'whose ssh user is root, or provide a privileged HostRunner. This provider never calls sudo.',
+  );
+};
+
+/**
+ * ⛔ A MASKED UNIT IS SOMEONE'S DECISION, NOT DRIFT. `systemctl mask` survives reboots and makes
+ *   start fail; unmasking here would silently overrule whoever masked it.
+ */
+export const assertUsable = (props: Pick<SystemdUnitProps, 'name'>, status: UnitStatus): void => {
+  if (status.loadState === 'masked' || status.unitFileState === 'masked') {
+    throw refuse(
+      props.name,
+      'is masked. If that is stale, `systemctl unmask` it deliberately, then redeploy. Nothing ' +
+        'was written.',
+    );
+  }
+};
+
+/**
+ * ⛔ A UNIT THIS RESOURCE DOES NOT OWN IS NEVER OVERWRITTEN. Alchemy's adoption probe guards a
+ *   create, but NOT the new name of a replace — the engine reads nothing there — so a rename onto
+ *   a unit file someone else already has would stop the old unit and write ours over theirs.
+ * ★ A file byte-identical to our render is exempt: it is this declaration's own leftover (a deploy
+ *   that died between write and reload), and rewriting it changes nothing.
+ */
+export const assertUnclaimed = async (
+  runner: HostRunner,
+  props: SystemdUnitProps,
+): Promise<void> => {
+  const path = unitPathFor(props);
+  const bytes = await runner.readFile(path);
+  const live = bytes === undefined ? undefined : digestOf(decoder.decode(bytes));
+  if (live !== undefined && live !== digestOf(unitText(props))) {
+    throw refuse(
+      props.name,
+      `${path} is already on this host and is not this resource. Remove it, or declare it as a ` +
+        'new resource and deploy with --adopt.',
+    );
+  }
+};
+
+/**
+ * The half of a rename check that needs only the NEW NAME: the old unit deletable, the new one
+ * writable and not masked.
+ * ★ ON ITS OWN it is for the rename unit-handlers.ts `diffHandler` spots while `content` is still
+ *   an Output. That plan is a delete-first replace too, so a masked target refused only in
+ *   reconcile would again arrive after the old unit was stopped. The unit file itself cannot be
+ *   compared until `content` resolves, so `assertUnclaimed` stays reconcile's job there.
+ */
+export const assertRenameTarget = async (
+  runner: HostRunner,
+  old: SystemdUnitAttributes,
+  name: string,
+): Promise<void> => {
+  assertMayWrite(runner, old.name);
+  assertMayWrite(runner, name);
+  assertUsable({ name }, await showUnit(runner, name));
+};
+
+/**
+ * A rename, checked at plan time: the new identity must be valid, writable, not masked and free,
+ * and the old one deletable — before the plan may promise a delete-first replace.
+ */
+export const assertReplaceable = async (
+  runner: HostRunner,
+  next: SystemdUnitProps,
+  old: SystemdUnitAttributes,
+  expect?: string,
+): Promise<void> => {
+  assertValid(next, expect);
+  await assertRenameTarget(runner, old, next.name);
+  await assertUnclaimed(runner, next);
+  await runner.checkWrite?.(unitPathFor(next), UNIT_WRITE);
+};

package/src/linux/unit-rename.test.ts

@@ -0,0 +1,76 @@
+/**
+ * The rename a plan sees while `content` is still an Output. `diffHandler` cannot run `diffUnit`
+ * there, but it still plans a delete-first replace — so the refusals that need only the new NAME
+ * have to fire in the plan, before Alchemy stops and removes the old unit.
+ *
+ * ★ The fully resolved rename is unit-preflight.test.ts. 🔴 Found by review (2026-09-22): this
+ *   branch returned the replace with no check at all.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { fakeLinuxHost } from './fake-linux-host.ts';
+import { renderUnit } from './unit-form.ts';
+import { diffHandler } from './unit-handlers.ts';
+import { diffUnit, reconcileUnit } from './unit-lifecycle.ts';
+
+const NAME = 'hf-example.service';
+const PATH = `/etc/systemd/system/${NAME}`;
+const RENAMED = 'hf-renamed.service';
+const RENAMED_PATH = `/etc/systemd/system/${RENAMED}`;
+const body = (exec: string) =>
+  renderUnit([
+    { lines: [['Description', 'example']], name: 'Unit' },
+    { lines: [['ExecStart', exec]], name: 'Service' },
+    { lines: [['WantedBy', 'multi-user.target']], name: 'Install' },
+  ]);
+
+const props = { content: body('/usr/bin/example'), name: NAME };
+// ★ An Effect is what isResolved() calls unresolved — the stand-in for a rendered digest.
+const pending = { content: Effect.succeed(props.content), name: RENAMED } as never;
+
+const running = async () => {
+  const fake = fakeLinuxHost({ dirs: { '/etc/systemd/system': 0 } });
+  const output = await reconcileUnit(fake.runner, props, undefined);
+  return { fake, output, writes: () => fake.calls.filter((call) => call[0] === 'write').length };
+};
+
+describe('a rename while content is still an Output', () => {
+  test('a free name plans a delete-first replace and writes nothing', async () => {
+    const { fake, output, writes } = await running();
+    const before = writes();
+    const diff = await Effect.runPromise(diffHandler(fake.runner, 'id', pending, output));
+    expect(diff).toEqual({ action: 'replace', deleteFirst: true });
+    expect(writes()).toBe(before);
+  });
+
+  test('a MASKED target is refused by the plan, with the old unit still running', async () => {
+    const { fake, output } = await running();
+    fake.placeUnit(RENAMED_PATH, body('/usr/bin/other'), { masked: true });
+    await expect(
+      Effect.runPromise(diffHandler(fake.runner, 'id', pending, output)),
+    ).rejects.toThrow(/is masked/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+    expect(fake.files.has(PATH)).toBe(true);
+  });
+
+  test('an unprivileged runner is refused before anything is removed', async () => {
+    const { fake, output } = await running();
+    const unprivileged = { ...fake.runner, effectiveUid: () => 1001, privileged: false };
+    await expect(
+      Effect.runPromise(diffHandler(unprivileged, 'id', pending, output)),
+    ).rejects.toThrow(/never calls sudo/);
+    expect(fake.units.get(NAME)?.active).toBe(true);
+  });
+});
+
+describe('a resolved rename', () => {
+  test('is read-only: the plan writes nothing, whatever it decided', async () => {
+    const { fake, output, writes } = await running();
+    const before = writes();
+    expect(await diffUnit(fake.runner, { ...props, name: RENAMED }, output)).toEqual({
+      action: 'replace',
+      deleteFirst: true,
+    });
+    expect(writes()).toBe(before);
+  });
+});