Skip to content

fix(responses): keep persona-scoped sessions stable across instruction drift - #1104

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-21_instructions-drift-keying
Sep 22, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-21_instructions-drift-keying

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Sep 21, 2026 •

Copy link
Copy Markdown
Owner

What / why

opencode's system-context reconcile rewrites the Responses instructions field whenever AGENTS.md changes mid-session. The compression session key mixed instructions into subagentNamespace's fingerprint, so each edit forked an orphan |sub:<fp> session and reset all compression state (#1102). This is the independent design for a bug that exists on master today; it is NOT a salvage of PR #1092's anchor-dependent hunk (that hunk only skips the fingerprint under stableSystemAnchor, which absorbs drift as notes — extracting it alone would merge genuinely different personas that share one conversation id, exactly what the fingerprint exists to prevent).

Skip the instructions fingerprint only when the winning conversation signal is a verified persona-scoped identifier (one id minted per persona, so an id can never be reused across personas):

  • opencode native: x-session-affinity with a ses_… value, or x-opencode-session. opencode stamps its session id on every model request and mints a fresh child session id for every task-tool subagent (sessions.create({ parentID })), so a fixed id carrying different instructions mid-conversation means "same persona, updated system context", not a new persona.
  • plugin declaration: x-bili-plugin-conversation + x-bili-plugin-instructions-mutable: 1. A cooperative plugin declares its host's ids are persona-scoped. Only the opencode plugins stamp it today; unverified hosts (dsh, hermes, …) stay on the fingerprinted path.

Everything else deliberately keeps the fingerprint: Codex body/header/metadata session ids (#150), x-claude-code-session-id (Claude subagents SHARE the main agent's session id, #970), grok/mcode/generic x-session-id, prompt-cache-key. The #150 persona-separation guarantee is untouched.

Changes

  • src/session-id.ts: extract conversationHeaderSource() (reports WHICH header won, needed because trust depends on the signal's origin, not just its value) + instructionsFingerprintExempt() with the trust set above and a full rationale comment.
  • src/server.ts: Responses identity branch keys exempt signals verbatim (like the trusted codexTurn branch) instead of through subagentNamespace.
  • src/plugin.ts: new PLUGIN_INSTRUCTIONS_MUTABLE_HEADER constant + manifest entry.
  • src/agent/opencode-native.ts, src/agent/opencode-v2.ts: stamp the declaration header.
  • PLUGIN.md: document the flag (manifest example + request-header list).
  • tests/responses-instructions-drift.test.ts: unit tests for the trust set + two end-to-end regressions (native opencode headers, plugin-declared) asserting no orphan fork + compressed state carried across the drift.

Migration: upgrading re-keys live opencode sessions from <id>|sub:<fp> to the bare conversation id — one final compression-state reset per in-flight conversation (no data loss; clients re-send full history on the next request).

Pre-flight

  • npm run typecheck clean
  • npm test: 2171 tests, 2169 pass, 0 fail, 2 skipped (the ACP_TEST_E2E-gated codex e2e)
  • npm run build clean
  • New test file: 7/7 pass. Negative control confirmed — reverting ONLY src/server.ts makes both e2e tests fail (the orphan fork reproduces), proving the tests actually exercise the fix.
  • tests/e2e/e2e-codex.test.ts E2E_CHECK=1 zero-token preflight passes; the full ACP_TEST_E2E=1 run needs the local sglang upstream at http://127.0.0.1:8199/v1 (not reachable in this environment), so it was not executed here. The change does not touch the codex identity path (codex keeps the fingerprint), so codex e2e behavior is unaffected.

Fixes #1102

@github-actions

github-actions Bot commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-21_instructions-drift-keying (9695a4e)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1104

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1104.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是带 ework-agent-pr 标记的已完成工作 — 我不会重做,现在拉取分支核对代码 + 检查 CI 状态,稍后给出结论。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — I pulled the branch (2026-09-21_instructions-drift-keying, single commit 71fdf76c, 0 commits behind master) and independently re-ran everything. Not redoing the work; verifying only.

Code review

  • src/session-id.ts — clientConversationHeader now delegates to the new conversationHeaderSource(); the refactor preserves behavior exactly (same priority walk, same trim, same x-bili-plugin marker gate for x-bili-plugin-conversation). instructionsFingerprintExempt() matches the documented trust set precisely: x-opencode-session (any value), x-session-affinity with a ses_… value, and x-bili-plugin-conversation + x-bili-plugin-instructions-mutable: 1 (flag must be exactly "1"). Everything else stays fingerprinted — verified the claude-shared-id case (Subagent first token stalls 1-2min: withSessionLock covers full forward + slow flash upstream first byte #970) stays split because x-claude-code-session-id outranks affinity and isn't in the trust set, and generic x-session-id/prompt-cache-key are excluded. The rationale comment records why each signal is in/out, which is what future reviewers will need.
  • src/server.ts — scoped to the Responses identity branch only (src/server.ts:1348-1357): exempt signals key verbatim, mirroring the existing trusted codexTurn branch above it. The codex path is untouched (codexTurn takes precedence before the exempt check fires), so the Codex 集成:guardian 审批请求进入压缩管线,导致明确授权无法被识别 #150 persona-separation guarantee holds. No other wire shape is affected — Anthropic/OpenAI have no top-level instructions field, so plugin/proxy-mode reasoning per AGENTS.md §6 is satisfied: opencode-in-plugin-mode rides the plugin-declaration path, opencode-in-pure-proxy-mode rides the ses_ affinity path.
  • src/plugin.ts — constant + manifest entry (discoverable via /__bili/plugin/manifest), so third-party plugins can learn the flag contract. V1/V2 opencode agents stamp it; unverified hosts (dsh, hermes, …) don't — correct conservative default.
  • PLUGIN.md — flag documented in both the manifest example and the request-header list, zh/en parity fine.
  • Tests — 5 unit tests pinning the trust set + priority order, plus 2 end-to-end regressions through a real proxy (native ses_ headers, and plugin-declared) asserting ONE session in stats, no |sub:<fp> fork, and compressed state carried across the drift (folded fillers off the wire, summary rendered in place).

Verification (all run by me on the head commit)

Check Result
npm run typecheck clean
npm test 2171 tests, 2169 pass, 0 fail, 2 skipped (the ACP_TEST_E2E-gated codex e2e) — matches your claim
npm run build success
Negative control (revert ONLY src/server.ts) both e2e regressions fail (orphan fork reproduces), 5/7 pass — reproduced independently
E2E_CHECK=1 codex e2e preflight pass
GitHub CI on 71fdf76c all 4 green: CI, e2e-fake-codex, PR Build Artifact, CI Windows codex overlay; mergeable_state: clean

The full ACP_TEST_E2E=1 codex run still needs the local sglang upstream (unreachable here) — but it's not required as a gate for this change since the codex identity path is byte-for-byte untouched.

One non-blocking observation: after upgrading, opencode sessions previously keyed under <id>|sub:<fp> will resume under the bare id (one-time compression-state reset). That's inherent to the fix — the old key was the bug — not a defect in this PR.

Per §7.4 this touches identity/session-binding logic, so it stays human-merge. 可以合并。

修了 opencode 会话中 AGENTS.md 变更导致 instructions 漂移、进而 fork 出孤儿 |sub:<fp> 压缩会话并重置全部压缩状态的问题(#1102);方案是仅对已验证的 persona-scoped 会话标识(opencode ses_ 头 / 插件声明头)跳过 instructions 指纹、按原值建键,其余信号(含 Codex #150、Claude 共享 id 子代理 #970)保持指纹不变。代码核对无误,typecheck/全量测试/build/负向对照/CI 全部通过,可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Verdict: MERGE (human review — correctly NOT auto-merge eligible: touches identity/session-binding + plugin-protocol surface).

Independently verified:

  • Negative control at base (9c01dbea11): stripped the unit tests and ran both new e2e tests → both FAIL (AssertionError … 2 !== 1, orphan |sub:<fp> fork reproduces). The tests exercise the fix, not the assertion machinery.
  • Gates at HEAD: typecheck clean · 2169/2171 pass (2 = ACP_TEST_E2E-gated) · build ok · new test file 7/7.
  • Trust-set claims verified against opencode source: affinity/session headers stamped on every model request (session/llm.ts:372-386); task-tool subagents mint fresh child sessions (tool/task.ts:68-72,140); ses_ prefix = [prefix, ulid()].join("_") (core/src/util/identifier.ts).
  • Kernel mechanics confirmed: empty instructions key verbatim (title-gen system: [] non-regression ✓); first non-empty fingerprint becomes a sticky anchor; drift → fork. The fix removes exactly the fork trigger at the single keying call site (src/server.ts:1348-1365), covering both compression modes (e2e fix: keep system prompt byte-stable for prefix cache #1 proxy via x-session-affinity, e2e fix: address all code review findings (condense, routing, session-id, dead code) #2 plugin via the x-bili-plugin-* trio).

Findings (none blocking):

  1. LOW — ses_-prefix / x-opencode-session trust is spoofable by header name (src/session-id.ts:105-106). Same trust class as all header-based identity (a client lying about its conversation id already collides today); conservative direction keeps the fingerprint for everything unverified. Optional hardening: also gate on user-agent: opencode/*.
  2. MINOR — migration behavior undocumented: upgrade re-keys live opencode sessions ses_x|sub:<fp> → ses_x, one final compression-state reset per in-flight conversation (no data loss; client re-sends full history). Please add one sentence to the PR body / release notes.
  3. MINOR — npx prettier --check newly fails on the 2 new files (src/session-id.ts, tests/responses-instructions-drift.test.ts); the other 4 touched files already failed at base (pre-existing — do NOT mass-reformat). prettier --write just those two.
  4. INFO / sequencing — semantic conflict with held feat: stable head-system anchor for prefix-cache preservation (#1085) #1092 (its 04c39e4 rewrites the same ternary at server.ts:1345-1366 under stableSystemAnchor). Whichever lands second must reconcile; this PR's origin-trust design is the better primitive — feat: stable head-system anchor for prefix-cache preservation (#1085) #1092 should rebase onto it.

Negative controls all pass: x-claude-code-session-id outranks affinity (#970 subagent split preserved ✓), codex body session_id stays fingerprinted (#150 ✓), bili never stamps x-session-affinity inbound (exemption cannot self-trigger ✓).

…n drift

opencode's system-context reconcile rewrites the Responses instructions field whenever AGENTS.md changes mid-session. The compression session key mixed instructions into subagentNamespace's fingerprint, so each edit forked an orphan |sub:<fp> session and reset all compression state (#1102).

Skip the instructions fingerprint only when the winning conversation signal is a verified persona-scoped identifier:
- opencode native: x-session-affinity ses_... / x-opencode-session
- plugin declaration: x-bili-plugin-conversation + x-bili-plugin-instructions-mutable: 1 (stamped by the opencode plugins; unverified hosts stay fingerprinted)

All other signals (codex body/header ids, claude shared-id subagents, grok, generic, pck) keep the fingerprint - the #150 persona-separation guarantee is untouched.

Fixes #1102
@ranxianglei
ranxianglei force-pushed the 2026-09-21_instructions-drift-keying branch from 71fdf76 to 9695a4e Compare September 22, 2026 01:31
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Acted on the review. New PR head: 9695a4e — rebased onto current master f0959e3 (the #1103 test-only merge; zero file overlap with this PR).

Done

  • Rebase + full re-verification on the new head (§7.2): typecheck clean · 2172 tests, 2170 pass / 0 fail / 2 skipped (ACP_TEST_E2E-gated) · build ok. Pushed with --force-with-lease after confirming the remote branch was still exactly at 71fdf76c (rebase ⇒ non-FF by construction). GitHub CI on 9695a4e: all 4 green (CI, e2e-fake-codex, PR Build Artifact, CI Windows codex overlay).
  • Finding fix: address all code review findings (condense, routing, session-id, dead code) #2 (migration note) — added to the PR body: "Migration: upgrading re-keys live opencode sessions from <id>|sub:<fp> to the bare conversation id — one final compression-state reset per in-flight conversation (no data loss; clients re-send full history on the next request)."

Not applied as written — needs your call (finding #3, prettier)

I checked what prettier --write would actually do before running it:

  • The repo has no prettier config (no .prettierrc*, no prettier key in package.json), no prettier devDependency, no format script, and no CI format gate.
  • Probed npx prettier --check src/**/*.ts: default settings → 107 files fail. Even with tabWidth:4, printWidth:140 (matching the codebase's 4-space style) → 78 files still fail; width 120 → 86. The codebase was never prettier-formatted — "the other 4 touched files already failed at base" holds trivially because essentially every file fails under any config.
  • Measured churn of --write on just the two named files: src/session-id.ts 23 diff-lines, tests/responses-instructions-drift.test.ts 255 diff-lines on a 229-line file (i.e. nearly every line reflows) under the closest-matching config; 267/588 under defaults. That would leave those two files stylistically inconsistent with the rest of the repo and bury the fix in whitespace — exactly what §7.2's diff-cleanliness rule forbids.

My recommendation: skip prettier for this PR (there is no gate to satisfy). If you want prettier as a project standard, the clean path is committing a .prettierrc that matches the existing style + devDep/script, then a separate dedicated repo-wide format PR — never bundled into a fix. Say the word and I'll run it on just these two files regardless.

Findings #1 / #4 — left untouched

PR is at 9695a4e, all gates green. Ready for human merge whenever.

已按 review 处理:rebase 到最新 master(f0959e3)并在新 head 上全量复验通过(typecheck/2172 测试/build/CI 四项全绿,head 现为 9695a4e),PR 描述补了迁移说明一句;prettier 一项未照办——仓库无任何 prettier 配置且全库文件在默认配置下全部不合规,单独格式化两个新文件会产生淹没真实改动的纯空白 diff(实测 23/255 行),建议本 PR 跳过、如需标准化另开专门格式化 PR,等你拍板;UA 加固(#1)与 #1092 排序(#4)按你的标记保持不动。可以合并。

@ranxianglei
ranxianglei merged commit 5c8831c into master Sep 22, 2026
8 checks passed
ranxianglei added a commit that referenced this pull request Oct 3, 2026
…-sharing hosts

dsh stamps ONE x-bili-plugin-conversation id on every model request of a
session, INCLUDING the auto-review classifyRisk() calls (fixed
REVIEW_POLICY system + a freshly-flattened user blob, fired before every
tool call under the Auto permission tier). Those review requests walked
the full pipeline under the MAIN conversation id: they overwrote the
usage baseline (#1916), evicted remembered snapshots (#1307's guard was
a partial stopgap), and fed orphan-GC — while the review blob is
synthesized fresh every time, so compressing it has zero reuse value.

Key dsh traffic by id + system hash (kernel subagentNamespace anchor
semantics): the FIRST system seen under the id keeps the raw key (the
main turn claims it — dsh composes its main system once per session and
puts the volatile time-context in a USER message, so main turns never
fork mid-conversation), a different system forks onto <id>|sub:<fp>
(the review persona), and an empty system is non-anchoring (verbatim
key, system-less auxiliary calls keep riding the main session).

- src/session-id.ts: dshPersonaFingerprintApplies (evidence-permitlist,
  the #1104/#1107 discipline — do NOT enable wholesale, #1106) +
  openaiSystemTextForPersona.
- src/server.ts: fork applied on the openai and anthropic lanes;
  personaForked sessions record under their suffixed id
  (recordPluginSession) so the single-valued conversations map keeps
  the raw key owned by the main session (#970 discipline).
- AGENTS.md: Key Design Decisions #9 — the rule for future hosts that
  reuse one session id across personas.
- tests: fork/stability/allowlist/anthropic-lane coverage (peekSession
  — getSession is get-or-create and would mint the sessions we assert
  about).

Refs #1916 #1307 #1314
@ranxianglei
ranxianglei deleted the 2026-09-21_instructions-drift-keying branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant