johnrucnapier-sketch · johnrucnapier-sketch · Jul 15, 2026 · Jul 15, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -9,7 +9,8 @@ Claude Code Recover is an independent, offline, evidence-first Claude Code proje
 - A `--route` argument records an explicit CLI input; the agent must still show it to the user and obtain confirmation before recovery work.
 - Do not add runtime networking, telemetry, update checks, dependency downloads, or shell-based command construction.
 - Keep bootstrap version behavior explicit: the same canonical version is force-reinstalled from the newly verified snapshot, older canonical installs require `--upgrade`, newer installs are never silently downgraded, active virtual environments must not receive `--user`, and an RC1 `acgm-recover` distribution must return `MIGRATION_REQUIRED` before any mutation.
-- Use `claude-code-recover` / `python -m claude_code_recover` as canonical RC2 entrypoints. Keep `acgm-recover` / `python -m acgm_recover` working only as the documented one-RC compatibility aliases.
+- Outside virtual environments, detect the PEP 668 marker before installation. Use `--break-system-packages` only when the selected pip advertises it and the canonical install command also contains `--user`; otherwise fail closed before mutation. If that override path fails, do not run an automatic uninstall because pip uninstall has no equivalent `--user` scope.
+- Use `claude-code-recover` / `python -m claude_code_recover` as canonical RC3 entrypoints. Keep `acgm-recover` / `python -m acgm_recover` working only as documented transition aliases.
 - Use only synthetic fixtures in tests. Never commit real transcripts, credentials, account identifiers, or private absolute paths.
 - On Windows, only bootstrap, installation, `--version`, `doctor`, and `guide` are currently in scope. Do not run or claim support for core `discover`, `inspect`, `build`, or `verify` until the Windows filesystem and Git safety port is complete.
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,13 @@
 # Changelog
 
-## 0.1.0-rc.2 — Unreleased
+## 0.1.0-rc.3 — Unreleased
+
+- Fixed automatic user installation on PEP 668 `EXTERNALLY-MANAGED` interpreters such as current Homebrew Python by detecting the marker and pairing pip's supported override with `--user`.
+- Added fail-closed dry-run/JSON reporting when the marker or pip capability cannot be verified; inherited `PIP_*` and Python user-site redirection variables are removed.
+- Preserved `MIGRATION_REQUIRED` as the earlier, zero-mutation RC1 distribution gate and disabled automatic uninstall after a failed externally-managed user install.
+- Added ordinary-interpreter, virtual-environment, supported/unsupported PEP 668, rollback, and dual-Python regression coverage.
+
+## 0.1.0-rc.2 — Public development preview
 
 - Renamed the product to Claude Code Recover so the recovery target is explicit: Claude Code project continuity, not an ACGM installation.
 - Moved the canonical repository contract to `johnrucnapier-sketch/Claude-Code-Recover`.
@@ -11,7 +18,7 @@
 
 ## 0.1.0-rc.1 — Development preview
 
-- Added the original cross-platform `python -m acgm_recover` entrypoint, now retained as an RC2 legacy alias.
+- Added the original cross-platform `python -m acgm_recover` entrypoint, now retained as a legacy transition alias.
 - Added an offline `guide` command that reports observable capabilities, requires explicit route input, and never inspects account/provider/model identity.
 - Added an offline, user-scoped `scripts/bootstrap.py` installer with dry-run, source-manifest validation, post-install verification, and failure cleanup guidance.
 - Added Agent-assisted clone/install instructions while keeping evidence discovery and route confirmation as separate authorizations.

