[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 (ccb1763)

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

[ranxianglei]

分诊(队列清理 #484): KEEP-VALID(文档,trivial)。

不变式本身(raw id / mNNNNN ref 永不复用,内核 #176 的 ref-slot 回收已在内核 #191 回滚)是本适配器真实依赖的契约(decompress 错归属)。master 的 AGENTS/README/CHANGELOG 均无此段(grep 0.0.48|reused|immutab 零命中)。

建议 rebase 时把版本特定措辞("不得 pin 0.0.48/0.0.49")改写为不变式 + pin 纪律规则(当前 pin 已是 0.0.81)。AGENTS.md 已被 d5e1bb3 重组,按现布局落位即可。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Rebased + rewritten per triage — ready to merge.

What changed on the branch (now ccb1763, single commit on top of master 72d8771 / v0.1.74):

• Rebased onto current master (was based on v0.1.55-era cbb753a).

• Rewrote the section as invariant + pin-discipline rule, dropping all version-specific bans ("must not pin 0.0.48/0.0.49", "bump from 0.0.47 only after…"). The new text in AGENTS.md §2, placed right after the exact-pin rule (item 6) — same slot as the original, valid under the d5e1bb3 layout:

  Kernel Contract: Message Ids Are Never Reused

  The kernel (acp-kernel) guarantees, and this adapter RELIES on: 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 (edited/truncated/folded). Summaries cite tags across turns and the model can cite any number it has ever seen, so a re-issued number silently misattributes on decompress. Capacity pressure is the kernel's problem to solve by widening the ref space, never by recycling numbers.

  The kernel's ref-slot reclamation (acp-kernel#176, shipped in 0.0.48–0.0.49) violated this contract and was reverted (acp-kernel#191). Pin discipline: before bumping acp-kernel, verify the target release preserves id/ref immutability — never pin a version that recycles ref numbers or raw ids.

Verified

1. acp-kernel#191 is merged (checked via API) — so "was reverted" is now a fact, not "pending"; and the historical mention of 0.0.48–0.0.49 stays as fact, not instruction.
2. Current pin is 0.0.81 (package.json, master) — well past the reverted range, honors the contract. The earlier "downgrade to 0.0.47 now" recommendation is moot.
3. Diff = AGENTS.md only, +15/−0; PR reports mergeable: true.
4. CI on new head: all 4 jobs green (ubuntu/windows × node 22/24). Docs-only change, no code touched.

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

中文摘要:按分诊建议把文档从版本特定禁令("不得 pin 0.0.48/0.0.49")改写为不变式 + pin 纪律规则,并 rebase 到当前 master(pin 已是 0.0.81,#191 已合并),diff 仅 AGENTS.md +15 行、CI 全绿,可以合并。