feat: package Recall on Pi native surfaces

[edheltzel]

Summary

• Declare Recall as a native Pi package for its two package resources: the lifecycle extensions and all nine Agent Skills.
• Install and configure pi-mcp-adapter separately for the recall-memory MCP server, preserving existing user choices and safely migrating legacy shadow copies.
• Use Pi supported session APIs for shutdown capture and pre-agent memory context.
• Document the integration and the hard limit plainly: Pi has no single package primitive spanning extensions, skills, and MCP.

Verified Pi surface

Verified against the installed Pi CLI 0.81.1 with pi --help, pi install --help, pi list --help, and pi --no-extensions --help.

Pi packages natively discover extensions, skills, prompts, and themes, but not MCP configuration.
The --mcp-config surface disappears under --no-extensions, confirming that MCP support in this installation comes from the separate adapter extension.
The implementation follows the pinned official package, skill, and extension lifecycle contracts.

Safety and compatibility

• Installation remains one human step through recall install --yes while composing the native Pi package and the separate MCP adapter/config underneath.
• Reinstall is idempotent.
• Existing explicit directTools preferences survive refresh.
• Legacy Recall-managed Pi shadows are removed, while customized or foreign collisions are backed up instead of overwritten.
• Claude packaging is unchanged.

Validation

• bun test: 1,256 passed, 0 failed across 104 files.
• bun run lint: passed.
• bash -n install.sh update.sh uninstall.sh lib/install-lib.sh: passed.
• bun run test:e2e:pi-integration: passed with Pi 0.81.1, two installs, nine skills, nine direct MCP tools, lifecycle capture, and legacy-shadow cleanup.
• bun run test:e2e:codex-plugin: passed after extracting the shared isolation helper.

The Pi E2E used disposable HOME, PI_CODING_AGENT_DIR, RECALL_HOME, and RECALL_DB_PATH paths.
The production database /Users/ed/.agents/Recall/recall.db was never opened by the test and had identical before/after metadata: size 178216960, mtime 1784748240001.284, inode 571168746.

Pi limitation

This is intentionally not a Codex-style or Claude-style all-in-one plugin bundle.
Pi has no verified manifest that installs extensions, skills, and MCP as one package, so Recall uses each native mechanism directly and lets the installer coordinate them without inventing a cross-host bundle abstraction.
The MCP adapter discovers direct tools after its initial metadata warmup; the first session can use the adapter proxy and then reload Pi for the nine direct recall_memory_* tools.

Related: #228

Issues

This PR closes nothing, deliberately - no closing keyword is used.

Re-checked against every issue in this repo (125 total, 31 open), reading acceptance criteria rather than matching titles. No open issue tracks Pi packaging, and nothing in this diff fully satisfies an existing issue. References below are keyword-free on purpose so none of them is silently closed on merge.

Base branch is main (the repo default), so any keyword added here would fire on merge - which is why none is present.

Partially addresses, but NOT closed

• Partially addresses 10 lifecycle tests fail in any git worktree — the environment AGENTS.md mandates for workers has a permanently red baseline #243 (10 lifecycle tests fail in any git worktree). 10 lifecycle tests fail in any git worktree — the environment AGENTS.md mandates for workers has a permanently red baseline #243's "note 1" flags a defect independent of the worktree trigger: _recall_jsonc_merge_mcp_entry claims success on a write that did not happen. This PR closes one instance of that class - when the parent container is missing, jsonc-parser's modify() cannot materialize the intermediate object, so the helper now builds the container explicitly and hard-fails on a no-op edit rather than printing success (plus a new creates mcp.json and its parent container on a fresh install test).

  10 lifecycle tests fail in any git worktree — the environment AGENTS.md mandates for workers has a permanently red baseline #243 itself is not fixed by this PR. Measured in a node_modules-less worktree, same machine, before vs after this branch:

  	tests/opencode-integration.test.ts	tests/pi-integration.test.ts
  main	31 pass / 5 fail (36)	19 pass / 5 fail (24)
  this branch	31 pass / 5 fail (36)	23 pass / 7 fail (30)

  The worktree red baseline goes from 10 to 12 failing tests - not a regression in behavior, but two of this PR's six new recall_configure_pi_mcp tests land in the same environment-dependent family. 10 lifecycle tests fail in any git worktree — the environment AGENTS.md mandates for workers has a permanently red baseline #243 stays open and is arguably slightly louder.