diff --git a/PACKAGE_MANIFEST.json b/PACKAGE_MANIFEST.json
@@ -26,15 +26,15 @@
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "AGENTS.md",
-      "sha256": "dcd656d40eedf1c9e61083b3f75485324dc3ff937f15ad8ec1e79a72f3a07b5a",
-      "size": 2141
+      "sha256": "d0824e2f185fc249a771f20ff1a403ec78129900054d08e4bcc079f1646862f7",
+      "size": 2493
     },
     {
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "CHANGELOG.md",
-      "sha256": "c46dc674527922db2786e275e4c1061c1080e1c3893bc03dcbb7530ebabc3b31",
-      "size": 3134
+      "sha256": "6e56bc14310d699fcccbe0d94aea731496972809fd8a847e1e9e284970086dfd",
+      "size": 3842
     },
     {
       "license": "CC-BY-4.0",
@@ -75,22 +75,22 @@
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "README.en.md",
-      "sha256": "3bf3f9f4b507d8da4d17a5eea5bf0f01a33f1383435a93539b73bb935547d5e9",
-      "size": 10379
+      "sha256": "2d5469fb890246d0a62b01b8fa33a0081e23bcddb4c9b26e83017ad758a517fd",
+      "size": 10799
     },
     {
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "README.md",
-      "sha256": "6c66e0e5f6d0ff8c2cd643243e82b22586ca2e61ac0296e758f5d313e672cfe4",
-      "size": 12285
+      "sha256": "ef87f8c03bc83dfaa638924b058eb00b27b2ca0066bd264f2fd333771931c44f",
+      "size": 12650
     },
     {
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "RELEASING.md",
-      "sha256": "3b45db8a06e7bd3d47467906cd10f370cd300809a42dc3b0f4c17d350f8fc38c",
-      "size": 1913
+      "sha256": "0c20b29a2fba36959d870721ef3d483bb1467650a9d8cf0bf08bdd2a5e47f1b1",
+      "size": 2214
     },
     {
       "license": "MIT",
@@ -103,14 +103,14 @@
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "SECURITY.md",
-      "sha256": "a393c1b4d785e593c31f57f45dceda77648bfdcd44626fddded0506e51e33c34",
-      "size": 7736
+      "sha256": "3fe67fd4e38ebd52f03b03b305247eb70a84dd493d906f874cb63fcbd7fac3ab",
+      "size": 8486
     },
     {
       "license": "MIT",
       "mode": "0644",
       "path": "VERSION",
-      "sha256": "b0b5813e7156d4ad22becc185a387f84a901d471c07592ecd5d4cf48e601b60d",
+      "sha256": "93f893b9b51cd2ee055332a64d4656e5bbbb652788acbaeaa7d1a6b32099d23f",
       "size": 11
     },
     {
@@ -131,15 +131,15 @@
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "docs/CLI_REFERENCE.md",
-      "sha256": "f6a7556f3b0a1bc2ed979d22c558257d9415034810884c8d959d51cd39cd56b4",
-      "size": 5832
+      "sha256": "21ee8a74c4c7d453bf93cbf05f1da76a61be2606cbabace24e4cfa0f54437329",
+      "size": 5823
     },
     {
       "license": "CC-BY-4.0",
       "mode": "0644",
       "path": "docs/INSTALLATION.md",
-      "sha256": "f7b774a9b36f6f83c0470f9f10f1b15e3d40d8e9e87a83b0959138ab4d5e4e7a",
-      "size": 8434
+      "sha256": "28fc1fa59b1245b02a90f51c1eb903fb0aced0f694da4d82332d0e2016715b5d",
+      "size": 10045
     },
     {
       "license": "CC-BY-4.0",
@@ -152,15 +152,15 @@
       "license": "MIT",
       "mode": "0644",
       "path": "pyproject.toml",
-      "sha256": "81aa10cae7fd521c3474a7c417415bd351ab0cbce1fd8a2494667ff6120fad2c",
+      "sha256": "b824c2f6a3c5db6e4453b95674735c74b41a75fced343ca4e54db331ad117ea9",
       "size": 1147
     },
     {
       "license": "MIT",
       "mode": "0755",
       "path": "scripts/bootstrap.py",
-      "sha256": "c78999ee0ea58721dcd2e504f05d29c0d36dfbae620d8513ebd7b506d0d3d838",
-      "size": 26804
+      "sha256": "bf8a10616c146476f1320b0c1e18d6ceb508fc7fa6093ad732255c6946c7cc26",
+      "size": 35200
     },
     {
       "license": "MIT",
@@ -180,8 +180,8 @@
       "license": "MIT",
       "mode": "0755",
       "path": "scripts/release_check.py",
-      "sha256": "ffc8245ea1641bf9685403e48e2a742de0721762644b094e9908de7bf59b0ca5",
-      "size": 10835
+      "sha256": "69169d89e79d6434ca9d037aaeebfd2c4e83715d3b0aa8aa5f33f2010b2a84c0",
+      "size": 11219
     },
     {
       "license": "MIT",
@@ -306,7 +306,7 @@
       "license": "MIT",
       "mode": "0644",
       "path": "src/claude_code_recover/constants.py",
-      "sha256": "6b5b311548ae2490a4dffad05c1120433005b79c15d77d51de70038c4f224936",
+      "sha256": "6c6fefe1d6852556837ba776ad8c81df3d99cf7bc1fb43de40c3bcbe879ea287",
       "size": 2454
     },
     {
@@ -376,8 +376,8 @@
       "license": "MIT",
       "mode": "0644",
       "path": "tests/test_bootstrap.py",
-      "sha256": "6b7abf9f21e8b46e2d3211633dd7390afbac7351d6c94f9fbe9b58299b6ef312",
-      "size": 13385
+      "sha256": "02cfa4e9c2bdfd76e47093c977d2a504b07431f543478b2cb82736d4e3f9e4a7",
+      "size": 27232
     },
     {
       "license": "MIT",
@@ -390,7 +390,7 @@
       "license": "MIT",
       "mode": "0644",
       "path": "tests/test_onboarding.py",
-      "sha256": "62abe395a1a5c4caeea50bcfe4efec0638ce6765552e9bbfbc5cace8ef651ca0",
+      "sha256": "8f7c32dc7e41498ac2fed7e40807a365bb6a94c4334664bda2857f9e9cd2cdc0",
       "size": 7489
     },
     {
@@ -431,5 +431,5 @@
   ],
   "package": "claude-code-recover",
   "schema_version": "1.0",
