docs: record kernel id-immutability contract + kernel pin guard

[ranxianglei]

Adds a "Kernel Contract" subsection to AGENTS.md §2, paired with kernel revert ranxianglei/acp-kernel#191:

Within a session, a raw content-hash id and a ref number (mNNNNN) denote exactly one message forever — never reused, never duplicated, even after the message dies. Capacity is solved by widening the ref space, never by recycling numbers.

This repo currently pins acp-kernel@0.0.48, which CONTAINS the unsafe ref reclamation (PR #176) — its processTurn pipeline prunes and re-issues numbers every turn. Recommendation recorded in the doc: move off 0.0.48 — either down to 0.0.47 (this repo does not use the 0.0.49 handoff renderer) or up to the revert release once it ships. Docs-only PR; version change to be decided by maintainer.

[github-actions]

📦 Built Extension Artifact

Branch: 2026-09-03_agents-id-invariant (34b6f0c)

Option A — Install from npm PR tag (recommended)

pi install npm:billion-context-pi@pr-280

Each push to this PR publishes a new version under the pr-280 npm tag.

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pi-pr280.tgz
pi install ./package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 ework agent · qwen3.8-27b

[bot] 🏷 Review complete — verdict: APPROVE (docs-only, diff = AGENTS.md +14 lines; all factual claims verified against the kernel repo and npm). Two minor wording nits + one recommendation on the pin question below.

Duplicate screening: no other issue/PR in this repo covers the id-immutability contract or the kernel pin — not a duplicate.

What I verified

1. Pin claim ✓ — master and the PR branch pin acp-kernel@0.0.48 (package.json:63, package-lock.json:14).
2. Version containment ✓ — from acp-kernel git tags: v0.0.47..v0.0.48 contains exactly test: outbound provider view stays byte-stable across context rounds #175 (stale-ref gate wording) + 做个dsh版吧大佬 #176 (ref-slot reclamation); v0.0.48..v0.0.49 adds only fix(setup): subagent ACP tool injection becomes an explicit /acp-subagents command (#179) #183 (handoff renderer renderHandoff/renderMessage/matchSession). So "做个dsh版吧大佬 #176 in 0.0.48/0.0.49" is exact.
3. "This repo does not use the 0.0.49 handoff renderer" ✓ — zero references to any handoff API in src/. Going further: I checked every symbol this repo imports from acp-kernel (29 across 15 files: createCore, parseCompressArgs, viableRanges, searchBlocks, blockDocs, buildStatusReport, …) against v0.0.47 exports — all exist there. The only new exports in 0.0.48 are pruneDeadRefs + BoundaryFailureReason, neither used here. Downgrading to 0.0.47 is API-safe; the sole loss vs 0.0.48 is test: outbound provider view stays byte-stable across context rounds #175's improved stale-ref-gate error wording (cosmetic).
4. Revert status ✓ — acp-kernel#191 is still OPEN; npm latest stable is 0.0.49 (still ships 做个dsh版吧大佬 #176); the revert exists only as prerelease tag pr-191 (0.0.49-pr.191.43). The doc's "wait for the revert release" guidance is correct as of today.
5. Stronger than the issue body states: the reclamation needs no host opt-in. In 0.0.48, assignRefsNode calls pruneDeadRefs before every allocation (kernel src/compress.ts:521) and syncBlocksNode → syncBlocks prunes again each turn (src/sync.ts:91) — both are in the default pipeline (buildNodes). So the shipped billion-context-pi@0.1.55 (bundles kernel 0.0.48) is exposed to silent decompress misattribution right now, not merely on a future bump. That raises the urgency of the pin decision.

Nits (non-blocking)

1. "…violated this and was reverted (kernel chore(deps): bump acp-kernel 0.0.30 -> 0.0.32 #191)" — chore(deps): bump acp-kernel 0.0.30 -> 0.0.32 #191 isn't merged yet (npm latest stable 0.0.49 still contains 做个dsh版吧大佬 #176). Suggest "is being reverted (acp-kernel#191, pending)". The following sentence ("only after the revert release ships") already signals it hasn't landed, so this is cosmetic.
2. "bump from 0.0.47 only after…" presumes a 0.0.47 baseline (true for the sibling host billion-context); this repo sits at 0.0.48, so the immediate action here is the parenthetical "bump back down to 0.0.47". Acceptable since the text is written for both hosts' AGENTS.md, just worth knowing.

Recommendation on the pin (your call, per the issue scope)

Given point 5 — the unsafe behavior is live in the currently published bundle, and the revert release's timing is unknown (#191 needs 2-agent review + human merge + CI publish) — I'd lean toward downgrading to 0.0.47 now (in this PR or an immediate follow-up) rather than waiting. It's verified API-safe by check 3 above and restores the never-reuse invariant for existing users immediately. If you want, say the word and I'll prepare the pin-downgrade commit (package.json + lockfile refresh + full typecheck/test/build pre-flight) as a follow-up PR.

Per system rules I can't merge — yours when ready: #280