@homeflare/alchemy 0.37.7 → 0.37.8

package/dist/linux/sudo-exec.d.ts

@@ -23,6 +23,22 @@
  *   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 type { Elevate } from './sudo-write.ts';

package/dist/linux/sudo-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sudo-exec.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAuC/C,iGAAiG;AACjG,eAAO,MAAM,YAAY,SACjB,UAAU,WACP,OAAO,YACN,SAAS,MAAM,EAAE,QACrB,SAAS,MAAM,EAAE,KACtB,OAAO,CAAC,UAAU,CA2CpB,CAAC"}
+{"version":3,"file":"sudo-exec.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAInE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AA4D/C,iGAAiG;AACjG,eAAO,MAAM,YAAY,SACjB,UAAU,WACP,OAAO,YACN,SAAS,MAAM,EAAE,QACrB,SAAS,MAAM,EAAE,KACtB,OAAO,CAAC,UAAU,CAuDpB,CAAC"}

package/dist/linux/unit-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unit-form.d.ts","sourceRoot":"","sources":["../../src/linux/unit-form.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,WAAW,GAAG;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,YAClC,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,yBAAyB,EACzB,qBAAqB,CACb,CAAC;AAEX,mGAAmG;AACnG,eAAO,MAAM,UAAU;aAAK,GAAG,EAAE,CAAC;aAAE,IAAI,EAAE,GAAK;aAAE,GAAG,EAAE,CAAC;CAAW,CAAC;AAEnE,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAmD,CAAC;AAE5F,4FAA4F;AAC5F,eAAO,MAAM,YAAY,cAAe,SAAS,MAAM,EAAE,GAAG,SAAS,KAAG,MAChC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,aAAa,gBACX,MAAM,YACT,MAAM,GAAG,SAAS,WACnB,OAAO,KACf,OAKF,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,UAAU,aAAc,SAAS,WAAW,EAAE,KAAG,MAKzC,CAAC;AAEtB,eAAO,MAAM,QAAQ,UAAW,gBAAgB,KAAG,MACA,CAAC;AAEpD,eAAO,MAAM,WAAW,UAAW,gBAAgB,KAAG,MACQ,CAAC;AAE/D,mGAAmG;AACnG,eAAO,MAAM,IAAI,QAA6C,CAAC;AAkB/D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,UAAW,gBAAgB,WAAW,MAAM,KAAG,MAAM,EAmC7E,CAAC"}
+{"version":3,"file":"unit-form.d.ts","sourceRoot":"","sources":["../../src/linux/unit-form.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,WAAW,GAAG;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,YAClC,qBAAqB,EACrB,qBAAqB,EACrB,+BAA+B,EAC/B,yBAAyB,EACzB,qBAAqB,CACb,CAAC;AAEX,mGAAmG;AACnG,eAAO,MAAM,UAAU;aAAK,GAAG,EAAE,CAAC;aAAE,IAAI,EAAE,GAAK;aAAE,GAAG,EAAE,CAAC;CAAW,CAAC;AAEnE,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAmD,CAAC;AAE5F,4FAA4F;AAC5F,eAAO,MAAM,YAAY,cAAe,SAAS,MAAM,EAAE,GAAG,SAAS,KAAG,MAChC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,aAAa,gBACX,MAAM,YACT,MAAM,GAAG,SAAS,WACnB,OAAO,KACf,OAKF,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,UAAU,aAAc,SAAS,WAAW,EAAE,KAAG,MAKzC,CAAC;AAEtB,eAAO,MAAM,QAAQ,UAAW,gBAAgB,KAAG,MACA,CAAC;AAEpD,eAAO,MAAM,WAAW,UAAW,gBAAgB,KAAG,MACQ,CAAC;AAE/D,mGAAmG;AACnG,eAAO,MAAM,IAAI,QAA6C,CAAC;AAgB/D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,UAAW,gBAAgB,WAAW,MAAM,KAAG,MAAM,EAmC7E,CAAC"}

package/dist/linux/unit-text.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The parts of `unit-form.ts`'s validation that inspect the unit file's TEXT rather than its
+ * props struct — split out so unit-form.ts stays under the file cap, and because these are one
+ * coherent concern: is this INI shape something systemd would actually load. Takes plain strings,
+ * never `SystemdUnitProps`, so it never needs to import back from unit-form.ts.
+ *
+ * ⛔ `[Install]` KEYS ARE `unit-form.ts`'s OWN LIST, NOT SYSTEMD'S FULL VOCABULARY — WantedBy,
+ *   RequiredBy, UpsertedBy, Also, Alias, per `systemd.unit(5)` §[Install]. `container-form.ts`'s
+ *   own header notes it deliberately does NOT reuse this set: a `.container` file's `[Install]`
+ *   supports only Alias/WantedBy/RequiredBy (`podman-systemd.unit(5)`), narrower than this.
+ */
+export declare const INSTALL_KEYS: Set<string>;
+/** Whether `text` has an `[Install]` section carrying at least one key systemd actually links on. */
+export declare const hasInstallSection: (text: string) => boolean;
+/**
+ * The first line that is neither blank nor a comment — the line whose shape actually decides
+ * whether the file "begins with a [Section]", per `textProblems` below.
+ * ★ systemd.syntax(7): "Empty lines and lines starting with '#' or ';' are ignored", with no
+ *   carve-out for the position before the first section — a comment header is ordinary content
+ *   there, same as anywhere else in the file.
+ */
+export declare const firstSubstantiveLine: (text: string) => string | undefined;
+/**
+ * 🔴 MEASURED FALSE, CT100 deploy 2026-09-26 00:11Z: the openbao-agent.service asset's first eight
+ *   lines are `#`-comments recording where the file was recovered from (verbatim from the live
+ *   host — homeflare-ct100's `src/openbao-agent/files/openbao-agent.service`), and the file is
+ *   byte-identical to what systemd already loads there. The old check tested the WHOLE text
+ *   against `/^\s*\[[A-Za-z]+]/` — `\s*` skips blank lines and indentation, never a `#`/`;`
+ *   comment — so a leading comment line failed it outright. This checks only the first
+ *   SUBSTANTIVE line, so any number of leading blank lines and comments are fine and a genuine
+ *   `key=value` before any section — the one real error this exists to catch — still fails, since
+ *   that line is neither blank nor a comment either.
+ */
+export declare const textProblems: (text: string) => string[];
+//# sourceMappingURL=unit-text.d.ts.map

package/dist/linux/unit-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-text.d.ts","sourceRoot":"","sources":["../../src/linux/unit-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,YAAY,aAAqE,CAAC;AAE/F,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,SAAU,MAAM,KAAG,OAIhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,SAAU,MAAM,KAAG,MAAM,GAAG,SAG6B,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,MAAM,EAajD,CAAC"}

package/docs/linux-sudo.md

@@ -76,15 +76,26 @@ Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path.
 `enable`/`disable`/`start`/`stop`/`restart` elevate only when the unit is not
 **masked** (`LoadState`, read alongside `FragmentPath` in the same call —
 masking is someone's decision, never overridden here) and its **own
-`FragmentPath`** is either under a declared prefix, or empty AND the verb is
+`FragmentPath`** is either under a declared prefix, empty AND the verb is
 `stop`/`disable` — the only two `unit-lifecycle.ts` `deleteUnit` ever sends
 against a unit whose file it may just have removed, so a second, idempotent
-delete pass still works. `enable`/`start`/`restart` with an empty
-`FragmentPath` are refused, closing a kernel-generated pseudo-unit
-(`init.scope`, a `session-N.scope`) as a target. A vendor unit like
-`pveproxy.service`, whose `FragmentPath` is `/usr/lib/systemd/system/…`, is
-refused before sudo ever runs: this runner cannot touch what it did not
-declare. `--user`, `--global`, `-H`, `-M` and `--root` are refused outright,
+delete pass still works — **or a systemd GENERATOR's own output** (measured,
+CT100 deploy 2026-09-26: `/run/systemd/generator`, and `.late`) **whose
+`SourcePath` is under a declared prefix.** That is exactly `Podman.Container`:
+Quadlet's generator writes `caddy.service`'s `FragmentPath` under
+`/run/systemd/generator`, never a path this runner would declare, but stamps
+`SourcePath` with the `.container` file that produced it — the thing this
+runner actually wrote, under `/etc/containers/systemd`. `SourcePath` is read
+in the same `systemctl show` as `FragmentPath`/`LoadState`, so no extra host
+round trip. A generated unit with no `SourcePath`, or one outside every
+prefix (a `.container` file elsewhere in Quadlet's OWN search path this
+runner was never told to own), still refuses. `enable`/`start`/`restart`
+with an empty `FragmentPath` are refused, closing a kernel-generated
+pseudo-unit (`init.scope`, a `session-N.scope`) as a target. A vendor unit
+like `pveproxy.service`, whose `FragmentPath` is `/usr/lib/systemd/system/…`
+— not a generator directory — is refused before sudo ever runs: this runner
+cannot touch what it did not declare, directly or through a generator.
+`--user`, `--global`, `-H`, `-M` and `--root` are refused outright,
 anywhere in the argv. `directory-lifecycle.ts`'s own `chown` argv is bare
 (`0`, `:0`, `0:0`); `canonicalize()` rewrites it to the `+`-forced form above
 before the allowlist ever sees it, so the unprivileged caller never has to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.37.7",
+  "version": "0.37.8",
   "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",

package/src/linux/container-form.ts

@@ -18,7 +18,7 @@
  *   or renders that file's contents.
  * ⛔ `[Install]` SUPPORTS ONLY `Alias=`/`WantedBy=`/`RequiredBy=` FOR A `.container` FILE (same doc,
  *   "Currently, only the Alias, WantedBy and RequiredBy keys are supported") — NOT `Also=`, which
- *   plain `systemd.unit(5)` allows and unit-form.ts's `INSTALL_KEYS` therefore lists. See
+ *   plain `systemd.unit(5)` allows and unit-text.ts's `INSTALL_KEYS` therefore lists. See
  *   container-generator.ts's header for why there is no `enabled` prop at all.
  */
 import { type UnitSection, configDigest, digestOf, renderUnit } from './unit-form.ts';

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