feat: pin Pi packages and manage resource directories

[kunchenguid]

Intent

Implement the public dotfiles Pi follow-up: declare exactly the audited npm codex-fast package at 0.2.6 and the captain-authorized immutable algal OpenAI server-compaction commit through Pi global settings without vendoring either; retain Pi runtime ownership of npm/git packages and document the clean-HOME Pi 0.82 startup auto-install behavior, immutable update process, experimental stale peer range, security implications, and privacy boundary. Change Home Manager from the two existing Pi child-file links to whole out-of-store themes and extensions directory links while retaining individual settings.json and models.json links, with a narrowly scoped migration that only removes the exact legacy managed links before collision checks. Add focused non-activating migration and configuration regression coverage. Do not manage auth, sessions, trust, caches, package trees, or any other Pi runtime state; do not modify private dotfiles, activate live configuration, vendor package sources, or create an upstream PR. The captain explicitly accepted the exact compaction commit on Pi 0.82 despite its upstream stale >=0.80.9 <0.81.0 peer bound after local load and remote-compaction proof; third-party packages execute with full user permissions.

What Changed

• Declare the audited Pi packages as immutable npm version and Git commit pins in global settings while leaving downloaded package trees and runtime state under Pi ownership.
• Manage the authored Pi themes and extensions as whole out-of-store directories, with a narrowly scoped migration for the two legacy child links before collision checks.
• Add non-activating regression coverage, document startup installation, updates, compatibility, security, and privacy boundaries, and expose AGENTS.md through a CLAUDE.md symlink.

Risk Assessment

✅ Low: The change is well bounded, satisfies the stated Pi package and runtime ownership constraints, and the corrected migration precisely recognizes the prior Home Manager link shape with matching non-activating regression coverage.

Testing

The non-activating Home Manager build and disposable migration regression passed, including preservation of unrelated Pi state. An isolated clean-HOME Pi 0.82.0 startup automatically installed npm package 0.2.6 and detached the compaction repository at commit c6d593087709e9481223dc6c6c2269b371b5e055 into Pi-owned npm/git directories.

Evidence: Focused Home Manager migration test

warning: Git tree '<isolated-no-mistakes-worktree>' has uncommitted changes
warning: Home Manager evaluation referenced '<nix-store-path>'
these activation derivations were built under '<nix-store-path>'
Pi package declarations, runtime boundary, link shape, and child-to-parent migration passed.

Evidence: Pi 0.82 isolated clean-HOME startup

Starting with <isolated-clean-home> on Pi 0.82.0

npm package 0.2.6 installed successfully
Cloning into '<isolated-clean-home>/.pi/agent/git/github.com/algal/pi-openai-server-compaction'...
HEAD is now at c6d5930 update README.md
Git package dependencies installed successfully

Resolved installed packages:
@ryan_nookpi/pi-extension-codex-fast-mode@0.2.6
c6d593087709e9481223dc6c6c2269b371b5e055
declared Pi peer range: >=0.80.9 <0.81.0
Pi-owned runtime directories: git,npm

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (2) ✅

• 🚨 home.nix:81 - The migration compared each link's immediate readlink value with the repository source, but Home Manager links $HOME entries to <nix-store-path>-home-manager-files/..., which only then resolves to the out-of-store source. A real upgrade would leave both child links and directories in place, causing checkLinkTargets to reject the new parent-directory links. The test originally created direct repository links. The fix matches the Home Manager-owned immediate target, verifies its fully resolved destination, and reproduces that two-hop shape in the test fixture.

🔧 Fix: Recognize Home Manager links during Pi directory migration

• 🚨 tests/pi-home-manager.sh:67 - The assertion expected canonicalization to preserve the ~/.dotfiles alias, but bootstrap makes that path a symlink to the repository, so canonicalization returns the repository's physical path instead. The fix compares both sides after canonicalization and asserts that the expected source resolves successfully.

🔧 Fix: Canonicalize expected Pi migration test source

✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• Inspected the target commit against the base for package pins, ownership boundaries, migration scope, and documentation.
• Ran the focused migration regression and the isolated clean-HOME Pi startup proof.
• Verified npm package identity, compaction repository commit, declared stale Pi peer range, and Pi-owned runtime directories.

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.