Related, but NOT closed

• Related to Migrate all Recall slash commands to Agent Skills — one namespace across Claude/Pi/omp #228 (already noted above): Pi now discovers the nine canonical recall-* Agent Skills through the native package manifest instead of symlinks, so the one-namespace surface Migrate all Recall slash commands to Agent Skills — one namespace across Claude/Pi/omp #228 established is preserved on a new mechanism. Migrate all Recall slash commands to Agent Skills — one namespace across Claude/Pi/omp #228 is already closed; this is context, not a claim.
• Related to recall doctor/installer: atomic config-write parity in _recall_ensure_mcp_entry (lib/install-lib.sh) #124 (atomic config-write parity in _recall_ensure_mcp_entry). This PR substantially rewrites the sibling _recall_jsonc_merge_mcp_entry - env/environment deep-merge, PRESERVE_KEYS, missing-container construction, no-op rejection - but none of recall doctor/installer: atomic config-write parity in _recall_ensure_mcp_entry (lib/install-lib.sh) #124's asks: still an in-place writeFileSync from bun -e, no temp-sibling + rename, no realpath resolution through symlinks, no backup taken immediately before the confirmed write. recall doctor/installer: atomic config-write parity in _recall_ensure_mcp_entry (lib/install-lib.sh) #124 stays open.

Considered and deliberately NOT linked

• chore: #230 audit debt — lifecycle test gaps, doc corrections, guide parity, stale comments #238 (Migrate all /Recall:* slash commands to recall-* Agent Skills #230 audit debt). This PR edits both files chore: #230 audit debt — lifecycle test gaps, doc corrections, guide parity, stale comments #238 names, without fixing the items it lists: docs/architecture.md still documents skill canonicals at ~/.agents/Recall/claude/shared/skills/ (actual: top-level shared/skills/), and FOR_PI.md still names only a few of the nine skills rather than enumerating them the way FOR_CLAUDE.md does. Touching the file is not addressing the issue.
• docs: stale backup path ~/.claude/backups/recall in installation.md + upgrading.md #174 (stale backup path docs). This PR edits docs/installation.md and docs/upgrading.md, but ~/.claude/backups/recall/ still appears at three sites in each (installation.md L122/L235/L278, upgrading.md L45/L84/L296). Not fixed.
• harden: uninstall wipes user-authored files — ownership inferred by name/dir while install is per-file (#230 audit) #236 (uninstall wipes user-authored files). remove_pi gains pi remove for the package registration; remove_skills_from's rm -rf and remove_slash_commands - the actual subject of harden: uninstall wipes user-authored files — ownership inferred by name/dir while install is per-file (#230 audit) #236 - are unchanged.
• Installer hardening (borrowed from mnemon review): JSON5-tolerant settings parsing, $HOME collision guard, remove emptied settings file on uninstall #231 (installer hardening: JSON5-tolerant settings parsing, $HOME collision guard, remove emptied settings file on uninstall). None of the three items is implemented; the JSONC tolerance here is the pre-existing jsonc-parser path for OpenCode/Pi, not the ~/.claude/settings.json reads Installer hardening (borrowed from mnemon review): JSON5-tolerant settings parsing, $HOME collision guard, remove emptied settings file on uninstall #231 targets.
• chore: fresh /ce-worktree worktrees miss node_modules → ~10 MCP-config tests fail spuriously #165 (fresh worktrees miss node_modules) - untouched; see the 10 lifecycle tests fail in any git worktree — the environment AGENTS.md mandates for workers has a permanently red baseline #243 measurement above.

Attribution note

#48 was resolved by #245 (the src/hosts/session-source.ts registry), and the Codex packaging work also landed there. Neither is re-claimed here.