@homeflare/alchemy 0.25.1 → 0.27.0

package/dist/linux/sudo-allowlist-chown.d.ts

@@ -0,0 +1,12 @@
+/** Bare `directory-lifecycle.ts` argv (`0`, `:0`, `0:0`, …) → the `+`-forced form sudo may run. */
+export declare const forceNumericOwner: (spec: string) => string;
+/**
+ * `chown`'s dispatch: a call bound to `context.temp` (its last argument equals it) is the
+ * file-ownership form above; everything else is the directory form, root-only
+ * (`sudo-allowlist-dir.ts`'s own `ROOT_OWNER`, `+`-forced the same way).
+ */
+export declare const chownProblem: (args: readonly string[], context: {
+    readonly prefixes: readonly string[];
+    readonly temp?: string;
+}) => string | undefined;
+//# sourceMappingURL=sudo-allowlist-chown.d.ts.map

package/dist/linux/sudo-allowlist-chown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-allowlist-chown.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-allowlist-chown.ts"],"names":[],"mappings":"AAuBA,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,SAAU,MAAM,KAAG,MAKhD,CAAC;AA4BF;;;;GAIG;AACH,eAAO,MAAM,YAAY,SACjB,SAAS,MAAM,EAAE,WACd;IAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACxE,MAAM,GAAG,SAKX,CAAC"}

package/dist/linux/sudo-allowlist-dir.d.ts

@@ -0,0 +1,6 @@
+export declare const MKDIR = "/usr/bin/mkdir";
+export declare const CHMOD = "/usr/bin/chmod";
+export declare const CHOWN = "/usr/bin/chown";
+export declare const RMDIR = "/usr/bin/rmdir";
+export declare const dirProgramProblem: (program: string, args: readonly string[], prefixes: readonly string[]) => string | undefined;
+//# sourceMappingURL=sudo-allowlist-dir.d.ts.map

package/dist/linux/sudo-allowlist-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-allowlist-dir.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-allowlist-dir.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,KAAK,mBAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,mBAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,mBAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,mBAAmB,CAAC;AA4BtC,eAAO,MAAM,iBAAiB,YACnB,MAAM,QACT,SAAS,MAAM,EAAE,YACb,SAAS,MAAM,EAAE,KAC1B,MAAM,GAAG,SAkCX,CAAC"}

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

