@homeflare/alchemy 0.54.0 → 0.56.0

package/src/ceph/ceph-config-option.test.ts

@@ -0,0 +1,213 @@
+/**
+ * `Ceph.ConfigOption` (K-D): validation against the named list, the reconcile/delete loop against
+ * fakeCephDial (no ssh) and a canned config-db read (no PVE). Config-options design acceptance
+ * tests #1 (allowlist) and #2 (fake-runner loop).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { PveTarget } from '../proxmox/credentials.ts';
+import {
+  type CephConfigOptionProps,
+  type CfgDbRow,
+  configOptionProblem,
+  findLive,
+} from './ceph-config-option-form.ts';
+import {
+  deleteCephConfigOption,
+  reconcileCephConfigOption,
+} from './ceph-config-option-reconcile.ts';
+import { fakeCephDial, fakeCephOk } from './fake-ceph-dial.ts';
+
+const MON = 'mon-a.example.test';
+const NAME = 'mgr/prometheus/exclude_perf_counters';
+const TARGET: PveTarget = { members: ['pve-a.example.test'], mount: 'proxmox-test', scheme: 'pve' };
+const PROPS: CephConfigOptionProps = {
+  monNodes: [MON],
+  name: NAME,
+  node: 'pve-a',
+  target: TARGET,
+  value: 'false',
+  who: 'mgr',
+};
+const HEALTHY_QUORUM = '{"quorum":[0,1,2]}';
+const row = (value: string, extra: Partial<CfgDbRow> = {}): CfgDbRow => ({
+  mask: '',
+  name: NAME,
+  section: 'mgr',
+  value,
+  ...extra,
+});
+
+/** A config-db read that answers each scripted snapshot in turn, last one repeating. */
+const rowsSeq = (...snapshots: (readonly CfgDbRow[])[]) => {
+  let at = 0;
+  return Effect.sync(() => snapshots[Math.min(at++, snapshots.length - 1)] ?? []);
+};
+const argvOf = (seen: readonly { readonly argv: readonly string[] }[]) => seen.map((c) => c.argv);
+const run = <A>(effect: Effect.Effect<A, unknown>) => Effect.runPromise(effect);
+
+describe('validation against the named option list', () => {
+  test('accepts the first named option for its own <who>', () => {
+    expect(configOptionProblem(PROPS)).toBeUndefined();
+  });
+
+  test('rejects a key that is not on the list', () => {
+    expect(configOptionProblem({ ...PROPS, name: 'osd_max_backfills', who: 'osd' })).toContain(
+      'not on the named option list',
+    );
+  });
+
+  test('rejects a listed key for an unlisted <who>', () => {
+    expect(configOptionProblem({ ...PROPS, who: 'global' })).toContain('may only be set for mgr');
+  });
+
+  test('rejects a lockout-class key and a flag-shaped value', () => {
+    expect(configOptionProblem({ ...PROPS, name: 'public_addr', who: 'mon' })).toContain('lockout');
+    expect(configOptionProblem({ ...PROPS, value: '--conf=/x' })).toContain('safe set');
+  });
+
+  test('rejects an empty mon list', () => {
+    expect(configOptionProblem({ ...PROPS, monNodes: [] })).toContain('monNodes');
+  });
+});
+
+describe('findLive maps the config-db read', () => {
+  test('the unmasked row for exactly {who, name}', () => {
+    expect(findLive([row('false')], 'mgr', NAME)).toEqual({
+      name: NAME,
+      value: 'false',
+      who: 'mgr',
+    });
+  });
+
+  test('a masked row, another section or another name is not this option', () => {
+    const rows = [
+      row('true', { mask: 'host:a' }),
+      row('true', { section: 'global' }),
+      row('true', { name: 'mgr/prometheus/x' }),
+    ];
+    expect(findLive(rows, 'mgr', NAME)).toBeUndefined();
+  });
+});
+
+describe('reconcile', () => {
+  test('live already matches (the codified exclude_perf_counters=false): zero ssh calls', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    const attrs = await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([row('false')]), { dial: fake.dial, log: () => {} }),
+    );
+    expect(attrs).toEqual({ name: NAME, value: 'false', who: 'mgr' });
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('absent: exactly one config set, then a fresh quorum check, then read back', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    const attrs = await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([], [row('false')]), {
+        dial: fake.dial,
+        log: () => {},
+      }),
+    );
+    expect(attrs.value).toBe('false');
+    expect(argvOf(fake.seen)).toEqual([
+      ['/usr/bin/ceph', 'config', 'set', 'mgr', NAME, 'false', '-f', 'json'],
+      ['/usr/bin/ceph', 'quorum_status', '-f', 'json'],
+    ]);
+  });
+
+  test('drifted value: the update is the same single config set', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await run(
+      reconcileCephConfigOption(PROPS, rowsSeq([row('true')], [row('false')]), {
+        dial: fake.dial,
+        log: () => {},
+      }),
+    );
+    expect(argvOf(fake.seen)[0]).toEqual([
+      '/usr/bin/ceph',
+      'config',
+      'set',
+      'mgr',
+      NAME,
+      'false',
+      '-f',
+      'json',
+    ]);
+    expect(fake.seen).toHaveLength(2);
+  });
+
+  test('a read-back that disagrees is refused, never recorded', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, rowsSeq([row('true')]), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/Not recorded/);
+  });
+
+  test('a non-listed key is refused before the read and before any ssh', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    let reads = 0;
+    const readRows = Effect.sync(() => {
+      reads++;
+      return [] as CfgDbRow[];
+    });
+    await expect(
+      run(
+        reconcileCephConfigOption({ ...PROPS, name: 'osd_max_backfills', who: 'osd' }, readRows, {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/named option list/);
+    expect(reads).toBe(0);
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a failed config-db read propagates, never treated as absent', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, Effect.fail(new Error('pve down')), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/pve down/);
+    expect(fake.seen).toHaveLength(0);
+  });
+
+  test('a degraded quorum after the write fails the row', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk('{"quorum":[]}')] });
+    await expect(
+      run(
+        reconcileCephConfigOption(PROPS, rowsSeq([], [row('false')]), {
+          dial: fake.dial,
+          log: () => {},
+        }),
+      ),
+    ).rejects.toThrow(/degraded/);
+  });
+});
+
+describe('delete', () => {
+  test('present: exactly one config rm, then a quorum check', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk(''), fakeCephOk(HEALTHY_QUORUM)] });
+    await run(
+      deleteCephConfigOption(PROPS, rowsSeq([row('false')]), { dial: fake.dial, log: () => {} }),
+    );
+    expect(argvOf(fake.seen)).toEqual([
+      ['/usr/bin/ceph', 'config', 'rm', 'mgr', NAME, '-f', 'json'],
+      ['/usr/bin/ceph', 'quorum_status', '-f', 'json'],
+    ]);
+  });
+
+  test('already absent: idempotent, nothing sent', async () => {
+    const fake = fakeCephDial({ [MON]: [fakeCephOk('')] });
+    await run(deleteCephConfigOption(PROPS, rowsSeq([]), { dial: fake.dial, log: () => {} }));
+    expect(fake.seen).toHaveLength(0);
+  });
+});

