@homeflare/alchemy 0.55.0 → 0.56.0

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

@@ -31,6 +31,15 @@ export declare const assertGuardedChain: (base: HostRunner, prefix: string, path
  * The mode/owner and read-back checks for a file write under `prefix`, plus the path chain.
  * ★ Reads only, as the operator — the same checks run at plan time (`checkWrite`) and before the
  *   install/mv pair. `expect` is `'file-or-absent'`: a write may create or replace.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set (sudo-runner.ts): a file on it
+ *   is read back through `sudo -n base64`, so it cannot be stranded by its own mode — every
+ *   other refusal below applies to it unchanged.
+ * ⛔ A LISTED FILE MAY NEVER BE HANDED TO A NON-ROOT UID, whatever its mode: its read back is
+ *   the elevated one, which refuses anything but a root-owned regular file, so a handoff with
+ *   operator-readable other bits (0644 uid 1001) would sail through the plain read-back check,
+ *   land, and die at EVERY later read — the stranding this guard exists to prevent (glm seat
+ *   round, 2026-10-18). Refused up front instead. An omitted owner is root under a prefix, so
+ *   plain root writes are untouched.
  */
-export declare const assertInstallable: (base: HostRunner, prefix: string, path: string, options: WriteOptions, groups: readonly number[] | undefined) => Promise<void>;
+export declare const assertInstallable: (base: HostRunner, prefix: string, path: string, options: WriteOptions, groups: readonly number[] | undefined, privilegedReads?: ReadonlySet<string>) => Promise<void>;
 //# sourceMappingURL=sudo-guard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sudo-guard.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EACf,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;AAgB5F,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAmB7E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,UAAU,UACR,MAAM,QACR,MAAM,UACJ,WAAW,KAClB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAyC9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SACtB,UAAU,UACR,MAAM,QACR,MAAM,WACH,YAAY,UACb,SAAS,MAAM,EAAE,GAAG,SAAS,KACpC,OAAO,CAAC,IAAI,CAWd,CAAC"}
+{"version":3,"file":"sudo-guard.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,WAAW,EACX,cAAc,EACf,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,CAAC;AAgB5F,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAmB7E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,UAAU,UACR,MAAM,QACR,MAAM,UACJ,WAAW,KAClB,OAAO,CAAC,QAAQ,GAAG,SAAS,CAyC9B,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,SACtB,UAAU,UACR,MAAM,QACR,MAAM,WACH,YAAY,UACb,SAAS,MAAM,EAAE,GAAG,SAAS,oBACnB,WAAW,CAAC,MAAM,CAAC,KACpC,OAAO,CAAC,IAAI,CAsBd,CAAC"}

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

@@ -8,7 +8,9 @@
  *   is the "no silent sudo" failure this exists to prevent.
  * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and a file's bytes never reach argv or the
  *   log: they travel through the staged file (sudo-stage.ts) alone.
- * ⛔ A PLAN NEVER ELEVATES. `checkWrite` and every read run through `base` — the plain
+ * ⛔ A PLAN ELEVATES EXACTLY ONE KIND OF CALL: the `privilegedReads` file's own read (below) —
+ *   the read a plan diff needs on a declared root-owned file. Every other read, and every
+ *   `checkWrite` host probe (`id -G`, `ls`, `stat`), runs through `base` — the plain
  *   `sshRunner()` — never through sudo. Nothing here probes sudo at construction.
  * ★ PROMISES, NOT EFFECTS, ON PURPOSE — the same divergence `../launchd/runner.ts` documents
  *   (H3 in the provider-standard skill): a consumer's own runner is a plain async implementation.

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

@@ -1 +1 @@
-{"version":3,"file":"sudo-runner.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,KAAK,gBAAgB,EAAa,MAAM,iBAAiB,CAAC;AAEnE,OAAO,EAUL,gBAAgB,EAKjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,MAAM,EAAe,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG;IACpD,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AAEF,eAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,WAAW,SAAS,MAAM,EAAE,KAAQ,WAAW,CAAC,MAAM,CActF,CAAC;AAkBF,eAAO,MAAM,iBAAiB,eAAgB,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,UAmFpF,CAAC;AAsBF,gGAAgG;AAChG,eAAO,MAAM,aAAa,YAAmB,oBAAoB,KAAG,OAAO,CAAC,UAAU,CAarF,CAAC"}
+{"version":3,"file":"sudo-runner.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,EAAE,KAAK,gBAAgB,EAAa,MAAM,iBAAiB,CAAC;AAEnE,OAAO,EAUL,gBAAgB,EAKjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,MAAM,EAAe,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG;IACpD,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AAEF,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C,CAAC;AAEF,eAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,WAAW,SAAS,MAAM,EAAE,KAAQ,WAAW,CAAC,MAAM,CActF,CAAC;AAkBF,eAAO,MAAM,iBAAiB,eAAgB,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,UAmFpF,CAAC;AAsBF,gGAAgG;AAChG,eAAO,MAAM,aAAa,YAAmB,oBAAoB,KAAG,OAAO,CAAC,UAAU,CAarF,CAAC"}

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

@@ -11,8 +11,11 @@ export type Elevate = (argv: readonly string[], context?: {
  * Plan-time and write-time share this: valid mode, the path chain, mode/owner refusals and the
  * read-back — everything a write can be refused for before anything is staged or run as root.
  * `undefined` outside every prefix, where the caller falls back to `base` directly.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set: a file on it is read back as
+ *   root (sudo-runner.ts's readFile), so the read-back refusal does not apply to it — the other
+ *   checks in assertInstallable still do.
  */
-export declare const vetWrite: (base: HostRunner, prefixes: readonly string[], path: string, options: WriteOptions) => Promise<{
+export declare const vetWrite: (base: HostRunner, prefixes: readonly string[], path: string, options: WriteOptions, privilegedReads?: ReadonlySet<string>) => Promise<{
     readonly mode: string;
     readonly prefix: string;
 } | undefined>;

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

@@ -1 +1 @@
-{"version":3,"file":"sudo-write.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-write.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,4FAA4F;AAC5F,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MACoC,CAAC;AAgC/E,oGAAoG;AACpG,MAAM,MAAM,OAAO,GAAG,CACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,QAAQ,SACb,UAAU,YACN,SAAS,MAAM,EAAE,QACrB,MAAM,WACH,YAAY,KACpB,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CASxE,CAAC;AAsBF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,SACrB,UAAU,WACP,OAAO,SACT,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,QACvC,MAAM,SACL,UAAU,WACR,YAAY,QACf,MAAM,KACX,OAAO,CAAC,IAAI,CAyCd,CAAC"}
+{"version":3,"file":"sudo-write.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-write.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAK9C,4FAA4F;AAC5F,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MACoC,CAAC;AAgC/E,oGAAoG;AACpG,MAAM,MAAM,OAAO,GAAG,CACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,SACb,UAAU,YACN,SAAS,MAAM,EAAE,QACrB,MAAM,WACH,YAAY,oBACH,WAAW,CAAC,MAAM,CAAC,KACpC,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CASxE,CAAC;AAsBF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,SACrB,UAAU,WACP,OAAO,SACT,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,QACvC,MAAM,SACL,UAAU,WACR,YAAY,QACf,MAAM,KACX,OAAO,CAAC,IAAI,CAyCd,CAAC"}

package/docs/linux-sudo-review-2026-09-23.md

@@ -0,0 +1,27 @@
+# The 2026-09-23 adversarial review of the linux sudo runner
+
+Extracted from [linux-sudo.md](./linux-sudo.md) to keep that doc under the 200-line
+cap. The findings it records are live rules of the runner, not history.
+
+🔴 **Adversarial review, 2026-09-23, two rounds — everything found is fixed
+and tested.** Round 1: a directory this runner elevates was checked for
+SHAPE only, never mode or owner. `mkdir -m 0777` and `chown <non-root uid>`
+both passed untouched, so a stack could declare `HostDirectory({ path:
+'/etc/systemd/system/x.service.d', mode: 0o777 })`, drop an `ExecStart=`
+override into it, and this runner's own next `daemon-reload` + `restart`
+would run it as root. Fixed: a directory this runner elevates is now always
+root-owned and never setuid/setgid or group/other-writable, unconditionally
+— a directory's OWNER always has write access through the owner bits alone,
+so no mode restriction alone could make a non-root-owned directory safe
+here. The same round tightened the shared `modeProblem` check
+(`../launchd/sudo-guard.ts`, used by both platforms): it exempted a file
+merely because its `uid` was non-root, missing that `{uid: 501, gid: 0,
+mode: 0o2775}` — setgid to root's own group — reaches the same escalation
+through the group instead. Round 2 found the round-1 `modeProblem` fix was
+itself incomplete (an OMITTED `gid`, not just an explicit `0`, defaults to
+root's own group under `install` — see the section above), the masked-unit
+and FragmentPath-scope gaps documented above, `install`'s own numeric-id
+ambiguity (also above), and a swallowed cleanup-`rm` failure (now included
+in the thrown error, with the leftover path named). All covered by tests:
+`sudo-allowlist.test.ts`, `sudo-lifecycle.test.ts`, `sudo-runner.test.ts`,
+`../launchd/sudo-modes.test.ts`.

package/docs/linux-sudo.md

@@ -60,18 +60,19 @@ staging directory is removed either way.
 
 Each is `/usr/bin/sudo -n -- <argv>`, every program by absolute path.
 
-| when                                 | argv                                                                                |
-| ------------------------------------ | ----------------------------------------------------------------------------------- |
-| a file under a prefix — stage→temp   | `/usr/bin/install -m <0644> -T -- <staged> <temp>`                                  |
-| its owner, if not root:root          | `/usr/bin/chown +<uid>[:+<gid>] -- <temp>` — numeric, `+`-forced, bound to `<temp>` |
-| a file under a prefix — temp→dest    | `/usr/bin/mv -f -T -- <temp> <dest>`                                                |
-| a file under a prefix is removed     | `/usr/bin/rm -f -- <path>`                                                          |
-| a directory under a prefix is made   | `/usr/bin/mkdir -m <octal> -- <path>` — never setuid/setgid or group/other-write    |
-| its mode is fixed                    | `/usr/bin/chmod <octal> -- <path>` — same restriction                               |
-| its owner is fixed                   | `/usr/bin/chown <owner> -- <path>` — **root only**: `+0`, `:+0` or `+0:+0`          |
-| it is removed                        | `/usr/bin/rmdir -- <path>`                                                          |
-| after any unit-file write/removal    | `/usr/bin/systemctl daemon-reload`                                                  |
-| a unit is enabled/disabled/started/… | `/usr/bin/systemctl <verb> -- <unit>`                                               |
+| when                                 | argv                                                                                          |
+| ------------------------------------ | --------------------------------------------------------------------------------------------- |
+| a file under a prefix — stage→temp   | `/usr/bin/install -m <0644> -T -- <staged> <temp>`                                            |
+| its owner, if not root:root          | `/usr/bin/chown +<uid>[:+<gid>] -- <temp>` — numeric, `+`-forced, bound to `<temp>`           |
+| a file under a prefix — temp→dest    | `/usr/bin/mv -f -T -- <temp> <dest>`                                                          |
+| a file under a prefix is removed     | `/usr/bin/rm -f -- <path>`                                                                    |
+| a directory under a prefix is made   | `/usr/bin/mkdir -m <octal> -- <path>` — never setuid/setgid or group/other-write              |
+| its mode is fixed                    | `/usr/bin/chmod <octal> -- <path>` — same restriction                                         |
+| its owner is fixed                   | `/usr/bin/chown <owner> -- <path>` — **root only**: `+0`, `:+0` or `+0:+0`                    |
+| it is removed                        | `/usr/bin/rmdir -- <path>`                                                                    |
+| after any unit-file write/removal    | `/usr/bin/systemctl daemon-reload`                                                            |
+| a unit is enabled/disabled/started/… | `/usr/bin/systemctl <verb> -- <unit>`                                                         |
+| a `privilegedReads` file is read     | `/usr/bin/base64 -- <path>` — exact listed path, root-owned regular file, or the read refuses |
 
 `enable`/`disable`/`start`/`stop`/`restart` elevate only when the unit is not
 **masked** (`LoadState`, read alongside `FragmentPath` in the same call —
@@ -103,7 +104,7 @@ know that syntax exists.
 
 ## What stays as the operator
 
-- Every read: `stat`, `readFile`, user/group lookups, `systemctl show`.
+- Every read: `stat`, `readFile`, user/group lookups, `systemctl show` — with one exact exception: a file on the runner's `privilegedReads` list is read with `sudo -n base64` (the plan-diff read a declared root-owned file needs; see the table above). Every other path, and every `checkWrite` host probe (`id -G`, `ls`, `stat`), stays the operator's own.
 - `checkWrite` — the plan-time half of a write, run at every plan so a
   refusal surfaces before any resource is applied, never at the write.
 - Files and directories outside every prefix (a foreign owner there is a
@@ -111,10 +112,11 @@ know that syntax exists.
 - `ls -ldn` and `mktemp -d` — the guard's chain read and the write's own
   staging, both unprivileged (`src/linux/sudo-listing.ts`, `sudo-stage.ts`).
 
-★ **So a plan never calls sudo**, and construction never does either:
-`sshSudoRunner()` runs one combined, read-only `test -x` for the nine
-absolute programs above, so a missing coreutils package or a systemd-free
-container fails with a clear message at construction — never a sudo probe.
+★ **So a plan calls sudo for exactly one thing** — reading a `privilegedReads`
+file — and construction never does: `sshSudoRunner()` runs one combined,
+read-only `test -x` for the nine absolute programs above, so a missing
+coreutils package or a systemd-free container fails with a clear message at
+construction — never a sudo probe.
 
 ## The host guard
 
@@ -144,31 +146,17 @@ prefix-sibling (`/usr/local/bin-x` is not under `/usr/local/bin`), or a
 `chown` by name, a bare digit, or any non-root id; `systemctl mask`/`--user`;
 a masked unit, any verb; `enable`/`start`/`restart` on a unit with no unit
 file; a root-owned file that would be group- or world-writable, setuid or
-setgid; a file the operator could not read back (both `Systemd.Unit` and
-`Remote.File` read every write back to compare digests).
+setgid; a file NOT on the `privilegedReads` list that the operator could not
+read back (both `Systemd.Unit` and `Remote.File` read every write back to
+compare digests); a listed file handed to a non-root uid, whatever its mode
+— the elevated read-back refuses anything but a root-owned regular file, so
+the handoff would land and then fail every read.
 
 🔴 **Adversarial review, 2026-09-23, two rounds — everything found is fixed
-and tested.** Round 1: a directory this runner elevates was checked for
-SHAPE only, never mode or owner. `mkdir -m 0777` and `chown <non-root uid>`
-both passed untouched, so a stack could declare `HostDirectory({ path:
-'/etc/systemd/system/x.service.d', mode: 0o777 })`, drop an `ExecStart=`
-override into it, and this runner's own next `daemon-reload` + `restart`
-would run it as root. Fixed: a directory this runner elevates is now always
-root-owned and never setuid/setgid or group/other-writable, unconditionally
-— a directory's OWNER always has write access through the owner bits alone,
-so no mode restriction alone could make a non-root-owned directory safe
-here. The same round tightened the shared `modeProblem` check
-(`../launchd/sudo-guard.ts`, used by both platforms): it exempted a file
-merely because its `uid` was non-root, missing that `{uid: 501, gid: 0,
-mode: 0o2775}` — setgid to root's own group — reaches the same escalation
-through the group instead. Round 2 found the round-1 `modeProblem` fix was
-itself incomplete (an OMITTED `gid`, not just an explicit `0`, defaults to
-root's own group under `install` — see the section above), the masked-unit
-and FragmentPath-scope gaps documented above, `install`'s own numeric-id
-ambiguity (also above), and a swallowed cleanup-`rm` failure (now included
-in the thrown error, with the leftover path named). All covered by tests:
-`sudo-allowlist.test.ts`, `sudo-lifecycle.test.ts`, `sudo-runner.test.ts`,
-`../launchd/sudo-modes.test.ts`.
+and tested** — the full record (the directory shape-only gap, the shared `modeProblem`
+escapes, the omitted-`gid` default, the masked-unit and `FragmentPath` scope gaps,
+`install`'s numeric-id ambiguity, the swallowed cleanup failure) lives in
+[linux-sudo-review-2026-09-23.md](./linux-sudo-review-2026-09-23.md).
 
 Every refusal throws `SudoRefusedError`: nothing ran as root. A privileged
 command that ran and failed throws a plain `Error` with its exit code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.55.0",
+  "version": "0.56.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",

package/src/launchd/sudo-guard-mode.ts

@@ -72,9 +72,15 @@ export const canRead = (
 /**
  * ⛔ REFUSE A FILE THE DEPLOYING USER COULD NOT READ BACK, before writing it. Both providers read
  *   every write back to verify it (host-file-lifecycle.ts, job-lifecycle.ts) and read it again at
- *   every plan, as the deploying user; this runner elevates writes, never reads. A root-only
- *   `0600` would be installed, then fail the read-back with EACCES and stay on disk with no state,
- *   so every later plan would fail too.
+ *   every plan, as the deploying user; a runner that elevates writes but no reads strands a
+ *   root-only `0600` on disk — installed, failing the read-back with EACCES, with no state, so
+ *   every later plan would fail too.
+ * ★ `readAsRoot` IS THE ONE EXCEPTION, and it is not this guard's to grant: the caller passes it
+ *   only when the RUNNER reads this exact path back through a privileged read (the linux
+ *   sshSudoRunner's `privilegedReads` list names the file, so its readFile goes through
+ *   `sudo -n base64`). The read-back then cannot fail with EACCES whatever the mode is, and the
+ *   refusal would be false; every other check — setuid/setgid, group-writable, the path chain —
+ *   still applies to that file exactly as before.
  * ★ An omitted owner is root (under a prefix the runner writes as root). An omitted group is the
  *   parent directory's, which is the group a new file gets on macOS.
  * ⚠️ Unknown groups never refuse: the read-back after the write stays the final judge.
@@ -84,7 +90,9 @@ export const assertReadableBack = async (
   path: string,
   options: WriteOptions,
   groups: readonly number[] | undefined,
+  readAsRoot = false,
 ): Promise<void> => {
+  if (readAsRoot) return;
   const operator = base.effectiveUid();
   const parent = path.slice(0, path.lastIndexOf('/')) || '/';
   const gid = options.gid ?? (await base.stat(parent))?.gid ?? 0;

package/src/linux/fake-sudo-root.ts

@@ -13,6 +13,7 @@
  *   separate "staged bytes" side-channel to model, unlike the Mac fake's local temp files.
  */
 import type { ExecResult, FileStat } from '../launchd/runner.ts';
+import { BASE64 } from './sudo-runner.ts';
 import { CHMOD, CHOWN, INSTALL, MKDIR, MV, RM, RMDIR, SYSTEMCTL_ABS } from './sudo-allowlist.ts';
 import type { fakeLinuxHost } from './fake-linux-host.ts';
 
@@ -113,6 +114,20 @@ const fileRoot = (
     if (path !== undefined) fake.files.delete(path);
     return ok();
   }
+  /**
+   * ★ `sudo -n base64 -- <path>` — the elevated read itself (sudo-runner.ts's readFile), so a
+   *   test can join the two halves: a hidden-mode file just written through the skipped guard
+   *   reads back AS ROOT here, never EACCES. Refuses exactly what the runner's own pre-elevation
+   *   check refuses: a root-owned REGULAR file, nothing else.
+   */
+  if (program === BASE64) {
+    const [, path] = args;
+    const entry = path === undefined ? undefined : fake.files.get(path);
+    if (entry === undefined || entry.kind !== 'file' || entry.uid !== 0) {
+      return fail(1, `base64: '${String(path)}': No such file or directory`);
+    }
+    return ok(`${Buffer.from(entry.bytes).toString('base64')}\n`);
+  }
   return undefined;
 };
 

package/src/linux/fake-sudo.ts

@@ -59,6 +59,14 @@ export type FakeSudoHostOptions = {
   readonly hostFactory?: (options: FakeLinuxOptions) => ReturnType<typeof fakeLinuxHost>;
   /** The runner's own declared prefixes. @default PREFIXES */
   readonly prefixes?: readonly string[];
+  /** The runner's exact-path elevated reads (`sshSudoRunner`'s `privilegedReads`). */
+  readonly privilegedReads?: readonly string[];
+  /**
+   * What `/usr/bin/id -G` answers (sudo-guard-mode.ts's `operatorGroups`). Unset, the fake has
+   * no `id` and `operatorGroups` reads `undefined` — "unknown groups never refuse" — which is
+   * what every pre-existing test relied on; set it to make the read-back refusal decidable.
+   */
+  readonly operatorGroups?: readonly number[];
 };
 
 /**
@@ -69,7 +77,12 @@ export type FakeSudoHostOptions = {
 export const fakeSudoHost = (
   extraDirs: Record<string, number> = {},
   acl: ReadonlySet<string> = new Set(),
-  { hostFactory = fakeLinuxHost, prefixes = PREFIXES }: FakeSudoHostOptions = {},
+  {
+    hostFactory = fakeLinuxHost,
+    prefixes = PREFIXES,
+    privilegedReads,
+    operatorGroups: idGroups,
+  }: FakeSudoHostOptions = {},
 ) => {
   const dirs: Record<string, number> = {};
   for (const prefix of prefixes) dirs[prefix] = 0;
@@ -131,6 +144,11 @@ export const fakeSudoHost = (
         return handleMktemp();
       }
       if (argv[0] === 'rm' || argv[0] === '/usr/bin/rm') return handleRm(argv);
+      // ★ Only modelled when a test asks for it: unset, `id` stays unknown and the read-back
+      //   guard keeps its "unknown groups never refuse" behavior (see the option's docs).
+      if (argv[0] === '/usr/bin/id' && argv[1] === '-G' && idGroups !== undefined) {
+        return ok(`${idGroups.join(' ')}\n`);
+      }
       if (argv[0] === '/usr/bin/systemctl')
         return fake.runner.exec(['systemctl', ...argv.slice(1)]);
       if (argv[0] !== SUDO) return fake.runner.exec(argv);
@@ -146,6 +164,7 @@ export const fakeSudoHost = (
   const runner = makeSshSudoRunner(prefixes, {
     base,
     log: (line) => logs.push(line),
+    ...(privilegedReads === undefined ? {} : { privilegedReads }),
     // ★ The real stager, unmodified: it only ever calls `base.exec`/`base.writeFileAtomic`, both
     //   of which this fake's `mktemp`/`ls`/operator-level paths already answer.
     stage: stageRemote(base),

package/src/linux/sudo-guard.ts

@@ -121,6 +121,15 @@ export const assertGuardedChain = async (
  * The mode/owner and read-back checks for a file write under `prefix`, plus the path chain.
  * ★ Reads only, as the operator — the same checks run at plan time (`checkWrite`) and before the
  *   install/mv pair. `expect` is `'file-or-absent'`: a write may create or replace.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set (sudo-runner.ts): a file on it
+ *   is read back through `sudo -n base64`, so it cannot be stranded by its own mode — every
+ *   other refusal below applies to it unchanged.
+ * ⛔ A LISTED FILE MAY NEVER BE HANDED TO A NON-ROOT UID, whatever its mode: its read back is
+ *   the elevated one, which refuses anything but a root-owned regular file, so a handoff with
+ *   operator-readable other bits (0644 uid 1001) would sail through the plain read-back check,
+ *   land, and die at EVERY later read — the stranding this guard exists to prevent (glm seat
+ *   round, 2026-10-18). Refused up front instead. An omitted owner is root under a prefix, so
+ *   plain root writes are untouched.
  */
 export const assertInstallable = async (
   base: HostRunner,
@@ -128,6 +137,7 @@ export const assertInstallable = async (
   path: string,
   options: WriteOptions,
   groups: readonly number[] | undefined,
+  privilegedReads?: ReadonlySet<string>,
 ): Promise<void> => {
   const mode = modeProblem(options);
   if (mode !== undefined) {
@@ -137,6 +147,17 @@ export const assertInstallable = async (
         'real owner. Nothing ran as root.',
     );
   }
+  const listed = privilegedReads?.has(path) === true;
+  const uid = options.uid ?? 0;
+  if (listed && uid !== 0) {
+    throw refuse(
+      path,
+      `is on the runner's privilegedReads list, so its read back is the elevated one — which ` +
+        `refuses anything but a root-owned regular file. Handing it to uid ${String(uid)} would ` +
+        'land and then fail every read. Keep it root-owned, or take it off the list. Nothing ' +
+        'ran as root.',
+    );
+  }
   await assertGuardedChain(base, prefix, path, 'file-or-absent');
-  await assertReadableBack(base, path, options, groups);
+  await assertReadableBack(base, path, options, groups, listed && uid === 0);
 };

package/src/linux/sudo-runner-privileged-read.test.ts

@@ -4,7 +4,8 @@
  */
 import { describe, expect, test } from 'bun:test';
 import type { FileStat, HostRunner } from '../launchd/runner.ts';
-import { SUDO } from './sudo-allowlist.ts';
+import { CHOWN, INSTALL, SUDO } from './sudo-allowlist.ts';
+import { fakeSudoHost } from './fake-sudo.ts';
 import {
   BASE64,
   SudoRefusedError,
@@ -90,3 +91,110 @@ describe('privilegedReads', () => {
     expect(checkPrivilegedReads([SECRETISH]).has(SECRETISH)).toBe(true);
   });
 });
+
+/**
+ * The write side of the same grant (the /etc/nut convergence, 2026-10-18): a file the runner
+ * reads back as root may be WRITTEN with a mode that hides it from the operator — its read-back
+ * goes through `sudo -n base64`, so it cannot strand itself. Every other refusal (setuid,
+ * group-writable, the path chain) still applies, and an UNLISTED file with the same mode keeps
+ * refusing exactly as before.
+ */
+describe('privilegedReads on the write path', () => {
+  const NUTISH = '/etc/nut/upsd.users';
+  const bytes = new TextEncoder().encode('new bytes\n');
+  const owner = { gid: 113, mode: 0o640, uid: 0 };
+
+  const mk = (options: { readonly listed?: boolean } = {}) =>
+    fakeSudoHost({}, new Set(), {
+      operatorGroups: [1000],
+      prefixes: ['/etc/nut'],
+      ...(options.listed === false ? {} : { privilegedReads: [NUTISH] }),
+    });
+
+  test('plan-time checkWrite passes for the listed 0640 root:nut file, refuses when unlisted', async () => {
+    const { runner } = mk();
+    const unlisted = mk({ listed: false });
+    if (runner.checkWrite === undefined || unlisted.runner.checkWrite === undefined) {
+      throw new Error('sshSudoRunner must expose checkWrite');
+    }
+    await runner.checkWrite(NUTISH, owner);
+    await expect(unlisted.runner.checkWrite(NUTISH, owner)).rejects.toThrow('would hide it');
+  });
+
+  test('writeFileAtomic installs and chowns the listed 0640 root:nut file under the prefix', async () => {
+    const { fake, privileged, runner } = mk();
+    fake.files.set(NUTISH, {
+      bytes: new TextEncoder().encode('old'),
+      gid: 113,
+      kind: 'file',
+      mode: 0o640,
+      uid: 0,
+    });
+    await runner.writeFileAtomic(NUTISH, bytes, owner);
+    const root = privileged();
+    expect(root.some((call) => call[0] === INSTALL)).toBe(true);
+    expect(root.some((call) => call[0] === CHOWN && call[1] === ':+113')).toBe(true);
+    const after = fake.files.get(NUTISH);
+    expect(new TextDecoder().decode(after?.bytes)).toBe('new bytes\n');
+    expect(after?.mode).toBe(0o640);
+    expect(after?.uid).toBe(0);
+    expect(after?.gid).toBe(113);
+    /**
+     * ★ THE JOINED GUARANTEE (deepseek round-2 ask): the file the guard let us write in a mode
+     *   that hides it from the operator reads back AS ROOT through the listed path — never
+     *   EACCES, never the operator's own read. This is the stranding the guard existed to
+     *   prevent, now provably absent end-to-end.
+     */
+    const before = root.length;
+    expect(new TextDecoder().decode(await runner.readFile(NUTISH))).toBe('new bytes\n');
+    expect(privileged()[before]).toEqual([BASE64, '--', NUTISH]);
+  });
+
+  test('an unlisted 0640 write still refuses, and nothing runs as root', async () => {
+    const { privileged, runner } = mk({ listed: false });
+    await expect(runner.writeFileAtomic(NUTISH, bytes, owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('with the set non-empty, a sibling under the same prefix still refuses', async () => {
+    // The skip is set MEMBERSHIP, never a prefix match: with NUTISH listed, its sibling
+    // upsmon.conf — same directory, same shape, same mode — keeps the refusal
+    // (glm round-2 ask, 2026-10-18).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite('/etc/nut/upsmon.conf', owner)).rejects.toThrow('would hide it');
+    expect(privileged()).toEqual([]);
+  });
+
+  test('a listed file still refuses setuid and group-writable modes', async () => {
+    const { runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o4755, uid: 0 })).rejects.toThrow(
+      'setuid/setgid',
+    );
+    await expect(runner.checkWrite(NUTISH, { gid: 0, mode: 0o0660, uid: 0 })).rejects.toThrow(
+      'writable by group',
+    );
+  });
+
+  test('a listed path handed to a non-root uid is refused outright, whatever its mode', async () => {
+    // The elevated read itself refuses anything but a root-owned regular file, so a handoff —
+    // even one with operator-readable other bits (0644 uid 1001) that the plain read-back check
+    // would pass — would land and then fail EVERY read: the stranding the guard exists to
+    // prevent (deepseek round-1; the other-readable case is the glm round ask).
+    const { privileged, runner } = mk();
+    if (runner.checkWrite === undefined) throw new Error('sshSudoRunner must expose checkWrite');
+    for (const handoff of [
+      { gid: 113, mode: 0o640, uid: 1001 },
+      { gid: 0, mode: 0o644, uid: 1001 },
+    ]) {
+      await expect(runner.checkWrite(NUTISH, handoff)).rejects.toThrow(
+        'Handing it to uid 1001 would land and then fail every read',
+      );
+      await expect(runner.writeFileAtomic(NUTISH, bytes, handoff)).rejects.toThrow(
+        'Keep it root-owned',
+      );
+    }
+    expect(privileged()).toEqual([]);
+  });
+});

package/src/linux/sudo-runner.ts

@@ -8,7 +8,9 @@
  *   is the "no silent sudo" failure this exists to prevent.
  * ⛔ EVERY PRIVILEGED ARGV IS LOGGED BEFORE IT RUNS, and a file's bytes never reach argv or the
  *   log: they travel through the staged file (sudo-stage.ts) alone.
- * ⛔ A PLAN NEVER ELEVATES. `checkWrite` and every read run through `base` — the plain
+ * ⛔ A PLAN ELEVATES EXACTLY ONE KIND OF CALL: the `privilegedReads` file's own read (below) —
+ *   the read a plan diff needs on a declared root-owned file. Every other read, and every
+ *   `checkWrite` host probe (`id -G`, `ls`, `stat`), runs through `base` — the plain
  *   `sshRunner()` — never through sudo. Nothing here probes sudo at construction.
  * ★ PROMISES, NOT EFFECTS, ON PURPOSE — the same divergence `../launchd/runner.ts` documents
  *   (H3 in the provider-standard skill): a consumer's own runner is a plain async implementation.
@@ -120,7 +122,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
 
   return {
     checkWrite: async (path, options) => {
-      await vetWrite(base, prefixes, path, options);
+      await vetWrite(base, prefixes, path, options, readable);
     },
     effectiveUid: () => base.effectiveUid(),
     exec: async (argv) => {
@@ -174,7 +176,7 @@ export const makeSshSudoRunner = (prefixList: readonly string[], deps: SshSudoDe
     sleep: (ms) => base.sleep(ms),
     stat: (path) => base.stat(path),
     writeFileAtomic: async (path, bytes, options) => {
-      const vetted = await vetWrite(base, prefixes, path, options);
+      const vetted = await vetWrite(base, prefixes, path, options, readable);
       if (vetted === undefined) {
         return base.writeFileAtomic(path, bytes, options).catch(outsidePrefixHint(path, prefixes));
       }

package/src/linux/sudo-write.ts

@@ -73,12 +73,16 @@ export type Elevate = (
  * Plan-time and write-time share this: valid mode, the path chain, mode/owner refusals and the
  * read-back — everything a write can be refused for before anything is staged or run as root.
  * `undefined` outside every prefix, where the caller falls back to `base` directly.
+ * ★ `privilegedReads` is the runner's exact-path elevated-read set: a file on it is read back as
+ *   root (sudo-runner.ts's readFile), so the read-back refusal does not apply to it — the other
+ *   checks in assertInstallable still do.
  */
 export const vetWrite = async (
   base: HostRunner,
   prefixes: readonly string[],
   path: string,
   options: WriteOptions,
+  privilegedReads?: ReadonlySet<string>,
 ): Promise<{ readonly mode: string; readonly prefix: string } | undefined> => {
   const prefix = prefixOf(path, prefixes);
   if (prefix === undefined) return undefined;
@@ -86,7 +90,7 @@ export const vetWrite = async (
   if (mode === undefined)
     throw new SudoRefusedError(`sshSudoRunner ${path}: mode must be 0–0o7777`);
   const groups = await operatorGroups(base);
-  await assertInstallable(base, prefix, path, options, groups);
+  await assertInstallable(base, prefix, path, options, groups, privilegedReads);
   return { mode, prefix };
 };
 

package/src/talos/talosctl.test.ts

@@ -2,7 +2,7 @@
  * talosctl binary override. Fake spawner only — the named path is never executed (it only has to
  * exist and be a trusted file; the fake answers `version --client` with the pinned version).
  */
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, expect, test } from 'bun:test';
@@ -26,6 +26,8 @@ trustBoundaryForTests(dir);
 const fixture = join(dir, 'talosctl');
 writeFileSync(fixture, '#!/bin/sh\n', { mode: 0o755 });
 chmodSync(fixture, 0o755);
+// macOS tmpdir is /var, a symlink to /private/var. The vetted command is the real path.
+const resolved = realpathSync(fixture);
 afterAll(() => rmSync(dir, { force: true, recursive: true }));
 
 const run = (binary: string | undefined, calls: FakeCall[]) =>
@@ -56,7 +58,7 @@ test('the binary option wins over HF_TALOSCTL', async () => {
   await withEnv('/definitely/not/here/talosctl', async () => {
     const calls: FakeCall[] = [];
     await run(fixture, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -64,7 +66,7 @@ test('HF_TALOSCTL selects the binary when the option is omitted', async () => {
   await withEnv(fixture, async () => {
     const calls: FakeCall[] = [];
     await run(undefined, calls);
-    expect(calls[0]?.command).toBe(fixture);
+    expect(calls[0]?.command).toBe(resolved);
   });
 });
 
@@ -84,7 +86,7 @@ test('the default talosctl is resolved on PATH, vetted and version-checked by ab
     withPath(dir, async () => {
       const calls: FakeCall[] = [];
       await run(undefined, calls);
-      expect(calls.map((call) => call.command)).toEqual([fixture, fixture]);
+      expect(calls.map((call) => call.command)).toEqual([resolved, resolved]);
     }),
   );
 });