-  "version": "0.1.0-rc.2"
+  "version": "0.1.0-rc.3"
 }
diff --git a/README.en.md b/README.en.md
@@ -2,7 +2,7 @@
 
 **When Claude Code, the original account, or the original platform is no longer available, rebuild a trustworthy, explainable, continuable project from surviving local code, Git, worktrees, session metadata, and transcript structure.**
 
-Current version: `0.1.0-rc.2`. The code is now a public development preview. No formal GitHub Release has been published, and a real-friend Claude Code end-to-end acceptance run is still pending.
+Current version: `0.1.0-rc.3`. The code is now a public development preview. No formal GitHub Release has been published, and a real-friend Claude Code end-to-end acceptance run is still pending.
 
 Claude Code Recover is an independent open-source tool. It is not affiliated with, endorsed by, or an official product of Anthropic.
 
@@ -35,6 +35,8 @@ It cannot restore an inaccessible vendor-side Session or recover an account. It
 
 Only Python 3.10+ (including pip) and Git are required. The installer validates `PACKAGE_MANIFEST.json`, builds a controlled local wheel in a temporary directory using only the Python standard library, then performs an offline user installation. It does not require setuptools/wheel, scan evidence, inspect an account, download dependencies, or select a route.
 
+Bootstrap recognizes PEP 668 `EXTERNALLY-MANAGED` interpreters, including current Homebrew Python. Only when the selected pip explicitly supports it does bootstrap combine `--break-system-packages` with `--user` for the offline user install. Ordinary interpreters and virtual environments never receive that override. If support cannot be verified, bootstrap fails closed before installation and explains the result in JSON.
+
 When an Agent clones and installs in the same task, instruct it to read `AGENTS.md`
 and `SECURITY.md` explicitly after the clone. A newly downloaded instruction file does
 not automatically reload an already-running Agent, and Git clone does not and should