package/src/ceph/ceph-config-options.test.ts

@@ -1,19 +1,32 @@
 /**
  * Structural guard on the named config-option list itself (mon-transport doc acceptance test #3):
- * the list contains none of the lockout classes, and it starts empty (D-C1).
+ * the list contains none of the lockout classes, and each entry is one reviewed line (D-C1).
  */
 import { describe, expect, test } from 'bun:test';
-import { NAMED_CONFIG_OPTIONS, isLockoutConfigOption } from './ceph-config-options.ts';
+import {
+  NAMED_CONFIG_OPTIONS,
+  allowedWhoFor,
+  isLockoutConfigOption,
+} from './ceph-config-options.ts';
 
 describe('NAMED_CONFIG_OPTIONS', () => {
-  test('starts empty', () => {
-    expect(NAMED_CONFIG_OPTIONS.size).toBe(0);
+  test('the first reviewed entry is the mgr prometheus perf-counter switch, for mgr only', () => {
+    expect(NAMED_CONFIG_OPTIONS.get('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mgr/prometheus/exclude_perf_counters')).toEqual(['mgr']);
+    expect(allowedWhoFor('mon_allow_pool_delete')).toEqual([]);
   });
 
   test('contains none of the lockout classes, whatever gets added later', () => {
-    const bad = [...NAMED_CONFIG_OPTIONS].filter((name) => isLockoutConfigOption(name));
+    const bad = [...NAMED_CONFIG_OPTIONS.keys()].filter((name) => isLockoutConfigOption(name));
     expect(bad).toEqual([]);
   });
+
+  test('every entry names at least one bounded <who>', () => {
+    for (const [name, whos] of NAMED_CONFIG_OPTIONS) {
+      expect([name, whos.length > 0]).toEqual([name, true]);
+      for (const who of whos) expect(who).toMatch(/^(global|mon|osd|mgr|mds|client)(\.[\w-]+)?$/);
+    }
+  });
 });
 
 describe('isLockoutConfigOption', () => {
@@ -31,14 +44,18 @@ describe('isLockoutConfigOption', () => {
     'keyring_path',
     'key',
     'mon_data_key',
+    'mgr/dashboard/key',
+    'mgr/restful/keyring',
   ])('flags %s', (name) => {
     expect(isLockoutConfigOption(name)).toBe(true);
   });
 
-  test.each(['mon_allow_pool_delete', 'osd_pool_default_size', 'mon_max_pg_per_osd'])(
-    'does not flag an ordinary tuning option like %s',
-    (name) => {
-      expect(isLockoutConfigOption(name)).toBe(false);
-    },
-  );
+  test.each([
+    'mgr/prometheus/exclude_perf_counters',
+    'mon_allow_pool_delete',
+    'osd_pool_default_size',
+    'mon_max_pg_per_osd',
+  ])('does not flag an ordinary tuning option like %s', (name) => {
+    expect(isLockoutConfigOption(name)).toBe(false);
+  });
 });

package/src/ceph/ceph-config-options.ts

@@ -3,10 +3,14 @@
  * through the mon-command transport (ceph-argv.ts's `configProblem`). Design:
  * docs/plans/2026-09-26-ceph-config-options.md, D-C1.
  *
- * ⛔ THE LIST STARTS EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. Nothing in K-A4 adds to
- *   it — `CephConfigOption` (K-D) is a separate, later family; this file exists now only so the
- *   transport's allowlist has something to bound `config` against from day one, per the accepted
- *   design ("config get/set for the named option list which starts EMPTY").
+ * ⛔ THE LIST STARTED EMPTY, AND EACH ADDITION IS ITS OWN REVIEWED PR LINE. `Ceph.ConfigOption`
+ *   (K-D, config-option.ts) is the only declarer; it refuses any `{who, name}` this map does not
+ *   carry before planning, and the transport's allowlist (ceph-argv-config.ts) refuses it again
+ *   before anything dials. One entry per line, each with a comment saying what it does and why it
+ *   is managed — never a batch.
+ * ★ EACH ENTRY ALSO NAMES THE `<who>` IT MAY BE SET FOR. This is the config-options design's
+ *   acceptance test #1 ("`<who>` bounded to the declared daemons"): an option listed for `mgr`
+ *   can never be written to `global`, `client.admin` or any other section through this transport.
  * ⛔ NEVER ADD ONE OF THE LOCKOUT CLASSES BELOW. `mon_host`, `public_network`, `cluster_network`,
  *   `public_addr`, `cluster_addr`, every `auth_*_required` and every `key`/`keyring`-bearing
  *   option re-address the mons or de-authenticate the whole cluster — cutting every VM disk — and
@@ -17,8 +21,22 @@
  *   never a `ceph config set` argv, which lands in the runner's log and the node's sudo journal.
  */
 
-/** Starts empty. Add one reviewed option name per PR line, never a batch. */
-export const NAMED_CONFIG_OPTIONS: ReadonlySet<string> = new Set([]);
+/**
+ * option name -> the `<who>` sections it may be set for. Add one reviewed line per PR, never a
+ * batch; the structural test (ceph-config-options.test.ts) runs the lockout guard over every key.
+ */
+export const NAMED_CONFIG_OPTIONS: ReadonlyMap<string, readonly string[]> = new Map<
+  string,
+  readonly string[]
+>([
+  // mgr prometheus module: `false` makes it export per-daemon perf counters (ceph_osd_op_*,
+  // ceph_rgw_* …) instead of omitting them. Set live 2026-10, codified here so plan reconciles it.
+  ['mgr/prometheus/exclude_perf_counters', ['mgr']],
+]);
+
+/** The `<who>` sections `name` may be set for — empty when the option is not on the list. */
+export const allowedWhoFor = (name: string): readonly string[] =>
+  NAMED_CONFIG_OPTIONS.get(name) ?? [];
 
 const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'mon_host',
@@ -28,8 +46,11 @@ const LOCKOUT_EXACT: ReadonlySet<string> = new Set([
   'cluster_addr',
 ]);
 
-/** `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, either side of `_`. */
-const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|_)key(ring)?($|_)/;
+/**
+ * `auth_*_required` (cephx enforcement) and anything key/keyring-shaped, bounded by `_` or by the
+ * `/` that separates an mgr module option (`mgr/<module>/<option>`) — so `mgr/x/key` is caught too.
+ */
+const LOCKOUT_PATTERN = /^auth_\w*_required$|(^|[_/])key(ring)?($|[_/])/;
 
 /** Whether `name` is a class this transport must never read a value for, adopt, or write. */
 export const isLockoutConfigOption = (name: string): boolean =>

package/src/ceph/config-option.ts

@@ -0,0 +1,112 @@
+/**
+ * `Ceph.ConfigOption` (K-D) — one `{who, name} = value` row of the Ceph mon config db, declared.
+ * Design: docs/plans/2026-09-26-ceph-config-options.md. Pure helpers: ceph-config-option-form.ts;
+ * the loop: ceph-config-option-reconcile.ts; the allowlist: ceph-argv-config.ts.
+ *
+ * ★ ONE RESOURCE PER OPTION, AND ONLY OPTIONS ON THE NAMED LIST. `NAMED_CONFIG_OPTIONS`
+ *   (ceph-config-options.ts) is the gate: each entry is its own reviewed PR line and names the
+ *   `<who>` it may be set for. Anything else is refused at `diff` (so the plan fails loudly) and
+ *   again by the transport before anything dials.
+ * ★ PLAN READS OVER THE PVE API, NEVER SSH. `read`/`diff` call `GET /nodes/{node}/ceph/cfg/db`
+ *   (read lease only — "a plan never elevates"). Only `reconcile`/`delete` reach ssh, through
+ *   ceph-transport.ts — the existing mon-command transport `Ceph.AuthEntity` uses, not a new one.
+ * ★ ADOPTION OF AN ALREADY-SET OPTION IS A ZERO-WRITE NO-OP. A cold `read` of a live row answers
+ *   `Unowned(attrs)` (the house rule for a marker-less API, H1), so a live option needs
+ *   `adopt(true)` on its row; `reconcile` then observes the matching value and writes nothing.
+ *   ⛔ Fix-live-then-codify is fine for this family exactly because of that: the plan proves it.
+ * ⚠️ PRECONDITION BEFORE DECLARING THE WHOLE CONFIG DB: the dead `public_addr` entries
+ *   (homeflare-proxmox docs/completeness-tb4-sdn-ceph.md, T3) must be removed by hand with
+ *   `ceph config rm` first, so fossils are never adopted. `public_addr` is a lockout class and can
+ *   never be declared here; a single named option (like the first one) is not blocked by it.
+ * ⚠️ THE COMPARED VALUE IS THE MON DB's, not the effective one: a ceph.conf override or a compiled
+ *   default is out of scope (CephConf is its own family).
+ * ⚠️ `defaultRemovalPolicy: 'retain'`: removing a row stops managing it; `config rm` runs only when
+ *   a removal policy of `destroy` is chosen deliberately for that row.
+ */
+import * as nodes from '@distilled.cloud/proxmox/nodes';
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { mintTier } from '../proxmox/credentials.ts';
+import { runPve } from '../proxmox/distilled-pve.ts';
+import type { PveRequirements } from '../proxmox/resource-spec.ts';
+import { UNREADABLE, readOrUnreadable, unreadableWarning } from '../proxmox/unreadable-read.ts';
+import {
+  type CephConfigOptionAttributes,
+  type CephConfigOptionProps,
+  configOptionProblem,
+  findLive,
+  matches,
+} from './ceph-config-option-form.ts';
+import {
+  deleteCephConfigOption,
+  reconcileCephConfigOption,
+} from './ceph-config-option-reconcile.ts';
+
+export type {
+  CephConfigOptionAttributes,
+  CephConfigOptionProps,
+} from './ceph-config-option-form.ts';
+
+export interface CephConfigOption extends Resource<
+  'Ceph.ConfigOption',
+  CephConfigOptionProps,
+  CephConfigOptionAttributes,
+  never,
+  PveRequirements
+> {}
+
+export const CephConfigOption = Resource<CephConfigOption>('Ceph.ConfigOption', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** The whole mon config db, over the PVE API, on a read lease. */
+const readRows = (props: Pick<CephConfigOptionProps, 'target' | 'node'>) =>
+  runPve(props.target, 'read', false, nodes.listNodeCephCfgDb({ node: props.node }));
+
+const refuse = (props: CephConfigOptionProps) => {
+  const problem = configOptionProblem(props);
+  return problem === undefined ? Effect.void : Effect.fail(new Error(problem));
+};
+
+export const CephConfigOptionProvider = () =>
+  Provider.effect(
+    CephConfigOption,
+    Effect.succeed(
+      CephConfigOption.Provider.of({
+        list: () => Effect.succeed([]),
+
+        read: Effect.fn(function* ({ olds, output }) {
+          const live = findLive(yield* readRows(olds), olds.who, olds.name);
+          if (live === undefined) return undefined;
+          return output !== undefined ? live : Unowned(live);
+        }),
+
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* refuse(news);
+          if (output === undefined) return undefined;
+          if (output.who !== news.who || output.name !== news.name)
+            return { action: 'replace' } as const;
+          const rows = yield* readOrUnreadable(readRows(news));
+          if (rows === UNREADABLE) {
+            yield* unreadableWarning(
+              'Ceph.ConfigOption',
+              `${news.who}/${news.name}`,
+              news.target.mount,
+              mintTier(news.target, 'read'),
+            );
+            return { action: 'noop' } as const;
+          }
+          const live = findLive(rows, news.who, news.name);
+          return { action: matches(live, news) ? 'noop' : 'update' } as const;
+        }),
+
+        reconcile: ({ news }) => reconcileCephConfigOption(news, readRows(news), {}),
+
+        delete: ({ olds }) => deleteCephConfigOption(olds, readRows(olds), {}),
+      }),
+    ),
+  );

package/src/ceph/index.ts

@@ -1,12 +1,16 @@
 /**
- * Ceph providers for Alchemy — the mon-command transport and `Ceph.AuthEntity` (K-A4).
+ * Ceph providers for Alchemy — the mon-command transport, `Ceph.AuthEntity` (K-A4) and
+ * `Ceph.ConfigOption` (K-D).
  *
  * ⛔ THIS BARREL IS THE PUBLIC API, DELIBERATELY SMALLER THAN THE DIRECTORY — see
  *   `../openbao/index.ts`'s header for why. The allowlist internals (ceph-argv.ts), the parsing
- *   (ceph-auth-parse.ts) and the reconcile loop (ceph-auth-reconcile.ts) are exported by path for
- *   a future `CephConfigOption` (K-D) or a test to reach directly, not published here.
+ *   (ceph-auth-parse.ts) and the reconcile loops (ceph-auth-reconcile.ts,
+ *   ceph-config-option-reconcile.ts) are reached by path from tests, not published here.
  */
 export type { CephAuthEntityAttributes, CephAuthEntityProps, CephCaps } from './auth-entity.ts';
 export { CephAuthEntity, CephAuthEntityProvider } from './auth-entity.ts';
 export type { CephDial, CephExecResult, CephTransportOptions } from './ceph-transport.ts';
 export { assertFreshQuorum, runCephCommand, sshCephDial } from './ceph-transport.ts';
+export type { CephConfigOptionAttributes, CephConfigOptionProps } from './config-option.ts';
+export { CephConfigOption, CephConfigOptionProvider } from './config-option.ts';
+export { NAMED_CONFIG_OPTIONS } from './ceph-config-options.ts';

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);
 };