feat(pi): ctx setup pi - Pi coding-agent CLI integration

[bilersan]

feat(pi): ctx setup pi — Pi coding-agent CLI integration

New AI-tool integration: ctx setup pi [--write] for the Pi coding-agent CLI
(earendil-works/pi, pi.dev). Pi has no built-in MCP by design, so the
integration is a thin TypeScript extension + Agent-Skills-standard skills +
AGENTS.md; all logic stays in the ctx binary via ctx system subcommands.

Spec: specs/pi-cli-integration.md (committed on-branch).

What ships

• Embedded extension — internal/assets/integrations/pi/extension/ctx.ts:
  flat .pi/extensions/ctx.ts shim wiring Pi lifecycle events to ctx system:
  • session_start: warm-up ctx agent --budget 4000 off the prompt path
  • before_agent_start: injects the packet as a persistent
    customType: "ctx-context" message (display: true) only when no ctx
    message exists in the live context — compaction-aware scan of
    sessionManager.buildContextEntries() (summary + kept tail +
    post-compaction entries), so kept-tail packets suppress re-injection and
    folded-away packets trigger it; fail-safe across /new /resume /fork
/reload
  • tool_result (bash, git commit regex, !isError): ctx system post-commit
    with the hook-JSON envelope on piped+closed stdin (node:child_process
    is mandatory — Pi's exec helper hardcodes stdio: ["ignore","pipe","pipe"])
  • tool_result (edit/write, !isError): check-task-completion;
    agent_settled: check-persistence; session_compact: cache drop
• ctx setup pi — deploy core (internal/cli/setup/core/pi/) mirroring
  the OpenCode integration: extension fatal, AGENTS.md + 10 bundled skills
  warn; refresh-in-place, symlink/non-regular refusal; dry-run prints the
  hook.pi blueprint; case cfgHook.ToolPi in setup root (no new
  subcommand, no new Use* constant)
• CI gate — tools/typecheck/pi/ (strict tsc --noEmit against
  @earendil-works/pi-coding-agent@0.84.2 types, committed lockfile) +
  typecheck-pi-extension job in .github/workflows/ci.yml
• Docs — Pi entry in supported-tools reference, docs/home/pi.md
  quickstart, multi-tool recipe, zensical nav

Validation

• go build ./..., golangci-lint (0 issues), targeted go test green
• Full-suite delta vs clean main: zero new failures (all failing packages
  pre-exist on this Windows machine: CRLF render drift, .exe exec, audit
  path exemptions)
• Scratch project: init + dry-run + --write + idempotent re-run +
  tamper-refresh (byte-identical to embedded)
• Live pi: extension loads clean (A/B run with/without .pi identical);
  full LLM round-trip blocked by local pi provider config — left for a
  working-provider machine
• tsc --noEmit passes against pi-coding-agent 0.84.2 types

Reviews

• Independent sub-agent review: approve-with-nits — all nits addressed
  (32c55041: docstring, frontmatter coverage, spec naming)
• claude -p fable-5 effort-max branch audit: ship-ready after one
  decision — the one decision (kept-tail duplicate-injection gap, MAJOR 1)
  resolved by switching the predicate to a buildContextEntries() scan
  (694f6d37, with a one-line stdin stream hardening)

Notes / follow-ups

• site/ HTML rebuild deferred: this machine's zensical toolchain renders
  entity-escape drift vs the committed artifacts; rebuild on the canonical
  build machine (documented in PI.5 / commit 03a7e776)
• TASKS.md PI.8 tracks the remaining low-priority audit follow-ups
  (post-compaction re-warm location, embedded-asset EOL pinning, unused
  tool_result nudge channel, tsconfig paths hardening)

[josealekhine]

@bilersan looks good; give some fresh cookies to your minions.

Some nits:

Minor

1. Stale re-injection predicate in user docs — docs/home/pi.md:85 and
   docs/operations/integrations.md:643 still say the packet is injected
   "when no ctx-injected message exists after the most recent
   compaction". Commit 694f6d37 replaced that predicate with the
   live-context scan precisely because it caused duplicate injection when a
   packet survived into the kept tail; the docs now describe behavior the
   code deliberately no longer has. Suggest reusing the spec's wording:
   "when no ctx message exists in the live context (summary + kept tail +
   post-compaction entries)".

