@homeflare/alchemy 0.37.6 → 0.37.8

package/src/linux/container-generator.test.ts

@@ -192,4 +192,37 @@ describe('verifyGenerated, directly', () => {
       }),
     ).toThrow(/earlier in Quadlet/);
   });
+
+  /**
+   * ⛔ REGRESSION — found on adversarial review. Before the FragmentPath check was added, a real,
+   *   already-loaded PLAIN unit (e.g. an admin's own `/etc/systemd/system/…` sharing this
+   *   container's service name) reported `LoadState=loaded` (it is a genuinely valid unit) and no
+   *   `SourcePath` (hand-written units never carry one) — both existing checks passed it silently,
+   *   so `verifyGenerated` was not the backstop its own doc comments claimed: a shadow that slipped
+   *   past `assertUnshadowed` (container-preflight.ts) would misapply silently, not throw loudly.
+   */
+  test('a loaded plain unit with no SourcePath is still caught, via FragmentPath', () => {
+    expect(() =>
+      verifyGenerated(NAME, PATH, SERVICE, {
+        activeState: 'active',
+        fragmentPath: '/etc/systemd/system/hf-example.service',
+        known: true,
+        loadState: 'loaded',
+        needDaemonReload: false,
+      }),
+    ).toThrow(/not from Quadlet.s generator/);
+  });
+
+  test('a real generated FragmentPath is not mistaken for a shadow', () => {
+    expect(() =>
+      verifyGenerated(NAME, PATH, SERVICE, {
+        activeState: 'active',
+        fragmentPath: `/run/systemd/generator/${SERVICE}`,
+        known: true,
+        loadState: 'loaded',
+        needDaemonReload: false,
+        sourcePath: PATH,
+      }),
+    ).not.toThrow();
+  });
 });

package/src/linux/container-generator.ts

@@ -55,6 +55,56 @@ import type { UnitStatus } from './systemctl.ts';
 /** MEASURED on CT100 2026-09-24: `systemctl show caddy.service -p FragmentPath`. */
 export const GENERATED_UNIT_DIRECTORY = '/run/systemd/generator';
 
