@bookedsolid/rea 0.49.0 → 0.50.0

package/dist/cli/doctor.js

@@ -20,6 +20,7 @@ import { computeHash } from '../audit/fs.js';
 import { PREPARE_COMMIT_MSG_BODY_MARKER, PREPARE_COMMIT_MSG_MARKER, } from './install/prepare-commit-msg.js';
 import { validateSettings } from '../config/settings-schema.js';
 import { checkSelfPinDeclaredSync, REA_PACKAGE_NAME, stripUtf8Bom } from './install/self-pin.js';
+import { checkGlobalCandidateSafety, checkReaDirSafety, checkRegistrySafety, globalRoot, isProjectTrusted, passwdHome, probeGlobalCliCapability, reaDir as globalReaDir, registryPath as globalRegistryPath, resolveGlobalCli, } from './global-cli.js';
 import { POLICY_FILE, REA_DIR, REGISTRY_FILE, getPkgVersion, log, reaPath } from './utils.js';
 function checkFileExists(label, filePath, fatal) {
     const exists = fs.existsSync(filePath);
@@ -2443,6 +2444,377 @@ export async function checkDelegationRoundTrip(baseDir) {
         detail: `probe via real .claude/hooks/delegation-capture.sh shell hook (hash=${storedHash.slice(0, 16)}, tag=${probeTag.slice(-8)})`,
     };
 }
