pi-tui-stability-patch

Version-locked runtime patch for the Node/npm distribution of Pi 0.83.0.

This package updates Pi's installed JavaScript runtime to add:

• application-owned alternate-screen viewport by default;
• explicit --main-screen compatibility mode;
• streaming assistant block reuse;
• manual follow-end intent preservation through layout clamps;
• component-row scroll anchors for content reflow above the viewport;
• constant-size alternate-screen shutdown without replaying the full transcript.

Safety model

This is an explicit host patch, not a Pi extension. npm install and npm pack never modify Pi. Changes happen only after an explicit install or reinstall command.

The installer:

1. supports only @earendil-works/[email protected] with its bundled @earendil-works/[email protected];
2. verifies every existing target file against the official npm 0.83.0 SHA-256 baseline before writing;
3. refuses mixed, modified, unsupported, native-Windows, and Bun-binary targets;
4. backs up every replaced file and records newly added files;
5. writes files atomically and rolls back a failed install;
6. refuses uninstall if patched files were modified afterward.

No privilege escalation is attempted. If the Pi installation is not writable, the command fails without using sudo.

Supported environment

• Node.js >=22.19.0
• Pi installed from npm as @earendil-works/[email protected]
• Linux, WSL, or macOS

Not supported:

• Bun standalone binaries
• native Windows installations
• forks or repacked Pi distributions with different target hashes
• Pi versions other than 0.83.0

Usage

Inspect the current installation:

npx pi-tui-stability-patch status

Install and restart Pi:

npx pi-tui-stability-patch install

Verify:

npx pi-tui-stability-patch verify

Restore the exact files backed up during installation:

npx pi-tui-stability-patch uninstall

Reapply after a clean reinstall of supported Pi:

npx pi-tui-stability-patch reinstall

Use --target <dir> when Pi cannot be discovered from PATH, or when testing an isolated installation. The directory may be the coding-agent package root or a parent containing node_modules/@earendil-works/pi-coding-agent.

Use --state-dir <dir> to override the backup/manifest directory. The default is:

~/.pi/patches/pi-tui-stability-patch/0.83.0

All commands accept --json.

Update behavior

pi update or npm reinstall may restore upstream files. Run status afterward. A new Pi version requires a separately reviewed payload; this package will refuse unknown versions instead of attempting a fuzzy patch.

Development

The published tarball includes patches/0.83.0/definition.json and provenance/alt-stop-no-replay.patch. The definition records the official baseline tarball hashes, the complete source commit sequence, the reviewed source tree digest, and the audited no-replay patch digest.

Payload generation is intentionally excluded from normal npm installation. It requires:

• official Pi 0.83.0 coding-agent, TUI, AI, and agent-core tarballs plus unpacked baselines at /tmp/pi-patch-npm or PI_PATCH_BASELINE;
• the reviewed source tree at PI_PATCH_SOURCE with the exact commit/diff provenance recorded in the generator.

The generator verifies provenance, installs the source tree's locked dependencies with npm ci --ignore-scripts when needed, replaces only AI/agent build dependencies with hash-pinned official 0.83.0 dist files, deletes existing TUI/coding-agent dist output, and performs clean builds before creating the payload.

PI_PATCH_SOURCE=/path/to/reviewed/source npm run build
npm run check
npm pack --dry-run

On DrvFS-mounted workspaces such as /mnt/d, use the staging command before publishing so ordinary package files receive 0644 mode:

npm run stage-release
cd /tmp/pi-tui-stability-patch-release-0.1.0
npm publish --access public

License

MIT. The payload contains modified portions of Pi and retains Pi's MIT license and copyright notice in NOTICE.