feat: add canonical conversation history journal

docs/architecture.md

@@ -36,13 +36,33 @@ serialization while using explicit sessions; they do not swap agent globals.
 | Workspace | Root, bound tool adapters, graph, GitHub client and launch context |
 | AgentSession | Actor, conversation, durable task scope, interaction controller, learning feedback and subagents |
 | Turn | Response state, callbacks, capability token, selected model and request usage |
+| ConversationHistory | Versioned private turn entries and provider/display projections, scoped by actor, interaction workspace and actual session ID |
+| EventsRepository | Transactional journal append, idempotent entry IDs, expected-head checks and private record reads over the existing SQLite `events` table |
 
 Session identity includes actor, interaction scope, session ID and workspace root.
 Personal memory retains its existing global workspace scope. Source snapshots and
 project history use the source scope. Changing projects selects another adapter owner;
 existing sessions retain their original workspace. Context variables carry session,
 event, approval and execution state through provider threads without global mutation.
 
+ConversationHistory records user input, each received provider response, correlated
+typed tool results, interaction references and turn outcomes. Entry payloads are
+versioned defensive JSON snapshots; private rows are not returned by generic event,
+SSE or interface APIs. The runtime records before the next dispatch and stops if a
+journal write fails. Workspace snapshot nodes carry a private journal checkpoint;
+rollback appends a branch-selection entry and preserves the abandoned branch.
+Legacy message lists are imported with provenance without parsing their text. Saved
+provider continuations remain bound to their original provider/model and cannot replay
+tools when that binding no longer validates.
+
+The provider projection restores typed responses and correlated tool replies, and
+fails if a native call/reply group or continuation binding is incomplete. The display
+projection renders each completed turn once. Context compaction remains a derived
+message view and never rewrites the journal. Context usage reports estimated,
+content-free component attribution, a stable-prefix fingerprint, newly introduced
+history, retransmission and duplicate-entry counts; provider-reported input totals
+remain separate from those estimates.
+
 ## Package responsibilities
 
 | Package | Responsibility |

docs/history-and-rollback.md

@@ -1,6 +1,6 @@
 # Conversation history and rollback
 
-History preserves conversation snapshots as a tree. Each node is tied to a user actor, workspace, session, and parent version. The current head represents the active line. Creating a new change after a rollback can leave the old branch available for inspection rather than discarding it.
+Workspace history preserves snapshots as a tree. Each node is tied to a user actor, workspace, session, and parent version, and its private checkpoint points to the canonical conversation journal. The journal retains full versioned provider responses and tool results independently of display snapshots. Rollback appends a branch selection; abandoned conversation entries remain stored and recoverable.
 
 ## Inspect history
 
