@bookedsolid/rea 0.48.1 → 0.49.0

package/THREAT_MODEL.md

@@ -495,6 +495,76 @@ Ref: `hooks/settings-protection.sh:86-336`, `.claude/hooks/settings-protection.s
 
 ---
 
+### 5.23 Bootstrap Allowlist (0.49.0)
+
+**Threat:** Pre-0.49.0, `rea init` wrote `.claude/hooks/blocked-paths-bash-gate.sh` and `.claude/hooks/protected-paths-bash-gate.sh` shims that depend on the `@bookedsolid/rea` CLI being resolvable from `node_modules/`. The init flow did NOT add the dep to the consumer's `package.json`. Any fresh clone of a consumer repo + `pnpm install` produced a brick state where the shims found no CLI and refused 100% of `Bash` calls — including the very `pnpm add -D @bookedsolid/rea` that would recover the install. Hot consumer paths (helixir, BST clients) routinely tripped this whenever a fresh checkout landed.
+
+Two paired fixes ship in 0.49.0. The structural fix is `rea init` self-pin (`src/cli/install/self-pin.ts`, §5.23.1 below). The bootstrap allowlist is the safety net that recovers consumers who upgraded to a hooks-shipping `rea init` but were NEVER on the self-pinned init flow.
+
+**Scope:** The bootstrap allowlist is a narrow CLI-missing recovery surface. It permits a small set of legitimate-shape PM invocations (bare `pnpm install` / `npm ci` / `yarn install`; `pnpm add -D @bookedsolid/rea` and its npm/yarn equivalents in BARE form) to flow when the CLI is unreachable AND `package.json` already declares `@bookedsolid/rea`. The precondition exists to differentiate consumers who have already opted into `@bookedsolid/rea` (post-`rea init`) from arbitrary repos. It is NOT a defense against agent-initiated package.json mutations — a path-based blocklist on `package.json` cannot distinguish agent writes from PM-tool writes, so that surface is explicitly out of scope here.
+
+**Mitigations:**
+
+- `hooks/_lib/bootstrap-allowlist.sh` exposes `bootstrap_allowlist_check`. The blocked-paths and protected-paths Bash gates consult it ONLY when (a) the CLI is unreachable AND (b) the substring scan said "this payload looks like it would write a protected/blocked path." When the allowlist returns "allow", the shim exits 0 BEFORE the CLI-missing banner fires.
+- Allowlist is ALWAYS-ON by default (`policy.bootstrap_allowlist.enabled: true`). No env-var ever participates in the decision — `REA_BOOTSTRAP_ALLOW=1`, `REA_FORCE_BOOTSTRAP=*`, etc. are inert. Operators who want to opt out set `policy.bootstrap_allowlist.enabled: false`.
+- Precondition: `<project>/package.json` exists, parses as a strict JSON object, and declares `@bookedsolid/rea` under `dependencies` OR `devDependencies` (NOT `optionalDependencies`, NOT `peerDependencies`, NOT `pnpm.overrides`). Without this declaration, the allowlist refuses every payload. The precondition is "consumer has run `rea init`, so a self-pin already exists" — not a defense against an attacker forging the declaration.
+- The argv shape allowlist is FIXED in the helper, not consumer-mutable from policy. Recognised shapes are precisely:
+  - pnpm: `pnpm install`, `pnpm i`, with optional `--frozen-lockfile` / `--no-frozen-lockfile`; `pnpm add -D @bookedsolid/rea` (bare); `pnpm add --save-dev @bookedsolid/rea` (bare).
+  - npm: `npm install`, `npm i`, `npm ci`; `npm install -D @bookedsolid/rea` (bare); `npm install --save-dev @bookedsolid/rea` (bare).
+  - yarn: `yarn`, `yarn install`; `yarn add -D @bookedsolid/rea` (bare); `yarn add --dev @bookedsolid/rea` (bare).
+  - corepack: `corepack enable`, `corepack enable {pnpm,yarn,npm}`, `corepack prepare {pnpm,yarn,npm}@<ver> --activate`.
+
+  Bun, `pnpm fetch`, `--global`/`-g`, any `--registry=` override, and any `--ignore-scripts` flag are deliberately OUT of the allowlist for 0.49.0 — adding any of them would broaden the contract beyond "recover the brick state."
+
+  **R6-P2 (codex round 6):** `@bookedsolid/rea` is accepted ONLY in its bare form. Version-pinned shapes `@bookedsolid/rea@<anything>` are REFUSED — this includes dist-tags (`@latest`, `@next`), exact versions (`@0.48.0`), and semver ranges (`@^0.50.0`). Version selection is `rea init` (caret pin at install time) and `rea upgrade` (managed-caret bump, audited via the TS path) territory; the Bash-tier bootstrap path must not allow a CLI-missing session to retarget the trusted gate binary by pinning a chosen version. `corepack prepare pnpm@<ver> --activate` retains the version slot because that selects the package-manager binary (out-of-scope for rea's gate trust), but the rea package spec itself is locked to bare.
+- Multi-segment payloads refuse: the gate's `cmd-segments.sh` segmentation runs ahead of the allowlist, and the helper itself re-counts segments as defense in depth. Any `&&`, `;`, `||`, `|`, newline, or backgrounding refuses.
+- argv[0] basename match is exact-string with no slashes — `./pnpm install`, `/usr/local/bin/pnpm install`, `pnpm/x install` all refuse. The character class for argv[0] is `[A-Za-z0-9._-]`.
+- The package-spec match for `@bookedsolid/rea` is the BARE form only (R6-P2). All versioned forms `@bookedsolid/rea@<ver>` refuse — dist-tags, exact versions, semver ranges, shell metacharacters, command substitutions, and empty `@`-suffixes all hit the refuse branch uniformly.
+- Quoted argv forms (`pnpm "install"`, `'pnpm' install`) refuse-fallthrough. This is a defense feature — a quoted token does NOT match the bare-string shape lists, so any attacker laundering through quotes hits the refuse branch.
+- IFS leakage is defeated by `local IFS=$' \t\n'` declared inside `bootstrap_allowlist_check`. A hostile parent shell that sets `IFS=:` (or worse) cannot reshape the splitter.
+- The `$proj` directory is realpath-resolved via `cd "$CLAUDE_PROJECT_DIR" && pwd -P` before the allowlist sees it. A hostile workspace whose `CLAUDE_PROJECT_DIR` symlinks outside the actual project does not get the allowlist sandbox: the hashing + audit-emit still references the resolved path, NOT the symlink.
+- Every `allow` verdict emits a `rea.bash.bootstrap_allow` audit record through the hash-chained log. Audit fields are fixed-shape: `shim`, `pm`, `argv_shape`, `argv_segments_sha256`, `package_json_sha256`, `package_json_declares_rea`, `declared_version_range` (truncated to 16 chars), `cli_resolution: "missing"`, `policy_enabled`. If `node` is unavailable, or the audit append fails (read-only `.rea/`, hasher missing, disk full), the allowlist REFUSES rather than allowing silently — every allow MUST be auditable.
+- **R19-P1 (codex round 19):** `package.json` is in `blocked_paths` on the `bst-internal` and `bst-internal-no-codex` profiles (and the dogfood `.rea/policy.yaml`). This narrows the Edit/Write-tier forge surface specifically — an L1 Bash session cannot first `Edit` `package.json` to ADD a `@bookedsolid/rea` declaration and then route an otherwise-disallowed PM command through the allowlist's "consumer already declares `@bookedsolid/rea`" precondition. The blocklist gates Write/Edit/MultiEdit/NotebookEdit tool calls via the existing path-based machinery (`settings-protection.sh`, `blocked-paths-enforcer.sh`); it does NOT gate PM-induced writes to the manifest (those are explicitly out of scope, below). External profiles inherit `enabled: true` from the schema default but do NOT add `package.json` to their blocked_paths list (consumers may need to edit package.json freely; the `bst-internal` posture is the strict one).
+
+**Trust boundary:** The bootstrap allowlist is reachable only when the CLI is unreachable. The CLI-present path through both gates flows through the full Node-binary scanner (`src/hooks/bash-scanner/`). Once `pnpm install` completes and `node_modules/@bookedsolid/rea/dist/cli/index.js` resolves, every subsequent Bash call is scanned by the canonical scanner — the allowlist no longer participates.
+
+**Out of scope (explicit non-claim):**
+
+- The allowlist does NOT prevent an attacker who can already write Bash payloads from invoking PM commands that mutate `package.json`. A path-based blocklist on `package.json` (re-added by R19-P1 above) defends against AGENT writes only — it cannot distinguish PM-tool writes from agent writes because the PM is invoked by Bash and the manifest mutation happens inside the PM process, not in argv that a static analyzer can see reliably. Defending against agent-initiated PM mutations requires a different abstraction (process-tree-aware policy, per-tool capability tokens, or operator-confirmed PM invocations) — none of which ship in 0.49.0. The R6-onward "manifest-write static analyzer" surface that would have attempted to close this gap was deliberately removed in R17 (scope-cut) because a path-based blocklist is the wrong abstraction for PM-process introspection. The 0.49.0 contract is solely: "recover the brick state without requiring the operator to disable hooks, AND gate agent-initiated Edit/Write to the manifest."
+
+**Residual risks:**
+
+- **CLOSED in R6-P2:** Pre-R6 the allowlist accepted `@bookedsolid/rea@<version>` and let a CLI-missing session forge a downgrade attack against a known-vulnerable historical rea version. R6-P2 strips all version-pinned forms from the allowlist; only the bare `@bookedsolid/rea` spec is permitted. Version selection lives in `rea init` (caret pin at install) and `rea upgrade` (managed-caret bump under audit). A CLI-missing Bash session can no longer retarget the trusted gate binary.
+- An attacker who controls a npm registry mirror could publish a malicious `@bookedsolid/rea` once the allowlist runs the install. Mitigation: npm OIDC provenance is verified by `rea init` post-install (out of scope here). Operators on a hostile mirror are exposed regardless of the allowlist. R6-P2 reduces the attack surface because the version range is bounded by the consumer's existing self-pin — the mirror cannot choose which version to ship; the consumer's caret pin does.
+- The `corepack prepare pnpm@<ver> --activate` shape allows arbitrary `<ver>` strings (within the 64-char `[A-Za-z0-9._^~+\-]` charset). This selects the package-MANAGER binary, not rea itself; consumers on a hostile pnpm version have other problems.
+- The allowlist's policy-enabled probe relies on a narrow inline YAML regex (block-form scan, flow-form match). A malformed or pathologically-shaped `bootstrap_allowlist:` block reads as "unparseable" → schema default = enabled. This is intentional: a corrupted policy MUST NOT silently strip the bootstrap recovery path. The full zod schema validation at CLI load time catches typos / wrong types at the canonical boundary.
+
+Ref: `hooks/_lib/bootstrap-allowlist.sh`, `hooks/blocked-paths-bash-gate.sh`, `hooks/protected-paths-bash-gate.sh`, `src/policy/loader.ts` (`BootstrapAllowlistPolicySchema`), `__tests__/hooks/bootstrap-allowlist/`.
+
+#### 5.23.1 `rea init` self-pin (paired structural fix)
+
+**Threat:** Same brick state described in §5.23. The bootstrap allowlist recovers consumers who get stuck; self-pin prevents them from getting stuck in the first place.
+
+**Mitigations:**
+
+- `rea init` writes `@bookedsolid/rea` as a `^<cli-version>` caret pin in the consumer's `devDependencies`. Workspace-root semantics: the upward walk finds the FIRST `package.json` from the invocation dir and stops; sub-package installs land at the sub-package, not the workspace root.
+- Idempotent: a re-run produces byte-identical `package.json`. Indent, EOL (LF vs CRLF), and trailing-newline are sniffed from the existing file and preserved.
+- Existing different version → warn + skip. The operator's pin is not mutated (covers exact-version reproducibility pins, workspace-relative paths, older-or-newer pins that disagree with the running CLI).
+- Dogfood short-circuit: `pkg.name === '@bookedsolid/rea'` skips silently.
+- `rea doctor` runs `checkSelfPinDeclared` and emits a `fail` row when `.claude/hooks/` is installed but no pin is declared. The recovery instruction names `rea upgrade` (which re-runs the self-pin step). This is the brick-state detector.
+- `rea upgrade` re-runs `selfPinRea` so legacy installs that pre-date 0.49.0 self-heal on the next upgrade. Same warn-and-skip posture on existing different version.
+
+**Trust boundary:** Self-pin only writes the `package.json` entry. It does not invoke any package manager, does not run lifecycle scripts, does not modify the lockfile. The consumer's next `pnpm install` is what materializes the install — same trust posture as a manual `pnpm add -D @bookedsolid/rea` would have.
+
+**Residual risks:**
+
+- An operator who runs `rea init` in a repo whose `package.json` is owned by a parent workspace will get a pin in the parent (the closest package.json found by the upward walk). This matches the architect's locked decision. Operators with per-package install discipline should run `rea init` from each sub-package directory after seeding a sub-package package.json.
+- An operator who pinned a workspace-relative path (`workspace:^`, `file:../rea`) gets `skipped-different` on every re-run. This is the correct behavior — the operator owns the pin. The doctor's `pass` detection accepts any non-empty string in dependencies/devDependencies as a valid pin (including workspace specs).
+
+Ref: `src/cli/install/self-pin.ts`, `src/cli/init.ts`, `src/cli/upgrade.ts`, `src/cli/doctor.ts` (`checkSelfPinDeclaredCheck`), `__tests__/cli/self-pin.test.ts`.
+
+---
+
 ## 6. Residual Risks and Open Issues
 
 | Risk                                                          | Severity | Status / Tracking              |

package/dist/cli/doctor.d.ts

@@ -29,6 +29,7 @@ export declare function checkFingerprintStore(baseDir: string): Promise<CheckRes
  */
 export declare const EXPECTED_AGENTS: string[];
 export declare const EXPECTED_HOOKS: string[];
+export declare function checkSelfPinDeclaredCheck(baseDir: string): CheckResult;
 /**
  * 0.30.0 Class M — validate `.claude/settings.json` against the zod
  * schema in `src/config/settings-schema.ts`.

package/dist/cli/doctor.js

@@ -19,6 +19,7 @@ import { DELEGATION_SIGNAL_TOOL_NAME } from '../audit/delegation-event.js';
 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 { POLICY_FILE, REA_DIR, REGISTRY_FILE, getPkgVersion, log, reaPath } from './utils.js';
 function checkFileExists(label, filePath, fatal) {
     const exists = fs.existsSync(filePath);
@@ -255,6 +256,240 @@ function checkHooksInstalled(baseDir) {
     }
     return { label: 'hooks installed + executable', status: 'fail', detail: issues.join('; ') };
 }
+/**
+ * 0.49.0 — fail when `.claude/hooks/` is present but no `@bookedsolid/rea`
+ * pin is declared in the consumer's `package.json`. This is the "brick
+ * state" detector — a fresh clone of a consumer repo whose hook shims
+ * exist but whose dependency declaration is missing is exactly the
+ * scenario the bash-gate bootstrap allowlist (paired Fix B) recovers
+ * from. Doctor surfaces it loudly so the operator runs `rea upgrade`
+ * (which re-runs the self-pin step) before assuming the shims have
+ * drifted.
+ *
+ * Statuses:
+ *   - `pass`  — hooks installed AND pin declared (in dependencies or
+ *               devDependencies).
+ *   - `pass`  — no `.claude/hooks/` directory (check is N/A; the
+ *               brick scenario does not exist).
+ *   - `pass`  — `pkg.name === '@bookedsolid/rea'` (dogfood — never
+ *               self-pins).
+ *   - `warn`  — hooks installed but NO `package.json` upward. The
+ *               bootstrap allowlist requires a pkg.json precondition,
+ *               so without one the gates cannot self-recover anyway.
+ *               We warn rather than fail to avoid spamming non-Node
+ *               consumers who landed `.claude/hooks/` through a
+ *               separate vendoring flow.
+ *   - `fail`  — hooks installed, package.json found, no rea pin.
+ *               This is the brick state.
+ *   - `fail`  — package.json exists but is malformed/non-object.
+ */
+/**
+ * R18-P1 (codex round 18) / R19-P2 (codex round 19): resolve the
+ * `@bookedsolid/rea` version that the consumer's HOOK SCRIPTS will
+ * actually invoke at runtime.
+ *
+ * Two layouts the shim chain accepts (mirrors `resolveCliDistPath`
+ * above):
+ *
+ *   1. `<baseDir>/node_modules/@bookedsolid/rea/package.json` — the
+ *      consumer install (`pnpm i @bookedsolid/rea`). The version is
+ *      that file's `version` field.
+ *
+ *   2. `<baseDir>/dist/cli/index.js` present AND `<baseDir>/package.json`
+ *      has `name === '@bookedsolid/rea'` — the rea-repo dogfood
+ *      after `pnpm build`. The dist is a build output of the same
+ *      package.json that declares the rea CLI, so its `version`
+ *      field is the CLI version the dogfood hooks will resolve.
+ *
+ * Pre-R18 doctor passed `getPkgVersion()` (the version of whatever
+ * `rea` binary launched `rea doctor`) into the pin-compat check.
+ * That caused false failures whenever an operator ran a newer
+ * GLOBAL CLI (e.g. `rea@0.50.0`) against a repo whose `package.json`
+ * intentionally pinned an older but compatible version. The repo's
+ * hooks resolve the LOCAL CLI; the global binary is irrelevant.
+ *
+ * R19-P2 narrows the fix: when neither layout resolves, return
+ * `null` — and the caller SKIPS the compat check entirely (no
+ * fallback to `getPkgVersion()`). Fresh clones (pre-`pnpm install`)
+ * and broken dist builds fall into this branch and now pass instead
+ * of false-failing.
+ *
+ * Returns `null` on any read/parse error or when no recognized
+ * layout matches. Best-effort, single read per call. Never throws.
+ */
+function resolveLocalCliVersion(baseDir) {
+    // Layout 1: consumer install via node_modules.
+    const nmPkgPath = path.join(baseDir, 'node_modules', '@bookedsolid', 'rea', 'package.json');
+    const nmVersion = readPackageVersion(nmPkgPath);
+    if (nmVersion !== null)
+        return nmVersion;
+    // Layout 2: rea-repo dogfood. The CLI is `<baseDir>/dist/cli/
+    // index.js`; the source of truth for its version is the SAME
+    // `<baseDir>/package.json` that declares it. Guard with name-
+    // match so we never mis-identify a consumer's package.json
+    // (which lacks the dist build) as a rea install.
+    const distCliPath = path.join(baseDir, 'dist', 'cli', 'index.js');
+    if (!fs.existsSync(distCliPath))
+        return null;
+    const dogfoodPkgPath = path.join(baseDir, 'package.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(dogfoodPkgPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    raw = stripUtf8Bom(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const pkg = parsed;
+    if (pkg['name'] !== REA_PACKAGE_NAME)
+        return null;
+    const version = pkg['version'];
+    return typeof version === 'string' && version.length > 0 ? version : null;
+}
+/**
+ * Helper for `resolveLocalCliVersion` — read a package.json's
+ * `version` field with the same BOM tolerance + defensive parse
+ * posture as the rest of the self-pin surface. Returns `null` on
+ * any failure.
+ */
+function readPackageVersion(pkgPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    raw = stripUtf8Bom(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const version = parsed['version'];
+    return typeof version === 'string' && version.length > 0 ? version : null;
+}
+export function checkSelfPinDeclaredCheck(baseDir) {
+    const label = `${REA_PACKAGE_NAME} declared in package.json`;
+    try {
+        // R11-P3 (codex round 11): pass the running CLI version so the
+        // check verifies the declared range admits it (not just that
+        // it's declared). Pre-R11 the check was presence-only — a stale
+        // pin like `"0.48.0"` reported pass even though the running
+        // CLI was 0.49.x. Doctor's job is to catch skew BEFORE it
+        // bricks the consumer.
+        //
+        // R18-P1 (codex round 18): prefer the LOCAL CLI's version
+        // (`<baseDir>/node_modules/@bookedsolid/rea`) over the global
+        // invoker's. The consumer's HOOKS resolve the local install at
+        // runtime, so that's the version the pin must admit.
+        //
+        // R19-P2 (codex round 19): when the local CLI is absent (no
+        // node_modules layout AND no dogfood dist build), SKIP the
+        // compat check entirely. Falling back to the invoker version
+        // (the R18-P1 implementation) still produced false-fails on
+        // fresh clones — an operator's newer global `rea@0.50.0`
+        // running doctor against a repo pinned `^0.49.0` before
+        // `pnpm install` saw fail-incompatible despite no real
+        // problem. With local CLI absent we cannot determine what
+        // version the hooks will run, so we report pass and let
+        // pnpm's own resolution-time errors surface any actual pin
+        // skew during install. The existing `fail-no-pin` /
+        // `fail-malformed` arms continue to catch the brick states.
+        const resolvedCliVersion = resolveLocalCliVersion(baseDir);
+        const result = checkSelfPinDeclaredSync(baseDir, resolvedCliVersion ?? undefined);
+        switch (result.kind) {
+            case 'pass':
+                return {
+                    label,
+                    status: 'pass',
+                    detail: `declared in ${result.declaredIn} as ${result.declaredRange}`,
+                };
+            case 'pass-no-hooks':
+                return {
+                    label,
+                    status: 'pass',
+                    detail: 'no .claude/hooks/ — check is N/A',
+                };
+            case 'pass-dogfood':
+                return {
+                    label,
+                    status: 'pass',
+                    detail: 'dogfood install (pkg.name === @bookedsolid/rea)',
+                };
+            case 'pass-no-pkg':
+                return {
+                    label,
+                    status: 'warn',
+                    detail: 'hook shims installed but no package.json found upward — bash gates will refuse on fresh clones (the bootstrap allowlist requires a package.json precondition)',
+                };
+            case 'fail':
+                return {
+                    label,
+                    status: 'fail',
+                    detail: `hook shims at ${path.relative(baseDir, result.hooksDir)} but ${REA_PACKAGE_NAME} is not declared in ${path.relative(baseDir, result.packageJsonPath)}. ` +
+                        `Fresh clones will brick (bash gates refuse without a CLI). Run \`rea upgrade\` to self-heal.`,
+                };
+            case 'fail-malformed':
+                return {
+                    label,
+                    status: 'fail',
+                    detail: `${path.relative(baseDir, result.packageJsonPath)} is missing or not a valid JSON object`,
+                };
+            // R10-P2 (codex round 10): symlinked package.json. Surface
+            // the write-path's refusal verbatim so the operator sees the
+            // same diagnostic at doctor time as they would at upgrade
+            // time (avoiding drift between the two surfaces).
+            case 'fail-symlink':
+                return {
+                    label,
+                    status: 'fail',
+                    detail: result.reason,
+                };
+            // R11-P3 (codex round 11): declared range doesn't admit the
+            // running CLI. Surface the helper's full reason — it includes
+            // the recovery command and the explainer.
+            case 'fail-incompatible':
+                return {
+                    label,
+                    status: 'fail',
+                    detail: result.reason,
+                };
+            // R11-P3: declared as workspace:* / file:.. / git URL / dist-
+            // tag. Can't statically determine whether the resolved version
+            // admits the running CLI; surface as fail so the operator
+            // audits the resolution path.
+            case 'fail-non-semver':
+                return {
+                    label,
+                    status: 'fail',
+                    detail: result.reason,
+                };
+        }
+    }
+    catch (e) {
+        return {
+            label,
+            status: 'fail',
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
 /**
  * 0.30.0 Class M — validate `.claude/settings.json` against the zod
  * schema in `src/config/settings-schema.ts`.
@@ -2239,6 +2474,12 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
         checkRegistryParses(baseDir, registryPath),
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
+        // 0.49.0 brick-state detector. Hook shims installed without a
+        // self-pin in package.json is the exact scenario the bash-gate
+        // bootstrap allowlist (paired fix) recovers from. Doctor surfaces
+        // it as a hard FAIL so the operator runs `rea upgrade` (which
+        // re-runs self-pin) before assuming the gates are broken.
+        checkSelfPinDeclaredCheck(baseDir),
         checkSettingsJson(baseDir),
         // 0.30.0 Class M — strict zod schema check of the full
         // .claude/settings.json shape. Complements checkSettingsJson

package/dist/cli/init.d.ts

@@ -55,6 +55,18 @@ export interface ResolvedConfig {
         email?: string;
         skipMerge?: boolean;
     };
+    /**
+     * R12-P1 (codex round 12 / 0.49.0): bootstrap_allowlist.enabled.
+     * Preserved across re-init so an operator who opted out via
+     * `bootstrap_allowlist: { enabled: false }` doesn't get silently
+     * re-enabled by the next `rea init`. Seeded from the layered
+     * profile on first install (only `bst-internal` currently pins
+     * `enabled: true` explicitly; every other profile inherits the
+     * zod schema default which is also `true`). When `undefined`, the
+     * writer emits no block — consumers fall through to the schema
+     * default at policy load.
+     */
+    bootstrapAllowlistEnabled?: boolean;
     fromReagent: boolean;
     reagentPolicyPath: string | null;
     reagentNotices: string[];

package/dist/cli/init.js

@@ -7,6 +7,7 @@ import { AutonomyLevel } from '../policy/types.js';
 import { HARD_DEFAULTS, loadProfile, mergeProfiles } from '../policy/profiles.js';
 import { copyArtifacts } from './install/copy.js';
 import { ensureReaGitignore } from './install/gitignore.js';
+import { checkUpgradeBlockingPin, selfPinRea } from './install/self-pin.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
 import { EXPECTED_HOOKS } from './doctor.js';
 import { installCommitMsgHook } from './install/commit-msg.js';
@@ -303,6 +304,9 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase, exi
         // `enabled: false`). Conditional spread so undefined → key omitted
         // (the field is exact-optional).
         ...attributionConfigSpread(layeredBase, existingPolicy),
+        // R12-P1 (codex round 12): preserve bootstrap_allowlist.enabled
+        // so an operator opt-out survives `rea init` re-runs.
+        ...bootstrapAllowlistConfigSpread(layeredBase, existingPolicy),
         fromReagent,
         reagentPolicyPath,
         reagentNotices: [],
@@ -348,6 +352,43 @@ function attributionConfigSpread(layered, existing) {
         },
     };
 }
+/**
+ * R12-P1 (codex round 12 / 0.49.0): same shape-spread helper for
+ * `bootstrap_allowlist.enabled`. Precedence:
+ *
+ *   1. Existing on-disk policy `bootstrap_allowlist.enabled` (highest).
+ *   2. Layered profile's `bootstrap_allowlist.enabled` (e.g.
+ *      `bst-internal` pins `true` explicitly).
+ *   3. Omitted — the writer skips emission and consumers fall through
+ *      to the zod schema default at policy-load time.
+ *
+ * The omit-vs-emit distinction matters: external profiles
+ * (open-source, client-engagement, etc.) leave the block unset, and
+ * we want a clean policy.yaml that does NOT mention the field unless
+ * the operator or the profile explicitly pinned it. That preserves
+ * the existing emit-only-when-set posture for the other preserved
+ * keys (local_review, commit_hygiene).
+ *
+ * Pre-R12 the field was dropped entirely on re-init — an operator
+ * who opted out via `bootstrap_allowlist: { enabled: false }` got
+ * silently flipped back to `true` (schema default). This helper
+ * closes that drop class.
+ */
+function bootstrapAllowlistConfigSpread(layered, existing) {
+    // Existing on-disk policy wins — preserves explicit opt-out.
+    if (existing?.bootstrapAllowlistEnabled !== undefined) {
+        return { bootstrapAllowlistEnabled: existing.bootstrapAllowlistEnabled };
+    }
+    // Profile-layer value next — `bst-internal` pins `true` explicitly
+    // so the on-disk policy shows the pinned posture rather than
+    // relying on the schema default.
+    const fromProfile = layered.bootstrap_allowlist?.enabled;
+    if (fromProfile !== undefined) {
+        return { bootstrapAllowlistEnabled: fromProfile };
+    }
+    // Neither set — omit from the emitted policy.yaml.
+    return {};
+}
 /**
  * G6 — Codex install-assist probe.
  *
@@ -563,6 +604,20 @@ function readExistingPolicyForPreservation(targetDir) {
                 out.attributionCoAuthor = preserved;
         }
     }
+    // R12-P1 (codex round 12 / 0.49.0): preserve bootstrap_allowlist
+    // across re-init. Critical for the documented opt-out — an
+    // operator who set `bootstrap_allowlist: { enabled: false }` MUST
+    // NOT have it silently flipped back to `true` by the next init.
+    // Inline (`bootstrap_allowlist: { enabled: false }`) and block
+    // (`bootstrap_allowlist:\n  enabled: false`) forms fold to the
+    // same parsed object via yaml.parse.
+    const bootstrapAllowlist = policy['bootstrap_allowlist'];
+    if (bootstrapAllowlist !== null && typeof bootstrapAllowlist === 'object') {
+        const ba = bootstrapAllowlist;
+        if (typeof ba['enabled'] === 'boolean') {
+            out.bootstrapAllowlistEnabled = ba['enabled'];
+        }
+    }
     return out;
 }
 function readExistingInstalledAt(policyPath) {
@@ -720,6 +775,16 @@ function writePolicyYaml(targetDir, config, layered) {
             lines.push(`  refuse_at_commits: ${config.commitHygieneRefuseAtCommits}`);
         }
     }
+    // R12-P1 (codex round 12 / 0.49.0): emit bootstrap_allowlist when
+    // the layered profile or the existing on-disk policy declared it.
+    // When unset, omit the block — consumers fall through to the zod
+    // schema default (`enabled: true`). The block form (vs flow form)
+    // mirrors what `bst-internal.yaml` emits so dogfood byte-fidelity
+    // is preserved.
+    if (config.bootstrapAllowlistEnabled !== undefined) {
+        lines.push(`bootstrap_allowlist:`);
+        lines.push(`  enabled: ${config.bootstrapAllowlistEnabled ? 'true' : 'false'}`);
+    }
     lines.push(``);
     fs.writeFileSync(policyPath, lines.join('\n'), 'utf8');
     return policyPath;
@@ -1425,6 +1490,9 @@ export async function runInit(options) {
             // seeded from the layered profile. Same precedence as the
             // wizard path above. Conditional spread for exact-optional.
             ...attributionConfigSpread(layeredBase, existingPolicy),
+            // R12-P1 (codex round 12): preserve bootstrap_allowlist.enabled
+            // so an operator opt-out survives `rea init` re-runs.
+            ...bootstrapAllowlistConfigSpread(layeredBase, existingPolicy),
             fromReagent,
             reagentPolicyPath,
             reagentNotices,
@@ -1459,6 +1527,40 @@ export async function runInit(options) {
             cancel('Init cancelled — no files written.');
         }
     }
+    // R11-P1 (codex round 11): blocking-pin pre-flight. Same security
+    // guarantee as `runUpgrade`'s pre-flight (R9-P1) but for the init
+    // surface. If `package.json` already pins `@bookedsolid/rea` to a
+    // version that does NOT admit the installed CLI version
+    // (workspace:*, file:.., git URLs, dist-tags, exact older pins,
+    // cross-major caret), writing 0.49 hooks + policy artifacts on
+    // top creates a hook/CLI skew: the bash gates resolve the older
+    // CLI from node_modules and that CLI's strict policy loader
+    // rejects the new `bootstrap_allowlist:` top-level key.
+    //
+    // Pre-R11 the pre-flight was upgrade-only. Operators running `rea
+    // init` to reinstall (a common pattern on consumer repos) hit
+    // the same trap. We run the same check here, BEFORE the first
+    // `.rea/` mkdir — so a refused init leaves the consumer's
+    // existing state untouched.
+    //
+    // Fresh-clone repos (no existing pin) return `kind: 'ok'` from
+    // the check, so this branch is a no-op for the canonical init
+    // path.
+    {
+        const initPinCheck = await checkUpgradeBlockingPin({
+            cwd: targetDir,
+            cliVersion: getPkgVersion(),
+            mode: 'init',
+        });
+        if (initPinCheck.kind === 'block' || initPinCheck.kind === 'block-symlink') {
+            // R10-P2: block-symlink is the symlinked-pkg.json variant.
+            // Both kinds share the `reason` field; throw with the
+            // operator-actionable explainer. The throw lands in
+            // `main().catch(...)` (src/cli/index.ts) which surfaces the
+            // multi-line message via the standard `err` path.
+            throw new Error(initPinCheck.reason);
+        }
+    }
     if (!fs.existsSync(reaDir))
         fs.mkdirSync(reaDir, { recursive: true });
     // 0.43.0 UX polish: wrap the file-write phase in a clack spinner so
@@ -1477,6 +1579,7 @@ export async function runInit(options) {
     let prePushResult;
     let mdResult;
     let gitignoreResult;
+    let selfPinResult;
     let manifestPath;
     let fragmentInput;
     try {
@@ -1514,6 +1617,32 @@ export async function runInit(options) {
         // `rea serve` / `rea cache` / `/freeze` can write under `.rea/`. Idempotent
         // append (and `rea upgrade` backfills older installs that never got this).
         gitignoreResult = await ensureReaGitignore(targetDir);
+        // 0.49.0 — self-pin `@bookedsolid/rea` as `^<cli-version>` in the
+        // consumer's package.json (devDependencies). Without this, the hook
+        // shims that init JUST wrote depend on a CLI that the next `pnpm
+        // install` does not actually install. The bash-gate bootstrap
+        // allowlist (Fix B) recovers the brick state when the dep IS
+        // declared but the CLI is not yet built; without the dep declared,
+        // the allowlist refuses (no precondition forge route — must be a
+        // legitimate top-level declaration). See `src/cli/install/self-pin.ts`
+        // for the full contract.
+        //
+        // R13-P1 (codex round 13): `mode: 'upgrade'` — managed-caret pins
+        // that don't admit the installed CLI MUST bump in place during
+        // `rea init` too. Pre-R13 init used the default `mode: 'init'`
+        // (warn-and-skip), but the R11-P1 preflight already filters out
+        // the non-managed-caret cases (workspace, file:, git, dist-tag,
+        // exact) — so anything reaching this line is either a fresh
+        // write OR a managed-caret bump. `mode: 'upgrade'` is the right
+        // semantics for both. Without this fix, `rea init` on a repo
+        // with `^0.49.0` + CLI 0.50.0 wrote new hooks/policy but left
+        // the pin behind — recreating the hook/CLI skew the preflight
+        // was supposed to prevent.
+        selfPinResult = await selfPinRea({
+            cwd: targetDir,
+            cliVersion: getPkgVersion(),
+            mode: 'upgrade',
+        });
         // G12 — record the install manifest. SHAs are of the files actually on disk
         // after the copy pass, so drift detection compares against real state (not
         // canonical, which may differ if the consumer's copy was aborted mid-run).
@@ -1577,6 +1706,38 @@ export async function runInit(options) {
     }
     for (const w of gitignoreResult.warnings)
         warn(w);
+    // 0.49.0 self-pin reporting. One line per outcome; warn-and-skip is
+    // surfaced loudly so the operator notices a mismatched pin.
+    //
+    // R18-P2 (codex round 18): R13-P1 switched `rea init` to
+    // `mode: 'upgrade'` so re-running init on a repo with a managed-
+    // caret pin from an older CLI auto-bumps to the new CLI's caret.
+    // The reporting ladder lacked a `'bumped'` arm — the file was
+    // mutated but the success summary printed no line about it,
+    // making the install output incomplete. Mirrors the `'bumped'`
+    // arm in `rea upgrade` (see src/cli/upgrade.ts) so the operator
+    // sees the pin delta explicitly in both surfaces.
+    if (selfPinResult.action === 'wrote' && selfPinResult.packageJsonPath !== null) {
+        console.log(`  ~ ${path.relative(targetDir, selfPinResult.packageJsonPath)} (self-pin: @bookedsolid/rea@${selfPinResult.pinnedRange})`);
+    }
+    else if (selfPinResult.action === 'bumped' && selfPinResult.packageJsonPath !== null) {
+        console.log(`  ✓ ${path.relative(targetDir, selfPinResult.packageJsonPath)} (self-pin: bumped @bookedsolid/rea from ${selfPinResult.existingRange ?? '?'} to ${selfPinResult.pinnedRange})`);
+    }
+    else if (selfPinResult.action === 'skipped-same' && selfPinResult.packageJsonPath !== null) {
+        console.log(`  · ${path.relative(targetDir, selfPinResult.packageJsonPath)} (self-pin: already declared)`);
+    }
+    else if (selfPinResult.action === 'skipped-different') {
+        warn(selfPinResult.message);
+    }
+    else if (selfPinResult.action === 'skipped-dogfood') {
+        // Silent — dogfood install, expected.
+    }
+    else if (selfPinResult.action === 'skipped-no-package-json') {
+        warn('self-pin skipped — no package.json found upward from target; bash gates will refuse on a fresh clone unless you add `@bookedsolid/rea` to a package.json');
+    }
+    else if (selfPinResult.action === 'skipped-malformed-package-json') {
+        warn(selfPinResult.message);
+    }
     console.log(`  + ${path.relative(targetDir, manifestPath)}`);
     if (mergeResult.warnings.length > 0) {
         console.log('');