+/**
+ * Whether `fragmentPath` is Quadlet's OWN generator output — the "did daemon-reload actually
+ * produce OUR unit" question `verifyGenerated` needs, as distinct from `isShadowingFragment`
+ * below (the "does something ELSE outrank the generator" question `assertUnshadowed` needs — the
+ * two are not complements of each other, see that function's header).
+ */
+export const isGeneratorFragment = (fragmentPath: string | undefined): boolean =>
+  fragmentPath !== undefined && fragmentPath.startsWith(`${GENERATED_UNIT_DIRECTORY}/`);
+
+/**
+ * ⛔ CORRECTED ON ADVERSARIAL RE-REVIEW OF THE FIX BELOW — the directories that ACTUALLY search
+ *   BEFORE `${GENERATED_UNIT_DIRECTORY}` in systemd's real Unit File Load Path (`systemd.unit(5)`,
+ *   tag v257, "Unit File Load Path"), highest to lowest precedence:
+ *     /etc/systemd/system.control, /run/systemd/system.control, /run/systemd/transient,
+ *     /etc/systemd/system, /etc/systemd/system.attached, /run/systemd/system,
+ *     /run/systemd/system.attached, [${GENERATED_UNIT_DIRECTORY}], /usr/local/lib/systemd/system,
+ *     /usr/lib/systemd/system, /run/systemd/generator.late.
+ * ⛔ `/usr/local/lib/systemd/system` AND `/usr/lib/systemd/system` ARE DELIBERATELY ABSENT — the
+ *   original version of this check (`isGeneratorFragment`'s NEGATION: "not the generator's own
+ *   output") treated ANY other FragmentPath as shadowing, including these two vendor directories,
+ *   which are LOWER precedence than the generator, not higher. A plain unit there is harmlessly
+ *   shadowed BY Quadlet's generated unit, same as `unit-form.ts`'s `UNIT_SEARCH_DIRECTORIES`
+ *   (measured via `systemd-analyze unit-paths`) independently lists them below `/run/systemd/system`,
+ *   and `systemctl.ts`'s own header distinguishes `/etc/systemd/system` from "the vendor's
+ *   `/usr/lib/systemd/system`" rather than lumping the two together. Refusing for either one blocked
+ *   a create/adopt apply would have handled fine — exactly the false positive S49 ("neither looser
+ *   nor stricter") forbids. `/etc/systemd/system.control`, `.attached` and `/run/systemd/transient`
+ *   are included for completeness against the man page though no family here writes into them.
+ */
+const SHADOWING_UNIT_DIRECTORIES = [
+  '/etc/systemd/system.control',
+  '/run/systemd/system.control',
+  '/run/systemd/transient',
+  '/etc/systemd/system',
+  '/etc/systemd/system.attached',
+  '/run/systemd/system',
+  '/run/systemd/system.attached',
+] as const;
+
+/**
+ * Whether `fragmentPath` genuinely OUTRANKS Quadlet's generator — the real question
+ * `container-preflight.ts`'s `assertUnshadowed` needs ("would writing our `.container` file and
+ * reloading still lose to this other unit?"), as opposed to the broader and wrong question the
+ * original check asked ("is this simply not the generator's own output?", which is also true of
+ * every LOWER-precedence vendor unit and wrongly refused those too).
+ */
+export const isShadowingFragment = (fragmentPath: string | undefined): boolean =>
+  fragmentPath !== undefined &&
+  SHADOWING_UNIT_DIRECTORIES.some((dir) => fragmentPath.startsWith(`${dir}/`));
+
 export class QuadletGeneratorError extends Error {
   constructor(name: string, detail: string) {
     super(`Podman.Container ${name}: ${detail}`);
@@ -85,6 +135,19 @@ export const needsVerificationReload = (containerPath: string, status: UnitStatu
  * resource is simply absent", which is what a plain `LoadState=not-found` would otherwise look
  * like to a caller that only knows the `Systemd.Unit` shape (a unit that has genuinely never been
  * declared also reads `not-found`).
+ *
+ * ⛔ THE FRAGMENTPATH CHECK BELOW WAS ADDED — found on adversarial review of `assertUnshadowed`
+ *   (container-preflight.ts): before it, this function trusted `LoadState`/`SourcePath` alone, and
+ *   neither one notices a genuinely-shadowing PLAIN unit. A real, already-loaded plain unit (e.g.
+ *   an admin's own `/etc/systemd/system/foo.service` sharing this container's service name) reports
+ *   `LoadState=loaded` — it is a valid unit — and `SourcePath` empty, since hand-written units never
+ *   carry one; both checks above pass it silently. MEASURED directly against this function: a
+ *   `status` built from exactly what `systemctl show` reports for that case (`loadState: 'loaded'`,
+ *   `fragmentPath` under `/etc/systemd/system`, `sourcePath: undefined`) did not throw before this
+ *   check existed. Without it, `assertUnshadowed`'s plan-time refusal was the ONLY thing standing
+ *   between a shadowing plain unit and a SILENT apply-time "success" that leaves the pre-existing
+ *   unit running untouched while state records attributes read back from it — not a loud mid-apply
+ *   throw, which is what earlier documentation of this fix claimed the pre-fix risk was.
  */
 export const verifyGenerated = (
   name: string,
@@ -102,6 +165,15 @@ export const verifyGenerated = (
         `'systemd-analyze --generators=true verify ${serviceName}' (podman-systemd.unit(5), Podman 5.4).`,
     );
   }
+  if (status.fragmentPath !== undefined && !isGeneratorFragment(status.fragmentPath)) {
+    throw new QuadletGeneratorError(
+      name,
+      `${serviceName} is loaded from ${status.fragmentPath}, not from Quadlet’s generator ` +
+        `(${GENERATED_UNIT_DIRECTORY}/…) — daemon-reload ran, but a plain unit at that path still ` +
+        'answers to this name, and systemd loaded IT, not ours. Move the plain unit aside — a ' +
+        'cutover — and redeploy.',
+    );
+  }
   if (status.sourcePath !== undefined && status.sourcePath !== containerPath) {
     throw new QuadletGeneratorError(
       name,

package/src/linux/container-lifecycle.test.ts

@@ -3,7 +3,8 @@
  * like it, cares most about the NEGATIVE assertions: an adopted container that already matches is
  * not restarted, a re-run restarts nothing, and a read that fails writes nothing. Generator-failure
  * rollback and the never-enable guarantee are in container-generator.test.ts; secret refusal is in
- * container-secrets.test.ts; the CT100 fixture is in container-fixture.test.ts.
+ * container-secrets.test.ts; the CT100 fixture is in container-fixture.test.ts; a plain unit
+ * shadowing the service name (`assertUnshadowed`) is in container-shadow.test.ts.
  */
 import { describe, expect, test } from 'bun:test';
 import { fakeQuadletHost } from './fake-quadlet.ts';
@@ -52,7 +53,7 @@ describe('create', () => {
     expect(fake.files.get(PATH)?.uid).toBe(0);
   });
 
-  test('a start that fails removes the file this deploy wrote and says the unit is down', async () => {
+  test('a start that fails removes the file this deploy wrote and reports the read-back state', async () => {
     const fake = host();
     const broken = {
       ...fake.runner,
@@ -61,8 +62,10 @@ describe('create', () => {
           ? { exitCode: 1, stderr: 'Job failed', stdout: '' }
           : fake.runner.exec(argv),
     };
+    // ★ Not a hardcoded "NOT running" claim (measured false for a refusal-before-sudo failure,
+    //   container-settle.ts's header) — a genuine read-back of what systemd now reports.
     await expect(reconcileContainer(broken, props('example/one:1'), undefined)).rejects.toThrow(
-      /NOT running/,
+      /unit is now inactive/,
     );
     expect(fake.files.has(PATH)).toBe(false);
   });

package/src/linux/container-lifecycle.ts

@@ -36,6 +36,7 @@ import {
 import {
   assertMayWrite,
   assertReplaceable,
+  assertUnshadowed,
   assertUsable,
   assertValid,
 } from './container-preflight.ts';
@@ -44,7 +45,24 @@ import { attributesOf, settle } from './container-settle.ts';
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-/** What is on the host now: the `.container` file's digest and the GENERATED unit's status. */
+/**
+ * What is on the host now: the `.container` file's digest and the GENERATED unit's status.
+ *
+ * ⛔ A FILE-LESS `known` UNIT IS NOT NECESSARILY OURS — found on adversarial review. The OLD test
+ *   here was `bytes === undefined && !status.known`: absent file, unknown unit → nothing. But a
+ *   PLAIN unit under `/etc/systemd/system` with the same service name also makes `status.known`
+ *   true, with no `.container` file behind it at all — the read then reported a container that has
+ *   never been declared as "exists", and a plan built on that said "adopted" for something a create
+ *   would later fail to make real (`assertUnshadowed`, container-preflight.ts, has the measured
+ *   precedence fact and the plan-time refusal). ⛔ `/usr/lib/systemd/system` is DELIBERATELY NOT
+ *   named alongside `/etc/systemd/system` here — corrected on adversarial re-review: it is LOWER
+ *   precedence than Quadlet's generator, not higher (`isShadowingFragment`, container-generator.ts),
+ *   so a plain unit there is exists-but-not-a-shadow: `readContainer` reports it as adopted, same as
+ *   before, and a create/update writes our `.container` file, which then wins for real. A REAL
+ *   Quadlet generation (this or an earlier apply's own file, later removed) reads no differently
+ *   here than before: its `FragmentPath` sits under Quadlet's own generator directory, which
+ *   `assertUnshadowed` never refuses.
+ */
 export const readContainer = async (
   runner: HostRunner,
   props: ContainerProps,
@@ -52,7 +70,10 @@ export const readContainer = async (
   const path = containerPathFor(props);
   const bytes = await runner.readFile(path);
   const status = await showUnit(runner, serviceNameFor(props));
-  if (bytes === undefined && !status.known) return undefined;
+  if (bytes === undefined) {
+    if (!status.known) return undefined;
+    assertUnshadowed(props, status);
+  }
   const sha = bytes === undefined ? '' : digestOf(decoder.decode(bytes));
   return attributesOf(
     props,

package/src/linux/container-preflight.ts

@@ -9,6 +9,7 @@
 import { type HostRunner, canActAsRoot } from '../launchd/runner.ts';
 import { UNIT_WRITE, digestOf } from './unit-form.ts';
 import { type UnitStatus, showUnit } from './systemctl.ts';
+import { GENERATED_UNIT_DIRECTORY, isShadowingFragment } from './container-generator.ts';
 import {
   type ContainerAttributes,
   type ContainerProps,
@@ -73,6 +74,52 @@ export const assertUnclaimed = async (runner: HostRunner, props: ContainerProps)
   }
 };
 
+/**
+ * ⛔ A PLAIN UNIT SHARING THE SERVICE NAME CAN OUTRANK QUADLET'S GENERATOR, SILENTLY — but only
+ *   when it sits in one of the directories that actually search BEFORE `${GENERATED_UNIT_DIRECTORY}`
+ *   in systemd's own unit load path (systemd.unit(5) "Unit File Load Path") — `/etc/systemd/system`
+ *   chief among them (`isShadowingFragment`, container-generator.ts, has the full list and the
+ *   measured facts). ⛔ CORRECTED ON ADVERSARIAL RE-REVIEW: an EARLIER version of this check refused
+ *   for ANY `FragmentPath` not literally under the generator directory, including the vendor
+ *   directories (`/usr/local/lib/systemd/system`, `/usr/lib/systemd/system`) — those are LOWER
+ *   precedence than the generator, not higher, so a plain unit there is harmlessly shadowed BY our
+ *   generated unit once we write and reload; refusing for it was a false positive that blocked a
+ *   create/adopt apply would have handled fine (exactly what S49 "neither looser nor stricter"
+ *   forbids). With no `.container` file of ours on disk yet, a `FragmentPath` under one of the
+ *   genuinely higher-precedence directories means some OTHER unit file — hand-written, or shipped by
+ *   a package, and admin-controlled rather than vendor-controlled — already answers to this name:
+ *   writing and reloading would generate a unit systemd never actually loads, because the
+ *   higher-precedence plain one still wins.
+ * ★ TWIN OF `unit-preflight.ts`'s `assertUnclaimed`, for the one failure mode `Systemd.Unit` can't
+ *   have: there is no generator standing between ITS file and the unit systemd loads, so nothing
+ *   there can be shadowed the way a Quadlet generation can.
+ * ★ ONLY WHEN THE `.container` FILE ITSELF IS ABSENT (called from `readContainer` in that branch):
+ *   a present file with different content is `assertUnclaimed`'s job; a present file that IS ours
+ *   generating a shadowed unit is `verifyGenerated`'s job (container-generator.ts, hardened to check
+ *   this same `FragmentPath` fact), at apply time, once daemon-reload has actually run — this is the
+ *   "nothing declared yet" half neither of those covers, and the one this bug leaves refusing only
+ *   mid-apply instead of at plan time for the directories that genuinely shadow.
+ * ⚠️ NEVER FIRES WITHOUT A CONCRETE `fragmentPath` TO NAME, AND NEVER FOR A MASKED UNIT — MEASURED
+ *   against this family's own fake (`fakeQuadletHost`, unlike `sudo-lifecycle.test.ts`'s, which is
+ *   a different fake and reads differently): `placeUnit(path, text, {masked: true})` still reports
+ *   a real `FragmentPath`. Refusing there anyway would work, but with THIS function's generic
+ *   "plain unit" wording instead of `assertUsable`'s specific, more actionable "is masked, run
+ *   `systemctl unmask` deliberately" — masking is a person's decision, not an accident to explain
+ *   as a name collision. `assertUsable` stays the one place that message comes from.
+ */
+export const assertUnshadowed = (props: Pick<ContainerProps, 'name'>, status: UnitStatus): void => {
+  if (!status.known || status.fragmentPath === undefined) return;
+  if (status.loadState === 'masked' || status.unitFileState === 'masked') return;
+  if (!isShadowingFragment(status.fragmentPath)) return;
+  throw refuseContainer(
+    props.name,
+    `${serviceNameFor(props)} already exists as a plain unit at ${status.fragmentPath}, not a ` +
+      `Quadlet generation — Quadlet's own output (${GENERATED_UNIT_DIRECTORY}/…) would be ` +
+      'shadowed by it and never actually run: systemd loads the higher-precedence file first. ' +
+      'Move the plain unit aside — a cutover — before declaring this container.',
+  );
+};
+
 /** The half of a rename check that needs only the NEW NAME — mirrors `assertRenameTarget`. */
 export const assertRenameTarget = async (
   runner: HostRunner,

package/src/linux/container-settle.ts

@@ -79,7 +79,18 @@ export const settle = async (
       await runner.removeFile(step.path).catch(() => undefined);
       await daemonReload(runner).catch(() => undefined);
     }
-    throw refuseContainer(props.name, `${detail} The container's unit is NOT running.`);
+    // 🔴 MEASURED FALSE, CT100 deploy 2026-09-26 00:11Z: this suffix used to assert "is NOT
+    //   running" unconditionally — even for a `detail` that was a REFUSAL before sudo ever ran
+    //   (the sudo ownership check on a Quadlet unit, say), where nothing about the running
+    //   container was touched. `caddy` stayed active/running through the whole failed deploy.
+    //   State only what this call actually knows: read the live state back, best-effort, rather
+    //   than assert either way.
+    const after = await showUnit(runner, step.serviceName).catch(() => undefined);
+    const stateNote =
+      after === undefined
+        ? 'Its running state was not re-checked.'
+        : `Its unit is now ${after.activeState}.`;
+    throw refuseContainer(props.name, `${detail} ${stateNote}`);
   };
   try {
     if (!wantStarted) {

package/src/linux/container-shadow.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `Podman.Container`'s read/plan behaviour when a PLAIN unit — never Quadlet's own generator
+ * output — already answers to the service name this resource would generate. Split from
+ * container-lifecycle.test.ts (see its header) because this is its own, self-contained scenario:
+ * container-preflight.ts's `assertUnshadowed`, called from `readContainer`.
+ *
+ * ★ WHY `readContainer` IS THE RIGHT LEVEL TO TEST. Alchemy's own cold-start adoption probe calls
+ *   `provider.read` directly to decide "create" vs "adopted" BEFORE `diff` ever runs (alchemy
+ *   beta.79 `Plan.ts` — no state row exists yet, so there is nothing to diff against). Our
+ *   provider's `read` (`readHandler`, container-handlers.ts) is a thin wrapper over
+ *   `readContainer`, so a refusal here IS the plan refusing, not merely a lower layer.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakeQuadletHost } from './fake-quadlet.ts';
+import type { ContainerProps } from './container-form.ts';
+import { readContainer, reconcileContainer } from './container-lifecycle.ts';
+
+const NAME = 'hf-example';
+const PATH = `/etc/containers/systemd/${NAME}.container`;
+const SERVICE = `${NAME}.service`;
+const PLAIN_UNIT_PATH = `/etc/systemd/system/${SERVICE}`;
+
+const props: ContainerProps = {
+  container: { image: 'example/one:1', network: 'host' },
+  install: { wantedBy: ['multi-user.target'] },
+  name: NAME,
+  service: { restart: 'always', restartSec: '5s' },
+};
+
+/** A unit systemd loaded from somewhere OTHER than Quadlet's own generator — e.g. a PLAIN unit
+ *  dropped in `/etc/systemd/system`, the case `assertUnshadowed` exists for. */
+const placePlainUnit = (fake: ReturnType<typeof fakeQuadletHost>) =>
+  fake.placeUnit(PLAIN_UNIT_PATH, '[Service]\nExecStart=/usr/bin/true\n', { active: true });
+
+describe('a plain unit already answers to the name, and our .container file is absent', () => {
+  test('the read refuses instead of reporting the container exists', async () => {
+    const fake = fakeQuadletHost();
+    placePlainUnit(fake);
+    await expect(readContainer(fake.runner, props)).rejects.toThrow(PLAIN_UNIT_PATH);
+  });
+
+  test('the refusal names Podman.Container, the unit and the fix — not a generic crash', async () => {
+    const fake = fakeQuadletHost();
+    placePlainUnit(fake);
+    await expect(readContainer(fake.runner, props)).rejects.toThrow(
+      /Podman\.Container hf-example:.*hf-example\.service.*plain unit.*move the plain unit aside/is,
+    );
+  });
+
+  test('nothing was written before the refusal — a plan promises this, it never risks it', async () => {
+    const fake = fakeQuadletHost();
+    placePlainUnit(fake);
+    await expect(readContainer(fake.runner, props)).rejects.toThrow();
+    expect(fake.files.has(PATH)).toBe(false);
+  });
+});
+
+describe('a masked unit keeps its own, more specific refusal', () => {
+  test('the read does not report it as a shadowing plain unit', async () => {
+    const fake = fakeQuadletHost();
+    fake.placeUnit(PLAIN_UNIT_PATH, '[Service]\nExecStart=/usr/bin/true\n', {
+      active: false,
+      masked: true,
+    });
+    // Masked still has a real FragmentPath on this fake (measured directly — see
+    // container-preflight.ts's `assertUnshadowed`), so this proves the exemption, not an absence.
+    const attrs = await readContainer(fake.runner, props);
+    expect(attrs).toMatchObject({ loadState: 'masked', name: NAME });
+  });
+
+  test('adopting it still refuses, with the masked message, not the shadow one', async () => {
+    const fake = fakeQuadletHost();
+    fake.placeUnit(PLAIN_UNIT_PATH, '[Service]\nExecStart=/usr/bin/true\n', {
+      active: false,
+      masked: true,
+    });
+    await expect(reconcileContainer(fake.runner, props, undefined, true)).rejects.toThrow(
+      /is masked/,
+    );
+  });
+});
+
+describe('a real Quadlet generation is unaffected', () => {
+  test('FragmentPath under the generator directory still reads as existing', async () => {
+    const fake = fakeQuadletHost();
+    await reconcileContainer(fake.runner, props, undefined);
+    // The source file is gone but the LAST generation is still on disk, unreloaded — exactly what
+    // a manual `rm` of the `.container` file leaves behind before the next `daemon-reload`.
+    fake.files.delete(PATH);
+    const attrs = await readContainer(fake.runner, props);
+    expect(attrs).toMatchObject({ containerPath: PATH, name: NAME, serviceName: SERVICE });
+  });
+});
+
+describe('neither a file nor a unit exists', () => {
+  test('read answers undefined, so a plan says create — never a refusal', async () => {
+    const fake = fakeQuadletHost();
+    expect(await readContainer(fake.runner, props)).toBeUndefined();
+  });
+});
+
+/**
+ * ⛔ REGRESSION FOR A FALSE POSITIVE — found on adversarial review. An earlier version of
+ *   `assertUnshadowed` refused for ANY `FragmentPath` not literally under the generator directory,
+ *   including a vendor unit at `/usr/lib/systemd/system` — which is LOWER precedence than
+ *   Quadlet's generator (`isShadowingFragment`, container-generator.ts, has the measured order), so
+ *   writing and reloading our `.container` file would actually win the name, same as any other
+ *   cutover from a package-installed daemon to a Podman container. Refusing there blocked exactly
+ *   the create/adopt an apply would have handled fine.
+ */
+describe('a plain unit at a directory LOWER precedence than the generator is not a shadow', () => {
+  test('a vendor unit at /usr/lib/systemd/system does not refuse — it reads as adopted', async () => {
+    const fake = fakeQuadletHost();
+    fake.placeUnit(`/usr/lib/systemd/system/${SERVICE}`, '[Service]\nExecStart=/usr/bin/true\n', {
+      active: true,
+    });
+    const attrs = await readContainer(fake.runner, props);
+    expect(attrs).toMatchObject({ name: NAME, serviceName: SERVICE });
+  });
+
+  test('a vendor unit at /usr/local/lib/systemd/system does not refuse either', async () => {
+    const fake = fakeQuadletHost();
+    fake.placeUnit(
+      `/usr/local/lib/systemd/system/${SERVICE}`,
+      '[Service]\nExecStart=/usr/bin/true\n',
+      { active: true },
+    );
+    const attrs = await readContainer(fake.runner, props);
+    expect(attrs).toMatchObject({ name: NAME, serviceName: SERVICE });
+  });
+});

package/src/linux/fake-sudo.ts

@@ -12,10 +12,15 @@
  *   `mktemp -d` registers a fresh 0700 directory the operator owns.
  * ★ SUDO REFUSES A CALL THAT WAS NOT LOGGED FIRST, so every test holds the runner to "logged
  *   before it runs", exactly as the Mac fake does.
+ * ★ `hostFactory`/`prefixes` (below) let sudo-lifecycle.test.ts drive `fakeQuadletHost` (not just
+ *   the plain `fakeLinuxHost`) through this SAME elevation wiring, for the Podman.Container-through
+ *   -sshSudoRunner regression tests — `fakeQuadletHost` returns the exact shape `fakeLinuxHost`
+ *   does (`FakeLinuxOptions` in, the same fields out), so every handler below that reads
+ *   `fake.dirs`/`fake.modes`/`fake.files` or calls `fake.runner.exec` works unchanged either way.
  */
 import type { ExecResult, FileStat, HostRunner } from '../launchd/runner.ts';
 import { SUDO_SAYS } from '../launchd/fake-sudo.ts';
-import { fakeLinuxHost } from './fake-linux-host.ts';
+import { type FakeLinuxOptions, fakeLinuxHost } from './fake-linux-host.ts';
 import { type RootState, asRoot } from './fake-sudo-root.ts';
 import { SUDO } from './sudo-allowlist.ts';
 import { makeSshSudoRunner } from './sudo-runner.ts';
@@ -49,17 +54,28 @@ const lsLine = (path: string, stat: FileStat, acl: boolean): string => {
   );
 };
 
+export type FakeSudoHostOptions = {
+  /** Swap `fakeLinuxHost` for a variant that models more than plain units — `fakeQuadletHost`. */
+  readonly hostFactory?: (options: FakeLinuxOptions) => ReturnType<typeof fakeLinuxHost>;
+  /** The runner's own declared prefixes. @default PREFIXES */
+  readonly prefixes?: readonly string[];
+};
+
 /**
  * `extraDirs` adds more directories to the fake filesystem (a pre-existing tree outside every
- * prefix, say); it never changes the runner's OWN prefixes, which stay `PREFIXES` throughout.
+ * prefix, say); it never changes the runner's OWN prefixes, which default to `PREFIXES`.
  * `acl` is the set of directory paths a test wants to carry the `+` (POSIX ACL) flag.
  */
 export const fakeSudoHost = (
   extraDirs: Record<string, number> = {},
   acl: ReadonlySet<string> = new Set(),
+  { hostFactory = fakeLinuxHost, prefixes = PREFIXES }: FakeSudoHostOptions = {},
 ) => {
-  const fake = fakeLinuxHost({
-    dirs: { '/etc/systemd/system': 0, '/usr/local/bin': 0, ...extraDirs },
+  const dirs: Record<string, number> = {};
+  for (const prefix of prefixes) dirs[prefix] = 0;
+  for (const [path, owner] of Object.entries(extraDirs)) dirs[path] = owner;
+  const fake = hostFactory({
+    dirs,
     euid: OPERATOR,
     users: { app: { gid: 60, home: '/opt/app', uid: 900 } },
   });
@@ -127,7 +143,7 @@ export const fakeSudoHost = (
     },
   };
 
-  const runner = makeSshSudoRunner(PREFIXES, {
+  const runner = makeSshSudoRunner(prefixes, {
     base,
     log: (line) => logs.push(line),
     // ★ The real stager, unmodified: it only ever calls `base.exec`/`base.writeFileAtomic`, both

package/src/linux/sudo-exec.ts

@@ -23,13 +23,44 @@
  *   is a valid type in `unit-form.ts`'s `TYPES` set) would also have elevated. Grepped: no code
  *   in this package ever calls `enable`/`start`/`restart` on a unit it has not itself just
  *   written a file for, so narrowing the exemption to `stop`/`disable` costs nothing legitimate.
+ * 🔴 MEASURED, CT100 deploy 2026-09-26 00:11Z: a THIRD gap, this one refusing a call that should
+ *   have been allowed. `Podman.Container caddy`'s generated `caddy.service` has
+ *   `FragmentPath=/run/systemd/generator/caddy.service` — Quadlet's generator output, never a
+ *   path this runner would ever declare as a prefix (nothing writes there directly) — so `restart`
+ *   was refused outright, even though the `.container` FILE THAT GENERATED IT lives at
+ *   `/etc/containers/systemd/caddy.container`, squarely under this runner's own
+ *   `/etc/containers/systemd` prefix, and this SAME runner had just written it. `SourcePath` is
+ *   the generator's own record of that file (systemctl.ts's header, MEASURED on CT100). So a
+ *   generated unit is now also reachable when its `FragmentPath` is the generator's OWN output
+ *   directory (`GENERATOR_DIRECTORIES` below) AND its `SourcePath` is under a declared prefix —
+ *   the thing this runner actually owns is the `.container` file, and the generated unit is
+ *   systemd's own derivative of it, not a foreign unit. Everything the check refused before still
+ *   refuses: a vendor unit's `FragmentPath` (`/usr/lib/systemd/system/...`) is not under a
+ *   generator directory at all; a generated unit with no `SourcePath`, or one outside every
+ *   prefix (a `.container` file elsewhere in Quadlet's OWN search path —
+ *   `podman-systemd.unit(5)` — that this runner was never told to own), still refuses.
  */
 import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+import { GENERATED_UNIT_DIRECTORY } from './container-generator.ts';
 import { SYSTEMCTL_ABS, SudoRefusedError, canonicalize, prefixOf } from './sudo-allowlist.ts';
 import { type ChainExpect, assertGuardedChain } from './sudo-guard.ts';
 import type { Elevate } from './sudo-write.ts';
 import { parseShow } from './systemctl.ts';
 
+/**
+ * ★ ONLY THE `.late` VARIANT ADDED — `container-generator.ts`'s own header names it as part of
+ *   systemd's real Unit File Load Path; `.early` is not named anywhere in this repo and no
+ *   generator this family drives (Quadlet writes only the base directory) uses it, so it stays
+ *   out rather than widen the check on an unmeasured guess.
+ */
+const GENERATOR_DIRECTORIES: readonly string[] = [
+  GENERATED_UNIT_DIRECTORY,
+  `${GENERATED_UNIT_DIRECTORY}.late`,
+];
+
+const isUnderGeneratorDirectory = (fragmentPath: string): boolean =>
+  GENERATOR_DIRECTORIES.some((dir) => fragmentPath.startsWith(`${dir}/`));
+
 const DIR_EXPECT: Readonly<Record<string, ChainExpect>> = {
   chmod: 'directory',
   chown: 'directory',
@@ -43,26 +74,33 @@ const EMPTY_FRAGMENT_OK: ReadonlySet<string> = new Set(['stop', 'disable']);
 const unitStatusOf = async (
   base: HostRunner,
   unit: string,
-): Promise<{ readonly fragmentPath: string; readonly loadState: string }> => {
+): Promise<{
+  readonly fragmentPath: string;
+  readonly loadState: string;
+  readonly sourcePath: string;
+}> => {
   const result = await base.exec([
     SYSTEMCTL_ABS,
     'show',
     '--no-pager',
     '-p',
-    'FragmentPath,LoadState',
+    // ★ SourcePath added for the Quadlet-generated-unit exception below — same property
+    //   systemctl.ts's own `showUnit` already reads for `Podman.Container`.
+    'FragmentPath,LoadState,SourcePath',
     '--',
     unit,
   ]);
   if (result.exitCode !== 0) {
     throw new SudoRefusedError(
-      `sshSudoRunner ${unit}: could not read FragmentPath/LoadState (systemctl show exit ` +
-        `${String(result.exitCode)}). Nothing ran as root.`,
+      `sshSudoRunner ${unit}: could not read FragmentPath/LoadState/SourcePath (systemctl show ` +
+        `exit ${String(result.exitCode)}). Nothing ran as root.`,
     );
   }
   const fields = parseShow(result.stdout);
   return {
     fragmentPath: fields.get('FragmentPath') ?? '',
     loadState: fields.get('LoadState') ?? '',
+    sourcePath: fields.get('SourcePath') ?? '',
   };
 };
 
@@ -93,7 +131,7 @@ export const elevatedExec = (
   const verb = canonical[1] ?? '';
   const unit = canonical[3] ?? '';
   return elevate(canonical, {}, async () => {
-    const { fragmentPath, loadState } = await unitStatusOf(base, unit);
+    const { fragmentPath, loadState, sourcePath } = await unitStatusOf(base, unit);
     if (loadState === 'masked') {
       throw new SudoRefusedError(
         `sshSudoRunner ${unit}: is masked. Masking is someone's decision, not drift; unmask it ` +
@@ -108,11 +146,23 @@ export const elevatedExec = (
           `${unit} is (a kernel-generated unit, say). Nothing ran as root.`,
       );
     }
-    if (prefixOf(fragmentPath, prefixes) === undefined) {
-      throw new SudoRefusedError(
-        `sshSudoRunner ${unit}: FragmentPath ${fragmentPath} is outside every declared prefix ` +
-          `(${prefixes.join(', ')}); refusing to touch a unit this runner does not own. Nothing ran as root.`,
-      );
+    if (prefixOf(fragmentPath, prefixes) !== undefined) return;
+    // ⛔ THE QUADLET CASE — see this file's header. A generator's OWN output directory is never a
+    //   prefix, so this is not "found it under a prefix, done" — it is "found it under the
+    //   generator, so check what GENERATED it instead."
+    if (
+      isUnderGeneratorDirectory(fragmentPath) &&
+      sourcePath !== '' &&
+      prefixOf(sourcePath, prefixes) !== undefined
+    ) {
+      return;
     }
+    const sourceNote =
+      sourcePath === '' ? '' : `, and its SourcePath ${sourcePath} is not under one either`;
+    throw new SudoRefusedError(
+      `sshSudoRunner ${unit}: FragmentPath ${fragmentPath} is outside every declared prefix ` +
+        `(${prefixes.join(', ')})${sourceNote}; refusing to touch a unit this runner does not ` +
+        'own. Nothing ran as root.',
+    );
   });
 };