[PR #5041] [MERGED] fix(hopper): verify and repair the Linux embedding runtime #6753

New issue

Closed

opened 2026-11-01 21:42:48 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:42:48 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5041
Author: @gensokyo-dev
Created: 10/18/2026
Status: ✅ Merged
Merged: 10/18/2026
Merged by: @gensokyo-dev

Base: main ← Head: fix/5015-hopper-linux-python-runtime

📝 Commits (2)

0c70be0 fix(hopper): verify and repair the Linux embedding runtime
0b44dc1 fix(hopper): preserve probe cancellation and process ownership

📊 Changes

14 files changed (+3653 additions, -60 deletions)

View changed files

📝 docs/installation.md (+14 -0)
📝 experiments/analysis-efficiency/README.md (+4 -0)
➕ experiments/analysis-efficiency/hopper-linux-python-runtime.json (+2270 -0)
➕ experiments/analysis-efficiency/hopper-linux-python-runtime.md (+203 -0)
📝 src/application/LinuxHopper.test.ts (+40 -0)
📝 src/application/LinuxHopper.ts (+178 -41)
➕ src/application/LinuxHopperPackageRuntime.test.ts (+264 -0)
➕ src/application/LinuxHopperPython.test.ts (+257 -0)
➕ src/application/LinuxHopperPython.ts (+157 -0)
📝 src/application/SetupHost.ts (+5 -2)
📝 src/application/SetupInstallFailure.ts (+2 -2)
📝 src/application/SetupPlan.ts (+1 -1)
📝 src/doctorRuntime.test.ts (+190 -1)
📝 src/doctorRuntime.ts (+68 -13)

📄 Description

Summary

Fixes #5015. On a clean Ubuntu 24.04 root, real setup reported ready while Python's embedding library was absent; Hopper's bridge then timed out. Installing only the matching shared library made the unchanged runtime and target work.

Setup now verifies the distribution Python shared runtime, conditionally installs the matching library, and verifies the load again. Doctor shares the same fresh, bounded inspection and preserves unknown configuration separately from missing dependencies.

Scope and boundaries

Existing Linux Hopper installer/dependency repair; maintainer scope decision: not applicable. No new target execution or mutation capability.
Probe: isolated /usr/bin/python3, 10-second work deadline, existing five-second stop/kill grace, 64-KiB output; no cache of changing system state. Only standard Ubuntu ABI/layout establishes the APT mapping; custom paths/SONAMEs remain unknown.
Approved plans disclose the conditional package command. Existing package output, cancellation reason and temporary cleanup semantics remain available. Running package transactions settle before cancellation prevents another stage. Cancelled doctor probes propagate the domain cancellation with completed display facts, and Python probe completion joins child exit.
CLI doctor reports system-interpreter facts; the Python interpreter selected inside Hopper remains unknown. MCP analysis contracts, catalog, target selection and Evidence semantics are unchanged.

Executed validation

Initial fix: npm run build:cached — passed. Current-head local rebuild was guard-stopped; current-head CI Build package passed.
Initial npm run test:focused -- seven affected source/CLI/publisher boundary files — 151 passed.
Current head: npm run test:run -- the same seven files — 154 passed, using authenticated same-head CI build outputs (no local rebuild success claim).
Follow-up cancellation/cleanup regressions: five files, 88 passed, including a real Python delayed-exit handshake and the shared stop-and-wait lifecycle suite.
npm run lint — passed, including resolved module boundaries.
npm run verify:test-discovery — passed.
Initial npm run docs:check — passed; current-head CI Docs Generation passed.
Actual public setup on a fresh full-UID Ubuntu root — ready, installed_hopper, clean dpkg --audit; actual public doctor healthy.
Pinned initial-fix normal-user real Hopper 6.6 demo: 13 control-ELF and 16 shipped-SQLite MCP calls passed, plus two public CLI parity workflows. Independent objdump oracle, native inventory/positive/negative/regex/case checks, repeated Evidence identity, unchanged target bytes and owned-process cleanup verified. SQLite MCP: 92.504 s, 90.138 CPU s, 1,580,445,696 B native-family peak.

Current head 0b44dc1533e85e979abead8fa9ff9e470e956b6e: 40/40 CI checks succeeded, including full package verification. Follow-up real public doctor, normal-user 13-call MCP control workflow and CLI/Evidence parity also passed; owned process cleanup and unchanged target bytes were verified. The CI runtime archive (run 39142585597, artifact 12142331918) matched SHA-256 1d342ccc12ef59f3fb842c9847fcaf6426d6c4a6b953f1de46c07f9d31a4c303; the restored dist/bridge manifest is ae91bd5cc39ba32b89ed0a00d8266730d9517d1ae954f246c9eb4e50c6af8044. Control MCP: 25.753 s, 23.883 native CPU s, 1,355,321,344 B peak; CLI: 9.276 s, 8.258 native CPU s, 634,195,968 B peak. Artifact transfer/extraction and shared infrastructure costs are unmeasured. The large SQLite cohort remains pinned to the preceding initial-fix artifact.

Qualification, measurements and failed attempts include the runtime/target identities and offline token estimates. This prerequisite fix makes no equivalent-task speedup or actual model-token reduction claim.

Validation limits

Full local check:fast was guard-stopped twice by external host memory pressure. verify:package completed install/update/module/discovery and several CLI stages, then was guard-stopped during setup/uninstall; it did not pass the complete gate. Local hooks were skipped for commit/push after the completed focused/lint checks; The corresponding current-head GitHub CI gates, including package verification, completed successfully before normal merge. No GitHub required-check bypass is requested.

Jobs retain an 8-GiB host limit; native/container plus controller caps total 6.5 GiB with one CPU and zero swap. Non-root installation through actual pkexec authorization, custom Hopper Python configurations, native Debian installation, other OSes and complex-investigation effectiveness remain unverified. No breaking tool/API or package metadata changes.

Author readiness

Human owner: @gensokyo-dev

The owner explicitly authorized ready PRs and delegated readiness entry in this session. The agent reviewed the final diff, relevant source and validation under that delegation; independent human review of this final diff is not asserted.

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 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/5041 **Author:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Created:** 10/18/2026 **Status:** ✅ Merged **Merged:** 10/18/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `fix/5015-hopper-linux-python-runtime` --- ### 📝 Commits (2) - [`0c70be0`](https://github.com/morluto/rea/commit/0c70be0030f6bb821c4292c4f5b7f776b365c8ec) fix(hopper): verify and repair the Linux embedding runtime - [`0b44dc1`](https://github.com/morluto/rea/commit/0b44dc1533e85e979abead8fa9ff9e470e956b6e) fix(hopper): preserve probe cancellation and process ownership ### 📊 Changes **14 files changed** (+3653 additions, -60 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+14 -0) 📝 `experiments/analysis-efficiency/README.md` (+4 -0) ➕ `experiments/analysis-efficiency/hopper-linux-python-runtime.json` (+2270 -0) ➕ `experiments/analysis-efficiency/hopper-linux-python-runtime.md` (+203 -0) 📝 `src/application/LinuxHopper.test.ts` (+40 -0) 📝 `src/application/LinuxHopper.ts` (+178 -41) ➕ `src/application/LinuxHopperPackageRuntime.test.ts` (+264 -0) ➕ `src/application/LinuxHopperPython.test.ts` (+257 -0) ➕ `src/application/LinuxHopperPython.ts` (+157 -0) 📝 `src/application/SetupHost.ts` (+5 -2) 📝 `src/application/SetupInstallFailure.ts` (+2 -2) 📝 `src/application/SetupPlan.ts` (+1 -1) 📝 `src/doctorRuntime.test.ts` (+190 -1) 📝 `src/doctorRuntime.ts` (+68 -13) </details> ### 📄 Description ## Summary Fixes #5015. On a clean Ubuntu 24.04 root, real setup reported `ready` while Python's embedding library was absent; Hopper's bridge then timed out. Installing only the matching shared library made the unchanged runtime and target work. Setup now verifies the distribution Python shared runtime, conditionally installs the matching library, and verifies the load again. Doctor shares the same fresh, bounded inspection and preserves unknown configuration separately from missing dependencies. ## Scope and boundaries - Existing Linux Hopper installer/dependency repair; maintainer scope decision: not applicable. No new target execution or mutation capability. - Probe: isolated `/usr/bin/python3`, 10-second work deadline, existing five-second stop/kill grace, 64-KiB output; no cache of changing system state. Only standard Ubuntu ABI/layout establishes the APT mapping; custom paths/SONAMEs remain unknown. - Approved plans disclose the conditional package command. Existing package output, cancellation reason and temporary cleanup semantics remain available. Running package transactions settle before cancellation prevents another stage. Cancelled doctor probes propagate the domain cancellation with completed display facts, and Python probe completion joins child exit. - CLI doctor reports system-interpreter facts; the Python interpreter selected inside Hopper remains unknown. MCP analysis contracts, catalog, target selection and Evidence semantics are unchanged. ## Executed validation - Initial fix: `npm run build:cached` — passed. Current-head local rebuild was guard-stopped; current-head CI **Build package** passed. - Initial `npm run test:focused --` seven affected source/CLI/publisher boundary files — **151 passed**. - Current head: `npm run test:run --` the same seven files — **154 passed**, using authenticated same-head CI build outputs (no local rebuild success claim). - Follow-up cancellation/cleanup regressions: five files, **88 passed**, including a real Python delayed-exit handshake and the shared stop-and-wait lifecycle suite. - `npm run lint` — passed, including resolved module boundaries. - `npm run verify:test-discovery` — passed. - Initial `npm run docs:check` — passed; current-head CI **Docs Generation** passed. - Actual public setup on a fresh full-UID Ubuntu root — `ready`, `installed_hopper`, clean `dpkg --audit`; actual public doctor healthy. - Pinned initial-fix normal-user real Hopper 6.6 demo: **13 control-ELF and 16 shipped-SQLite MCP calls passed**, plus two public CLI parity workflows. Independent objdump oracle, native inventory/positive/negative/regex/case checks, repeated Evidence identity, unchanged target bytes and owned-process cleanup verified. SQLite MCP: 92.504 s, 90.138 CPU s, 1,580,445,696 B native-family peak. Current head `0b44dc1533e85e979abead8fa9ff9e470e956b6e`: **40/40 CI checks succeeded**, including full package verification. Follow-up real public doctor, normal-user 13-call MCP control workflow and CLI/Evidence parity also passed; owned process cleanup and unchanged target bytes were verified. The CI runtime archive (run `39142585597`, artifact `12142331918`) matched SHA-256 `1d342ccc12ef59f3fb842c9847fcaf6426d6c4a6b953f1de46c07f9d31a4c303`; the restored dist/bridge manifest is `ae91bd5cc39ba32b89ed0a00d8266730d9517d1ae954f246c9eb4e50c6af8044`. Control MCP: 25.753 s, 23.883 native CPU s, 1,355,321,344 B peak; CLI: 9.276 s, 8.258 native CPU s, 634,195,968 B peak. Artifact transfer/extraction and shared infrastructure costs are unmeasured. The large SQLite cohort remains pinned to the preceding initial-fix artifact. [Qualification, measurements and failed attempts](https://github.com/morluto/rea/blob/0b44dc1533e85e979abead8fa9ff9e470e956b6e/experiments/analysis-efficiency/hopper-linux-python-runtime.md) include the runtime/target identities and offline token estimates. This prerequisite fix makes no equivalent-task speedup or actual model-token reduction claim. ## Validation limits Full local `check:fast` was guard-stopped twice by external host memory pressure. `verify:package` completed install/update/module/discovery and several CLI stages, then was guard-stopped during setup/uninstall; it did **not** pass the complete gate. Local hooks were skipped for commit/push after the completed focused/lint checks; The corresponding current-head GitHub CI gates, including package verification, completed successfully before normal merge. No GitHub required-check bypass is requested. Jobs retain an 8-GiB host limit; native/container plus controller caps total 6.5 GiB with one CPU and zero swap. Non-root installation through actual pkexec authorization, custom Hopper Python configurations, native Debian installation, other OSes and complex-investigation effectiveness remain unverified. No breaking tool/API or package metadata changes. ## Author readiness Human owner: @gensokyo-dev The owner explicitly authorized ready PRs and delegated readiness entry in this session. The agent reviewed the final diff, relevant source and validation under that delegation; independent human review of this final diff is not asserted. - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:42:48 +00:00