@bookedsolid/rea 0.49.0 → 0.50.0

package/dist/cli/trust.js

@@ -0,0 +1,222 @@
+/**
+ * `rea trust [<path>]` / `rea untrust [<path>]` / `rea trust --list`
+ *
+ * Operator-facing management of the per-user global-CLI allow-list
+ * `<home>/.rea/trusted-projects` (design §9). Blessing a project into this
+ * registry is the A5 CONSENT gate that lets the opt-in global rea CLI tier
+ * (`hooks/_lib/shim-runtime.sh`) govern that checkout without adding
+ * `@bookedsolid/rea` to a shared `package.json`.
+ *
+ * The registry can only ever ENABLE enforcement, never DISABLE a gate — so
+ * mutating it is a deliberate act of vouching for a checkout's policy, not a
+ * privilege expansion. (The governed-session mutation guard is Phase 4.)
+ *
+ * TEST ISOLATION: `home` + `cwd` are injectable parameters that default to the
+ * passwd home + `process.cwd()`. Tests inject a temp dir and never touch the
+ * real `~/.rea/`. NO CLI FLAG exposes `home` — an env/flag-redirectable trust
+ * root would re-open the N3 surface the tier closes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNotGovernedSession, checkReaDirSafety, checkRegistrySafety, deleteRegistry, isProjectTrusted, passwdHome, projectPathControlCharReason, readRegistry, registryPath, writeRegistry, } from './global-cli.js';
+import { err, log } from './utils.js';
+/** Resolve the injected-or-passwd home; err + non-zero on a passwd failure. */
+function resolveHome(injected) {
+    if (injected !== undefined)
+        return injected;
+    try {
+        return passwdHome();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Print a safety refusal (reason + exact fix) to stderr. */
+function printRefusal(fail) {
+    err(fail.reason);
+    err(`  fix: ${fail.remediation}`);
+}
+/**
+ * `rea trust [<path>]`. Returns the process exit code.
+ *   0 — trusted (or already trusted; idempotent)
+ *   1 — `<home>/.rea` is unsafe (symlink/foreign/world-writable), or no passwd
+ *   2 — path does not exist / is not a directory / contains illegal bytes
+ */
+export function runTrust(options = {}) {
+    const home = resolveHome(options.home);
+    if (home === undefined) {
+        err('cannot determine your home directory from the password database — refusing');
+        return 1;
+    }
+    // Refuse under a governed agent session BEFORE any path resolution / FS work.
+    const governed = assertNotGovernedSession('trust', home, options.procReader !== undefined ? { procReader: options.procReader } : {});
+    if (governed !== null)
+        return governed;
+    const cwd = options.cwd ?? process.cwd();
+    const rawTarget = options.path ?? cwd;
+    const abs = path.resolve(cwd, rawTarget);
+    let real;
+    try {
+        real = fs.realpathSync(abs);
+    }
+    catch {
+        err(`path does not exist: ${abs}`);
+        return 2;
+    }
+    let st;
+    try {
+        st = fs.statSync(real);
+    }
+    catch {
+        err(`path does not exist: ${abs}`);
+        return 2;
+    }
+    if (!st.isDirectory()) {
+        err(`not a directory: ${abs}`);
+        return 2;
+    }
+    // Reject ANY control character (CR/LF/NUL/tab/…) BEFORE reporting success:
+    // writeRegistry would silently drop such a line as malformed, so a
+    // success message without persistence would be a lie. Shared validator so
+    // `rea install --global --trust` refuses identically.
+    const ctrl = projectPathControlCharReason(real);
+    if (ctrl !== null) {
+        err(`invalid path: ${ctrl}: ${JSON.stringify(real)}`);
+        return 2;
+    }
+    const safety = checkReaDirSafety(home);
+    if (!safety.ok) {
+        printRefusal(safety);
+        return 1;
+    }
+    if (isProjectTrusted(real, home)) {
+        log(`Already trusted: ${real}`);
+        return 0;
+    }
+    const members = readRegistry(home);
+    members.push(real);
+    writeRegistry(members, home);
+    log(`Trusted: ${real}`);
+    return 0;
+}
+/**
+ * `rea untrust [<path>]`. Removes the exact-match line for both the resolved
+ * absolute path AND its realpath (when resolvable), so a since-moved or
+ * symlinked project can still be untrusted. Empties → delete the file.
+ *   0 — removed, or nothing to remove (idempotent)
+ *   1 — `<home>/.rea` is unsafe, or no passwd
+ */
+export function runUntrust(options = {}) {
+    const home = resolveHome(options.home);
+    if (home === undefined) {
+        err('cannot determine your home directory from the password database — refusing');
+        return 1;
+    }
+    // Refuse under a governed agent session BEFORE any path resolution / FS work.
+    const governed = assertNotGovernedSession('untrust', home, options.procReader !== undefined ? { procReader: options.procReader } : {});
+    if (governed !== null)
+        return governed;
+    const cwd = options.cwd ?? process.cwd();
+    const rawTarget = options.path ?? cwd;
+    const abs = path.resolve(cwd, rawTarget);
+    // Remove both the raw absolute form AND the realpath (design §6): a member was
+    // stored as realpath, but the operator may pass either form. Display the
+    // realpath when resolvable (symmetry with `trust`), else the raw abs form
+    // (the project may have moved/been deleted).
+    const candidates = new Set();
+    candidates.add(abs);
+    let display = abs;
+    try {
+        const real = fs.realpathSync(abs);
+        candidates.add(real);
+        display = real;
+    }
+    catch {
+        /* not resolvable (project moved/deleted) — the abs form still matches */
+    }
+    const safety = checkReaDirSafety(home);
+    if (!safety.ok) {
+        printRefusal(safety);
+        return 1;
+    }
+    const members = readRegistry(home);
+    const kept = members.filter((m) => !candidates.has(m));
+    const removed = members.length - kept.length;
+    if (removed === 0) {
+        log(`Not trusted; nothing to remove: ${display}`);
+        return 0;
+    }
+    if (kept.length === 0) {
+        deleteRegistry(home);
+        log(`Untrusted: ${display}`);
+        log('trusted-projects is now empty; removed the registry file');
+        return 0;
+    }
+    writeRegistry(kept, home);
+    log(`Untrusted: ${display}`);
+    return 0;
+}
+/**
+ * `rea trust --list`. Prints the registry members one per line to stdout
+ * (pipe-friendly). Perm-gated: a tampered `<home>/.rea` or registry file →
+ * exit 1 with remediation.
+ *   0 — printed (possibly "No trusted projects.")
+ *   1 — tampered root, or no passwd
+ */
+export function runTrustList(options = {}) {
+    const home = resolveHome(options.home);
+    if (home === undefined) {
+        err('cannot determine your home directory from the password database — refusing');
+        return 1;
+    }
+    const dirSafety = checkReaDirSafety(home);
+    if (!dirSafety.ok) {
+        printRefusal(dirSafety);
+        return 1;
+    }
+    const regSafety = checkRegistrySafety(home);
+    if (!regSafety.ok) {
+        printRefusal(regSafety);
+        return 1;
+    }
+    // Absent registry OR present-but-empty → same friendly line.
+    if (regSafety.absent) {
+        log('No trusted projects.');
+        return 0;
+    }
+    const members = readRegistry(home);
+    if (members.length === 0) {
+        log('No trusted projects.');
+        return 0;
+    }
+    for (const m of members) {
+        process.stdout.write(`${m}\n`);
+    }
+    return 0;
+}
+/**
+ * Register `rea trust [path]` (with `--list`) and `rea untrust [path]`.
+ * The thin action wrappers translate the run functions' exit codes into
+ * `process.exit`. `registryPath` is imported only to keep the module's public
+ * surface discoverable for doctor (Phase 3b) — no behavior here.
+ */
+export function registerTrustCommands(program) {
+    void registryPath; // referenced for tree-shake stability / doctor cohesion
+    program
+        .command('trust [path]')
+        .description('Bless a project into the per-user global-CLI allow-list (<home>/.rea/trusted-projects). Default path = cwd. `--list` prints the current registry.')
+        .option('--list', 'print the trusted-projects registry instead of adding a path')
+        .action((pathArg, opts) => {
+        const code = opts.list === true
+            ? runTrustList({})
+            : runTrust(pathArg !== undefined ? { path: pathArg } : {});
+        process.exit(code);
+    });
+    program
+        .command('untrust [path]')
+        .description('Remove a project from the per-user global-CLI allow-list. Default path = cwd. Empties the registry file when the last entry is removed.')
+        .action((pathArg) => {
+        const code = runUntrust(pathArg !== undefined ? { path: pathArg } : {});
+        process.exit(code);
+    });
+}

package/dist/hooks/bash-scanner/protected-scan.d.ts

@@ -51,6 +51,30 @@ export interface ProtectedScanContext {
      * pollute stdout.
      */
     stderr?: (line: string) => void;
+    /**
+     * The passwd-derived absolute home directory
+     * (`os.userInfo().homedir` — libuv `getpwuid_r`, NOT `$HOME` /
+     * `$XDG_*`). When set, `<passwdHome>/.rea` becomes a FIRST-CLASS
+     * absolute protected root: any write whose resolved target (or
+     * resolved parent + basename, for create-paths) lands anywhere under
+     * it is REFUSED. This protects the safe-global-CLI trust root
+     * (`~/.rea/cli`, `~/.rea/trusted-projects`) the shim-runtime derives
+     * the same way (`shim_global_entry_gate` → `os.userInfo().homedir`).
+     *
+     * Passwd-derived ONLY — never `$HOME` / `$XDG_*`: an agent can set
+     * those in-process, so an env-derived root is exactly the redirect
+     * surface this gate closes. A trust root an agent can move is not a
+     * trust root (same rule as the shim).
+     *
+     * When UNDEFINED the global-root gate is disabled entirely (the
+     * scanner behaves byte-identically to the pre-feature build — the
+     * legacy `~/`-is-dynamic fail-closed posture is preserved). The two
+     * production callers (`rea hook scan-bash`, `protected-paths-bash-
+     * gate`) populate it from `os.userInfo().homedir`; a passwd lookup
+     * failure leaves it undefined (feature-absent parity, mirroring the
+     * shim's silent "unavailable").
+     */
+    passwdHome?: string;
 }
 interface EffectivePatterns {
     /** Full effective protected set (default OR override + invariants − relax). */

package/dist/hooks/bash-scanner/protected-scan.js

@@ -270,7 +270,7 @@ function checkPathProtected(pathLc, effective, options) {
  * blocks on either match. Either may be a sentinel string for
  * outside-root / expansion-uncertainty.
  */
-function normalizeTarget(reaRoot, raw, form) {
+function normalizeTarget(reaRoot, raw, form, passwdHome) {
     // 1. Strip surrounding matching quotes (the parser already strips
     //    them for SglQuoted/DblQuoted, but a literal node can still hold
     //    `'.rea/HALT'` in pathological cases). Defensive.
@@ -331,11 +331,47 @@ function normalizeTarget(reaRoot, raw, form) {
             resolvedLc: null,
         };
     }
-    // 2c. Codex round 1 F-24: `~/` or bare `~` expands to $HOME at
-    //     runtime, which may equal reaRoot (any project rooted at the
-    //     user's home dir). Treat as dynamic to be safe — refuse on
-    //     uncertainty rather than guess at HOME.
-    if (t === '~' || t.startsWith('~/') || t.startsWith('~')) {
+    // 2c. Tilde handling. `~` and `~/…` bash-expand to the home dir at
+    //     runtime. Two postures:
+    //
+    //     - passwdHome AVAILABLE (safe-global-CLI gate active): resolve
+    //       `~`/`~/…` against the PASSWD-derived home so the downstream
+    //       global-root + project-relative checks see a concrete absolute
+    //       path. This is what lets `~/.rea/x` REFUSE (lands under the
+    //       protected `<passwdHome>/.rea` root) while `~/.reafoo` /
+    //       `~/.rea-backup` ALLOW (siblings — boundary-anchored, NOT under
+    //       the root). We resolve against passwd-home, never `$HOME`: the
+    //       goal is to refuse writes that WOULD land in the passwd-derived
+    //       `~/.rea` (the common case where `$HOME` == passwd-home); if an
+    //       agent moved `$HOME`, its `~/.rea/x` cannot reach the real root
+    //       anyway, so approximating with passwd-home is the safe
+    //       direction.
+    //
+    //     - passwdHome UNDEFINED (feature-absent parity): keep the
+    //       original Codex round 1 F-24 fail-closed posture — `~` may
+    //       equal reaRoot (project rooted at home), so refuse on
+    //       uncertainty.
+    //
+    //     `~user`, `~+`, `~-` and other tilde-prefix forms are NEVER
+    //     statically resolvable (a foreign user's home / `$PWD` / `$OLDPWD`)
+    //     → always fail-closed, regardless of passwdHome.
+    if (t === '~' || t.startsWith('~/')) {
+        if (passwdHome !== undefined && passwdHome.startsWith('/')) {
+            // Drop the leading `~`, keep the `/tail` (empty for bare `~`).
+            t = t === '~' ? passwdHome : passwdHome + t.slice(1);
+            // Fall through to normalization with the resolved absolute path.
+        }
+        else {
+            return {
+                pathLc: '__rea_unresolved_expansion__',
+                sentinel: 'expansion',
+                original: raw,
+                resolvedLc: null,
+            };
+        }
+    }
+    else if (t.startsWith('~')) {
+        // ~user / ~+ / ~- — not statically resolvable → refuse on uncertainty.
         return {
             pathLc: '__rea_unresolved_expansion__',
             sentinel: 'expansion',
@@ -363,6 +399,32 @@ function normalizeTarget(reaRoot, raw, form) {
     }
     const hadDotDot = normalized.includes('..');
     const collapsed = collapseDotDot(abs);
+    // 4b. Passwd-derived `<passwdHome>/.rea` global-root gate. This runs
+    //     BEFORE the isInsideRoot early-returns because the absolute
+    //     `~/.rea` root is (in the common case) OUTSIDE the project root —
+    //     without this, an absolute write like
+    //     `/Users/me/.rea/trusted-projects` falls through to the
+    //     `__outside_root_allowed` branch and is ALLOWED. This is NOT a
+    //     naive `realpath(target)` prefix check: it reuses the same
+    //     lexical `collapsed` form (handles non-existent create-path
+    //     leaves + `..`-normalization with no FS access) plus the
+    //     symlink-walk-to-nearest-existing-ancestor resolver (handles a
+    //     symlinked parent / symlinked home) — the identical machinery the
+    //     project-relative path logic below uses. Bare cwd-relative writes
+    //     (`cd ~/.rea && > trusted-projects`) are covered upstream by the
+    //     walker's cwd model, which flags the `cd` target (a
+    //     `cwd_protected_unresolvable` detection carrying `~/.rea`) and
+    //     routes it through THIS function.
+    if (passwdHome !== undefined && passwdHome.startsWith('/')) {
+        if (targetHitsGlobalReaRoot(collapsed, passwdHome)) {
+            return {
+                pathLc: '__rea_global_root__',
+                sentinel: 'global_root',
+                original: raw,
+                resolvedLc: null,
+            };
+        }
+    }
     // 5. Outside-root sentinel — fires ONLY for paths that contained
     //    `..` segments and resolved outside REA_ROOT (helix-022 #1
     //    semantic). A bare absolute path like `/tmp/foo` is just an
@@ -488,6 +550,68 @@ function realpathSafe(p) {
         return null;
     }
 }
+/**
+ * Case-insensitive "is `p` inside directory `dir` (or equal to it)".
+ * Both are absolute lexical paths without trailing slashes. The `+ '/'`
+ * boundary anchor is load-bearing: it keeps `<home>/.rea-backup` and
+ * `<home>/.reafoo` OUT of the `<home>/.rea` root (siblings, not
+ * descendants). Case-insensitive to match the project-relative matcher
+ * (macOS APFS default is case-insensitive — helix-015 #2), so `~/.REA`
+ * is caught too.
+ */
+function isUnderDirCI(p, dir) {
+    const pl = p.toLowerCase();
+    const dl = dir.toLowerCase();
+    return pl === dl || pl.startsWith(dl + '/');
+}
+/**
+ * True when the resolved write target lands under the passwd-derived
+ * `<passwdHome>/.rea` root. Checks TWO forms, mirroring the
+ * project-relative logic:
+ *
+ *   1. Lexical `collapsed` (from `collapseDotDot`, no FS access) against
+ *      the lexical `<passwdHome>/.rea`. This is what catches non-existent
+ *      create-path leaves (`> ~/.rea/new-registry`) and `..`-normalized
+ *      escapes — `realpath(target)` would ENOENT-fail on those, which is
+ *      exactly the naive-approach failure codex flagged (P1-4).
+ *
+ *   2. The symlink-resolved form (walk to the nearest existing ancestor,
+ *      realpath it, re-attach the unresolved tail) against
+ *      `realpath(<passwdHome>/.rea)`. This catches a symlinked parent
+ *      (an in-project symlink whose target is under `~/.rea`) or a
+ *      symlinked home dir (`/Users` ↔ firmlink, `/home` ↔ symlink).
+ *
+ * The `<passwdHome>/.rea` root need NOT exist on disk — the whole point
+ * is to refuse an agent CREATING it (seeding a fake `trusted-projects`
+ * registry), so form (1) fires regardless of existence.
+ */
+function targetHitsGlobalReaRoot(collapsed, passwdHome) {
+    // Lexical global root, e.g. `/Users/me/.rea`. `path.join` normalizes a
+    // trailing slash on passwdHome; collapseDotDot strips any `..` in it.
+    const globalRoot = collapseDotDot(path.join(passwdHome, '.rea'));
+    // Form 1: lexical (create-path + `..`-safe, no FS).
+    if (isUnderDirCI(collapsed, globalRoot))
+        return true;
+    // Form 2: symlink-resolved parent. Best-effort — a dynamic sentinel
+    // (symlink cycle / depth cap) is left to the caller's step-6 handling.
+    let resolved = null;
+    try {
+        resolved = resolveSymlinksWalkUp(collapsed);
+    }
+    catch {
+        resolved = null;
+    }
+    if (typeof resolved === 'string') {
+        const realGlobalRoot = realpathSafe(globalRoot) ?? globalRoot;
+        if (isUnderDirCI(resolved, realGlobalRoot))
+            return true;
+        // Defensive: when `<passwdHome>/.rea` does not exist, realpathSafe
+        // returns the lexical form — still compare against it directly.
+        if (isUnderDirCI(resolved, globalRoot))
+            return true;
+    }
+    return false;
+}
 /**
  * Walk to the nearest existing ancestor, realpath-it, then re-attach
  * the unresolved tail.
@@ -800,7 +924,28 @@ export function scanForProtectedViolations(ctx, detections) {
         }
         if (d.path.length === 0)
             continue;
-        const norm = normalizeTarget(ctx.reaRoot, d.path, d.form);
+        const norm = normalizeTarget(ctx.reaRoot, d.path, d.form, ctx.passwdHome);
+        if (norm.sentinel === 'global_root') {
+            return blockVerdict({
+                reason: [
+                    'PROTECTED PATH (bash): write to the per-user rea trust root (~/.rea) blocked.',
+                    '',
+                    `  Resolved under:  ${ctx.passwdHome ?? '~'}/.rea`,
+                    `  Original token:  ${norm.original}`,
+                    `  Detected as:     ${d.form}`,
+                    '',
+                    '  Rule: the passwd-derived ~/.rea tree (the safe-global-CLI trust root —',
+                    "        ~/.rea/cli and ~/.rea/trusted-projects) is unreachable via agent",
+                    '        writes, including create-paths, cwd-relative writes after `cd ~/.rea`,',
+                    '        mv/cp/install destinations, and symlinked parents. A human must edit',
+                    '        it directly. This root is derived from the password database, never',
+                    '        $HOME/$XDG_* — an agent-movable root would defeat the protection.',
+                ].join('\n'),
+                hitPattern: '(~/.rea global trust root)',
+                detectedForm: d.form,
+                ...(d.position.line > 0 ? { sourcePosition: d.position } : {}),
+            });
+        }
         if (norm.sentinel === 'expansion') {
             return blockVerdict({
                 reason: [

package/dist/hooks/protected-paths-bash-gate/index.js

@@ -26,11 +26,29 @@
  */
 import path from 'node:path';
 import fs from 'node:fs';
+import os from 'node:os';
 import { parse as parseYaml } from 'yaml';
 import { checkHalt, formatHaltBanner } from '../_lib/halt-check.js';
 import { parseHookPayload, MalformedPayloadError, TypePayloadError, readStdinWithTimeout, } from '../_lib/payload.js';
 import { runProtectedScan } from '../bash-scanner/index.js';
 import { appendAuditRecord, InvocationStatus, Tier } from '../../audit/append.js';
+/**
+ * Passwd-derived absolute home for the `~/.rea` global-root scanner gate.
+ * `os.userInfo().homedir` (libuv `getpwuid_r`), NEVER `$HOME` / `$XDG_*`.
+ * Undefined on passwd-lookup failure or a non-absolute home → gate
+ * disabled (feature-absent parity, mirroring `shim_global_entry_gate`).
+ */
+function passwdDerivedHome() {
+    try {
+        const home = os.userInfo().homedir;
+        if (typeof home === 'string' && home.startsWith('/'))
+            return home;
+    }
+    catch {
+        /* no passwd entry → gate disabled */
+    }
+    return undefined;
+}
 function loadPolicyPermissive(reaRoot) {
     const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
     const empty = { protectedRelax: [] };
@@ -121,7 +139,11 @@ export async function runProtectedPathsBashGate(options = {}) {
     if (patchSession.length > 0) {
         relax.push('.claude/hooks/');
     }
-    // 7. Scan.
+    // 7. Scan. Passwd-derived home enables the `~/.rea` global-root gate
+    //    (safe-global-CLI). Never `$HOME` / `$XDG_*` — an agent can move
+    //    those in-process; a passwd-lookup failure disables the gate
+    //    (feature-absent parity, mirroring the shim's silent "unavailable").
+    const passwdHome = passwdDerivedHome();
     const verdict = runProtectedScan({
         reaRoot,
         policy: {
@@ -130,6 +152,7 @@ export async function runProtectedPathsBashGate(options = {}) {
                 : {}),
             protected_paths_relax: relax,
         },
+        ...(passwdHome !== undefined ? { passwdHome } : {}),
         stderr: (line) => writeStderr(line),
     }, cmd);
     // 8. Audit.

package/dist/policy/loader.d.ts

@@ -315,6 +315,13 @@ declare const PolicySchema: z.ZodObject<{
     }, {
         enabled?: boolean | undefined;
     }>>;
+    runtime: z.ZodOptional<z.ZodObject<{
+        allow_global_cli: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        allow_global_cli?: boolean | undefined;
+    }, {
+        allow_global_cli?: boolean | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -399,6 +406,9 @@ declare const PolicySchema: z.ZodObject<{
     bootstrap_allowlist?: {
         enabled: boolean;
     } | undefined;
+    runtime?: {
+        allow_global_cli?: boolean | undefined;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -483,6 +493,9 @@ declare const PolicySchema: z.ZodObject<{
     bootstrap_allowlist?: {
         enabled?: boolean | undefined;
     } | undefined;
+    runtime?: {
+        allow_global_cli?: boolean | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -380,6 +380,50 @@ const BootstrapAllowlistPolicySchema = z
     enabled: z.boolean().default(true),
 })
     .strict();
+/**
+ * 0.50.0 — runtime resolver policy. Currently the sole field is
+ * `allow_global_cli`, the OPTIONAL project-level veto over the global rea
+ * CLI resolver tier in `hooks/_lib/shim-runtime.sh`.
+ *
+ * The global tier is gated PRIMARILY by a per-user registry (A5 consent
+ * gate). This project-level knob is a SECONDARY veto layered on top —
+ * registry can only ENABLE the tier; policy can only further-RESTRICT it.
+ * The asymmetry is deliberate: a project can refuse the global CLI even
+ * when the machine's registry has blessed it, but a project can NEVER
+ * turn the tier ON when the registry has not.
+ *
+ * Tri-state (locked):
+ *   - absent   → permitted (registry alone governs — the veto is silent)
+ *   - `true`   → permitted (affirm; identical effect to absent, but
+ *                explicit — a project can pin "yes, the global tier is
+ *                fine here")
+ *   - `false`  → veto (the project refuses the global tier even when the
+ *                registry has blessed it)
+ *
+ * `.optional()` — NOT `.default()` — so absent stays distinguishable from
+ * an explicit `false`. The distinction is load-bearing: the shim's veto
+ * wiring (a later phase) must treat "field omitted" (registry governs)
+ * differently from "explicitly false" (project refuses), and a schema
+ * default would collapse the two.
+ *
+ * Deliberately OFF / absent by default — no profile and no shipped
+ * `.rea/policy.yaml` carries a `runtime:` block. The global CLI tier is a
+ * per-developer / per-machine opt-in via the per-user registry; the
+ * project-level veto exists only for repos that want to affirmatively
+ * refuse it, so its natural state is "not present."
+ *
+ * Strict mode rejects unknown keys so a typo (`allow_globcli`,
+ * `allow_global_clis`) fails loudly at policy load rather than silently
+ * omitting the veto. The `runtime` schema is REQUIRED even though it holds
+ * a single optional field: the top-level `PolicySchema` is `.strict()`, so
+ * without a `runtime` schema ANY `policy.yaml` carrying a `runtime:` block
+ * would fail to load entirely.
+ */
+const RuntimePolicySchema = z
+    .object({
+    allow_global_cli: z.boolean().optional(),
+})
+    .strict();
 const PolicySchema = z
     .object({
     version: z.string(),
@@ -459,6 +503,14 @@ const PolicySchema = z
     // `hooks/_lib/bootstrap-allowlist.sh` and
     // `THREAT_MODEL.md §5.X`.
     bootstrap_allowlist: BootstrapAllowlistPolicySchema.optional(),
+    // 0.50.0 runtime resolver policy — currently only the optional
+    // `allow_global_cli` project-level veto over the global rea CLI
+    // resolver tier. `.optional()` so a vanilla install with no
+    // `runtime:` block leaves the tier governed by the per-user registry
+    // alone (absent → permitted). See `RuntimePolicySchema` for the full
+    // tri-state contract and the registry-primary / policy-secondary
+    // asymmetry.
+    runtime: RuntimePolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/types.d.ts

@@ -474,6 +474,37 @@ export interface GatewayHealthPolicy {
 export interface GatewayPolicy {
     health?: GatewayHealthPolicy;
 }
+/**
+ * Runtime resolver policy (0.50.0+).
+ *
+ * Governs the global rea CLI resolver tier in
+ * `hooks/_lib/shim-runtime.sh`. The tier is enabled PRIMARILY by a
+ * per-user registry (an A5 consent gate). `allow_global_cli` is the
+ * OPTIONAL project-level SECONDARY veto: registry can only ENABLE the
+ * tier, this knob can only further-RESTRICT it. A project can refuse the
+ * global CLI even when the registry has blessed it, but a project can
+ * never turn the tier ON when the registry has not.
+ *
+ * See `RuntimePolicy.allow_global_cli` for the tri-state contract.
+ */
+export interface RuntimePolicy {
+    /**
+     * Project-level veto over the global rea CLI resolver tier. Tri-state
+     * (locked):
+     *   - `undefined` (omitted) → permitted; the per-user registry alone
+     *     governs the tier. This is the default state — no shipped profile
+     *     or `.rea/policy.yaml` carries a `runtime:` block.
+     *   - `true`  → permitted; explicit affirmation (same effect as absent,
+     *     but pins "the global tier is fine in this repo").
+     *   - `false` → veto; the project refuses the global tier even when the
+     *     registry has blessed the machine.
+     *
+     * Modeled as an optional boolean (not defaulted) so absent stays
+     * distinguishable from an explicit `false` — the shim's veto wiring
+     * treats "registry governs" and "project refuses" as different states.
+     */
+    allow_global_cli?: boolean;
+}
 export interface Policy {
     version: string;
     profile: string;
@@ -575,6 +606,15 @@ export interface Policy {
      * architect locked).
      */
     bootstrap_allowlist?: BootstrapAllowlistPolicy;
+    /**
+     * Runtime resolver policy (0.50.0+). Currently only the optional
+     * `allow_global_cli` project-level veto over the global rea CLI
+     * resolver tier in `hooks/_lib/shim-runtime.sh`. Absent → the tier is
+     * governed by the per-user registry alone; `false` → the project
+     * refuses the tier even when registry-blessed; `true` → explicit
+     * affirmation. See `RuntimePolicy` for the full contract.
+     */
+    runtime?: RuntimePolicy;
 }
 /**
  * Bootstrap allowlist policy (0.49.0+).