@bookedsolid/rea 0.48.1 → 0.49.0

package/dist/cli/install/self-pin.js

@@ -0,0 +1,853 @@
+/**
+ * `rea init` self-pin (0.49.0).
+ *
+ * # Problem
+ *
+ * `rea init` writes hook shims under `.claude/hooks/` that depend on the
+ * `@bookedsolid/rea` CLI being resolvable from `node_modules/`. The
+ * pre-0.49.0 init flow did NOT add the dep to the consumer's
+ * `package.json`, so any fresh clone + `pnpm install` produced a repo
+ * where the shims found no CLI and (correctly) refused every Bash
+ * call — including the very `pnpm add -D @bookedsolid/rea` that would
+ * recover the install. The bash-gate bootstrap allowlist (Fix B) is the
+ * paired safety net; this module is the structural fix.
+ *
+ * # Contract
+ *
+ * - Caret-pinned (`^<current-CLI-version>`) entry in `devDependencies`.
+ * - Lands in workspace ROOT `package.json`. Walks up from `targetDir`
+ *   until a `package.json` is found; refuses to mutate a parent that
+ *   the operator did not explicitly target (we only mutate when the
+ *   FIRST `package.json` we find IS the target).
+ * - Existing different version: warn + skip (do NOT mutate). The
+ *   operator owns their pin.
+ * - Idempotent: re-runs are byte-identical when the pin already
+ *   matches. Detects and preserves indent / EOL / trailing-newline so
+ *   no spurious diff churn lands in the consumer's repo.
+ * - Dogfood short-circuit: when the consumer's `pkg.name` is
+ *   `@bookedsolid/rea` itself, skip silently — the dogfood install
+ *   pins the version via the build, not via the manifest.
+ *
+ * # Why caret
+ *
+ * A caret pin (`^0.49.0` → satisfies 0.49.x AND 0.50.0+) gives
+ * consumers automatic minor-version uptake without breaking when the
+ * shim ABI bumps. Major bumps remain a deliberate operator action.
+ *
+ * # Why warn-and-skip on existing different version
+ *
+ * Three scenarios where this matters:
+ *
+ *   1. Operator explicitly pinned an exact version (`"0.48.1"`) for
+ *      reproducibility — `rea init` overwriting that to caret would
+ *      silently widen their pin.
+ *   2. Operator is running an OLDER `rea init` against a `package.json`
+ *      that has a NEWER `rea` pin. Downgrading the pin would brick the
+ *      install once the operator's lockfile resolves against it.
+ *   3. Operator deliberately pinned a workspace-relative path (`"workspace:^"`,
+ *      `"file:../rea"`). Replacing that with a registry pin breaks the
+ *      monorepo wiring.
+ *
+ * Warn-and-skip preserves operator intent in all three cases.
+ */
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import semver from 'semver';
+/** Package name we self-pin. */
+export const REA_PACKAGE_NAME = '@bookedsolid/rea';
+/**
+ * Look for `package.json` in the explicit target directory ONLY. No upward
+ * walk.
+ *
+ * P2-4 (codex round 1 / locked design): the architect's "pin lands in
+ * workspace root package.json (refuse to mutate parent the operator did
+ * not explicitly target)" rule is implemented here as a hard refusal to
+ * walk past `start`. Earlier revisions walked upward up to 64 directories
+ * — that meant `rea init` invoked from a workspace subdirectory (e.g.
+ * `apps/web/`) with no `package.json` of its own would silently land on
+ * the monorepo root's manifest and mutate it. That violates the locked
+ * intent: the operator picked the cwd; if there's no `package.json`
+ * there, we refuse rather than guessing which parent to touch.
+ *
+ * Concretely:
+ *   - `apps/web/` with no package.json → return `null`, caller maps to
+ *     `skipped-no-package-json` (operator-facing message says
+ *     "no package.json in the target directory").
+ *   - `apps/web/` with its own package.json → pin there.
+ *   - Monorepo root with package.json → pin there.
+ *
+ * The walk-up semantics also applied to `checkSelfPinDeclaredSync` (the
+ * doctor brick-state detector). Same tightening — doctor reports the
+ * absence rather than scanning the parent chain. Operators who want
+ * doctor to validate a parent's pin run `rea doctor` from that parent.
+ */
+function findPackageJson(start) {
+    const cur = path.resolve(start);
+    const candidate = path.join(cur, 'package.json');
+    if (fsSync.existsSync(candidate))
+        return candidate;
+    return null;
+}
+/**
+ * Detect indent / EOL / trailing-newline so re-serialization preserves
+ * the operator's existing formatting verbatim. JSON.stringify with a
+ * numeric `space` argument always emits `\n` separators, so we
+ * post-process to apply CRLF when the source used it.
+ */
+function detectShape(raw) {
+    // EOL: take the first newline pair we encounter. Default to LF.
+    let eol = '\n';
+    const lf = raw.indexOf('\n');
+    if (lf > 0 && raw[lf - 1] === '\r')
+        eol = '\r\n';
+    // Indent: find the first line that begins with a space-or-tab and
+    // count the leading whitespace. Falls back to 2 (the package.json
+    // convention) when the file has no nested indentation visible.
+    let indent = 2;
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        const m = /^(\t+|[ ]+)\S/.exec(line);
+        if (!m)
+            continue;
+        const ws = m[1] ?? '';
+        if (ws.startsWith('\t')) {
+            indent = 1; // tab-indented; JSON.stringify will use `\t` when we pass it directly
+        }
+        else {
+            indent = ws.length;
+        }
+        break;
+    }
+    // Clamp to a sensible range. 0 indent (single-line JSON) is preserved
+    // by the caller — we don't re-serialize when no change is needed.
+    if (indent < 1 || indent > 8)
+        indent = 2;
+    const trailingNewline = raw.endsWith('\n');
+    return { indent, eol, trailingNewline };
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF / EF BB BF) from a string, returning the
+ * rest. No-op when no BOM is present.
+ *
+ * Some Windows operators commit `package.json` with a leading BOM; `JSON.parse`
+ * rejects it (the spec says JSON.parse must error on a leading BOM). We
+ * silently strip it before parse — npm and pnpm both tolerate either form
+ * when writing back, so dropping the BOM on save is the simpler, more
+ * invariant choice. The alternative (detect-and-preserve) would need an
+ * extra field on `FileShape` plus a re-prepend in `serialize`, and the cost
+ * (one operator who deliberately wanted a BOM no longer has one) is much
+ * lower than the cost of an unrecoverable false-positive
+ * `skipped-malformed-package-json` on every BOM-bearing manifest.
+ *
+ * P3-1 (codex round 1): extracted into a shared helper so the same canonical
+ * BOM-strip applies to BOTH `readPackageJson` (the write path used by
+ * `selfPinRea`) AND `checkSelfPinDeclaredSync` (the doctor brick-state
+ * detector). Pre-extraction, only the write path stripped — doctor would
+ * report `fail-malformed` for a BOM-prefixed manifest that self-pin
+ * tolerated fine, which is the asymmetric-fix class we explicitly want
+ * to defend against.
+ */
+export function stripUtf8Bom(input) {
+    if (input.length > 0 && input.charCodeAt(0) === 0xfeff) {
+        return input.slice(1);
+    }
+    return input;
+}
+function checkPackageJsonShapeSync(pkgPath) {
+    let lst;
+    try {
+        lst = fsSync.lstatSync(pkgPath);
+    }
+    catch (e) {
+        // ENOENT is fine — caller handles missing pkg.json with its own
+        // logic. Any other error: treat as 'lstat-error' so the caller
+        // can fall through to existing read paths (which will surface
+        // the same error in a context-appropriate way).
+        const code = e.code;
+        if (code === 'ENOENT')
+            return 'ok';
+        return 'lstat-error';
+    }
+    if (lst.isSymbolicLink())
+        return 'symlink';
+    return 'ok';
+}
+async function checkPackageJsonShape(pkgPath) {
+    let lst;
+    try {
+        lst = await fs.lstat(pkgPath);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return 'ok';
+        return 'lstat-error';
+    }
+    if (lst.isSymbolicLink())
+        return 'symlink';
+    return 'ok';
+}
+/**
+ * Build the operator-facing refusal message for a symlinked
+ * package.json. Pulled out as a helper so `selfPinRea` (throws),
+ * `checkUpgradeBlockingPin` (returns block), and
+ * `checkSelfPinDeclaredSync` (returns fail-symlink) all surface
+ * IDENTICAL wording. Drift between these three surfaces would
+ * confuse operators reading the same diagnostic at different layers.
+ */
+function buildSymlinkRefusalMessage(pkgPath) {
+    return (`rea self-pin refusing: ${pkgPath} is a symlink. ` +
+        `Writing through it would mutate a file outside the requested ` +
+        `project tree (the symlink's target). ` +
+        `To reconcile, either replace the symlink with a regular ` +
+        `package.json or run rea init/upgrade in the target directory ` +
+        `the symlink points to.`);
+}
+async function readPackageJson(pkgPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(pkgPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    // P2-3 (codex round 1): strip leading UTF-8 BOM. The original bytes
+    // tracked in `raw` go forward without the BOM so `detectShape` does
+    // not have to special-case its leading-whitespace scans either.
+    raw = stripUtf8Bom(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(parsed))
+        return null;
+    return { raw, parsed, shape: detectShape(raw) };
+}
+/**
+ * Format a JS object back to a JSON string honoring the detected shape.
+ * Always uses spaces (JSON.stringify's `space` argument). Trailing
+ * newline is restored if the original carried one.
+ *
+ * Indent semantics: pass the indent count directly to JSON.stringify.
+ * When the source was tab-indented (`indent === 1` per detectShape's
+ * conversion above) we still emit spaces — JSON.stringify only supports
+ * a string or a positive integer for indent, and supporting tabs would
+ * require post-processing every indent run. The cost (one operator who
+ * tabs their package.json sees a one-time switch to spaces) is lower
+ * than the risk of indent-conversion bugs.
+ */
+/**
+ * Managed-caret pin shape (P1-1 / codex round 2).
+ *
+ * Matches what `selfPinRea` itself writes — a caret prefix followed by
+ * a 2- or 3-segment semver, with optional `-prerelease` tail. Anything
+ * NOT matching this shape is treated as operator-authored and
+ * `mode: 'upgrade'` will hands-off rather than bump.
+ *
+ * Examples that MATCH (rea-managed):
+ *   `^0.49.0`, `^0.49`, `^1.0.0`, `^1.2.3-beta.1`
+ *
+ * Examples that DO NOT MATCH (operator-authored, hands-off):
+ *   `workspace:^`, `workspace:*`, `file:../rea`, `git+https://...`,
+ *   `next`, `latest`, `0.49.0` (exact pin), `~0.49.0` (tilde),
+ *   `>=0.49.0 <0.50.0` (range), `0.49.x` (x-range), `^0.49.0 || ^0.48.0`.
+ *
+ * R4-P2 (codex round 4): the per-shape "is this a managed pin?" gate
+ * is still our own regex (semver doesn't have a "did rea write this?"
+ * concept — operator-authored carets like `^1.2.3` would also satisfy
+ * any semver-only shape gate, and we explicitly don't want to bump
+ * those without an audit-traceable rea-managed marker). The
+ * VERSION-SATISFIES decision uses `semver.satisfies` so prerelease
+ * upgrades are handled correctly: a non-prerelease range like
+ * `^0.49.0` does NOT satisfy `0.49.1-beta.0` (npm spec excludes
+ * prereleases from non-prerelease ranges); the pre-fix predicate
+ * compared major/minor only and treated this as already-covered,
+ * leaving the pin pointing at the older CLI when newer hooks shipped.
+ */
+const MANAGED_CARET_RE = /^\^(\d+)\.(\d+)(?:\.(\d+))?(?:-[A-Za-z0-9.+-]+)?$/;
+/**
+ * Extract the major version number from a managed-caret range string,
+ * or null when the input is not a managed-caret shape (in which case
+ * the caller hands off — operator-authored).
+ */
+function managedCaretMajor(range) {
+    const m = MANAGED_CARET_RE.exec(range);
+    if (m === null || m[1] === undefined)
+        return null;
+    return Number(m[1]);
+}
+/**
+ * Decide whether `rea upgrade` should auto-bump an existing pin to the
+ * newly-written caret. Returns `true` only when:
+ *
+ *   1. `existing` matches the managed-caret shape (we wrote it; it
+ *      isn't a workspace/file/git/tag/exact pin).
+ *   2. `newRange` ALSO matches the managed-caret shape (sanity — the
+ *      function should never be called with a non-caret target, but
+ *      the predicate stays self-contained).
+ *   3. Both ranges share the same major version. Cross-major bumps
+ *      are intentional operator decisions and we hands-off.
+ *   4. The existing caret does NOT already admit the version the new
+ *      range would resolve to. We extract the floor version from
+ *      `newRange` (strip the leading `^`) and ask
+ *      `semver.satisfies(floor, existing)`:
+ *
+ *        - `^0.49.0` + `^0.49.5` → 0.49.5 satisfies ^0.49.0 → NO bump
+ *        - `^0.49.0` + `^0.50.0` → 0.50.0 does NOT satisfy → BUMP
+ *        - `^0.49.0` + `^0.49.1-beta.0` → prerelease does NOT satisfy
+ *          a non-prerelease range (npm spec) → BUMP (R4-P2)
+ *        - `^1.0.0` + `^1.5.0` → 1.5.0 satisfies ^1.0.0 → NO bump
+ *        - `^1.0.0` + `^1.1.0-beta.0` → prerelease does NOT satisfy
+ *          → BUMP (R4-P2)
+ *
+ * The pre-fix predicate compared major/minor by hand, which
+ * mis-classified prerelease bumps as already-covered. Switching to
+ * `semver.satisfies` gives us npm-spec-correct semver behavior in
+ * one place.
+ */
+export function shouldBumpManagedCaret(existing, newRange) {
+    const existingMajor = managedCaretMajor(existing);
+    if (existingMajor === null)
+        return false;
+    const newMajor = managedCaretMajor(newRange);
+    if (newMajor === null)
+        return false;
+    if (existingMajor !== newMajor)
+        return false;
+    // Extract the version floor from the new range. `^X.Y.Z` floor is
+    // exactly `X.Y.Z` (with optional prerelease tail). Strip the `^`;
+    // semver.satisfies handles the rest. We do not use `semver.minVersion`
+    // here because for prerelease shapes (`^0.49.1-beta.0`) its result
+    // is `0.49.1-beta.0` — same as a manual strip — but for our managed
+    // shape the strip is unambiguous and avoids the cross-version
+    // semver quirks.
+    const newFloor = newRange.startsWith('^') ? newRange.slice(1) : newRange;
+    // Coerce-via-parse to validate the floor is a real semver; if not,
+    // we cannot reason about it and hands-off.
+    if (semver.valid(newFloor) === null)
+        return false;
+    // R9-P1 (codex round 9 / 0.49.0): hands-off on downgrades. The
+    // managed-caret bump is an UPGRADE primitive — when the existing
+    // caret pins a HIGHER floor than the new CLI version, the operator
+    // explicitly pinned newer-than-us (deliberate forward pin) and we
+    // must not silently rewrite their pin DOWN to an older floor. The
+    // R9-P1 abort gate in `runUpgrade` handles this case separately:
+    // it sees `shouldBumpManagedCaret = false` AND `existing range
+    // does not admit new CLI`, then blocks the upgrade with a clear
+    // operator-actionable message rather than silently downgrading.
+    const existingFloor = existing.startsWith('^') ? existing.slice(1) : existing;
+    if (semver.valid(existingFloor) !== null && semver.lt(newFloor, existingFloor)) {
+        return false;
+    }
+    // `includePrerelease: false` is semver's default and what we want:
+    // a non-prerelease range like `^0.49.0` does NOT include
+    // `0.49.1-beta.0`, so the !satisfies branch correctly returns true
+    // and we bump.
+    return !semver.satisfies(newFloor, existing);
+}
+/**
+ * Determine whether the existing `@bookedsolid/rea` pin would block
+ * `rea init` / `rea upgrade` from writing 0.49 artifacts safely.
+ * See type doc.
+ *
+ * R11-P1 (codex round 11): the check applies to BOTH `rea init` and
+ * `rea upgrade`. The implementation is unchanged; only the
+ * operator-facing message prefix varies with `mode`.
+ */
+export async function checkUpgradeBlockingPin(options) {
+    const newCliVersion = options.cliVersion;
+    const newPinnedRange = `^${newCliVersion}`;
+    const cmdName = options.mode === 'init' ? 'rea init' : 'rea upgrade';
+    const pkgPath = findPackageJson(options.cwd);
+    if (pkgPath === null)
+        return { kind: 'no-pkg-json' };
+    // R10-P2 (codex round 10): symlink check BEFORE `readPackageJson`
+    // so the parser never touches the symlink target. Even on the
+    // read-only preview path, surfacing this as a block is the right
+    // signal to the operator — `selfPinRea`'s write path would throw
+    // moments later anyway, and the upgrade preflight needs to refuse
+    // before any artifact-writing step.
+    if (checkPackageJsonShapeSync(pkgPath) === 'symlink') {
+        return {
+            kind: 'block-symlink',
+            packageJsonPath: pkgPath,
+            newCliVersion,
+            newPinnedRange,
+            reason: buildSymlinkRefusalMessage(pkgPath),
+        };
+    }
+    const pkg = await readPackageJson(pkgPath);
+    if (pkg === null)
+        return { kind: 'malformed-pkg-json', packageJsonPath: pkgPath };
+    if (pkg.parsed['name'] === REA_PACKAGE_NAME) {
+        return { kind: 'dogfood', packageJsonPath: pkgPath };
+    }
+    const deps = isPlainObject(pkg.parsed['dependencies']) ? pkg.parsed['dependencies'] : null;
+    const devDeps = isPlainObject(pkg.parsed['devDependencies'])
+        ? pkg.parsed['devDependencies']
+        : null;
+    const existingDep = deps !== null && typeof deps[REA_PACKAGE_NAME] === 'string'
+        ? deps[REA_PACKAGE_NAME]
+        : undefined;
+    const existingDevDep = devDeps !== null && typeof devDeps[REA_PACKAGE_NAME] === 'string'
+        ? devDeps[REA_PACKAGE_NAME]
+        : undefined;
+    // Authoritative pin (matches `selfPinRea`'s precedence).
+    const existing = existingDep ?? existingDevDep;
+    if (existing === undefined) {
+        return { kind: 'ok', packageJsonPath: pkgPath };
+    }
+    // Exact match — pin already at the new version. No skew possible.
+    if (existing === newPinnedRange) {
+        return { kind: 'ok', packageJsonPath: pkgPath, existingRange: existing };
+    }
+    // Managed-caret bumpable — `selfPinRea` will rewrite the pin in
+    // place; no skew once the upgrade completes.
+    if (shouldBumpManagedCaret(existing, newPinnedRange)) {
+        return { kind: 'ok', packageJsonPath: pkgPath, existingRange: existing };
+    }
+    // Does the existing pin admit the new CLI version?
+    //   - Pin is a valid semver range AND semver.satisfies(newCliVersion, existing)
+    //     → ok (e.g. `^0.49.0` admits `0.49.5`).
+    //   - Pin is NOT a valid semver range (workspace:*, file:.., git URL,
+    //     dist-tag like `next`) → semver.validRange returns null →
+    //     we cannot statically determine admittance → block on uncertainty.
+    //     The operator can re-run after editing the manifest.
+    let admits = false;
+    if (semver.validRange(existing) !== null) {
+        admits = semver.satisfies(newCliVersion, existing);
+    }
+    if (admits) {
+        return { kind: 'ok', packageJsonPath: pkgPath, existingRange: existing };
+    }
+    // Build the operator-facing reason. Customize the third bullet for
+    // workspace / file / git / tag shapes — those need a workspace-
+    // specific fix path.
+    const isWorkspacePin = existing.startsWith('workspace:');
+    const isFilePin = existing.startsWith('file:');
+    const isGitPin = existing.startsWith('git') ||
+        existing.startsWith('github:') ||
+        existing.startsWith('gitlab:') ||
+        existing.startsWith('bitbucket:') ||
+        /^https?:\/\//.test(existing);
+    const isLooksDistTag = semver.validRange(existing) === null && !isWorkspacePin && !isFilePin && !isGitPin;
+    const lines = [
+        `${cmdName} refusing: package.json pins ${REA_PACKAGE_NAME} to "${existing}"`,
+        `which does not admit the installed CLI version ${newCliVersion}.`,
+        '',
+        `Writing ${newCliVersion} hooks/policy artifacts now would create a hook/CLI skew:`,
+        `your shims would resolve the older CLI from node_modules, which cannot`,
+        `parse the new policy.yaml schema (strict).`,
+        '',
+        // R12-P2 (codex round 12): recommend the bare-spec form. The
+        // CLI-missing bootstrap allowlist (hooks/_lib/bootstrap-allowlist.sh)
+        // accepts ONLY `pnpm add -D @bookedsolid/rea` — bare. Version-
+        // pinned `@bookedsolid/rea@^X.Y.Z` forms are REFUSED at the bash
+        // gate (R6-P2 lock — security: prevents attacker version-pin
+        // downgrade in the CLI-missing state). If we recommended the
+        // version-pinned form here, agents running the diagnostic-
+        // suggested command would loop forever — the bash gate refuses
+        // the very recovery command we printed. The bare-spec form
+        // installs the latest version matching the consumer's existing
+        // constraint (or absolute latest if no constraint); a follow-up
+        // `${cmdName}` then runs the managed-caret bump (R2-P1-1) to
+        // set the canonical pin under audit.
+        'To reconcile, choose one:',
+        `  1. pnpm add -D ${REA_PACKAGE_NAME}     (installs latest within range,`,
+        `                                  then re-run: ${cmdName})`,
+        `  2. Edit package.json to pin a version that admits ${newCliVersion},`,
+        '     then: pnpm install',
+    ];
+    if (isWorkspacePin) {
+        lines.push(`  3. workspace:* points to a sibling package; ensure that package's`, `     version admits ${newCliVersion} before re-running ${cmdName}`);
+    }
+    else if (isFilePin) {
+        lines.push(`  3. file: pins to a local path; ensure the linked package's`, `     version admits ${newCliVersion} before re-running ${cmdName}`);
+    }
+    else if (isGitPin) {
+        lines.push(`  3. git URL pins to a remote ref; ensure the target ref's`, `     package version admits ${newCliVersion} before re-running ${cmdName}`);
+    }
+    else if (isLooksDistTag) {
+        lines.push(`  3. dist-tag "${existing}" resolves at install time; ensure the`, `     tag currently points at a version that admits ${newCliVersion}`);
+    }
+    else {
+        lines.push(`  3. If using workspace:* or file:.., ensure the workspace target`, `     resolves to >= ${newCliVersion} before re-running ${cmdName}`);
+    }
+    lines.push('', `Then re-run: ${cmdName}`);
+    return {
+        kind: 'block',
+        packageJsonPath: pkgPath,
+        existingRange: existing,
+        newCliVersion,
+        newPinnedRange,
+        reason: lines.join('\n'),
+    };
+}
+function serialize(obj, shape) {
+    let s = JSON.stringify(obj, null, shape.indent);
+    if (shape.eol === '\r\n') {
+        s = s.replace(/\n/g, '\r\n');
+    }
+    if (shape.trailingNewline) {
+        s += shape.eol;
+    }
+    return s;
+}
+/**
+ * Idempotent self-pin step. See module header for the full contract.
+ */
+export async function selfPinRea(options) {
+    const pinnedRange = `^${options.cliVersion}`;
+    const pkgPath = findPackageJson(options.cwd);
+    if (pkgPath === null) {
+        return {
+            action: 'skipped-no-package-json',
+            packageJsonPath: null,
+            pinnedRange,
+            message: `self-pin skipped — no package.json in the target directory ${options.cwd}. ` +
+                `rea init refuses to walk up and mutate a parent the operator did not ` +
+                `explicitly target — re-invoke from the workspace root if that is the ` +
+                `intent.`,
+        };
+    }
+    // R10-P2 (codex round 10): refuse symlinked package.json BEFORE
+    // any read or write. Writing through a symlink mutates the target
+    // — typically outside the requested project tree — which violates
+    // the R2-P4 "don't mutate a parent the operator did not target"
+    // contract.
+    //
+    // Live mode THROWS — security refusals must surface, not silently
+    // no-op. Dry-run mode RETURNS a `skipped-symlink-package-json`
+    // skip-shape so `rea upgrade --dry-run` can complete a full preview
+    // even when the symlink would block the live run. The upgrade
+    // pre-flight (`checkUpgradeBlockingPin`) already surfaced a
+    // `block-symlink` to the operator before reaching this code path,
+    // so dry-run consumers see the diagnostic ONCE at the pre-flight
+    // and the downstream `selfPinRea({ dryRun: true })` call simply
+    // reports "skipped — symlinked" without re-throwing.
+    if ((await checkPackageJsonShape(pkgPath)) === 'symlink') {
+        const message = buildSymlinkRefusalMessage(pkgPath);
+        if (options.dryRun === true) {
+            return {
+                action: 'skipped-symlink-package-json',
+                packageJsonPath: pkgPath,
+                pinnedRange,
+                message,
+            };
+        }
+        throw new Error(message);
+    }
+    const pkg = await readPackageJson(pkgPath);
+    if (pkg === null) {
+        return {
+            action: 'skipped-malformed-package-json',
+            packageJsonPath: pkgPath,
+            pinnedRange,
+            message: `self-pin skipped — ${pkgPath} is missing or not a valid JSON object`,
+        };
+    }
+    // Dogfood short-circuit: pkg.name === '@bookedsolid/rea'.
+    if (pkg.parsed['name'] === REA_PACKAGE_NAME) {
+        return {
+            action: 'skipped-dogfood',
+            packageJsonPath: pkgPath,
+            pinnedRange,
+            message: `self-pin skipped — this IS @bookedsolid/rea (dogfood)`,
+        };
+    }
+    // Conflict check: where does `@bookedsolid/rea` currently live?
+    // We look in dependencies + devDependencies — those are the surfaces
+    // the bootstrap allowlist (Fix B) accepts. We do NOT look in
+    // peerDependencies / optionalDependencies / pnpm.overrides — those
+    // are NOT bootstrap declarations and inserting our pin there would
+    // silently shift the contract.
+    const deps = isPlainObject(pkg.parsed['dependencies']) ? pkg.parsed['dependencies'] : null;
+    const devDeps = isPlainObject(pkg.parsed['devDependencies'])
+        ? pkg.parsed['devDependencies']
+        : null;
+    const existingDep = deps !== null && typeof deps[REA_PACKAGE_NAME] === 'string'
+        ? deps[REA_PACKAGE_NAME]
+        : undefined;
+    const existingDevDep = devDeps !== null && typeof devDeps[REA_PACKAGE_NAME] === 'string'
+        ? devDeps[REA_PACKAGE_NAME]
+        : undefined;
+    // P1-1 (codex round 2): upgrade-mode bump predicate. Resolved here
+    // once so the dependencies + devDependencies branches share the
+    // same shape gate. `mode: 'upgrade'` opts the caller in to auto-
+    // bumping a managed-caret pin when the existing range does not
+    // admit the new CLI minor (pre-1.0 caret = tilde, so `^0.49.0`
+    // does NOT admit `0.50.0` and a 0.49 → 0.50 upgrade would otherwise
+    // ship newer hooks against the older CLI — exactly the brick state
+    // this whole feature exists to prevent). `mode: 'init'` (default)
+    // never bumps: respects whatever pin the operator already chose.
+    const mode = options.mode ?? 'init';
+    const allowBump = mode === 'upgrade';
+    // R3-P2: dry-run prefixes "would " on the mutation messages so the
+    // operator-visible string is unambiguous. The `action` discriminant
+    // itself is identical between dry-run and live run — callers that
+    // pattern-match on `action` see the same value either way; only the
+    // message and the absence of an on-disk write differ.
+    const dryRun = options.dryRun ?? false;
+    const wroteVerb = dryRun ? 'would add' : 'added';
+    const bumpedVerb = dryRun ? 'would bump' : 'bumped';
+    // A dep present in `dependencies` AND `devDependencies` is unusual
+    // but legal. We treat the `dependencies` value as authoritative for
+    // conflict detection (npm install resolves it that way) and refuse
+    // to mutate the more constrained surface. Operator owns it.
+    if (existingDep !== undefined) {
+        if (existingDep === pinnedRange) {
+            return {
+                action: 'skipped-same',
+                packageJsonPath: pkgPath,
+                pinnedRange,
+                existingRange: existingDep,
+                message: `self-pin: ${REA_PACKAGE_NAME} already pinned in dependencies as ${existingDep}`,
+            };
+        }
+        if (allowBump && shouldBumpManagedCaret(existingDep, pinnedRange)) {
+            await writePin(pkgPath, pkg, 'dependencies', pinnedRange, deps, devDeps, dryRun);
+            return {
+                action: 'bumped',
+                packageJsonPath: pkgPath,
+                pinnedRange,
+                existingRange: existingDep,
+                message: `self-pin: ${bumpedVerb} ${REA_PACKAGE_NAME} pin in dependencies from ` +
+                    `${existingDep} to ${pinnedRange} (managed-caret upgrade)`,
+            };
+        }
+        return {
+            action: 'skipped-different',
+            packageJsonPath: pkgPath,
+            pinnedRange,
+            existingRange: existingDep,
+            message: `self-pin: ${REA_PACKAGE_NAME} already pinned in dependencies as ${existingDep} ` +
+                `(different from ${pinnedRange}) — leaving operator's pin intact`,
+        };
+    }
+    if (existingDevDep !== undefined) {
+        if (existingDevDep === pinnedRange) {
+            return {
+                action: 'skipped-same',
+                packageJsonPath: pkgPath,
+                pinnedRange,
+                existingRange: existingDevDep,
+                message: `self-pin: ${REA_PACKAGE_NAME} already pinned in devDependencies as ${existingDevDep}`,
+            };
+        }
+        if (allowBump && shouldBumpManagedCaret(existingDevDep, pinnedRange)) {
+            await writePin(pkgPath, pkg, 'devDependencies', pinnedRange, deps, devDeps, dryRun);
+            return {
+                action: 'bumped',
+                packageJsonPath: pkgPath,
+                pinnedRange,
+                existingRange: existingDevDep,
+                message: `self-pin: ${bumpedVerb} ${REA_PACKAGE_NAME} pin in devDependencies from ` +
+                    `${existingDevDep} to ${pinnedRange} (managed-caret upgrade)`,
+            };
+        }
+        return {
+            action: 'skipped-different',
+            packageJsonPath: pkgPath,
+            pinnedRange,
+            existingRange: existingDevDep,
+            message: `self-pin: ${REA_PACKAGE_NAME} already pinned in devDependencies as ${existingDevDep} ` +
+                `(different from ${pinnedRange}) — leaving operator's pin intact`,
+        };
+    }
+    // No existing pin — write a new one into devDependencies.
+    const result = await writePin(pkgPath, pkg, 'devDependencies', pinnedRange, deps, devDeps, dryRun);
+    if (result.newRaw === pkg.raw) {
+        return {
+            action: 'skipped-same',
+            packageJsonPath: pkgPath,
+            pinnedRange,
+            existingRange: pinnedRange,
+            message: `self-pin: ${REA_PACKAGE_NAME} already pinned at ${pinnedRange} (byte-identical)`,
+        };
+    }
+    return {
+        action: 'wrote',
+        packageJsonPath: pkgPath,
+        pinnedRange,
+        message: `self-pin: ${wroteVerb} ${REA_PACKAGE_NAME}@${pinnedRange} to devDependencies in ${pkgPath}`,
+    };
+}
+/**
+ * Write the rea pin into either `dependencies` or `devDependencies`
+ * (caller picks). Sorts the target dep block alphabetically (matches
+ * the pre-refactor behavior for devDependencies and is the common
+ * tooling convention for both). Preserves top-level key order in the
+ * package.json object so the on-disk diff is minimal — JSON.stringify
+ * honors insertion order in V8.
+ *
+ * Returns `{ newRaw }` so the caller can compare against
+ * `pkg.raw` for the byte-fidelity guard.
+ *
+ * P1-1 (codex round 2): extracted as a shared helper so the new-write
+ * path and the upgrade-mode bump path use the same serializer. Pre-
+ * extraction the bump path would have needed duplicated logic.
+ */
+async function writePin(pkgPath, pkg, target, pinnedRange, deps, devDeps, dryRun) {
+    const baseBlock = target === 'dependencies' ? deps : devDeps;
+    const newBlock = { ...(baseBlock ?? {}), [REA_PACKAGE_NAME]: pinnedRange };
+    const sortedKeys = Object.keys(newBlock).sort();
+    const sortedBlock = {};
+    for (const k of sortedKeys)
+        sortedBlock[k] = newBlock[k];
+    const out = { ...pkg.parsed, [target]: sortedBlock };
+    const newRaw = serialize(out, pkg.shape);
+    // R3-P2: skip the write when previewing. The caller still gets the
+    // `newRaw` value back so the byte-fidelity guard ("did this even
+    // change?") works identically in both modes.
+    if (!dryRun && newRaw !== pkg.raw) {
+        await fs.writeFile(pkgPath, newRaw, 'utf8');
+    }
+    return { newRaw };
+}
+export async function checkSelfPinDeclared(baseDir, cliVersion) {
+    return checkSelfPinDeclaredSync(baseDir, cliVersion);
+}
+/**
+ * Synchronous variant of {@link checkSelfPinDeclared}. `rea doctor`
+ * runs all checks sync; the read+parse cost here is microseconds so
+ * the sync form is acceptable.
+ *
+ * R11-P3 (codex round 11): when `cliVersion` is provided, this check
+ * also verifies that the declared range admits the running CLI
+ * version (semver.satisfies). Without `cliVersion` the check
+ * reverts to presence-only behavior (backwards-compat for callers
+ * that don't yet pass the version). The doctor wrapper
+ * (`checkSelfPinDeclaredCheck`) passes `getPkgVersion()` so the
+ * skew detection always runs in the doctor surface.
+ */
+export function checkSelfPinDeclaredSync(baseDir, cliVersion) {
+    const hooksDir = path.join(baseDir, '.claude', 'hooks');
+    if (!fsSync.existsSync(hooksDir)) {
+        return { kind: 'pass-no-hooks' };
+    }
+    const pkgPath = findPackageJson(baseDir);
+    if (pkgPath === null) {
+        return { kind: 'pass-no-pkg', hooksDir };
+    }
+    // R10-P2 (codex round 10): mirror the write-path's symlink refusal
+    // here so doctor surfaces the same diagnostic. Operators get
+    // told about the misconfiguration BEFORE running `rea upgrade`,
+    // which would throw at the symlink check otherwise.
+    if (checkPackageJsonShapeSync(pkgPath) === 'symlink') {
+        return {
+            kind: 'fail-symlink',
+            packageJsonPath: pkgPath,
+            reason: buildSymlinkRefusalMessage(pkgPath),
+        };
+    }
+    let raw;
+    try {
+        raw = fsSync.readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        return { kind: 'fail-malformed', packageJsonPath: pkgPath };
+    }
+    // P3-1 (codex round 1): tolerate a leading UTF-8 BOM the same way
+    // the write path does — otherwise doctor reports `fail-malformed`
+    // on Windows-authored manifests that selfPinRea handles fine.
+    raw = stripUtf8Bom(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: 'fail-malformed', packageJsonPath: pkgPath };
+    }
+    if (!isPlainObject(parsed)) {
+        return { kind: 'fail-malformed', packageJsonPath: pkgPath };
+    }
+    const pkg = { raw, parsed, shape: detectShape(raw) };
+    if (pkg.parsed['name'] === REA_PACKAGE_NAME) {
+        return { kind: 'pass-dogfood', packageJsonPath: pkgPath };
+    }
+    const deps = isPlainObject(pkg.parsed['dependencies']) ? pkg.parsed['dependencies'] : null;
+    const devDeps = isPlainObject(pkg.parsed['devDependencies'])
+        ? pkg.parsed['devDependencies']
+        : null;
+    // Resolve the authoritative pin + its location (deps wins over
+    // devDeps, matching `selfPinRea`'s precedence).
+    let declaredRange;
+    let declaredIn;
+    if (deps !== null && typeof deps[REA_PACKAGE_NAME] === 'string') {
+        declaredRange = deps[REA_PACKAGE_NAME];
+        declaredIn = 'dependencies';
+    }
+    else if (devDeps !== null && typeof devDeps[REA_PACKAGE_NAME] === 'string') {
+        declaredRange = devDeps[REA_PACKAGE_NAME];
+        declaredIn = 'devDependencies';
+    }
+    if (declaredRange === undefined || declaredIn === undefined) {
+        return { kind: 'fail', packageJsonPath: pkgPath, hooksDir };
+    }
+    // R11-P3 (codex round 11): pin-compatibility check. When the
+    // caller passed a `cliVersion`, run semver.satisfies against the
+    // declared range. Non-semver shapes (workspace:*, file:.., git,
+    // dist-tag) cannot be resolved statically — surface a dedicated
+    // `fail-non-semver` so the operator audits the resolution path
+    // rather than seeing a misleading `pass`.
+    if (cliVersion !== undefined) {
+        const validRange = semver.validRange(declaredRange);
+        if (validRange === null) {
+            return {
+                kind: 'fail-non-semver',
+                packageJsonPath: pkgPath,
+                declaredRange,
+                declaredIn,
+                reason: `Self-pin declared as a non-semver shape: ${REA_PACKAGE_NAME} pinned to ` +
+                    `"${declaredRange}" in ${declaredIn}.\n\n` +
+                    `rea doctor cannot statically determine whether the resolved version admits the\n` +
+                    `installed CLI version ${cliVersion}. Workspace, file:, git URL, and dist-tag\n` +
+                    `pins resolve at install time — if the resolved version does not admit ${cliVersion},\n` +
+                    `your hook scripts will resolve the older CLI from node_modules and may fail to\n` +
+                    `parse the current policy.yaml schema.\n\n` +
+                    // R12-P2 (codex round 12): bare-spec form only. The
+                    // CLI-missing bash gate refuses version-pinned adds.
+                    `To reconcile, either:\n` +
+                    `  1. Replace the pin with pnpm add -D ${REA_PACKAGE_NAME}\n` +
+                    `     (installs latest within range, then re-run: rea upgrade)\n` +
+                    `  2. Verify the resolved version admits ${cliVersion} (check node_modules/${REA_PACKAGE_NAME}/package.json)`,
+            };
+        }
+        // semver.satisfies with includePrerelease so a 0.49.0-beta.0
+        // running CLI passes against `^0.49.0` (otherwise a prerelease
+        // would fail-incompatible against its own non-prerelease range).
+        const admits = semver.satisfies(cliVersion, validRange, { includePrerelease: true });
+        if (!admits) {
+            return {
+                kind: 'fail-incompatible',
+                packageJsonPath: pkgPath,
+                declaredRange,
+                declaredIn,
+                currentCliVersion: cliVersion,
+                reason: `Self-pin declared but incompatible: package.json pins ${REA_PACKAGE_NAME} to ` +
+                    `"${declaredRange}" in ${declaredIn} which does not admit the installed CLI ` +
+                    `version ${cliVersion}.\n\n` +
+                    `Your hook scripts will resolve the older CLI from node_modules and may fail to\n` +
+                    `parse the current policy.yaml schema (strict).\n\n` +
+                    // R12-P2 (codex round 12): bare-spec form only — see the
+                    // R9-P1 reason builder above for the full rationale.
+                    `To reconcile:\n` +
+                    `  pnpm add -D ${REA_PACKAGE_NAME}     (installs latest within range,\n` +
+                    `                                       then re-run: rea upgrade)`,
+            };
+        }
+    }
+    return {
+        kind: 'pass',
+        packageJsonPath: pkgPath,
+        declaredRange,
+        declaredIn,
+    };
+}