+/** realpath a path, returning null on any failure (missing / ENOENT / loop). */
+function realpathOrNull(p) {
+    if (p === null)
+        return null;
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is the global tier vetoed by this repo's policy? Mirrors `shim_run`'s
+ * step 4-global-veto, which shells `rea hook policy-get runtime.allow_global_cli`:
+ *   - explicit `runtime.allow_global_cli: false`      → veto
+ *   - `true` / no `runtime:` block / EMPTY output      → allow
+ *   - a MISSING `.rea/policy.yaml`                      → allow (policy-get exits
+ *     0 with empty output for an absent file — the tier is ALLOWED)
+ *   - a PRESENT but malformed/unreadable policy         → veto (policy-get exits
+ *     non-zero → the shim's fail-closed branch refuses the tier)
+ *
+ * The missing-vs-malformed distinction is load-bearing: turning file-absent into
+ * a veto (the old behavior) misreported a trusted checkout with no policy.yaml as
+ * `policy-veto` while the shim actually runs the global CLI.
+ */
+function globalTierVetoed(baseDir) {
+    const policyPath = reaPath(baseDir, POLICY_FILE);
+    // Absent policy ⇒ allow (parity with `policy-get` exit 0 + empty output).
+    if (!fs.existsSync(policyPath))
+        return false;
+    try {
+        return loadPolicy(baseDir).runtime?.allow_global_cli === false;
+    }
+    catch {
+        // Present but malformed/unreadable ⇒ fail-closed veto (parity with the
+        // shim's non-zero `policy-get` branch).
+        return true;
+    }
+}
+/**
+ * THE single predicate (F1). Resolve which tier a checkout runs through and
+ * why, consuming `global-cli.ts`. Follows the authoritative Phase-3b decision
+ * tree top-to-bottom; each branch corresponds to a `shim_run` outcome so the
+ * parity test can assert byte-agreement on `tier` + `cliRealpath`.
+ *
+ * `home` defaults to the passwd-derived home (env-immune by design); tests
+ * inject a temp home to stay hermetic. `probeCapability` defaults to the shared
+ * `probeGlobalCliCapability` (spawns the real CLI); tests inject a fake to stay
+ * hermetic. NO CLI flag exposes either parameter.
+ */
+export function resolveGlobalCliTier(baseDir, home = passwdHome(), probeCapability = probeGlobalCliCapability) {
+    const inProjectReal = realpathOrNull(resolveCliDistPath(baseDir));
+    // In-project ALWAYS wins (shim step 4). The bash shim NEVER consults
+    // <home>/.rea when an in-project @bookedsolid/rea resolves — so we MUST
+    // short-circuit BEFORE any global-root safety / resolvability / candidate
+    // check. Otherwise a repo that vendors rea locally, whose user also has a
+    // stale or permission-damaged ~/.rea/cli, would get a FALSE [fail] from
+    // `rea doctor` even though the hooks happily run the in-project CLI. A
+    // broken or unused global tree must never produce a warn/fail here.
+    if (inProjectReal !== null) {
+        // Note the global root's mere existence (a benign [info]) but do NOT probe
+        // or sandbox it — it is unused, and the shim would never touch it.
+        const reason = fs.existsSync(globalRoot(home)) ? 'in-project-wins' : 'global-root-absent';
+        return { tier: 'in-project', reason, cliRealpath: inProjectReal, globalCliRealpath: null };
+    }
+    // Platform guard (before ANY global work). The global tier is POSIX-ONLY (v1):
+    // the bash `shim_global_entry_gate` calls `process.geteuid()`, which is
+    // undefined on Windows / Git Bash, so it falls back to `unavailable` and the
+    // tier NEVER resolves there. Mirror that gate EXACTLY (`geteuid` presence, not
+    // `platform === 'win32'`) so doctor never claims a global tier the hooks can't
+    // resolve. In-project resolution above is unaffected; this is NOT a fail —
+    // the feature simply isn't available on this platform.
+    if (typeof process.geteuid !== 'function') {
+        return {
+            tier: 'in-project',
+            reason: 'global-unavailable-platform',
+            cliRealpath: null,
+            globalCliRealpath: null,
+        };
+    }
+    // No in-project CLI — the global tier now governs.
+    // Global root absent → feature unused; the (empty) in-project resolver governs.
+    if (!fs.existsSync(globalRoot(home))) {
+        return {
+            tier: 'in-project',
+            reason: 'global-root-absent',
+            cliRealpath: null,
+            globalCliRealpath: null,
+        };
+    }
+    // <home>/.rea safety gate (shim A5.3a). Unsafe → shim degrades to no-CLI;
+    // doctor hard-fails.
+    const safety = checkReaDirSafety(home);
+    if (!safety.ok) {
+        return {
+            tier: 'in-project',
+            reason: 'global-root-unsafe',
+            cliRealpath: null,
+            globalCliRealpath: null,
+            safety,
+        };
+    }
+    // <home>/.rea/trusted-projects safety gate (shim A5.3b) — checked BEFORE
+    // membership, exactly as the shim's entry gate does. A symlinked / hardlinked
+    // / group-or-other-accessible (non-0600) registry makes the shim REFUSE the
+    // global CLI entirely (silent no-CLI fallback); doctor must NOT then report
+    // `trusted`/`global` — it would send the operator to the wrong remediation.
+    // An ABSENT registry is safe here (`ok:true, absent:true`) — it just means
+    // nothing is trusted yet, which the membership check below reports as
+    // `untrusted`.
+    const registrySafety = checkRegistrySafety(home);
+    if (!registrySafety.ok) {
+        return {
+            tier: 'in-project',
+            reason: 'global-registry-unsafe',
+            cliRealpath: null,
+            globalCliRealpath: null,
+            safety: registrySafety,
+        };
+    }
+    // Root present but no resolvable CLI under it (blessed-but-not-installed).
+    const globalCli = resolveGlobalCli(home);
+    if (globalCli === null) {
+        return {
+            tier: 'in-project',
+            reason: 'global-unresolvable',
+            cliRealpath: null,
+            globalCliRealpath: null,
+        };
+    }
+    const globalReal = realpathOrNull(globalCli);
+    // The remaining branches mirror the shim's GLOBAL path when the in-project
+    // resolver missed. The shim evaluates them in this order:
+    //   entry gate (registry membership) -> A1–A4 candidate sandbox -> veto.
+    // Reproduce that order so the tier verdict matches for every scenario.
+    // Trust-registry membership (shim A5.5) keyed on realpath(cwd). An untrusted
+    // checkout fails the entry gate BEFORE the candidate is ever sandboxed.
+    const cwdReal = realpathOrNull(baseDir);
+    if (cwdReal === null || !isProjectTrusted(cwdReal, home)) {
+        return {
+            tier: 'in-project',
+            reason: 'untrusted',
+            cliRealpath: null,
+            globalCliRealpath: globalReal,
+        };
+    }
+    // A1–A4 candidate sandbox (shim `shim_sandbox_check_global`). A
+    // blessed-but-hostile tree (symlinked index.js, foreign owner, wrong pkg
+    // name, …) makes the shim fall back to no-CLI — so doctor must NOT claim
+    // global. Reported as a fail row (a hostile global tree is worth surfacing).
+    const candSafety = checkGlobalCandidateSafety(globalCli, globalRoot(home), home);
+    if (!candSafety.ok) {
+        return {
+            tier: 'in-project',
+            reason: 'global-candidate-unsafe',
+            cliRealpath: null,
+            globalCliRealpath: globalReal,
+            candidateSafety: candSafety,
+        };
+    }
+    // Capability floor (shim step 4-global-veto read). The shim's veto step runs
+    // `<global CLI> hook policy-get runtime.allow_global_cli`; a CLI that predates
+    // that subcommand (older/manually-seeded ~/.rea/cli that still passes A1–A4)
+    // exits non-zero → the shim FAIL-CLOSES to no-CLI. Doctor must NOT then claim
+    // `global`. Probe `hook policy-get --help` on the sandbox-validated realpath;
+    // a failing probe reports NOT-global so operators get the right remediation
+    // (re-run `rea install --global`), not a false "global active".
+    if (!probeCapability(candSafety.realpath).ok) {
+        return {
+            tier: 'in-project',
+            reason: 'global-cli-incapable',
+            cliRealpath: null,
+            globalCliRealpath: globalReal,
+        };
+    }
+    // Project veto over the global tier (shim step 4-global-veto), read only
+    // AFTER the sandbox confirmed the candidate — exactly the shim's ordering.
+    if (globalTierVetoed(baseDir)) {
+        return {
+            tier: 'in-project',
+            reason: 'policy-veto',
+            cliRealpath: null,
+            globalCliRealpath: globalReal,
+        };
+    }
+    // Trusted + sandbox-clean + not vetoed → the global CLI is the active tier.
+    // Prefer the sandbox-validated realpath (identical to `globalReal` for a
+    // non-symlinked tree, but it is the exact path the shim would execute).
+    return {
+        tier: 'global',
+        reason: 'trusted',
+        cliRealpath: candSafety.realpath,
+        globalCliRealpath: globalReal,
+    };
+}
+/**
+ * Read the global CLI's declared version from the package.json that sits
+ * beside whichever install shape `resolveGlobalCli` matched. Best-effort;
+ * returns null when neither shape carries a readable version.
+ */
+function readGlobalCliVersion(home) {
+    const root = globalRoot(home);
+    const candidates = [
+        path.join(root, 'node_modules', '@bookedsolid', 'rea', 'package.json'),
+        path.join(root, 'package.json'),
+    ];
+    for (const p of candidates) {
+        const v = readPackageVersion(p);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+/**
+ * Render the global rea CLI section as flat `CheckResult` rows. Off-by-default
+ * quiet: when the global root does NOT exist, emits exactly ONE `info` row.
+ * When it exists, walks the authoritative decision tree via
+ * `resolveGlobalCliTier` and always names the RESOLVED REALPATH (helix-013.1
+ * lesson). A `global-root-unsafe` / `global-unresolvable` verdict yields a
+ * `fail` row so `rea doctor` exits 1.
+ *
+ * The registry named in these rows is the per-user GLOBAL-CLI TRUST REGISTRY
+ * (`<home>/.rea/trusted-projects`), NOT `.rea/registry.yaml` (the MCP
+ * fingerprint store).
+ */
+export function checkGlobalCli(baseDir, homeArg, probeCapability = probeGlobalCliCapability) {
+    // P2-2: the passwd lookup throws on an arbitrary/unmapped UID (containers,
+    // CI, `nobody`). The feature is off-by-default quiet — a passwd failure must
+    // degrade to ONE info row, NEVER abort `rea doctor` before any row renders.
+    let home;
+    if (homeArg !== undefined) {
+        home = homeArg;
+    }
+    else {
+        try {
+            home = passwdHome();
+        }
+        catch {
+            return [
+                {
+                    label: 'global rea CLI',
+                    status: 'info',
+                    detail: 'unavailable — could not resolve home directory from the password database',
+                },
+            ];
+        }
+    }
+    const dir = globalReaDir(home);
+    const reg = globalRegistryPath(home);
+    const root = globalRoot(home);
+    if (!fs.existsSync(root)) {
+        return [
+            {
+                label: 'global rea CLI',
+                status: 'info',
+                detail: 'not installed — in-project resolution active; see `rea install --global`',
+            },
+        ];
+    }
+    const tier = resolveGlobalCliTier(baseDir, home, probeCapability);
+    // POSIX-only tier on a platform without geteuid (Windows/Git Bash). A single
+    // benign info row — never a fail/warn (the feature is simply unavailable, and
+    // in-project resolution still governs).
+    if (tier.reason === 'global-unavailable-platform') {
+        return [
+            {
+                label: 'global rea CLI',
+                status: 'info',
+                detail: 'POSIX-only; not available on this platform',
+            },
+        ];
+    }
+    if (tier.reason === 'global-root-unsafe') {
+        const s = tier.safety;
+        return [
+            {
+                label: 'global rea CLI root safety',
+                status: 'fail',
+                detail: `${s.reason} — fix: \`${s.remediation}\``,
+            },
+        ];
+    }
+    if (tier.reason === 'global-registry-unsafe') {
+        const s = tier.safety;
+        return [
+            {
+                label: 'global-CLI trust registry safety',
+                status: 'fail',
+                detail: `${s.reason} — the shim refuses the global CLI while the trust registry is tampered; fix: \`${s.remediation}\``,
+            },
+        ];
+    }
+    if (tier.reason === 'global-unresolvable') {
+        return [
+            {
+                label: 'global rea CLI',
+                status: 'fail',
+                detail: `${root} present but no resolvable CLI (expected dist/cli/index.js) — re-run \`rea install --global\``,
+            },
+        ];
+    }
+    if (tier.reason === 'global-candidate-unsafe') {
+        const c = tier.candidateSafety;
+        return [
+            {
+                label: 'global rea CLI candidate safety',
+                status: 'fail',
+                detail: `blessed global CLI tree fails the sandbox (${c.code}): ${c.reason} — the shim refuses it; re-run \`rea install --global\` to reinstall a clean tree`,
+            },
+        ];
+    }
+    if (tier.reason === 'global-cli-incapable') {
+        return [
+            {
+                label: 'global rea CLI capability',
+                status: 'fail',
+                detail: `resolved global CLI at ${tier.globalCliRealpath} does not implement \`rea hook policy-get\` (needs ~0.26.0+) — the shim falls back to no-CLI at the veto step; re-run \`rea install --global\` to reinstall a current CLI`,
+            },
+        ];
+    }
+    // In-project wins: an in-project CLI resolved, so the shim never consults the
+    // global tree. Emit exactly ONE benign info row — NEVER a warn/fail for the
+    // unused global tree (it may legitimately be broken/stale and it does not
+    // matter here). We deliberately do NOT read the global version or sandbox it.
+    if (tier.reason === 'in-project-wins') {
+        return [
+            {
+                label: 'global rea CLI',
+                status: 'info',
+                detail: `present at ${root} but unused — this checkout resolves the in-project CLI (${tier.cliRealpath})`,
+            },
+        ];
+    }
+    const version = readGlobalCliVersion(home);
+    const rows = [
+        {
+            label: 'global rea CLI installed',
+            status: 'pass',
+            detail: `${version !== null ? `v${version} ` : ''}at ${tier.globalCliRealpath}`,
+        },
+    ];
+    switch (tier.reason) {
+        case 'policy-veto':
+            rows.push({
+                label: 'global rea CLI active tier',
+                status: 'info',
+                detail: 'policy.runtime.allow_global_cli: false — global tier vetoed by this repo; in-project required',
+            });
+            break;
+        case 'trusted':
+            rows.push({
+                label: 'global rea CLI active tier',
+                status: 'pass',
+                detail: `global — this checkout is trusted (in the global-CLI trust registry ${reg}); hooks run ${tier.cliRealpath}`,
+            });
+            rows.push({
+                label: 'global rea CLI residual risk',
+                status: 'info',
+                detail: `integrity relies on filesystem ownership of ${dir}; prefer in-project install for shared or CI checkouts`,
+            });
+            break;
+        case 'untrusted':
+            rows.push({
+                label: 'global rea CLI active tier',
+                status: 'warn',
+                detail: `this checkout is NOT in the global-CLI trust registry ${reg} — hooks FAIL-CLOSED here until you trust it; run: rea trust`,
+            });
+            break;
+    }
+    return rows;
+}
 /**
  * Assemble the full checklist for a given baseDir. Exported so tests can
  * exercise the conditional branching without capturing stdout from
@@ -2563,6 +2935,13 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
             detail: 'disabled via policy.review.codex_required — skipping Codex-related checks',
         });
     }
+    // 0.50.0 Phase 3b — global rea CLI resolution section. Off-by-default quiet:
+    // one `info` row when the global root is absent (the common case). When the
+    // root exists, the section names the active tier + resolved realpath and
+    // hard-fails on an unsafe/unresolvable global root. `globalHome` is the
+    // injectable passwd-home seam for hermetic tests; production passes nothing
+    // and the check reads the env-immune passwd home.
+    checks.push(...checkGlobalCli(baseDir, options.globalHome));
     return checks;
 }
 /**

package/dist/cli/global-cli.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Shared resolution + safety module for the opt-in GLOBAL rea CLI tier.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Phase 1b landed the bash shim's global resolver in `hooks/_lib/shim-runtime.sh`
+ * (`shim_global_entry_gate`, `shim_sandbox_check_global`): it resolves a
+ * per-user rea CLI from `<pw_dir>/.rea/cli`, gated by a per-user allow-list
+ * `<pw_dir>/.rea/trusted-projects`, and derives `pw_dir` from the PASSWORD
+ * DATABASE (`os.userInfo().homedir`), NEVER from `$HOME`/`$XDG_*` — an agent can
+ * set those in-process, so an env-derived root is the N3 redirect surface the
+ * tier closes. A trust root an agent can move is not a trust root.
+ *
+ * This module is the TypeScript MIRROR of that bash logic, consumed by the
+ * writer-side CLIs (`rea trust` / `rea untrust` / `rea install --global`) and by
+ * `rea doctor` (Phase 3b). The bash shim is the pre-CLI authority; a parity test
+ * binds this mirror to it (Phase 3b F1).
+ *
+ * TEST-ISOLATION CONTRACT
+ * -----------------------
+ * `pw_dir` is `os.userInfo().homedir` — passwd-derived and therefore ENV-IMMUNE
+ * by design, so tests CANNOT redirect it with `$HOME`/`$XDG`. Every function that
+ * touches the per-user root instead takes the home dir as a parameter that
+ * DEFAULTS to `os.userInfo().homedir` at the call site. Production entrypoints
+ * pass the default; tests inject a temp dir and stay hermetic without ever
+ * mutating the real `~/.rea/`. NO CLI FLAG exposes this parameter — that would
+ * re-introduce the env-redirect threat we are closing.
+ */
+/**
+ * The passwd-derived home directory. Isolated in one helper so every default
+ * parameter reads from the same source. Reads the password database via libuv
+ * `getpwuid_r`, NOT the environment. Throws on a squashed/absent passwd entry —
+ * the caller decides whether that is fatal (writer CLIs) or a silent
+ * tier-unavailable (the shim already handles that side in bash).
+ */
+export declare function passwdHome(): string;
+/** `<home>/.rea` — the per-user rea config root. */
+export declare function reaDir(home?: string): string;
+/** `<home>/.rea/cli` — where `npm install --prefix` drops the global CLI tree. */
+export declare function globalRoot(home?: string): string;
+/** `<home>/.rea/trusted-projects` — the per-user global-CLI allow-list. */
+export declare function registryPath(home?: string): string;
+/** One walked process's parent PID + command name. */
+export interface ProcInfo {
+    ppid: number;
+    comm: string;
+}
+/** Reads a single pid's `{ ppid, comm }`, or `null` when it can't be read. */
+export type ProcReader = (pid: number) => ProcInfo | null;
+/**
+ * Default process reader: Linux `/proc/<pid>/comm` + `/proc/<pid>/status`
+ * (PPid), else macOS/BSD `ps -o ppid=,comm= -p <pid>`. Best-effort — any
+ * failure returns `null` (which stops the walk fail-safe, never throwing).
+ * Mirrors `hooks/_lib/shim-cache.sh`'s session-token ancestry walk.
+ */
+export declare function defaultProcReader(pid: number): ProcInfo | null;
+/**
+ * Walk the parent-PID chain (bounded depth) looking for a `claude` /
+ * `claude-code` ancestor. Returns `true` only on a POSITIVE match; `false` on
+ * not-found OR any undeterminable step (fail-safe — an undeterminable walk
+ * degrades the guard to the `CLAUDE_PROJECT_DIR` signal alone, it never weakens
+ * to "allow" when ancestry says claude). A plain human terminal is not a claude
+ * descendant → no false positive; a human using Claude Code's `!` shell IS a
+ * descendant → correctly detected (trust is out-of-band).
+ */
+export declare function isClaudeAncestor(reader?: ProcReader, startPid?: number, maxHops?: number): boolean;
+/**
+ * Refuse a `~/.rea`-MUTATING command when running under a Claude Code agent
+ * session. TWO independent signals, either of which triggers a refusal:
+ *   1. `CLAUDE_PROJECT_DIR` is set + non-empty (rea's established "running under
+ *      Claude Code" signal — the reaRoot source in `src/cli/hook.ts`, set for
+ *      every agent Bash call).
+ *   2. A `claude` / `claude-code` process is an ancestor (codex P1: signal (1)
+ *      alone is bypassable — `CLAUDE_PROJECT_DIR= rea trust`,
+ *      `env -u CLAUDE_PROJECT_DIR rea trust` clear the var in the child, which a
+ *      subprocess CANNOT do for its own parent chain).
+ *
+ * The three mutating commands (`trust`, `untrust`, `install --global`) call this
+ * FIRST. Trust must be established by a HUMAN in a plain shell OUTSIDE the agent
+ * loop — the real dual-consent. The Write-tier scanner protects literal
+ * `~/.rea` writes; this closes the INDIRECT `rea trust`-writes-there path the
+ * scanner cannot see statically, AND which a bash command-string matcher cannot
+ * catch either (`node <path>/dist/cli/index.js trust`, `npx --no-install …
+ * trust`, wrapped shells all bypass a string matcher — the CLI is the only real
+ * chokepoint).
+ *
+ * NO override env — the strictness IS the dual-consent. Read-only commands
+ * (`trust --list`) are NOT guarded. Fail-safe: an undeterminable ancestry walk
+ * falls back to the `CLAUDE_PROJECT_DIR` signal alone (never weakens).
+ *
+ * Returns the refusal exit code (`1`) after emitting to stderr when governed;
+ * returns `null` when allowed. The `procReader` is injectable so tests stay
+ * hermetic + cross-platform.
+ */
+export declare function assertNotGovernedSession(cmdLabel: string, home?: string, deps?: {
+    procReader?: ProcReader;
+}): number | null;
+/**
+ * Fixed advisory header (design §6): the first line is bound verbatim; the two
+ * following `#` lines are advisory. Fixed content keeps the file byte-idempotent
+ * (devex F3). The header is `grep -Fxq`-immune: realpath queries start with `/`
+ * and never match a `#` line.
+ */
+export declare const REGISTRY_HEADER_LINES: readonly string[];
+/**
+ * Reject a project path that would corrupt the one-realpath-per-line registry
+ * format or be silently dropped by {@link writeRegistry}. Any C0 control
+ * character (`\x00`–`\x1f`: NUL, tab, LF, **CR**, …) breaks the whole-line
+ * contract — a `\r` in particular is treated as malformed by
+ * {@link isWellFormedMemberLine}, so a writer that skipped this check would
+ * report success and then silently drop the entry.
+ *
+ * This is the SHARED rejection point every registry-writing entrypoint
+ * (`rea trust`, `rea install --global --trust`) MUST consult BEFORE reporting
+ * success. Returns a short human-readable reason on rejection, or `null` when
+ * the path is safe to store.
+ */
+export declare function projectPathControlCharReason(realpath: string): string | null;
+/**
+ * Is `line` a well-formed member line? A member = a bare absolute path with no
+ * control characters (NUL / tab / LF / CR / …) and no surrounding whitespace (a
+ * leading-space line would never `grep -Fxq`-match a trimmed query, so we treat
+ * it as malformed). Comment/blank lines are NOT members (inert to the reader).
+ * The control-character test is the shared {@link projectPathControlCharReason}
+ * so the reader and the writer-side validators can never drift.
+ */
+export declare function isWellFormedMemberLine(line: string): boolean;
+/**
+ * Read the registry's MEMBER lines (design §6 reader). Skips `#`-prefixed and
+ * blank lines; returns every remaining non-blank line verbatim (no trimming —
+ * whole-line semantics mirror `grep -Fxq`). Absent/unreadable file → `[]`.
+ *
+ * This is a lenient read: it returns candidate lines as-stored (including any
+ * malformed content a hand-edit introduced) so the writer can normalize + drop
+ * them on the next rewrite. Use {@link isProjectTrusted} for a membership test.
+ */
+export declare function readRegistry(home?: string): string[];
+/**
+ * Exact whole-line membership test (mirrors the shim's `grep -Fxq -- "$p"`).
+ * `projRealpath` is expected to be an absolute realpath. A comment line can
+ * never match because queries start with `/`.
+ */
+export declare function isProjectTrusted(projRealpath: string, home?: string): boolean;
+/**
+ * Full-rewrite the registry (design §6 writer). NEVER appends. Normalizes the
+ * given paths: drops malformed lines (with a single one-line stderr notice),
+ * then dedups + sorts + joins with a single trailing LF after the fixed header.
+ * Byte-idempotent: `writeRegistry(home, readRegistry(home))` reproduces the file
+ * byte-for-byte for well-formed input.
+ *
+ * Atomicity: ensures `<home>/.rea` exists `0700`, writes the normalized content
+ * to `<home>/.rea/.trusted-projects.tmp.<pid>` under `umask 077` + explicit
+ * `chmod 0600`, then `rename()`s over the target. On failure the tmp file is
+ * unlinked and the original is left intact.
+ *
+ * SAFETY: this helper does NOT gate on ownership/symlink/permissions — callers
+ * MUST run {@link checkReaDirSafety} first and surface the remediation string.
+ * It ensures the dir exists but refuses nothing.
+ */
+export declare function writeRegistry(paths: string[], home?: string): void;
+/**
+ * Delete the registry file (used when `trust`/`untrust` empties it). Missing
+ * file is not an error. Does NOT touch the `<home>/.rea` dir.
+ */
+export declare function deleteRegistry(home?: string): void;
+export type SafetyReason = 'symlink' | 'not-dir' | 'not-file' | 'foreign-owner' | 'world-writable' | 'bad-mode' | 'bad-nlink';
+export interface SafetyOk {
+    ok: true;
+    /** True when the path does not exist yet (a to-be-created target — safe). */
+    absent: boolean;
+}
+export interface SafetyFail {
+    ok: false;
+    code: SafetyReason;
+    /** Human-readable reason (no remediation verb). */
+    reason: string;
+    /** The exact shell command to fix it (design §9 remediation strings). */
+    remediation: string;
+}
+export type SafetyResult = SafetyOk | SafetyFail;
+/**
+ * Validate `<home>/.rea` (mirrors shim A5.3a). Rejects a symlink, a non-dir, a
+ * foreign owner, or a group/other-writable dir (`mode & 0o022`). An ABSENT dir
+ * is safe (`{ ok: true, absent: true }`) — the writer creates it 0700. Never
+ * lstats `<home>` or above (firmlinks / BSD `/home` symlinks legitimately live
+ * there).
+ */
+export declare function checkReaDirSafety(home?: string): SafetyResult;
+/**
+ * Validate `<home>/.rea/trusted-projects` (mirrors shim A5.3b). Rejects a
+ * symlink, a non-regular file, a foreign owner, a group/other-ACCESSIBLE file
+ * (`mode & 0o077`, the strict 0600 mask — NOT the 0o022 dir mask), or a
+ * hardlinked file (`nlink !== 1`; a pre-existing in-project hardlink is a
+ * same-uid mutation primitive — codex P2-7). An ABSENT registry is safe
+ * (`{ ok: true, absent: true }`) — nothing is trusted yet.
+ */
+export declare function checkRegistrySafety(home?: string): SafetyResult;
+/**
+ * Probe the global CLI under `<home>/.rea/cli`: (1) the `npm install --prefix`
+ * shape `node_modules/@bookedsolid/rea/dist/cli/index.js`, then (2) the
+ * bare-drop fallback `dist/cli/index.js`. Returns the first existing candidate
+ * path, or `null` when neither exists (not installed). Pure existence probe —
+ * pair it with {@link checkGlobalCandidateSafety} to reproduce the shim's
+ * A1–A4 sandbox before treating the candidate as the active tier.
+ */
+export declare function resolveGlobalCli(home?: string): string | null;
+/**
+ * Read the `version` of the currently-installed global CLI from the
+ * `package.json` beside whichever install shape {@link resolveGlobalCli}
+ * matched: (1) `node_modules/@bookedsolid/rea/package.json` (npm-prefix shape),
+ * then (2) `<gRoot>/package.json` (bare-drop). Best-effort (BOM-tolerant); a
+ * leading UTF-8 BOM is stripped. Returns `null` when neither shape carries a
+ * readable non-empty `version`. Used by `rea install --global` to decide
+ * whether a requested `--version` differs from what is already on disk.
+ */
+export declare function installedGlobalCliVersion(home?: string): string | null;
+/** Result of the `rea hook policy-get` capability probe. */
+export interface GlobalCliCapability {
+    ok: boolean;
+    stderr?: string;
+}
+/**
+ * Prove a resolved global CLI implements `rea hook policy-get` — the subcommand
+ * the global-tier shim invokes for the `allow_global_cli` veto read
+ * (`shim_run` step 4-global-veto). Spawns `node <cliPath> hook policy-get
+ * --help`; a non-zero exit means the CLI predates the `hook policy-get`
+ * subcommand (~0.26.0) and the shim would fall back to no-CLI at the veto step.
+ *
+ * This is the ONE shared implementation consumed by both `rea install --global`
+ * (as the post-install backstop) and `rea doctor` (the global-tier floor), so
+ * the two surfaces never drift. Signature-compatible with install's injectable
+ * `probeCapability` dep — tests inject a fake to stay hermetic; NO CLI flag
+ * exposes it.
+ */
+export declare function probeGlobalCliCapability(cliPath: string): GlobalCliCapability;
+export type GlobalCandidateFailCode = 'symlink' | 'perm' | 'hardlink' | 'escapes-root' | 'shape' | 'no-rea-pkg' | 'unavailable';
+export interface GlobalCandidateOk {
+    ok: true;
+    /** `realpath(candidate)` — the validated path the shim would execute. */
+    realpath: string;
+}
+export interface GlobalCandidateFail {
+    ok: false;
+    code: GlobalCandidateFailCode;
+    /** Human-readable reason (no remediation verb). */
+    reason: string;
+}
+export type GlobalCandidateSafety = GlobalCandidateOk | GlobalCandidateFail;
+/**
+ * Reproduce the bash shim's A1–A4 candidate sandbox (`shim_sandbox_check_global`
+ * in `hooks/_lib/shim-runtime.sh`) over a resolved global CLI candidate. This is
+ * the missing half of {@link resolveGlobalCli}: existence alone is NOT enough to
+ * treat a candidate as runnable — the shim ALSO refuses a hostile/malformed tree
+ * (blessed-but-hostile), and `rea doctor` must refuse identically or it would
+ * claim `global` for a candidate the shim falls back from.
+ *
+ * Evaluation order mirrors the shim (cheapest/most-decisive first):
+ *   - A2  per-component `lstat` walk from the candidate UP TO AND INCLUDING
+ *         `<home>/.rea` (= `dirname(gRoot)`; STOP there — never lstat the home
+ *         dir or above, where firmlinks / BSD `/home` symlinks legitimately
+ *         live). Reject ANY symlink component, foreign owner, group/other-write
+ *         (`mode & 0o022`), or a device-number change vs `gRoot` (mount/bind
+ *         aliasing). The candidate `index.js` itself must have `nlink === 1`.
+ *   - A1  `realpath(candidate)` contained in `realpath(gRoot)`.
+ *   - A4  realpath ends in `dist/cli/index.js` (ALWAYS-on for the global tier).
+ *   - A3  an ancestor `package.json` (≤20 hops) has `name === "@bookedsolid/rea"`
+ *         AND that `package.json` has `nlink === 1`.
+ *
+ * `unavailable` (an `lstat`/`realpath` that threw — ENOENT / automount) is
+ * surfaced as a fail here because doctor treats "sandbox did not confirm safe"
+ * the same as "not the active tier": the shim likewise does NOT set the global
+ * CLI in that case. Callers map ANY `ok:false` to "global tier NOT active".
+ */
+export declare function checkGlobalCandidateSafety(candidate: string, gRoot: string, home?: string): GlobalCandidateSafety;