Keep provider context history readable after downgrade

[brennanb2025]

ELI5

A chat can need a fresh agent context while keeping its earlier history. The current storage rules reject that transition for Claude and Codex because older Orca builds would stop reading the whole chat. This prerequisite lets older builds read the latest context and lets an upgraded build recover the earlier provider history. The existing /clear behavior is unchanged in this PR; in-place clear follows separately.

What Changed

Store the latest provider context in the existing handle array, with earlier links in one optional, disjoint record-level archive. New readers reconstruct the truthful full chain; older writers preserve the archive while resuming, changing Claude's resume point, forking, or superseding a context the provider never saved. Records without replacements retain their existing bytes.

The 256-link limit applies to each context, so an older writer can grow its visible segment without invalidating the archived history on upgrade. Validation uses an iterative walk without recursive archive nesting. If an older build adopts an invisible historical context into another chat, that chat's visible claim wins on upgrade, including provider-ID address corrections; an archived claim reserves history against another adoption and cannot override the visible owner.

Why

Keeping one conversation requires separating its provider history from the context it currently resumes. A record-level archive survives old writers that rebuild the handle array, while an archive attached to the replaced link would be lost. Retaining truthful creation links avoids pretending a discarded context was resumed or forked. This also supports failed-restore replacement storage, without enabling a new Claude/Codex fallback policy here.

Differences from the common pattern:

• Intended: provider ancestry remains on the conversation record, with a shallow stored archive and a cap per context. No new migration, retry flag, background work or polling is introduced.
• Intended: an older build sees only the latest segment and can adopt an archived context elsewhere; on upgrade the visible claim takes priority. Native chat has no real users, so no migration is added.
• Temporary: same-conversation clear and orchestration cleanup are separate dependent PRs. This prerequisite changes storage and ownership, without changing the clear command.

Linked Issue

N/A — maintainer follow-up from a native chat audit

Visual Proof

Captured terminal output from the actual historical-module suite on final head fd9234eed1f: shipped v1.4.222 and the prerequisite base each read and save the new Claude/Codex records, with the archive-aware HEAD control also passing. All 28 cases pass. This is a headless rendering of unabridged test stdout, not live provider or app UI evidence.

Testing

• After the final main sync, 234 cases passed across 18 focused/control/historical files, followed by all 50 orchestration caller cases. The dedicated verbose compatibility run passed another 28 cases for the proof above: 312 passing test executions across 19 distinct files, with repeated matrix cases counted explicitly.
• Shipped v1.4.222 and prerequisite base readers/writers: unchanged records, repeated replacements, 256 archived + 256 visible links, old Claude resume-point updates, old unsaved supersession/fork, and old adoption followed by upgrade in both record orders. Latest release is included dynamically.
• Follow-up ownership correction: its new order-independent assertion and 50 existing orchestration caller cases passed under Node (51 total).
• Compatibility review follow-up: actual archive support selects rolling-baseline expectations, and HEAD provides an automatic forward control. The shipped-baseline override passed 28 checks; this archive-aware baseline override passed 36 checks. One first-run checkout extraction timed out, then the populated-cache run passed.
• Node, web and CLI typechecks passed through the machine queue; node typecheck was rerun for the ownership correction and the test-only compatibility follow-up. Both pre-sync and final post-sync pre-push orca-ci-checks passed all 22 static checks. Final-head CI finished: 20 checks passed, 17 were skipped and none failed; all ten test shards passed. Skipped live/platform gates were not counted as passes. Final CI run.
• macOS arm64, Node 26.5.0: full durable transaction measured with UUID-sized identifiers, 3 warmups and 30 bounded operations. At 512 links, renewal/update p95 was 9.15/6.44 ms (119.5 KB); at 4096 links, 61.40/71.23 ms (884.6 KB). Loading 100 ordinary records took 629 ms cold, 193/226 ms warm. All agreed representative byte/latency budgets passed.
• One later 2048-link sample after startup allocations spiked to 391 ms p95; two requested fresh-process confirmations returned 7.74 ms p95 at load average about 40. The coordinator classified the nonmonotonic outlier as shared-machine/garbage-collection noise; the cause was not independently measured, and the outlier remains disclosed.

The reliability class is agent-session.provider-ownership: the oracle is actual old read/write/adoption followed by a new reader retaining ancestry and selecting the existing visible owner. The matching gate is experimental and partial; its relevant inexpensive controls pass. Local/daemon PTY lifecycle and geometry are unaffected. Storage remains execution-host owned with no new RPC or stream opcode. Hardware Linux/Windows, live SSH/WSL/paired clients, and real providers were not run for this storage-only prerequisite.

• Automated tests added/updated
• Live rendered UI/provider QA (no user-visible change in this prerequisite)

Review