@@ -63,7 +65,7 @@ bin/claude-code-recover verify --bundle "/path/to/new-bundle" --check-sources
 
 The repository wrapper can be replaced by the current interpreter's module entrypoint: commonly `python3 -m claude_code_recover` on macOS/Linux or `py -3 -m claude_code_recover` on Windows. Bootstrap uses the same interpreter that launched it and does not assume a fixed alias.
 
-For one RC cycle, RC2 keeps the RC1 compatibility aliases `acgm-recover` and `python -m acgm_recover`. They are legacy; new documentation and automation must use the canonical names. When the old distribution is detected, bootstrap returns a non-executable `MIGRATION_REQUIRED` plan before any mutation; cross-distribution uninstall is never hidden inside `--upgrade`. The old repository URL `https://github.com/johnrucnapier-sketch/ACGM-Recover` is documented only to identify or migrate an old checkout, not as the RC2 installation source.
+RC3 continues to provide the RC1 transition aliases `acgm-recover` and `python -m acgm_recover`. They are legacy; new documentation and automation must use the canonical names. When the old distribution is detected, bootstrap returns a non-executable `MIGRATION_REQUIRED` plan before any mutation; cross-distribution uninstall is never hidden inside `--upgrade`. The old repository URL `https://github.com/johnrucnapier-sketch/ACGM-Recover` is documented only to identify or migrate an old checkout, not as the RC3 installation source.
 
 Default source locations target macOS. On Linux or custom layouts, use `--no-default-sources` with explicit `--claude-projects-root`, `--metadata-root`, and `--auxiliary-root` values.
 

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 **当 Claude Code、原账号或原平台已经不可用时，从幸存的本机代码、Git、worktree、Session metadata 和 transcript 结构中，重建一个可信、可解释、可继续开发的项目。**
 
-当前版本：`0.1.0-rc.2`。代码现作为公开开发预览；尚未发布正式 GitHub Release，也尚未经过真实 Claude Code 朋友端到端验收。
+当前版本：`0.1.0-rc.3`。代码现作为公开开发预览；尚未发布正式 GitHub Release，也尚未经过真实 Claude Code 朋友端到端验收。
 
 Claude Code Recover 是独立开源工具，与 Anthropic 不存在隶属关系，也不代表 Anthropic 的官方产品或背书。
 
@@ -35,6 +35,8 @@ Claude Code Recover 不是事前备份，也不是把聊天导成 HTML。
 
 安装前只要求 Python 3.10+（含 pip）和 Git。安装器会先校验 `PACKAGE_MANIFEST.json`，再用 Python 标准库在临时目录构建受控本地 wheel，并以当前用户身份离线安装；不要求预装 setuptools/wheel，不会扫描证据、读取账号、联网下载依赖或自动选择路线。
 
+安装器会识别 PEP 668 `EXTERNALLY-MANAGED` Python（包括当前 Homebrew Python）。只有在当前 pip 明确支持时，它才会把 `--break-system-packages` 与 `--user` 同时用于离线用户级安装；普通 Python 和虚拟环境不会使用该 override。无法确认支持时会在任何安装修改前失败关闭，并在 JSON 中说明检测结果。
+
 让 Agent 在同一任务中代为下载和安装时，必须明确要求它在 clone 完成后主动读取
 `AGENTS.md` 与 `SECURITY.md`。新下载的仓库规则不会让已经运行中的 Agent 自动重载，
 Git clone 本身也不会、且不应自动执行安装代码。
@@ -73,7 +75,7 @@ bin/claude-code-recover verify \
 
 仓库 wrapper 之外也可以使用当前解释器的 module 入口：macOS/Linux 常见写法是 `python3 -m claude_code_recover`，Windows 常见写法是 `py -3 -m claude_code_recover`。安装器实际使用的是启动它的同一个 Python，不依赖某个固定别名。
 