Nit

2. Spec latency claim overstates the warm-up guarantee —
   specs/pi-cli-integration.md:129-131 says "the prompt path never waits
   on ctx agent". On a cache miss — a first prompt that outruns the
   session_start warm-up, or the first prompt after compaction (the
   session_compact handler drops the cache) — before_agent_start awaits
   fetchPacket on the prompt path, bounded by the 15s timeout. PI.8
   already tracks the post-compaction re-warm; soften the spec sentence to
   match ("the first prompt normally injects from cache").

3. "Plugin hook" terminology in the Pi skill tree —
   pi/skills/ctx-agent/SKILL.md:16 says "The plugin hook already runs
   ctx agent on session start". Pi has extensions, not plugins; the
   wording is inherited byte-for-byte from the OpenCode tree. Since the
   trees are intentionally identical, fix it neutrally in both (e.g. "the
   tool integration already runs…") or accept it.

4. No drift guard on the intentionally-identical skill trees — the
   pi/opencode skill trees and the skill.go/validate.go deploy files are
   exact mirrors, but nothing enforces that. A cheap byte-identity test (or
   an eventual shared deploy helper — this is now the second full copy)
   would freeze the mirror; without it the trees will drift silently the
   first time someone edits one side. Candidate for PI.8.

5. Caret range in the typecheck gate's package.json —
   tools/typecheck/pi/package.json:9 declares
   "@earendil-works/pi-coding-agent": "^0.84.2" while the PR, README, and
   extension header all speak of pinning 0.84.2. npm ci + the committed
   lockfile pin CI today, but any lockfile regeneration silently floats to
   the newest 0.x minor. An exact 0.84.2 makes the gate's intent
   self-enforcing.

[bilersan]

Thanks for the read. Two commits since your comment:

• 9520e17 merges main (Codex + hook sweep + dependabot). All seven conflicts were the shared tool insertion points; both sides kept, Pi placed after Codex so the branch diff stays a pure addition.
• 6288c22 addresses the nits:

1. Docs predicate — docs/home/pi.md and the Pi section of docs/operations/integrations.md now use the spec wording: injected "when no ctx message exists in the live context (summary + kept tail + post-compaction entries)". Grep for the old "after the most recent compaction" phrase is empty.
2. Spec latency — softened to "the first prompt normally injects from cache", with the cache-miss path spelled out (first prompt outrunning the warm-up, or first prompt after session_compact drops the cache) and the 15s subprocess bound. The session_compact re-warm stays in PI.8(a), now with a note to cache the fetch promise so a cold-start prompt can't spawn a second ctx agent.
3. "Plugin hook" — now "The tool integration already runs ctx agent on session start" in both the Pi and OpenCode ctx-agent skills.
4. Drift guard — internal/assets/pi_test.go / TestPiSkillsMirrorOpenCode: walks both embedded trees, byte-equal in both directions, fails naming the file (verified by mutating one skill). The shared deploy helper is parked as PI.8(e); skill.go/validate.go differ only by package name and constants today.
5. Exact pin — "@earendil-works/pi-coding-agent": "0.84.2" in package.json and the lockfile root entry; npm ci + tsc --noEmit green.

Also folded in from an independent review pass: three DECISIONS.md entries for the choices the spec cited as "decided 2026-08-23" (display:true, live-context predicate, flat single-file extension); flag-era "flag loss can only cause an extra injection" wording replaced in the spec and the extension header comment (comment-only, typecheck green); README integrations row lists Pi.

One bundled chore: go.work.sum +2 lines (grpc v1.83.1 sums) — a clean main build on go 1.26.3 leaves the same drift. Happy to drop it from the branch if you'd rather take it separately.

Still pending: the live Pi round-trip (spec verification step 3) needs a machine with a working Pi provider; PI.6 records the block. Locally on Windows the full suite shows the same 28 pre-existing failing packages as clean main, zero new; lint 0 issues.