Round 1 found a P2 ownership lookup issue, fixed with focused and existing caller tests; round 2 verified it closed. Round 2 found a P2 rolling-baseline test assumption, reproduced against this implementation and fixed with actual extracted-module support detection, latest-head writes, archive-aware adoption refusal and forward controls. Fresh round 3 found no P0–P3 issues and verified both earlier findings closed; it executed 292 passing tests with matrix overlap disclosed. The final main sync was conflict-free; no authored implementation change followed the clean review.

Agent skill upstream boundary

• Not applicable; no upstream skill source copied or translated.

Notes

• Scope limited to provider-context storage and ownership
• Self-reviewed for correctness and measured routine-write cost
• Execution-host, folder workspace, downgrade and cross-platform contracts considered
• Targeted tests, three typechecks and static checks passed

[brennanb2025]

Older Orca builds could set aside a Claude or Codex chat when its saved provider history contained a fresh replacement. This PR keeps the latest context readable to those builds and preserves earlier provenance through their normal writes; it also ensures a visible owner takes priority when a downgraded build adopted an archived context elsewhere. The clear command itself is unchanged; same-conversation clear and orchestration cleanup follow separately.

Three independent review rounds finished with no P0–P3 findings. Round 1 fixed a provider-session address selecting the archived owner instead of the visible owner; round 2 fixed compatibility tests that assumed the moving release baseline could never read archives; round 3 verified both closed and ran 292 passing test executions. The final main sync was conflict-free, followed by 234 focused/control/historical cases, 50 orchestration caller cases, a repeated 28-case compatibility proof, all three queued typechecks and all 22 static checks. The uploaded terminal-output screenshot is in the PR body.

Final-head CI (fd9234eed1f) finished: 20 checks passed, 17 were skipped and none failed. All ten test shards, cross-version compatibility, relay integration, static analysis and both packaging jobs passed; skipped live/platform gates were not counted as passes. There are no red checks to classify as this PR, main or infrastructure. Final CI run.

Actual historical modules, durable record writes, growth beside a full archive, resume-point changes, replacement of an unsaved context and subsequent branching and ownership on re-upgrade were exercised. Live providers, rendered app flows, live SSH/WSL/paired clients and hardware Windows/Linux were not run; this is storage-only test evidence. Representative durable-write/startup budgets passed, but the disclosed 2048-link timing spike remains and its shared-load/garbage-collection cause was not independently measured. No migration, typed-provider restore fallback or clear UI was added.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 542534dd-0a28-498d-9142-118bac418324

📥 Commits

Reviewing files that changed from the base of the PR and between e0a98a4 and fd9234e.

📒 Files selected for processing (19)

• src/main/native-chat/agent-session-wire/structured-provider-session-ownership.ts
• src/main/runtime/agent-session-reservation-admission.ts
• src/main/runtime/orchestration/structured-session-mail-address.test.ts
• src/main/runtime/orchestration/structured-session-mail-address.ts
• src/shared/agent-session-legacy-handoff-lease.ts
• src/shared/agent-session-provider-claims.test.ts
• src/shared/agent-session-provider-claims.ts
• src/shared/agent-session-provider-context-history.test.ts
• src/shared/agent-session-provider-context-history.ts
• src/shared/agent-session-provider-context.test-fixture.ts
• src/shared/agent-session-provider-handle-replacement.ts
• src/shared/agent-session-provider-handle.test.ts
• src/shared/agent-session-provider-handle.ts
• src/shared/agent-session-provider-link-validation.ts
• src/shared/agent-session-record-stored-form.ts
• src/shared/agent-session-record.ts
• tests/e2e/cross-version-wire/agent-session-context-history-downgrade.unit.test.ts
• tests/e2e/cross-version-wire/agent-session-handle-replacement-downgrade.unit.test.ts
• tests/e2e/cross-version-wire/agent-session-historical-store.test-fixture.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds version-1 persistence for replaced provider-context links and updates provider-handle chain validation to apply a 256-link limit to the current context. Provider ownership lookups now use claims that distinguish archived links from visible links. The change also adds unit and cross-version tests for persistence, ownership, adoption, and historical store behavior.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to fd923

No merge-blocking issue is established for provider-context history or ownership. The change is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.46% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 26 functions across 19 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving provider context history for downgrade compatibility.
Description check	✅ Passed	The description is detailed and covers the required explanation, changes, rationale, testing, review status, compatibility considerations, and checklist items. The linked issue section is marked N/A, …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[brennanb2025]

Closing: this isn't needed.

This PR changed how a chat saves its list of agent sessions, so that an older Orca build could still open a chat after the in-place /clear (#26579) recorded "this fresh session replaced that one". Users don't run older builds, though. Only the dev team switches to older builds, and we don't need cleared chats to open there.

Instead, #26579 will be reworked onto main: on /clear the chat starts a fresh session list with just the new agent session. What users see is unchanged (same chat and tab, fresh agent, a "Context cleared" divider). The pre-clear session stays reachable through the agent's own history, much as Claude Code's /resume keeps the old conversation after /clear. No new save format and no compatibility rules are needed.