@@ -10,7 +10,7 @@ Use `/history` in the terminal UI or the session-history routes listed in [tool-
 
 In the TUI, choose a numbered history node to preview the target. Explicitly confirm with `/rollback NUMBER confirm` after reviewing it. The session head is updated only through the rollback operation. A stale head or a mismatched session is rejected instead of overwriting a newer branch. In the web API, the rollback endpoint is scoped to the requested session and node; authenticate and inspect its preview/result before continuing work.
 
-Rollback restores the recorded files in scope and rewinds the selected conversation history. It does not reverse external effects such as messages, network requests, deployments, provider charges, or database changes outside the captured workspace. It also does not imply that shared memory claims, agent credentials, or another session's state have been erased. Check those stores separately.
+Rollback restores the recorded files in scope and selects the conversation branch captured by that node. It does not reverse external effects such as messages, network requests, deployments, provider charges, or database changes outside the captured workspace. It also does not imply that shared memory claims, agent credentials, or another session's state have been erased. Check those stores separately.
 
 ## Recovery points and safety
 

docs/index.md

@@ -43,6 +43,7 @@ This index covers the current product guides, developer references, and dated en
 - [V3 plan index](superpowers/plans/index.md) links the issue-specific implementation plans and identifies their coverage.
 - [V3 execution receipt implementation plan](superpowers/plans/2026-10-14-v3-issue-236.md) records receipt identity, explicit task binding, structured effect verification, compatibility, and validation for issue #236.
 - [V3 runtime events implementation plan](superpowers/plans/2026-10-14-v3-issue-255.md) records the canonical event contract, correlation, interface adapters, and validation for issue #255.
+- [V3 canonical conversation history plan](superpowers/plans/2026-10-15-v3-issue-247.md) records the private journal, runtime integration, history checkpoints, context accounting, and validation for issue #247.
 - Machine-readable audit receipts and benchmark inputs remain beside their corresponding reports under `docs/` and `docs/benchmarks/`.
 
 The repository's [English overview](../README.md) links here. Technical guides are maintained in English; README translations provide localized entry points.

docs/providers.md

@@ -110,6 +110,15 @@ fixture does not establish live gateway acceptance.
 Offline fixtures and installed SDK types validate the contract; they do not establish
 live provider interoperability.
 
+Conversation history is owned by the runtime. It records full structured responses,
+correlated tool results and provider-bound continuation state in private journal
+entries; public runtime events remain redacted projections. Native requests restore
+typed call/reply groups only when every reply and the saved provider/model binding
+validate. After restart, a mismatched continuation is reported and pauses native
+projection rather than silently rebinding or executing a tool again. See
+[architecture](architecture.md) for journal scope, rollback branching and context
+accounting behavior.
+
 ## Optional dependencies
 
 `pip install -e '.[web]'` installs FastAPI and Uvicorn. Provider extras are `.[claude]`, `.[gemini]`, `.[perplexity]`, `.[bedrock]`, and `.[vertex]`; `.[cloud]` groups the cloud integrations. `.[browser]` installs Playwright; browser execution also needs a browser installation. `.[all]` installs the supported optional Python integrations. The official installer has its own pinned set of dependencies; see [installation](installation.md).

docs/superpowers/plans/2026-10-15-v3-issue-247.md

@@ -0,0 +1,85 @@
+# V3 Issue #247: Canonical conversation history
+
+**Issue:** [#247 — Canonical conversation history](https://github.com/EvanProgramming/OpenKyrozen/issues/247)
+**Requirements:** R101–R105, R107, R113, R114, R191
+**Branch:** `Evan/v3-247-conversation-history`, based on `main` at `d71d2bd42b68485feb4571d3aad490d7d8327aa3`
+**Delivery:** one GPG-signed PR; leave the PR unmerged and issue open.
+
+## Scope and ownership
+
+The runtime owns turn recording and projections. Reuse the SQLite `events` table through private repository methods, with a `ConversationHistory` service for immutable scoped records, projections, forks, and import reconciliation. Keep workspace snapshots in `HistoryManager`; link snapshot nodes to journal cursors transactionally rather than adding another history store. Provider continuation remains private and bound to the adapter/model that created it. Interfaces consume display projections, and generic event/SSE APIs never expose journal payloads. AgentEngine replacement, structured compaction redesign, and unrelated V3 issues are out of scope.
+
+The implementation path currently spans `openkyrozen/persistence/events.py` and `store.py`, `openkyrozen/agent/runtime.py` and `loop.py`, `action_rounds.py`, `initial_response.py`, `response_recovery.py`, `prompts.py`, context accounting, `openkyrozen/workspace/history.py`, and the CLI/TUI/Web chat adapters. Existing typed contracts live in `openkyrozen/providers/models.py`; public runtime events live in `openkyrozen/agent/events.py` and remain redacted projections.
+
+## Indexed implementation plan
+
+### Task 1 — Private journal repository and immutable entry model
+
+- [x] Add regressions for append idempotency, conflicting duplicate IDs, stale expected heads, deep defensive snapshots, unsupported versions, scope isolation, and generic event/API privacy.
+- [x] Extend the existing event repository with transaction-scoped conversation append/read/head methods. Use unique entry IDs and expected-head checks; do not expose journal rows through generic event listing.
+- [x] Add versioned immutable entries and `ConversationHistory` with user/workspace/session scope, append, provider/display projections, fork/branch, and explicit legacy import operations.
+- [x] Add lossless codecs for `ModelResponse`, `ToolReply`, and `ToolResult`; validate continuation provider/model binding before native projection.
+
+### Task 2 — Runtime-owned recording and restart behavior
+
+- [x] Record user input, actual model responses, correlated tool results, interaction/plan references, and turn outcomes exactly once; fail closed before any subsequent dispatch if persistence fails.
+- [x] Reconcile legacy `AgentRuntime.chat()` message lists through an explicit import adapter without deleting or rewriting the prior branch.
+- [x] Restore scoped history on session initialization, including the actual CLI/default session ID. Never infer historic protocol actions by parsing prose and never execute restored calls.
+- [x] Add restart/branch tests, including a saved continuation with a changed adapter/model that pauses native projection explicitly without rebinding or replay.
+
+### Task 3 — Workspace history linkage and conversation projection
+
+- [x] Link workspace snapshot nodes to the journal cursor in the same transaction as history-node creation; rollback appends branch selection while preserving abandoned journal records and existing filesystem recovery behavior.
+- [x] Replace accumulated action-round summaries with one evolving projection. Record each provider response and result once; repairs append only their correction. Keep routing, learning, compaction, and delegation requests auxiliary.
+- [x] Retain legacy list shapes and compaction as derived views; native projections preserve complete call/reply groups or fail safely.
+
+### Task 4 — Context assembly, integrations, and evidence
+
+- [x] Route CLI/TUI/Web user/final recording through runtime projections; remove duplicate interface writes while preserving display and wire contracts.
+- [x] Build deterministic stable/dynamic/conversation prompt sections, remove automatic graph-context injection, and preserve registry schemas and the existing one-inventory-per-request legacy path.
+- [x] Extend `context_usage()` with content-free attribution, prefix fingerprint, new/retransmitted history and duplicate-entry counts while preserving existing fields and separating estimates from provider totals.
+- [x] Update architecture/provider/history docs and tests. Run Python 3.12/3.13 focused and full validation, browser tests with installed Chromium, Go TUI and offline acceptance; record all skips.
+- [ ] Obtain independent review, fix material findings, verify signed commit locally and on GitHub, attach PR, and wait for final-head CI/reviews.
+
+## Validation record
+
+### Post-review fixes on PR #283
+
+- [x] Reproduce and fix seven new Codex findings from review of `1112102`: typed history request projection, occurrence-based duplicate metrics, rollback conflict translation, journal-only session discovery, textless failure projection, empty canonical Web branch authority, and in-loop tool inventory refresh.
+- [x] Reproduce and fix three additional Codex findings: typed-message context preflight, failure-path cache refresh, and preventing a truncated display cache from replacing canonical history.
+- [x] Fix the matching CodeRabbit findings and isolate the Web journal test from shared database/session state. Preserve the explicit restart policy: mismatched provider/model continuation fails closed instead of being converted to text or rebound.
+- [x] Re-run focused regressions and both supported Python full suites; repository checks passed. Final-head CI and review-thread resolution remain pending publication.
+- [x] Reproduce and fix four further final-head findings: safely compact legacy dictionary prefixes ahead of native history; pin final provider continuations even when they have no tool calls; include model-free turn outcomes in provider projection without duplicating model responses; and keep the canonical journal authoritative over older Web snapshots.
+- Follow-up signature check: GitHub reports the prior head commit `d20fbf7` as `bad_email`; the account's published GPG key marks `piggyevan123@gmail.com` verified and the noreply address unverified. A corrected follow-up uses the verified email; the existing commit history is not rewritten.
+
+PASS — Python 3.12 and 3.13 focused conversation-history, rollback, interaction, Web, streaming, and native-provider suites (92 tests per focused run; one unrelated browser skip in the initial focused runs).
+
+PASS — Full Python 3.12 and 3.13 suites: `KYROZEN_BROWSER_TESTS=1 make test PYTHON=.venv/bin/python` and `.venv313/bin/python` (833 tests each, including browser session/auth tests).
+
+PASS — Python 3.13 `make check`, `make lint`, `make docs-check`, and `make tui-test`; `git diff --check`.
+
+PASS — Latest focused compaction, conversation-history, native-provider, provider-contract, and Web suites: 106 tests on Python 3.13.
+
+PASS — Latest full Python 3.12 and 3.13 suites: 837 tests each with `KYROZEN_BROWSER_TESTS=1`; browser session/auth coverage ran.
+
+PASS — Latest `make check`, `make lint`, `make docs-check`, `make tui-test`, and `git diff --check`. `make check` and `make docs-check` require the project virtual environment on `PATH`; the system Python lacked the installed `requests` dependency.
+
+PASS — Four final-head review findings reproduced and fixed. Their review threads still need replies and resolution after the signed commit is published.
+
+PASS — Seven Codex findings reproduced and fixed: rollback session refresh, nested branch projection, legacy snapshot backfill, authoritative Web journal projection, early acceptance finalization, atomic rollback notifications, and per-dispatch context metrics (including typed native messages). Added regressions pass.
+
+PASS — Post-review regressions: canonical provider projection and call/reply correlation, repeated journal identity accounting, stale rollback error translation, journal-only session discovery without payload exposure, textless error projection, empty canonical Web branch, and tool inventory replacement/fingerprint invalidation.
+
+PASS — Final Python 3.12 and 3.13 full suites: 833 tests each, including browser auth/session tests with `KYROZEN_BROWSER_TESTS=1`. An earlier Python 3.12 run hit a transient 5-second headless-startup timeout; the isolated test and subsequent complete run passed.
+
+PASS — Context-preflight, failed-turn cache, truncation, saved-model binding, and Web test-isolation regressions pass. Mismatched provider/model continuations are explicitly rejected, preserving the no-rebind restart policy.
+
+PASS — Python 3.13 `make check`, `make lint`, `make docs-check`, and `make tui-test`; `git diff --check`.
+
+PASS — CodeRabbit reviewed head `2f0c746` and posted four findings; three were fixed. Its automatic recovery suggestion was declined because converting/rebinding mismatched continuation state would violate the selected fail-closed restart policy. Codex posted three further findings; all are fixed. Threads remain open until the fixes are published.
+
+PASS — Two additional Codex findings on `469ca5a` were reproduced and fixed: explicit legacy replacement now commits its branch marker and replacement entries in one head-checked transaction, and context history metrics remap only retained message identities after preflight or overflow compaction. Atomic-failure and compacted-history regressions pass.
+
+## Compatibility and risks
+
+Legacy callers keep their message-list shape through an explicit import adapter. Private journal rows contain full conversation and continuation data and must remain unavailable to generic event APIs, logs, and interface projections. If a saved native continuation cannot be validated against its live adapter/model, the request pauses for explicit recovery; tools are never automatically replayed.

docs/superpowers/plans/2026-10-16-v3-issue-242.md

@@ -45,4 +45,3 @@ Check storage concurrency under `BEGIN IMMEDIATE`, in-memory rollback on all exc
 ## Validation record
 
 Implementation is complete on `Evan/v3-242-atomic-plan-edits`. Python 3.12 and 3.13 each passed all 815 tests with browser tests enabled. `make check`, `make lint`, `make docs-check`, `make tui-test`, `make tui-acceptance`, `make agent-acceptance`, and `make subagent-acceptance` passed. Focused plan and migration suites passed (46 tests). Independent review found and verified fixes for typed operation schemas, atomic scheduling claims, and rejection of mixed legacy/canonical arguments. No paid provider calls or new dependencies were used. The repository and issue were refreshed before creating this plan; `main` was `d71d2bd42b68485feb4571d3aad490d7d8327aa3`, issue #242 remains open, and PR #283 remains open and unmerged.
-

docs/superpowers/plans/index.md

@@ -14,6 +14,7 @@
 - [V3 #245 — Versioned, user-approved Strategic Plans](2026-10-16-v3-issue-245.md)
 - [V3 #236 — Execution receipts and task association](2026-10-14-v3-issue-236.md)
 - [V3 #255 — Shared typed runtime events](2026-10-14-v3-issue-255.md)
+- [V3 #247 — Canonical conversation history](2026-10-15-v3-issue-247.md)
 
 Add a linked issue-specific plan here before coding any later V3 issue.
 

openkyrozen/agent/__init__.py

@@ -1,5 +1,6 @@
 """OpenKyrozen agent module."""
 
 from .events import RuntimeEvent
+from .conversation import ConversationEntry, ConversationHistory
 
-__all__ = ["RuntimeEvent"]
+__all__ = ["RuntimeEvent", "ConversationEntry", "ConversationHistory"]