@@ -0,0 +1,40 @@
+import { INSTALL, SUDO, SudoRefusedError, checkPrefixes, octalMode, prefixOf } from '../launchd/sudo-allowlist.ts';
+export { INSTALL, SUDO, SudoRefusedError, checkPrefixes, octalMode, prefixOf };
+export { CHMOD, CHOWN, MKDIR, RMDIR } from './sudo-allowlist-dir.ts';
+/** ★ Absolute program paths, so neither sudo nor the command is looked up on the operator's PATH. */
+export declare const MV = "/usr/bin/mv";
+export declare const RM = "/usr/bin/rm";
+export declare const SYSTEMCTL_ABS = "/usr/bin/systemctl";
+/** The bare names `directory-lifecycle.ts` and `systemctl.ts` already send through `exec()`. */
+export declare const DIRECTORY_PROGRAMS: ReadonlySet<string>;
+/**
+ * The bare argv a provider sends → the absolute argv sudo may run. Unknown programs pass through.
+ * ★ `chown`'s owner argument is ALSO rewritten here, to the `+`-forced form `sudo-allowlist-dir.ts`
+ *   and `sudo-allowlist-chown.ts` now require — `directory-lifecycle.ts` never has to know that
+ *   syntax exists, and the allowlist checks exactly what will actually reach `sudo`.
+ */
+export declare const canonicalize: (argv: readonly string[]) => readonly string[];
+/** The one source `install` may copy, the one temp `install`/`mv` may touch, and the prefixes. */
+export type AllowContext = {
+    readonly prefixes: readonly string[];
+    readonly staged?: string;
+    readonly temp?: string;
+};
+/** `undefined` when `argv` is exactly an allowed privileged shape, else the reason it is not. */
+export declare const privilegedProblem: (argv: readonly string[], context: AllowContext) => string | undefined;
+/** Where one exec goes: run as the operator, run as root through the allowlist, or refused. */
+export type Route = {
+    readonly as: 'operator';
+} | {
+    readonly as: 'root';
+} | {
+    readonly refuse: string;
+};
+/**
+ * ★ ROUTING NEVER TOUCHES THE HOST. mkdir/chmod/chown/rmdir go to root only under a declared
+ *   prefix — outside one they run as the operator, who may well own that path (H3/rule 7).
+ *   systemctl's write verbs always ATTEMPT root; the FragmentPath check that can still refuse one
+ *   needs a host read, so it runs in the runner's `before` hook, not here.
+ */
+export declare const routeExec: (argv: readonly string[], prefixes: readonly string[]) => Route;
+//# sourceMappingURL=sudo-allowlist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-allowlist.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-allowlist.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,OAAO,EACP,IAAI,EACJ,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,QAAQ,EACT,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAC/E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErE,qGAAqG;AACrG,eAAO,MAAM,EAAE,gBAAgB,CAAC;AAChC,eAAO,MAAM,EAAE,gBAAgB,CAAC;AAChC,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAElD,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAKjD,CAAC;AASH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAU,SAAS,MAAM,EAAE,KAAG,SAAS,MAAM,EAQrE,CAAC;AAIF,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AA2FF,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,SACtB,SAAS,MAAM,EAAE,WACd,YAAY,KACpB,MAAM,GAAG,SAWX,CAAC;AAEF,+FAA+F;AAC/F,MAAM,MAAM,KAAK,GACb;IAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,SAAS,SAAU,SAAS,MAAM,EAAE,YAAY,SAAS,MAAM,EAAE,KAAG,KAyBhF,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * `sshSudoRunner.exec()`'s root branch: the host reads that decide whether a routed-to-root
+ * directory or systemctl call may actually elevate. Split out of sudo-runner.ts, which keeps only
+ * the wiring. sudo-allowlist.ts's `routeExec` already decided root vs operator vs refuse from the
+ * argv alone; this is the part that needs the host.
+ *
+ * ⛔ THE FragmentPath CHECK IS WHAT MAKES `pveproxy.service` UNREACHABLE. A vendor unit's file
+ *   lives under `/usr/lib/systemd/system` or `/lib/systemd/system` — never a prefix this runner
+ *   would declare — so `enable`/`start`/… on it is refused before sudo runs. A unit with NO file
+ *   at all (FragmentPath empty) is let through for `stop`/`disable` only, because
+ *   `unit-lifecycle.ts` `deleteUnit` calls exactly those two on a unit whose file this same
+ *   delete already removed a moment before — refusing that would make a second, idempotent
+ *   delete pass fail.
+ * 🔴 MEASURED (adversarial review, round 2, 2026-09-23): two gaps in this check, both closed here.
+ *   (1) A MASKED unit (`systemctl mask`, a symlink to `/dev/null`) also reads `FragmentPath=`
+ *   empty, so `enable`/`start`/`restart` on a masked `pveproxy.service` would have elevated —
+ *   `systemctl` itself would then refuse the write, but nothing here should even try; masking is
+ *   someone's deliberate decision (`unit-preflight.ts`'s `assertUsable` already refuses it at the
+ *   PROVIDER layer, and this is the same rule enforced again at the lowest level, in case a
+ *   caller reaches `exec()` directly). (2) The empty-FragmentPath exemption applied to EVERY
+ *   write verb, not just the two `deleteUnit` actually needs — so `enable`/`start`/`restart` on a
+ *   kernel-generated pseudo-unit with no file at all (`init.scope`, a `session-N.scope`; `.scope`
+ *   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.
+ */
+import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+import type { Elevate } from './sudo-write.ts';
+/** `argv` has already been routed to root; canonicalise it and run the read this shape needs. */
+export declare const elevatedExec: (base: HostRunner, elevate: Elevate, prefixes: readonly string[], argv: readonly string[]) => Promise<ExecResult>;
+//# sourceMappingURL=sudo-exec.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,36 @@
+/**
+ * The checks sudo-runner.ts makes against the host, as the operator, before it runs a file or
+ * directory operation as root. sudo-allowlist.ts checks the argv; this checks what the paths in
+ * it actually are — the Linux twin of `../launchd/sudo-guard.ts`, rebuilt on `sudo-listing.ts`'s
+ * ONE `ls -ldn` call instead of an lstat per directory, because ssh pays a handshake per call
+ * (ssh-runner.ts: no multiplexing unless the caller opts in) where a local syscall pays nothing.
+ *
+ * ⛔ EVERY DIRECTORY FROM `/` DOWN TO THE FILE MUST BE ROOT'S ALONE, for the same reason the Mac
+ *   guard insists on it: a directory anyone else may write lets them swap what lies under it — a
+ *   symlink where the file was — between this read and the privileged call. A root-owned symlink
+ *   ABOVE the prefix (Debian's merged-`/usr`, `/lib` -> `usr/lib`) is the system's own and is
+ *   followed, exactly as `aboveDirs`/`betweenDirs` from the Mac guard already encode; a symlink AT
+ *   or BELOW the prefix is refused outright — a write should never chase one there.
+ * ⛔ THE ACL SIGNAL IS THE `+` FLAG ALONE (sudo-listing.ts header): `ls`, not `getfacl`, which is
+ *   absent on the estate's Debian hosts. A directory that carries one is refused whatever it
+ *   grants — the guard cannot tell a read-only entry from a write one, so it fails closed.
+ */
+import type { FileStat, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import { aboveDirs, assertReadableBack, betweenDirs, canRead, modeProblem, operatorGroups } from '../launchd/sudo-guard.ts';
+export { aboveDirs, assertReadableBack, betweenDirs, canRead, modeProblem, operatorGroups };
+/** What must be at `path` itself, for the operation about to run there. */
+export type ChainExpect = 'file' | 'file-or-absent' | 'directory' | 'absent';
+/**
+ * Refuse a prefix that is not root-only, a symlink or wrong kind between the prefix and `path`,
+ * an ACL anywhere in the chain, or a target that is not what `expect` says. ONE `ls -ldn` for the
+ * directory chain, plus one plain `stat` for the target (see `targetProblem`'s note on why they
+ * are separate calls). ⚠️ Reads only, as the operator — so `checkWrite` runs this at plan time too.
+ */
+export declare const assertGuardedChain: (base: HostRunner, prefix: string, path: string, expect: ChainExpect) => Promise<FileStat | undefined>;
+/**
+ * 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.
+ */
+export declare const assertInstallable: (base: HostRunner, prefix: string, path: string, options: WriteOptions, groups: readonly number[] | undefined) => Promise<void>;
+//# sourceMappingURL=sudo-guard.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,37 @@
+/**
+ * sshSudoRunner(): the Linux twin of `../launchd/sudo-runner.ts` — the same idea (the deploy runs
+ * as the operator, and only a fixed allowlist of calls goes through `sudo -n`), rebuilt for a
+ * non-root ssh user with passwordless sudo instead of a local macOS session. See
+ * docs/linux-sudo.md for the full argv table and what is measured versus reasoned.
+ *
+ * ⛔ `sudo -n`, NEVER A PROMPT — same rule, same reason: a deploy that stops to ask for a password
+ *   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
+ *   `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.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+import { type SshRunnerOptions } from './ssh-runner.ts';
+import { SudoRefusedError } from './sudo-allowlist.ts';
+import { type Staged } from './sudo-stage.ts';
+export { SudoRefusedError };
+export type SshSudoRunnerOptions = SshRunnerOptions & {
+    /** Directories root may write under. Required; absolute, normalised, never `/`. */
+    readonly prefixes: readonly string[];
+    /** One line per privileged argv, before it runs. @default a line on stderr */
+    readonly log?: (line: string) => void;
+};
+/** What a sudo runner is built from. ★ Split out so the tests swap the host, never the logic. */
+export type SshSudoDeps = {
+    /** Runs everything, including `sudo` itself. `await sshRunner(options)` for the real one. */
+    readonly base: HostRunner;
+    readonly stage: (bytes: Uint8Array) => Promise<Staged>;
+    readonly log: (line: string) => void;
+};
+export declare const makeSshSudoRunner: (prefixList: readonly string[], deps: SshSudoDeps) => HostRunner;
+/** The real sudo runner: `sshRunner()` for everything, `/usr/bin/sudo -n` for the allowlist. */
+export declare const sshSudoRunner: (options: SshSudoRunnerOptions) => Promise<HostRunner>;
+//# sourceMappingURL=sudo-runner.d.ts.map

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

@@ -0,0 +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;CACvC,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;CACtC,CAAC;AAeF,eAAO,MAAM,iBAAiB,eAAgB,SAAS,MAAM,EAAE,QAAQ,WAAW,KAAG,UA2DpF,CAAC;AAsBF,gGAAgG;AAChG,eAAO,MAAM,aAAa,YAAmB,oBAAoB,KAAG,OAAO,CAAC,UAAU,CAYrF,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * Where sudo-runner.ts puts a file's bytes before `install` copies them into a fresh temp file
+ * that `mv` then renames into place. The Linux twin of `../launchd/sudo-stage.ts` — rewritten,
+ * not reused, because staging happens ON THE REMOTE HOST through the base runner's own calls,
+ * never through `node:fs` against this process's local disk.
+ *
+ * ★ WHY STAGE AT ALL. The operator cannot write inside a root-owned directory, and the bytes must
+ *   not travel through argv (they would reach the log and `ps`). So they are written, as the
+ *   operator, to a private file on the SAME host, and `install` copies that one file.
+ * ⛔ A 0700 DIRECTORY, A 0600 FILE: between the write and the install, nobody but the operator and
+ *   root can read the bytes or swap the file. `mktemp -d` creates its directory 0700 by
+ *   construction (GNU coreutils); the payload's own mode is asked for explicitly.
+ */
+import type { HostRunner } from '../launchd/runner.ts';
+/** A file staged for `install`, and how to remove it again. */
+export type Staged = {
+    readonly path: string;
+    readonly dispose: () => Promise<void>;
+};
+/** `stage` in `SshSudoDeps` — closes over the base runner so every call writes to the same host. */
+export declare const stageRemote: (base: HostRunner) => (bytes: Uint8Array) => Promise<Staged>;
+//# sourceMappingURL=sudo-stage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sudo-stage.d.ts","sourceRoot":"","sources":["../../src/linux/sudo-stage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,+DAA+D;AAC/D,MAAM,MAAM,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAItF,oGAAoG;AACpG,eAAO,MAAM,WAAW,SACf,UAAU,aACH,UAAU,KAAG,OAAO,CAAC,MAAM,CA0BxC,CAAC"}

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

@@ -0,0 +1,25 @@
+import type { ExecResult, HostRunner, WriteOptions } from '../launchd/runner.ts';
+import type { Staged } from './sudo-stage.ts';
+/** `<dir>/.<basename>.hf-<12 hex>.tmp`, in `dest`'s own directory — never anywhere else. */
+export declare const deriveTemp: (dest: string) => string;
+/** A privileged call: allowlisted, logged, run. Shared with sudo-runner.ts's own exec() routing. */
+export type Elevate = (argv: readonly string[], context?: {
+    readonly staged?: string;
+    readonly temp?: string;
+}, before?: () => Promise<unknown>) => Promise<ExecResult>;
+/**
+ * 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.
+ */
+export declare const vetWrite: (base: HostRunner, prefixes: readonly string[], path: string, options: WriteOptions) => Promise<{
+    readonly mode: string;
+    readonly prefix: string;
+} | undefined>;
+/**
+ * Stage, `install` into a fresh temp file beside `path`, `chown` it if a non-root owner was
+ * declared, `mv` it into place. Cleans up the temp on a failed `mv`, and always disposes the
+ * stage — whether or not the write succeeded.
+ */
+export declare const writeUnderPrefix: (base: HostRunner, elevate: Elevate, stage: (bytes: Uint8Array) => Promise<Staged>, path: string, bytes: Uint8Array, options: WriteOptions, mode: string) => Promise<void>;
+//# sourceMappingURL=sudo-write.d.ts.map

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

@@ -0,0 +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"}

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

@@ -107,6 +107,8 @@ export declare const isUnitRunning: (activeState: string, subState: string | und
 export declare const renderUnit: (sections: readonly UnitSection[]) => string;
 export declare const unitText: (props: SystemdUnitProps) => string;
 export declare const unitPathFor: (props: SystemdUnitProps) => string;
+/** ★ Exported so sudo-allowlist.ts validates a systemctl unit operand against the same pattern. */
+export declare const NAME: RegExp;
 /**
  * Every refusal at once, so one plan shows the whole list.
  * ⛔ THE TWO STRUCTURAL RULES, both proven by systemd's own output rather than assumed:

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;AAoB/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":"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"}

package/dist/litellm/fake-litellm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-litellm.d.ts","sourceRoot":"","sources":["../../src/litellm/fake-litellm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,0BAA0B,EAAE,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,SAAS,WAAW,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B;AAKD,eAAO,MAAM,gBAAgB,aAAc;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACtD,qGAAqG;IACrG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC,KAAG,WAyEH,CAAC"}
+{"version":3,"file":"fake-litellm.d.ts","sourceRoot":"","sources":["../../src/litellm/fake-litellm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,SAAS,0BAA0B,EAAE,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,SAAS,WAAW,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B;AAKD,eAAO,MAAM,gBAAgB,aAAc;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACtD,qGAAqG;IACrG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC,KAAG,WA2EH,CAAC"}

package/dist/proxmox/fake-pve-lxc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-pve-lxc.d.ts","sourceRoot":"","sources":["../../src/proxmox/fake-pve-lxc.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzE,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACtF,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,WAAW,eAAe,CAAC;AACxC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAwC/C,eAAO,MAAM,OAAO,QAAO,OA2H1B,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,QAAQ,SAAU,OAAO,aAG0C,CAAC"}
+{"version":3,"file":"fake-pve-lxc.d.ts","sourceRoot":"","sources":["../../src/proxmox/fake-pve-lxc.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzE,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACtF,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,WAAW,eAAe,CAAC;AACxC,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAwC/C,eAAO,MAAM,OAAO,QAAO,OAoI1B,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,QAAQ,SAAU,OAAO,aAG0C,CAAC"}

package/docs/launchd-sudo.md

@@ -79,9 +79,18 @@ sudo.
   refuse. Measured 2026-09-21: `/Library/LaunchDaemons`, `/private/etc`, `/opt` and `/usr/local`,
   and everything above them, carry none.
 - **A root-owned file that would be group- or world-writable, setuid or setgid** (`mode & 0o6022`;
-  an omitted owner is root). ⛔ Anyone in that class could rewrite a file root installed (a
-  daemon's config, a script it runs), and a setuid root file runs as root for whoever executes it.
-  A file handed to another user (`owner`) is theirs to change, so its mode is theirs too.
+  root-owned means an omitted owner, uid `0`, **or an omitted or `0` gid** — any of the four keeps
+  every check active). ⛔ Anyone in that class could rewrite a file root installed (a daemon's
+  config, a script it runs), and a setuid root file runs as root for whoever executes it. 🔴
+  MEASURED (adversarial review, 2026-09-23, two rounds): round 1 found checking only `uid` let
+  `{uid: 501, gid: 0, mode: 0o2775}` — setgid to root's own group, group-writable, merely OWNED by
+  uid 501 — through untouched. Round 2 found the round-1 fix still missed an OMITTED `gid`: on the
+  Linux sibling runner, GNU `install` run as root via `sudo -n` defaults a missing `-g` to root's
+  own group whenever the destination directory is not itself setgid (measured true of every prefix
+  this codebase declares), so `{uid: 501, mode: 0o2775}` — `group` simply never declared — reaches
+  the identical escalation by omission; this check is shared code, so it is fixed the same way on
+  both platforms rather than relied on to differ safely by OS default. A file handed to another
+  owner is theirs to change only when BOTH the uid and the gid are explicitly, genuinely theirs.
 - A path outside every prefix that needs root: another user as the owner, say.
 - A symlink or missing directory between the prefix and the file, or anything but a regular file
   at the path. ⚠️ `install src <directory>` copies _into_ the directory, and a symlink to one does

package/docs/linux-host.md

@@ -30,9 +30,9 @@ Layer.mergeAll(linuxProviders(runner) /* the stack's other providers */);
   "nothing is there". This is the rule that stops a dropped link reading as a
   deleted config.
 - ⛔ **No silent sudo.** `privileged` is `false` and nothing here calls `sudo`.
-  A root-owned path needs a destination whose ssh **user is root**, or a
-  privileged runner of your own. The Linux twin of `sudoRunner()` — with its
-  own argv allowlist — is deliberately a separate, later change.
+  A root-owned path needs a destination whose ssh **user is root**, or
+  `sshSudoRunner()` — the Linux twin of `sudoRunner()`, with its own argv
+  allowlist: [linux-sudo.md](./linux-sudo.md).
 - The probe at construction (`uname -s`, `id -u`) refuses anything that is not
   Linux: the scripts use GNU/BusyBox spellings (`stat -c`, `base64`, `mv -f`).
 

package/docs/linux-sudo.md

@@ -0,0 +1,187 @@
+# Deploying a Linux host as an unprivileged ssh user — `sshSudoRunner()`
+
+The Linux twin of [`sudoRunner()`](./launchd-sudo.md): the deploy runs as the ssh
+user, and only a fixed allowlist of calls goes through `sudo -n`, in exact argv
+shapes, logging each one. It is an explicit opt-in — `sshRunner()` stays the
+default and never elevates (docs/linux-host.md).
+
+```ts
+import { linuxProviders, sshSudoRunner } from '@homeflare/alchemy/linux';
+
+const runner = await sshSudoRunner({
+  host: 'n2',
+  // ⛔ Required: the directories root may write. Each — every directory above
+  //   it, and every directory below it on the way to a file — must be one
+  //   that root owns and only root may write, by mode bits and by POSIX ACL;
+  //   checked at every privileged call.
+  prefixes: ['/etc/systemd/system', '/usr/local/bin'],
+  // log: (line) => …, // default: one line on stderr per privileged call
+});
+// Provide linuxProviders(runner) alongside the stack's other provider layers.
+```
+
+⚠️ **Target: an ssh user that is NOT root, with passwordless sudo** —
+`(ALL) NOPASSWD: ALL` on the sudoers line, as `homeflare-proxmox` declares for
+`tim` on each Proxmox node. `sshRunner()` already covers an ssh user that IS
+root; this is for the other case.
+
+## Why `install` alone isn't enough here
+
+macOS's `sudoRunner()` writes a file with one privileged call: `install -S`
+stages a temp file beside the target and renames it, atomically, inside
+`install` itself. **GNU `install` has no such mode** — it opens the
+destination and writes through it (`src/linux/ssh-scripts.ts`'s own header).
+So this runner does the staging and the atomic swap itself:
+
+| step | who        | what                                                                |
+| ---- | ---------- | ------------------------------------------------------------------- |
+| 1    | operator   | `mktemp -d` (0700), then `writeFileAtomic` the bytes into it (0600) |
+| 2    | **root**   | `install -m <4 octal> -T -- <staged> <temp>` — no `-o`/`-g`, ever   |
+| 3    | **root**\* | `chown +<uid>[:+<gid>]` — only when a non-root owner was declared   |
+| 4    | **root**   | `mv -f -T -- <temp> <dest>` — rename(2), same directory, atomic     |
+
+`<temp>` is `<dest's directory>/.<basename>.hf-<12 hex>.tmp`, derived per
+call and verified **absent** by the operator before step 2 runs. `install`
+never takes `-o`/`-g`: unlike `chown`, GNU `install`'s own `get_ids()`
+(coreutils `src/install.c`) always tries `getpwnam`/`getgrnam` on the string
+FIRST, with no way to force numeric parsing — so `install -o 0` on a host
+that ever had a user literally named `"0"` would install owned by THAT
+account, not uid 0. `install` therefore always leaves the temp owned by
+whoever `sudo` ran it as (root:root), and a declared non-root owner or group
+is set afterward by step 3's `chown`, which DOES support forcing numeric
+parsing (`+<id>`, skipping the name lookup — gnulib's `userspec.c`). `mv` is
+the one call that ever touches `<dest>`, and rename(2) is atomic by
+construction. On any failure after step 2, the temp is removed with
+`sudo -n rm -f -- <temp>` — if THAT also fails, the thrown error says so and
+names the path, rather than leaving it a silent mystery. The operator's own
+staging directory is removed either way.
+
+## What runs as root: the whole list
+
+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>`                                               |
+
+`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
+`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,
+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
+know that syntax exists.
+
+## What stays as the operator
+
+- Every read: `stat`, `readFile`, user/group lookups, `systemctl show`.
+- `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
+  refusal naming the declared prefixes, not a silent write attempt).
+- `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.
+
+## The host guard
+
+Before any privileged file or directory call, and in `checkWrite`, one
+`ls -ldn` read (as the operator) covers every directory from `/` down to the
+target's parent (`src/linux/sudo-listing.ts` — one ssh round trip for the
+whole chain, because ssh pays a handshake per call with no multiplexing
+unless the caller opts in). Refused: any directory in that chain not owned
+by root, or writable by group or other; a POSIX ACL `+` flag anywhere in it
+(the signal is the flag alone — `getfacl` is absent on the estate's Debian
+hosts, so an ACL is refused whatever it grants, fail closed); a symlink at or
+below the prefix; a target of the wrong kind for what is about to happen to
+it (a directory sitting where a file write expects absent or a file, say).
+A root-owned symlink **above** the prefix (Debian's merged-`/usr`, `/lib` ->
+`usr/lib`) is the system's own and is followed, mirroring the Mac guard.
+
+## Refused before sudo is asked
+
+Same spirit as [launchd-sudo.md](./launchd-sudo.md)'s list: any argv whose
+program is `sudo`; `install` with `-o`/`-g` at all (refused outright — see
+above); `install` from a source it did not stage, or to a target that is not
+the temp it derived; `chown` on the temp with a bare (non-`+`-forced) id, a
+name, or a path that is not that exact temp; `mv` whose source is not that
+same temp, or whose destination is not under a declared prefix; `rm -r`; any
+of the directory programs with an extra operand, a relative path, `..`, a
+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).
+
+🔴 **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`.
+
+Every refusal throws `SudoRefusedError`: nothing ran as root. A privileged
+command that ran and failed throws a plain `Error` with its exit code.
+
+## What is measured vs reasoned
+
+⚠️ **REASONED, NOT MEASURED — never run live** unless marked otherwise: the
+write path (`install`→`mv`, `rm`, `mkdir`/`chmod`/`chown`/`rmdir`,
+`daemon-reload`/`enable`/`disable`/`start`/`stop`/`restart`) has never been
+run against a real host by this runner. Each is checked for exit 0 and its
+effect read back, never assumed — the same discipline
+[linux-host-measured.md](./linux-host-measured.md) already keeps for the
+unprivileged writes.
+
+★ **Exercised read-only against `n2` (Debian 13 / trixie, systemd 257
+(257.13-1~deb13u1), coreutils 9.7-3, merged `/usr` — `/bin -> usr/bin`), ssh
+user `tim` uid 1000, `(ALL) NOPASSWD: ALL`, 2026-09-23.** `sshSudoRunner()`
+built successfully (the `test -x` construction check passed for all nine
+programs); `checkWrite('/etc/systemd/system/hf-pve-cluster-check.service',
+{mode:0o644, uid:0, gid:0})` and
+`checkWrite('/usr/local/bin/hf-pve-cluster-check', {mode:0o755, uid:0,
+gid:0})` both returned successfully (the real directory chain read as
+root-owned, no group/other write, no ACL, both targets absent); a read-only
+`systemctl show -p LoadState -- hf-pve-cluster-check.service` answered
+`LoadState=not-found`. **The runner's own log stayed empty across every
+call** — nothing was elevated. Nothing was written, enabled, started or
+reloaded on `n2`.

package/docs/repo-policy-ruleset-hazards.md

@@ -1,5 +1,13 @@
 # `declareRepoPolicy` — the ruleset half's hazards
 
+⚠️ **Status 2026-09-23: `declareRepoPolicy` no longer takes this path.** It is rewired onto
+`GitHub.RepositoryRuleset` — the bridge resource in `repository-ruleset.ts` — which closes the
+duplicate-on-first-deploy hazard below by probing for a same-named ruleset before ever creating
+one, and fixes the never-noop hazard by normalizing before comparing (see
+[repository-ruleset.md](./repository-ruleset.md)). Everything on this page is still an accurate
+account of upstream `GitHub.Ruleset` itself, kept for anyone who declares it directly rather
+than through this kit, and as the record of why the bridge exists.
+
 Everything here is about `GitHub.Ruleset` in `alchemy@2.0.0-beta.79`, not about the
 policy this kit declares. It is extracted from [repo-policy.md](./repo-policy.md) so the
 reasoning stays whole rather than being shaved to fit a line cap.

package/docs/repo-policy.md

@@ -9,7 +9,7 @@ import { declareRepoPolicy } from '@homeflare/alchemy/github';
 import * as Effect from 'effect/Effect';
 
 Effect.gen(function* () {
-  // policy.repository → GitHub.Repository, policy.ruleset → GitHub.Ruleset
+  // policy.repository → GitHub.Repository, policy.ruleset → GitHub.RepositoryRuleset
   const policy = yield* declareRepoPolicy('api', {
     owner: 'my-org',
     repository: 'api',
@@ -18,8 +18,12 @@ Effect.gen(function* () {
 });
 ```
 
-Provide `GitHub.providers()`. This subpath ships **no provider of its own** — everything
-here composes Alchemy's first-class `GitHub.Repository` and `GitHub.Ruleset`.
+Provide `GitHub.providers()` **and** `RepositoryRulesetProvider()` from this subpath.
+⚠️ **Rewired 2026-09-23**: the ruleset half now composes this house's own
+`GitHub.RepositoryRuleset` (see [repository-ruleset.md](./repository-ruleset.md)), not
+upstream `GitHub.Ruleset` — every hazard [below](#-the-ruleset-half-has-hazards-of-its-own)
+describes upstream's behavior and is now what this bridge exists to close, not what
+`declareRepoPolicy` still does.
 
 `repoPolicy(options)` is the same thing without the resources: the two prop objects, pure,
 for a test or for a stack that wants to declare them itself.
@@ -105,16 +109,22 @@ not name a job behind a `paths:` filter, a matrix leg, or anything a skipped wor
 silence. Contexts are trimmed, de-duplicated and **sorted**, so writing the same two the
 other way round is not a diff.
 
-## ⛔ The ruleset half has hazards of its own
+## ⛔ The ruleset half's hazards — closed by the bridge, still worth reading
 
 The vendor `Ruleset` **cannot be adopted** — a first deploy onto a repository that
 already has a ruleset of that name creates a **second** one beside it, both enforcing —
 it **never plans a no-op**, and it replaces its `rules` and `bypass_actors` **wholesale**.
-None of that applies to the repository half.
+None of that ever applied to the repository half.
 
-⛔ Read [repo-policy-ruleset-hazards.md](./repo-policy-ruleset-hazards.md) before the
-first deploy. It carries the preflight `gh api repos/<owner>/<repo>/rulesets` command and
-the repository-half-only escape hatch.
+As of the 2026-09-23 rewire, `declareRepoPolicy`'s ruleset half goes through
+`GitHub.RepositoryRuleset`, which probes by name before creating and normalizes before
+comparing — see [repository-ruleset.md](./repository-ruleset.md). The wholesale-replace
+behavior is unchanged (it is how the underlying `PUT` works), now enforced as a named
+refusal rather than a silent drop.
+
+⛔ Read [repo-policy-ruleset-hazards.md](./repo-policy-ruleset-hazards.md) for the full
+account of upstream `GitHub.Ruleset`'s own behavior — still accurate for anyone who
+declares it directly rather than through this kit.
 
 ## Required reviews are opt-in, and `0` is refused
 
@@ -125,10 +135,15 @@ default, where a pull request is gated by its checks.
 
 ⛔ `requiredApprovals: 0` is **refused**, not treated as "no reviews". Zero approvals is
 the solo-maintainer shape — every change through a pull request, no second person — and
-it works only with `require_extra_approval_for_unattributed_changes: false`. Alchemy's
-`Ruleset` has no property for that field, and GitHub defaults it to `true` when it is
-omitted (measured 2026-09-17), which blocks the very pull requests the zero was meant to
-let through. Accepting it would ship a rule that does the opposite of what it says.
+it works only with `require_extra_approval_for_unattributed_changes: false`, which GitHub
+defaults to `true` when it is omitted (measured 2026-09-17), blocking the very pull
+requests the zero was meant to let through.
+⚠️ **Still refused after the 2026-09-23 rewire**, though the underlying resource
+(`GitHub.RepositoryRuleset`) can now send that flag — `RepoPolicyOptions` has no field to
+ask for it, so `repoPolicy` would otherwise ship a rule that does the opposite of what it
+says. A caller that genuinely wants `0` declares `RepositoryRuleset` directly with
+`extraApprovalForUnattributedChanges: false` (see
+[repository-ruleset.md](./repository-ruleset.md)) instead of going through this helper.
 
 ## ★ `strict` is always off, and is not a parameter