[PR #109] [MERGED] feat(analysis): persist snapshots and close Hopper reliably #1839

New issue

Closed

opened 2026-10-16 21:11:39 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:11:39 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/109
Author: @morluto
Created: 7/13/2026
Status: ✅ Merged
Merged: 7/13/2026
Merged by: @morluto

Base: main ← Head: codex/hopper-analysis-snapshots

📝 Commits (3)

179870e fix(hopper): cancel analysis and close documents reliably
c439b9e feat(analysis): add provider-neutral persistent snapshots
2c707ab fix(hopper): return addresses for procedure relationships

📊 Changes

33 files changed (+1794 additions, -350 deletions)

View changed files

📝 README.md (+32 -7)
📝 bridge/hopper_bridge.py (+30 -3)
➕ src/application/AnalysisSnapshotCache.ts (+212 -0)
➕ src/application/AnalysisSnapshotFiles.ts (+51 -0)
📝 src/application/BinarySession.ts (+131 -106)
➕ src/application/BinarySessionPort.ts (+75 -0)
➕ src/application/BoundedJsonFiles.ts (+130 -0)
📝 src/application/DirectAnalysis.ts (+175 -27)
📝 src/application/EvidenceBundleFiles.ts (+16 -117)
➕ src/application/UnknownEvidence.ts (+49 -0)
📝 src/application/runtime.ts (+1 -0)
📝 src/cli.ts (+19 -9)
📝 src/config.ts (+17 -7)
➕ src/contracts/sessionLifecycleInputs.ts (+13 -0)
➕ src/contracts/toolContractTypes.ts (+36 -0)
📝 src/contracts/toolContracts.ts (+26 -37)
📝 src/contracts/toolOutputSchemas.ts (+10 -1)
➕ src/domain/analysisSnapshot.ts (+226 -0)
📝 src/domain/evidence.ts (+4 -2)
📝 src/domain/evidenceBundle.ts (+50 -0)

...and 13 more files

📄 Description

Summary

stop Hopper background analysis during shutdown, wait for it to finish, close only the session-owned document, and verify the shutdown acknowledgement
add provider-neutral persistent analysis snapshots for exact immutable CLI and MCP analysis reuse
bind snapshots to binary digest, format, architecture, loader arguments, operation parameters, and provider identity
reject cursor/default-document reads, mutating or filesystem-writing operations, cross-target Evidence, custom Hopper loader overrides, and snapshots after metadata mutation
return deterministic entry-point addresses from direct caller/callee tools, matching their public contract
atomically import/export bounded owner-only snapshot files under separately approved roots

Fixes #108.

Contract and behavior changes

open_binary accepts an optional snapshot_path. close_binary accepts snapshot_path and overwrite; a failed save leaves the binary session open. The MCP inventory remains 68 tools.

Exact CLI evidence can be returned before Hopper starts:

export REA_ANALYSIS_SNAPSHOT_ROOTS_JSON='["/safe/analysis"]'
rea analyze /safe/bin/app --snapshot /safe/analysis/app.json
rea analyze /safe/bin/app --snapshot /safe/analysis/app.json

Sanitized MCP lifecycle example:

{"name":"open_binary","arguments":{"path":"/safe/bin/app","snapshot_path":"/safe/analysis/app.json"}}
{"name":"close_binary","arguments":{"snapshot_path":"/safe/analysis/app.json","overwrite":true}}

Verification

npm run check — 62 files, 419 tests, coverage thresholds passed
npm run verify:package — packaged CLI/setup/skill and 68-tool target-free MCP server passed
HOPPER_TARGET_PATH=/bin/ls HOPPER_SECOND_TARGET_PATH=/bin/cat npm run verify:hopper — passed against real Hopper with 68 tools, two distinct binaries, address-shaped relationships, target switching, and clean shutdown
npm run knip
npm run jscpd
npm run scan:todos
Autoreview found and drove fixes for state-dependent replay, mutation invalidation, cross-target evidence, loader/provider identity, filesystem side effects, atomic import, and lifecycle annotations

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/109 **Author:** [@morluto](https://github.com/morluto) **Created:** 7/13/2026 **Status:** ✅ Merged **Merged:** 7/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/hopper-analysis-snapshots` --- ### 📝 Commits (3) - [`179870e`](https://github.com/morluto/rea/commit/179870e8256419402464f02c918146865c6fbb93) fix(hopper): cancel analysis and close documents reliably - [`c439b9e`](https://github.com/morluto/rea/commit/c439b9e7787f3947eced0126a9c7b4d091584363) feat(analysis): add provider-neutral persistent snapshots - [`2c707ab`](https://github.com/morluto/rea/commit/2c707abb66433f9065733398a0e5ea9af04cfb96) fix(hopper): return addresses for procedure relationships ### 📊 Changes **33 files changed** (+1794 additions, -350 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+32 -7) 📝 `bridge/hopper_bridge.py` (+30 -3) ➕ `src/application/AnalysisSnapshotCache.ts` (+212 -0) ➕ `src/application/AnalysisSnapshotFiles.ts` (+51 -0) 📝 `src/application/BinarySession.ts` (+131 -106) ➕ `src/application/BinarySessionPort.ts` (+75 -0) ➕ `src/application/BoundedJsonFiles.ts` (+130 -0) 📝 `src/application/DirectAnalysis.ts` (+175 -27) 📝 `src/application/EvidenceBundleFiles.ts` (+16 -117) ➕ `src/application/UnknownEvidence.ts` (+49 -0) 📝 `src/application/runtime.ts` (+1 -0) 📝 `src/cli.ts` (+19 -9) 📝 `src/config.ts` (+17 -7) ➕ `src/contracts/sessionLifecycleInputs.ts` (+13 -0) ➕ `src/contracts/toolContractTypes.ts` (+36 -0) 📝 `src/contracts/toolContracts.ts` (+26 -37) 📝 `src/contracts/toolOutputSchemas.ts` (+10 -1) ➕ `src/domain/analysisSnapshot.ts` (+226 -0) 📝 `src/domain/evidence.ts` (+4 -2) 📝 `src/domain/evidenceBundle.ts` (+50 -0) _...and 13 more files_ </details> ### 📄 Description ## Summary - stop Hopper background analysis during shutdown, wait for it to finish, close only the session-owned document, and verify the shutdown acknowledgement - add provider-neutral persistent analysis snapshots for exact immutable CLI and MCP analysis reuse - bind snapshots to binary digest, format, architecture, loader arguments, operation parameters, and provider identity - reject cursor/default-document reads, mutating or filesystem-writing operations, cross-target Evidence, custom Hopper loader overrides, and snapshots after metadata mutation - return deterministic entry-point addresses from direct caller/callee tools, matching their public contract - atomically import/export bounded owner-only snapshot files under separately approved roots Fixes #108. ## Contract and behavior changes `open_binary` accepts an optional `snapshot_path`. `close_binary` accepts `snapshot_path` and `overwrite`; a failed save leaves the binary session open. The MCP inventory remains 68 tools. Exact CLI evidence can be returned before Hopper starts: ```sh export REA_ANALYSIS_SNAPSHOT_ROOTS_JSON='["/safe/analysis"]' rea analyze /safe/bin/app --snapshot /safe/analysis/app.json rea analyze /safe/bin/app --snapshot /safe/analysis/app.json ``` Sanitized MCP lifecycle example: ```json {"name":"open_binary","arguments":{"path":"/safe/bin/app","snapshot_path":"/safe/analysis/app.json"}} {"name":"close_binary","arguments":{"snapshot_path":"/safe/analysis/app.json","overwrite":true}} ``` ## Verification - `npm run check` — 62 files, 419 tests, coverage thresholds passed - `npm run verify:package` — packaged CLI/setup/skill and 68-tool target-free MCP server passed - `HOPPER_TARGET_PATH=/bin/ls HOPPER_SECOND_TARGET_PATH=/bin/cat npm run verify:hopper` — passed against real Hopper with 68 tools, two distinct binaries, address-shaped relationships, target switching, and clean shutdown - `npm run knip` - `npm run jscpd` - `npm run scan:todos` - Autoreview found and drove fixes for state-dependent replay, mutation invalidation, cross-target evidence, loader/provider identity, filesystem side effects, atomic import, and lifecycle annotations --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:11:39 +00:00