-RC2 为已有 RC1 安装保留一个发布周期的兼容别名：旧命令 `acgm-recover`、旧 module `python -m acgm_recover` 仍可使用，但已标记为 legacy；新文档和自动化必须使用 canonical 名称。检测到旧 distribution 时，bootstrap 会在任何修改前返回非可执行的 `MIGRATION_REQUIRED` 计划，不会把跨 distribution 卸载藏进 `--upgrade`。旧仓库地址 `https://github.com/johnrucnapier-sketch/ACGM-Recover` 仅用于识别和迁移旧 checkout，不是 RC2 的安装地址。
+RC3 继续为已有 RC1 安装保留过渡兼容别名：旧命令 `acgm-recover`、旧 module `python -m acgm_recover` 仍可使用，但已标记为 legacy；新文档和自动化必须使用 canonical 名称。检测到旧 distribution 时，bootstrap 会在任何修改前返回非可执行的 `MIGRATION_REQUIRED` 计划，不会把跨 distribution 卸载藏进 `--upgrade`。旧仓库地址 `https://github.com/johnrucnapier-sketch/ACGM-Recover` 仅用于识别和迁移旧 checkout，不是 RC3 的安装地址。
 
 当前默认本机数据路径针对 macOS；Linux 或自定义位置可显式传入：
 

diff --git a/RELEASING.md b/RELEASING.md
@@ -2,7 +2,7 @@
 
 No stable release is authorized by this RC repository state.
 
-The canonical RC2 product, distribution, archive prefix, tag documentation, and repository URL must use `Claude Code Recover`, `claude-code-recover`, and `https://github.com/johnrucnapier-sketch/Claude-Code-Recover`. The RC1 names are compatibility aliases only and must not become the primary release identity.
+The canonical RC3 product, distribution, archive prefix, tag documentation, and repository URL must use `Claude Code Recover`, `claude-code-recover`, and `https://github.com/johnrucnapier-sketch/Claude-Code-Recover`. The RC1 names are compatibility aliases only and must not become the primary release identity.
 
 A release candidate may be published only after:
 
@@ -14,8 +14,9 @@ A release candidate may be published only after:
 6. `PACKAGE_MANIFEST.json` is current.
 7. The result remains honest about `STRUCTURAL_ONLY` / `REVIEW_REQUIRED` / `HANDOFF_READY`; checksum success is not presented as handoff readiness.
 8. `scripts/bootstrap.py --dry-run --json` and a clean user installation pass without network access or evidence scanning.
-9. The canonical module/CLI entrypoints, one-RC legacy aliases, no-route `guide`, and all three explicit route arguments are tested; an installed RC1 distribution must produce `MIGRATION_REQUIRED` with zero pip mutation.
-10. Windows onboarding tests confirm installation support while also confirming `recovery_runtime_supported: false` and the absence of generated `discover/build` commands.
-11. The worktree is clean and the intended release commit, tag, and artifact are reviewed.
+9. Ordinary Python, virtual-environment, and PEP 668 supported/unsupported paths are tested. The override must appear only beside `--user`; an unsupported path must fail before wheel build or pip mutation, and a failed override install must not trigger automatic uninstall.
+10. The canonical module/CLI entrypoints, transition aliases, no-route `guide`, and all three explicit route arguments are tested; an installed RC1 distribution must produce `MIGRATION_REQUIRED` before the PEP 668 probe and with zero pip mutation.
+11. Windows onboarding tests confirm installation support while also confirming `recovery_runtime_supported: false` and the absence of generated `discover/build` commands.
+12. The worktree is clean and the intended release commit, tag, and artifact are reviewed.
 
 Do not describe an RC as stable. Do not publish from a dirty worktree. Do not reuse ACGM V3 tags or overwrite the original ACGM repository. Do not describe Windows bootstrap success as Windows core recovery support.