@openchambery/web 2.0.0-beta.1 → 2.0.0-beta.4

package/server/lib/assistants/DOCUMENTATION.md

@@ -111,7 +111,8 @@ and keep their existing error result handling.
 - Successful `assign_session` and `watch_session` return `terminate: true` to stop the mutation loop. The harness then requests a tools-disabled model summary. Prerequisite tools (`list_projects` / `list_sessions`) may still run before assign/watch/stop in the same turn; multi-operation user intents remain ordered **across turns** after a successful assign/watch.
 - Same contact-turn assign gate (tools instance lifetime only, not cross-turn): identical args after success replay the cached success result (no second worker); different args after success, or parallel mismatched args, fail closed with a validation error. The idempotent key includes worker model selection and current-turn attachment scope. Failure clears the gate so a corrected retry may run. Parallel identical args share one in-flight promise.
 - After a successful assign or watch, the service persists the existing session card into the contact transcript (user bubbles first, then the card) and watches that worker session in `assistant_contact_watch` (watch baselines the live status). The user-facing outcome is the session card plus any short **spoken** preamble; English tool-result confirms (`Opened a coding session.`, `Watching that coding session.`, `Created assistant…`, `Sent to…`) for card/side-effect tools are **not** written into the transcript.
-- Existing OpenCode SSE on the same `globalEventHub` as notifications (`session.idle`, `session.error`, `session.status`, `question.asked`, `permission.asked`) updates **the same card** (`busy` → `complete` / `error` / `question` / `cancelled`). **No canned settle transcript bubbles** (`oc.settle.complete` / `error` / `question` are not written). On **complete, error, or cancelled (user interrupt)** when the watch status actually changed, the service schedules an async contact-lane **continuation** (`inContactTurnLane` + `runContactTurn`) per related assistant: no admitted user row (internal `userText` only), active contact turn (green dot / 3-dot), stable resume id `resume_${assistantID}_${sessionID}_${status}_${updatedAt}`, bounded last worker assistant text (~2000 chars; fetch failure still resumes with status only). Cancelled continuations include `reason: user_interrupted` so the contact can acknowledge the user's abort. The contact Agent can perform read-only lookups and summarize in the user's language, but cannot reassign or mutate a session during this notification — the user sees that Agent summary, not 「会话已完成/会话失败」. `question` updates the card only (worker waiting on the user). `stop_session` cancellation does not schedule this continuation. Session-goal settle (`emitGoalNotification`) uses the same reporter — not a second scheduler. Idle after `session.error` must not rewrite 失败 as 完成 (`changed=false` → no second resume). Same complete status re-reported is idempotent.
+- Existing OpenCode SSE on the same `globalEventHub` as notifications (`session.idle`, `session.error`, `session.status`, `session.execution.*`, `question.asked`, `permission.asked`) updates **the same card** (`busy` → `complete` / `error` / `question` / `cancelled`). **No canned settle transcript bubbles** (`oc.settle.complete` / `error` / `question` are not written). On **complete, error, or cancelled (user interrupt)** when the watch status actually changed, the service schedules an async contact-lane **continuation** (`inContactTurnLane` + `runContactTurn`) per related assistant: no admitted user row (internal `userText` only), active contact turn (green dot / 3-dot), stable resume id `resume_${assistantID}_${sessionID}_${status}_${updatedAt}`, bounded last worker assistant text (~2000 chars; fetch failure still resumes with status only). Cancelled continuations include `reason: user_interrupted` so the contact can acknowledge the user's abort. The contact Agent can perform read-only lookups and summarize in the user's language, but cannot reassign or mutate a session during this notification — the user sees that Agent summary, not 「会话已完成/会话失败」. `question` updates the card only (worker waiting on the user). `stop_session` cancellation does not schedule this continuation. Session-goal settle (`emitGoalNotification`) uses the same reporter — not a second scheduler. Idle after `session.error` must not rewrite 失败 as 完成 (`changed=false` → no second resume). Same complete status re-reported is idempotent.
+- **Shutdown interrupt (ticket 07):** official `session.execution.interrupted` reason is `user | shutdown | superseded | inactivity`. **`reason: shutdown` does not settle** the watch and does **not** schedule contact resume — upstream keeps the execution claim for restart recovery. The card stays `busy` until an authoritative terminal (`session.execution.succeeded` / `failed` / user interrupt / reconcile). `reason: user` settles `cancelled` + resume. Other non-shutdown interrupts settle `error` unless `MessageAbortedError`. No parallel recovery store — the existing watch row remains the owner.
 - Restart or a missed `session.idle` cannot leave the watch stuck: boot and the existing 60s reconcile timer `listInFlightWatches` and poll OpenCode `session.get` / `message.list`. Idle, `time.completed`, or a missing session settles the same card (`busy` → 完成) and triggers the same contact continuation (no `oc.settle.complete` bubble). `session.error` or last-assistant `info.error` settles 失败 + resume once; last-assistant `MessageAbortedError` settles `cancelled` + the interrupt notify once. Transport / non-404 get errors leave the watch in flight (failure is not empty success). One failed watch does not block unrelated watches. Reconcile reuses `reportAssignedSession`, so an error watch is never rewritten as complete. Tombstoned assistants skip resume.
 - Worker sessions stamp `metadata.openchamber.assigned` (`from: 'contact'`, `assistantID`, `name`). They must **not** use `openchamber.assistant.assistantID` — that marker hides archived Assistant bindings from Chat.
 - `AssistantDTO.assignedSessionIDs` lists in-flight (`busy`/`question`) watches for assigned worker sessions. Session-card busy stays on the card; it does **not** drive the list green dot.
@@ -243,13 +244,17 @@ and keep their existing error result handling.
 
 ## History coverage
 
-Snapshots expose the latest 50 `historySessionIDs` in chronological order and `historySessionCount` for the full count. The messages pagination endpoint owns complete history, including the current binding. A successful direct, shared, or queued OpenCode admission writes its user message and provisional parts to the Assistant SQLite mirror before the HTTP operation settles; this covered admission row survives binding replacement, restart, and an unavailable OpenCode history endpoint. Matching live parts replace provisional parts by message ID. Other event mirrors retain raw JSON as uncovered (`covered=0`) provisional fallback rows: they remain visible in archived history until an explicit shrink signal. Authoritative OpenCode backfill upserts covered rows and reconciles authoritative parts, rejects entries whose embedded session ID belongs to another session, and never deletes provisional mirrors merely because a successful page omitted them. Pagination `complete` only records that the OpenCode cursor was exhausted; it does not authorize deleting uncovered event mirrors. The only shrink whitelist is explicit `message.removed`, an authoritative `message.list` 404 (`session-missing`), or assistant deletion. Late archived `message.updated` / `message.part.updated` and session lifecycle events (`session.idle`, `session.error`, `session.status` busy/retry/idle) call `invalidateBackfill` to reopen that session's cursor/complete without clearing covered flags. `history-state.js` owns the pure backfill reducer (`invalidate` → preserve; `page` → complete iff next cursor empty, always preserve; `session-missing` → discard provisional). Backfill persists the OpenCode `x-next-cursor` header verbatim and derives completion from its presence. A demand request commits up to three upstream pages and returns committed archived mirror rows (covered and provisional) with a stable scan-boundary cursor when more work remains. Startup begins one non-blocking current-binding backfill page. Archived rows preserve their stored directory; a legacy null directory triggers an authoritative session lookup of `data.directory` and `data.project.worktree`, with containment validation before persistence. Unresolved legacy directories remain `null` in persisted and historical response data. Ordinary mirror upserts preserve covered rows and never blanket-invalidate a session; explicit authoritative upserts elevate coverage; session-wide `invalidateCoverage` preserves every already-covered user row, including admitted rows whose local marker was replaced by live OpenCode info, while resetting other coverage on archive/re-archive; message-scoped coverage invalidation runs only after structural part deletes that require re-backfill. Removing an assistant tombstones the row and deletes its session history, message/part mirrors, and backfill state in one transaction. Schema v11 adds the mirror coverage marker.
+Snapshots expose the latest 50 `historySessionIDs` in chronological order and `historySessionCount` for the full count. The messages pagination endpoint owns complete OpenCode history across archived and current bindings.
 
-`assistants` owns Assistant configuration, session bindings, and a durable assistant-owned OpenCode message/part mirror in `assistants.sqlite`. Routes register before the generic OpenCode proxy.
+**V2 authority:** OpenCode session projections (`message.list` / `GET /session/:id/message`) are the sole message-body source. Assistant SQLite does **not** persist message/part bodies on send, share, live events, or demand reads. Legacy `assistant_message_mirror` / `assistant_message_part_mirror` / `assistant_message_backfill` tables may still exist for leftover rows and assistant-delete cleanup, but runtime never writes or serves them for history. Live SSE events may still drive assigned-session watch settlement; they do not cache transcript bodies.
 
-`GET /api/openchamber/assistants/capability` returns `supported`, the persisted `enabled` switch, domain revision, relay-derived stable `serverInstanceID`, and explicit v2 gaps `sharingAvailable`, `archiveMetadataAvailable`, and `sessionMetadataAvailable` (all `false`). Fresh databases default `enabled` to off; Settings flips the switch, and product navigation entries stay hidden until it is on. `PUT /api/openchamber/assistants/settings` changes the global switch with `expectedRevision`. CRUD and snapshots live under `/api/openchamber/assistants`. Session routes are `POST /:id/session/ensure`, `/:id/session/new`, and `/:id/session/compact`; composer sends use `POST /:id/messages` (contact harness, not `session.prompt`); contact history is `GET /:id/contact/messages` (full transcript, including rows before a clear-memory boundary); contact reset wipe is `POST /:id/contact/reset`; shared contact read watermark is `POST /:id/contact/read`; session cards are `POST /:id/contact/cards`; read-only inter-assistant DMs are `POST /:fromID/contact/dm`; assistant-owned scheduled tasks are `GET /:id/scheduled-tasks`. Shares still use `POST /:id/share` and `GET /share-operations/:operationID`.
+`GET /api/openchamber/assistants/:assistantID/messages?before=&limit=` returns `{ entries: [{ sessionID, directory, info, parts }], nextCursor, complete, partial, failed? }`. The service lists bindings from `assistant_session_history` plus the live current session and walks them newest-first. Each binding reads the official v2 projection (`message.list` / `GET /api/session/:id/message`): first page uses `order=desc` only; continuation uses the opaque `cursor` only (never combine `order` + `cursor`). Rows keep the authoritative projection sequence (not `time.created` re-sort). The Host `before` cursor stores binding ordinal + upstream opaque cursor + page-local `skip` (positions only — no message bodies). A demand request uses at most three upstream pages with a stable `limit` page size. Public `entries` are ascending. `complete` is true only when every binding is exhausted and nothing failed. A mid-scan binding failure sets `partial: true`, `complete: false`, `failed: [{ sessionID, sessionOrdinal, status }]`, keeps already-fetched newer siblings, and leaves `nextCursor` on that binding so a retry can fill the gap without permanently skipping it. Transient 5xx/network failures retry up to three times; persistent total failure (no successful binding and no entries) throws `upstream_error`. Authoritative 404 for a binding skips it without blocking others. Leftover mirror rows are ignored. When `fetchImpl` is injected, history uses the same official path shape (`/api/session/:id/message`, `limit`, first-page `order=desc` or continuation `cursor`, optional `directory`).
 
-`AssistantDTO.mode` remains `continuous` or `stateless` (default `continuous`) for share/queue OpenCode session binding. It is **not** a user-facing memory setting: Settings no longer exposes the continuous/stateless toggle, and new assistants stay continuous contact history with server-side LLM trim. `historySessionIDs` lists prior OpenCode session bindings in chronological order (oldest first, capped). Continuous Assistants keep one long-lived current session across composer turns. Stateless Assistants create and bind a fresh OpenCode session for every composer send, share admission, and queued delivery so the model executes without prior transcript context; prior sessions remain available in OpenCode history. The Assistant surface follows the current binding, so each stateless turn rematerializes onto that fresh session. `AssistantDTO.workspacePath` retains the configuration value: `null` selects the managed workspace and a string selects a registered project path. `AssistantDTO.managedWorkspacePath` always carries the canonical managed target at `dataDir/assistant-workspaces/<assistantID>`, including for project-configured Assistants. `AssistantDTO.effectiveWorkspacePath` carries the resolved OpenCode session directory. `AssistantDTO.variant` is nullable and reaches OpenCode `session.prompt` with provider, model, agent, and system prompt. `SessionBinding` is `{ sessionID, directory, sessionGeneration }` with the effective directory. `ensure` and `new` return `SessionBinding`; `compact` returns `{ binding, summarized: true }`; messages return `{ binding, messageID, admitted: true }`; shares return top-level `{ operationID, assistantID, sessionID, messageID, state, phase, attempt, leaseExpiresAt, errorCode }`. `contracts.js` exports serialization fixtures for these DTOs. Binding replacement uses generation CAS, so concurrent creation retains one winner while orphan sessions stay available in OpenCode history. Workspace changes create and bind a session in the new directory. Session metadata carries `openchamber.assistant.assistantID` and `name` as the authoritative ownership marker. New OpenCode sessions use the fixed human title `[Assistant] ${name}` and are archived via `session.update({ time: { archived } })` immediately after create and before binding is returned, so ordinary active lists never flash them; metadata isolation still applies if archive fails after create. The session index and global session lists hide system sessions by this metadata (never by title prefix). Assistant history and direct source open remain the entry points.
+`assistants` owns Assistant configuration, session bindings, and contact/share metadata in `assistants.sqlite`. OpenCode message bodies are read from upstream projections, not mirrored. Routes register before the generic OpenCode proxy.
+
+`GET /api/openchamber/assistants/capability` returns `supported`, the persisted `enabled` switch, domain revision, relay-derived stable `serverInstanceID`, and explicit v2 gaps `sharingAvailable` (always `false`), `archiveMetadataAvailable` (true only when Host archive is injected), and `sessionMetadataAvailable` (always `false`). Fresh databases default `enabled` to off; Settings flips the switch, and product navigation entries stay hidden until it is on. `PUT /api/openchamber/assistants/settings` changes the global switch with `expectedRevision`. CRUD and snapshots live under `/api/openchamber/assistants`. Session routes are `POST /:id/session/ensure`, `/:id/session/new`, and `/:id/session/compact`; composer sends use `POST /:id/messages` (contact harness, not `session.prompt`); contact history is `GET /:id/contact/messages` (full transcript, including rows before a clear-memory boundary); contact reset wipe is `POST /:id/contact/reset`; shared contact read watermark is `POST /:id/contact/read`; session cards are `POST /:id/contact/cards`; read-only inter-assistant DMs are `POST /:fromID/contact/dm`; assistant-owned scheduled tasks are `GET /:id/scheduled-tasks`. Shares still use `POST /:id/share` and `GET /share-operations/:operationID`.
+
+`AssistantDTO.mode` remains `continuous` or `stateless` (default `continuous`) for share/queue OpenCode session binding. It is **not** a user-facing memory setting: Settings no longer exposes the continuous/stateless toggle, and new assistants stay continuous contact history with server-side LLM trim. `historySessionIDs` lists prior OpenCode session bindings in chronological order (oldest first, capped). Continuous Assistants keep one long-lived current session across composer turns. Stateless Assistants create and bind a fresh OpenCode session for every composer send, share admission, and queued delivery so the model executes without prior transcript context; prior sessions remain available in OpenCode history. The Assistant surface follows the current binding, so each stateless turn rematerializes onto that fresh session. `AssistantDTO.workspacePath` retains the configuration value: `null` selects the managed workspace and a string selects a registered project path. `AssistantDTO.managedWorkspacePath` always carries the canonical managed target at `dataDir/assistant-workspaces/<assistantID>`, including for project-configured Assistants. `AssistantDTO.effectiveWorkspacePath` carries the resolved OpenCode session directory. `AssistantDTO.variant` is nullable and reaches OpenCode `session.prompt` with provider, model, agent, and system prompt. `SessionBinding` is `{ sessionID, directory, sessionGeneration }` with the effective directory. `ensure` and `new` return `SessionBinding`; `compact` returns `{ binding, summarized: true }`; messages return `{ binding, messageID, admitted: true }`; shares return top-level `{ operationID, assistantID, sessionID, messageID, state, phase, attempt, leaseExpiresAt, errorCode }`. `contracts.js` exports serialization fixtures for these DTOs. Binding replacement uses generation CAS, so concurrent creation retains one winner while orphan sessions stay available in OpenCode history. Workspace changes create and bind a session in the new directory. Session metadata carries `openchamber.assistant.assistantID` and `name` as the authoritative ownership marker. New OpenCode sessions use the fixed human title `[Assistant] ${name}` and persist that isolation through the Host session-metadata store immediately after create (`persistSessionMetadata` + `onSystemSessionPersisted`) so the sidebar index drops them without waiting for list sync. They are archived via Host archive immediately after create and before binding is returned, so ordinary active lists never flash them; metadata isolation still applies if archive fails after create. The session index and global session lists hide system sessions by this metadata (never by title prefix). Assistant history and direct source open remain the entry points.
 
 **Contact send admission + SSE (this PR)**
 
@@ -264,11 +269,11 @@ Snapshots expose the latest 50 `historySessionIDs` in chronological order and `h
 
 Composer messages carry a client message ID. The service accepts the existing OpenCode delivery parts (`{ type: 'text' }` and `{ type: 'file', mime, url, filename? }` data URLs — not a second attachment store), extracts text (`[attachment]` when the send is file-only), admits the user at 202, then runs the contact harness asynchronously (`runContactTurn` / pi-agent-core, thinking off, pi `read` / `write` / `edit` / `bash` in the assistant workspace, OpenChamber tools `new_conversation` / `clear_chat_history` / `list_projects` / `list_sessions` / `get_assistant_settings` / `update_default_prompt` / `create_assistant` / `schedule_task` / `message_assistant` / `assign_session`, merged `.agents`/`.claude` skills, plus the registered-projects catalog each turn) through the OpenChamber completions gateway (public HTTP non-streaming; in-process `onTextDelta` for contact SSE). Assistant bubbles and tool cards persist when they publish (bubble `done:true` / card insert) and turn end upserts any remainder. File parts survive `GET /:id/contact/messages`. The harness forwards those file parts to the completions gateway. Image data URLs reach `session.prompt` only when the connected catalog marks the model as vision-capable; otherwise generate keeps the `[image: …]` description and text-file bytes so a non-vision model cannot stall the contact turn. Gateway 502 responses include `{ error, message }` so the composer can show the OpenCode error string. OpenCode `session.prompt` is not the contact conversation engine; assign uses it only on the **worker** session. Share and queued delivery still use it on Assistant bindings. OpenCode `204` is an admitted empty response. A 404 restores one generation-scoped binding before retrying. Ambiguous network errors preserve the client message ID without another send. Every committed Assistant revision publishes `openchamber:assistants-changed` only after its SQLite transaction completes; clients use the tip to reload the authoritative snapshot after worker-driven stateless binding changes. `POST /:id/session/abort` requires the same `{ sessionID, sessionGeneration }`, returns the binding and `aborted: true`, reports a changed binding as `revision_conflict`, and preserves upstream missing-session `not_found` semantics.
 
-`GET /api/openchamber/assistants/:assistantID/messages?before=&limit=` returns archived and current bindings as `{ entries: [{ sessionID, directory, info, parts }], nextCursor, complete }`. It reads assistant-owned mirror rows in chronological session and message order, pages toward older rows with an opaque stable cursor, and preserves the raw OpenCode `info` and `part` JSON. `directory` is the effective workspace for that source session and is nullable for legacy archived rows with an unknown workspace. `complete === (nextCursor === null)` marks arrival at the oldest available history. The service reads the latest persisted `limit + 1` rows first, then demand-backfills one page at a time from the newest incomplete archived session covered by the cursor; a request performs at most three upstream pages and reuses persisted pages without upstream access. Backfill page commits are independent. Each `message.list` page attempt retries only transient 5xx/network-class SDK failures up to three times with short backoff; persistent failures still throw `upstream_error`. An authoritative OpenCode 404 for an archived or old binding marks that session's backfill complete via the `session-missing` reducer path, deletes only its uncovered event mirrors, preserves covered/admitted rows, and continues scanning other incomplete sessions so one deleted session cannot permanently block Assistant history. Successful backfill pages upsert authoritative rows without clearing provisional mirrors missing from that snapshot. Concurrent ensure that replaces a missing current binding archives the old ID and creates a new one; 404 completion never deletes covered history under either identity. A required-page failure surfaces as an upstream error only when the current request's `pageRows()` is empty; when the current range already has covered or provisional rows, the service returns that partial result and keeps the incomplete cursor retryable. Provisional event mirrors stay readable as `covered=0` fallbacks until a shrink-whitelist signal or a later authoritative upsert elevates them. Current-session live sync overrides the matching SQLite message identity in the UI.
+`GET /api/openchamber/assistants/:assistantID/messages?before=&limit=` is documented under **History coverage** (OpenCode projection source; no SQLite body mirror).
 
 Queue admission accepts `{ kind: 'assistant', assistantID }`, captures a structured binding plus provider, model, agent, nullable variant, default prompt/system, compiled text parts, and durable attachment descriptors. Direct messages, shares, and queued Assistant deliveries accept up to 129 strict OpenCode text/file parts, including up to 64 file parts. Queue dispatch uses `sendWithCapturedConfig`, so queued work never reads mutable Assistant configuration. Continuous delivery retains binding fencing and a changed binding produces `stale_target`. Stateless delivery instead belongs to the stable `assistant:<assistantID>` queue lane: it ignores disposable binding replacement, serializes prompt admissions per Assistant, and creates a fresh execution Session for every row.
 
-Share operations persist operation identity, Assistant identity, payload hash, phase, session ID, message ID, state, attempt, lease expiry, and error for seven days. `ShareOperationDTO` exposes top-level `sessionID` and `messageID` with `state` in `submitting`, `running`, `completed`, `failed`, or `unresolved`; it carries no binding. Admission and claims use SQLite transactions and compare-and-swap updates. A `reserving` phase is inserted or read under `BEGIN IMMEDIATE` before any session ensure or creation side effect. Its unique owner chooses and records the session and message IDs before claim and submit; duplicate matching requests reuse and poll that operation, while payload conflicts return `idempotency_conflict` without session work. Reservation-owner session creation failures delete the still-reserving record so a retry can reserve and recover. `running` work has a lease; `submitted` phase reconciles through message-ID lookup; expired submitted work becomes `unresolved`; failed work permits one CAS claimant to retry. `ShareOperationDTO` is available from the share response and `GET /share-operations/:operationID`. Repeated shares reuse that record. Ordinary composer messages create no operation record, but every accepted message creates or refreshes its Assistant message-mirror row.
+Share operations persist operation identity, Assistant identity, payload hash, phase, session ID, message ID, state, attempt, lease expiry, and error for seven days. `ShareOperationDTO` exposes top-level `sessionID` and `messageID` with `state` in `submitting`, `running`, `completed`, `failed`, or `unresolved`; it carries no binding. Admission and claims use SQLite transactions and compare-and-swap updates. A `reserving` phase is inserted or read under `BEGIN IMMEDIATE` before any session ensure or creation side effect. Its unique owner chooses and records the session and message IDs before claim and submit; duplicate matching requests reuse and poll that operation, while payload conflicts return `idempotency_conflict` without session work. Reservation-owner session creation failures delete the still-reserving record so a retry can reserve and recover. `running` work has a lease; `submitted` phase reconciles through message-ID lookup; expired submitted work becomes `unresolved`; failed work permits one CAS claimant to retry. `ShareOperationDTO` is available from the share response and `GET /share-operations/:operationID`. Repeated shares reuse that record. Ordinary composer messages create no operation record. Share/queue admissions do not write Assistant message-mirror bodies; OpenCode projection remains authoritative.
 
 Schema v2 migrates legacy Inbox bindings once. It prefers the legacy Inbox session, then the latest successful operation or turn session. Schema v5 makes `workspace_path` nullable and migrates stored managed paths under `dataDir/assistant-workspaces/<assistantID>` to `NULL`. Schema v7 adds `mode` (`continuous` | `stateless`, default `continuous`) and preserves legacy `assistant.mode` during Inbox migration. Schema v10 establishes demand-driven history backfill semantics; existing mirror rows remain partial until a complete backfill state is persisted. Schema v13 adds `assistant_contact_read_state` and seeds existing contact transcripts to the current tip (default-read). New records use `assistant_v2` and carry no legacy topic field. Legacy topic, turn, operation, and assistant tables remain migration sources and compatibility backups. Runtime code never reads or writes them. Migration retains OpenCode sessions and messages.
 
@@ -276,7 +281,7 @@ Assistant workspaces resolve only under the Assistant workspace root or configur
 
 ### Session operations from a contact
 
-Contact tools expose `assign_session` (new or continued session), `steer_session` (insert a user instruction using SDK `session.prompt` with `delivery: steer`, without a model override), `stop_session` (real SDK abort), `archive_session` (SDK update `time.archived`), and `delete_session` (SDK delete). All existing-session mutations resolve directory from authoritative session metadata and apply the same registered-project scope checks. They accept exact session IDs from references, history, or `list_sessions`; ambiguous targets require clarification. Delete is permanent and is only offered for an explicit deletion request. SDK failures remain tool errors, never success confirmations; a failed mutation does not clear its watch. Successful archive/delete cancel assistant watches and pending automatic resumes, just as explicit stop does. Archive itself does not abort OpenCode execution: stopping and archiving are separate operations. Steering preserves the upstream session's model and does not create a second session. Terminal operation tools execute once per successful contact turn. All surfaces use the same server contact tool implementation.
+Contact tools expose `assign_session` (new or continued session), `steer_session` (insert a user instruction using SDK `session.prompt` with `delivery: steer`, without a model override), `stop_session` (real SDK abort), `archive_session` (Host archive via `session-metadata` `openchamber.archive.archivedAt`, not upstream `session.update`), and `delete_session` (SDK delete; Host metadata cleanup follows `session.deleted`). All existing-session mutations resolve directory from authoritative session metadata and apply the same registered-project scope checks. They accept exact session IDs from references, history, or `list_sessions`; ambiguous targets require clarification. Delete is permanent and is only offered for an explicit deletion request. SDK failures remain tool errors, never success confirmations; a failed mutation does not clear its watch. Successful archive/delete cancel assistant watches and pending automatic resumes, just as explicit stop does. Archive itself does not abort OpenCode execution: stopping and archiving are separate operations. Steering preserves the upstream session's model and does not create a second session. Terminal operation tools execute once per successful contact turn. All surfaces use the same server contact tool implementation.
 
 ### Contact context and background notification boundary
 
@@ -291,6 +296,6 @@ Assign/watch tools forward the contact AbortSignal into their service calls and
 
 `read_session` is a read-only contact tool available on user turns and background notifications. An `@session:<id>` chip supplies identity only. The model reads contents through this tool before answering about the reference, and treats returned messages as quoted data, never as new user instructions or authorization to resume/watch/mutate. The quoted payload stays on the tool transcript for the model; contact bubbles keep only the spoken preamble and the post-read reply.
 
-The service resolves the exact session and registered project through the existing authoritative session resolver, then calls SDK `message.list` with `limit` (default 20, maximum 50), optional opaque `before`, and the turn AbortSignal. The upstream `x-next-cursor` is returned unchanged as `nextCursor`. Missing sessions, transport errors, malformed message lists and cross-session message identity mismatches fail closed. Empty successful lists remain distinguishable from failures.
+The service resolves the exact session and registered project through the existing authoritative session resolver, then calls SDK `message.list` with `limit` (default 20, maximum 50) and the turn AbortSignal. The first page sends `order=desc`; a continuation sends only the opaque `before` as `cursor` (upstream rejects `order` together with `cursor`). Native v2 rows are projected to role + parts and quoted oldest→newest. The upstream body `cursor.next` (falling back to the `x-next-cursor` header) is returned unchanged as `nextCursor`. Missing sessions, transport errors, malformed message lists and cross-session message identity mismatches fail closed. Empty successful lists remain distinguishable from failures.
 
 Results retain message IDs, roles, text and bounded tool-result/file metadata. Text is limited to 4,000 characters per field and 24,000 total; each message contributes at most 20 parts. File URLs/bodies, reasoning and tool inputs are omitted. `partial` explicitly marks truncation, omissions or older pages. Reading creates no watch, prompt or other mutation.

package/server/lib/assistants/contracts.js

@@ -68,7 +68,17 @@ export const assistantContractFixtures = Object.freeze({
   messageAdmission: Object.freeze({ binding: Object.freeze({ sessionID: 'ses_fixture', directory: '/workspace', sessionGeneration: 4 }), messageID: 'msg_fixture', admitted: true, revision: 4 }),
   abortResponse: Object.freeze({ binding: Object.freeze({ sessionID: 'ses_fixture', directory: '/workspace', sessionGeneration: 4 }), aborted: true }),
   shareOperation: Object.freeze({ operationID: 'share_fixture', assistantID: 'assistant_fixture', sessionID: 'ses_fixture', messageID: 'msg_fixture', state: 'running', phase: 'submitted', attempt: 1, leaseExpiresAt: 1234, errorCode: null }),
-  historicalMessages: Object.freeze({ entries: Object.freeze([Object.freeze({ sessionID: 'ses_fixture', directory: null, info: Object.freeze({ id: 'msg_fixture', sessionID: 'ses_fixture', role: 'assistant', time: Object.freeze({ created: 1234 }) }), parts: Object.freeze([]) })]), nextCursor: null, complete: true }),
+  historicalMessages: Object.freeze({
+    entries: Object.freeze([Object.freeze({
+      sessionID: 'ses_fixture',
+      directory: null,
+      info: Object.freeze({ id: 'msg_fixture', sessionID: 'ses_fixture', role: 'assistant', time: Object.freeze({ created: 1234 }) }),
+      parts: Object.freeze([]),
+    })]),
+    nextCursor: null,
+    complete: true,
+    partial: false,
+  }),
   /** Frozen GET /assistants/:id/contact/messages page envelope (UI contract). */
   contactMessagesPage: Object.freeze({
     messages: Object.freeze([]),

package/server/lib/assistants/projection-history.test.js

@@ -8,14 +8,6 @@ import { createAssistantsService } from './service.js';
 const require = createRequire(import.meta.url);
 const root = () => fs.mkdtempSync(path.join(os.tmpdir(), 'assistants-proj-'));
 
-const v2Error = (result) => {
-  if (!result?.error) return result;
-  const error = new Error(result.error.code || 'upstream');
-  error.status = result.error.status ?? result.error.statusCode ?? result.status;
-  error.cause = { status: error.status };
-  error.reason = 'UnexpectedStatus';
-  throw error;
-};
 const createV2Client = (overrides = {}) => {
   const create = overrides.create ?? (async () => ({ id: crypto.randomUUID() }));
   const get = overrides.get ?? (async () => ({ id: 'present' }));
@@ -43,7 +35,14 @@ const createV2Client = (overrides = {}) => {
     },
     message: {
       list: async (input) => {
-        const result = await list({ ...input, before: input?.cursor });
+        // Official contract fixture: refuse order+cursor combinations.
+        if (input?.cursor && input?.order != null) {
+          const error = new Error('InvalidRequestError');
+          error.status = 400;
+          error._tag = 'InvalidRequestError';
+          throw error;
+        }
+        const result = await list(input);
         if (result?.error) return result;
         if (Array.isArray(result?.data) || result?.cursor || result?.response) return result;
         if (Array.isArray(result)) return { data: result, cursor: {} };
@@ -62,6 +61,8 @@ const setup = (directory = root(), client = {}, options = {}) => {
     getOpenCodeAuthHeaders: () => ({ authorization: 'Bearer test' }),
     fetchImpl,
     clientFactory: () => createV2Client(client),
+    // Contact composer send needs a harness stub; body authority is OpenCode projection.
+    runContactTurn: serviceOptions.runContactTurn ?? (async ({ userText }) => ({ text: `reply:${userText}`, bubbles: [`reply:${userText}`] })),
     ...serviceOptions,
   });
   if (enabled) {
@@ -72,11 +73,60 @@ const setup = (directory = root(), client = {}, options = {}) => {
 };
 const assistantInput = { name: 'A', providerID: 'p', modelID: 'm' };
 
-const projectionEntry = (sessionID, id, created, text = id) => ({
-  info: { id, sessionID, role: 'assistant', time: { created } },
+const projectionEntry = (sessionID, id, created, text = id, role = 'assistant') => ({
+  info: { id, sessionID, role, time: { created } },
   parts: [{ id: `prt_${id}`, sessionID, messageID: id, type: 'text', text }],
 });
 
+/** Official v2 SessionMessageInfo-shaped user/assistant with content (not only parts). */
+const syntheticContentEntry = (sessionID, id, created, role, text) => ({
+  id,
+  sessionID,
+  type: role,
+  time: { created },
+  content: [{ type: 'text', text }],
+});
+
+/**
+ * Official-shaped desc pager: non-empty pages always expose cursor.next (even the
+ * logical last page); an empty follow-up page is the finite end.
+ */
+const createOfficialDescPager = (rowsBySession, pageLimitDefault = null) => {
+  const state = new Map();
+  for (const [sessionID, rows] of Object.entries(rowsBySession)) {
+    state.set(sessionID, rows);
+  }
+  const calls = [];
+  const list = async (input) => {
+    const sessionID = input.sessionID;
+    const limit = Number(input.limit) || pageLimitDefault || 50;
+    const rows = state.get(sessionID) || [];
+    calls.push({
+      sessionID,
+      limit,
+      order: input.order ?? null,
+      cursor: input.cursor ?? null,
+      hasOrder: input.order != null,
+    });
+    let start = 0;
+    if (input.cursor) {
+      const marker = String(input.cursor).replace(/^next:/, '');
+      const idx = rows.findIndex((row) => (row.info?.id ?? row.id) === marker);
+      start = idx >= 0 ? idx + 1 : rows.length;
+    }
+    const page = rows.slice(start, start + limit);
+    // Non-empty ⇒ always next (even past the last real row marker).
+    const next = page.length > 0
+      ? `next:${page[page.length - 1].info?.id ?? page[page.length - 1].id}`
+      : null;
+    return {
+      data: page,
+      cursor: next ? { previous: null, next } : { previous: null, next: null },
+    };
+  };
+  return { list, calls };
+};
+
 describe('ticket 11 assistants read from OpenCode projections', () => {
   it('does not persist message bodies after send, share, or live events', async () => {
     const directory = root();
@@ -105,8 +155,8 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
     const calls = [];
     const service = setup(directory, {
       create: async () => ({ data: { id: `ses_${++creates}` } }),
-      messages: async ({ sessionID, limit, order }) => {
-        calls.push({ sessionID, limit, order });
+      messages: async ({ sessionID, limit, order, cursor }) => {
+        calls.push({ sessionID, limit, order, cursor });
         if (sessionID === 'ses_1') return { data: [projectionEntry('ses_1', 'msg_old', 1, 'from-projection')] };
         return { data: [projectionEntry(sessionID, 'msg_live', 2, 'current')] };
       },
@@ -130,8 +180,131 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
     expect(page.entries.map((entry) => entry.info.id)).toEqual(['msg_old', 'msg_live']);
     expect(page.entries[0]?.parts[0]?.text).toBe('from-projection');
     expect(page.entries.some((entry) => entry.info.id === 'msg_mirror')).toBe(false);
-    expect(calls.every((call) => call.order === 'desc')).toBe(true);
+    // First page of each binding may use order=desc; never with a cursor.
+    expect(calls.every((call) => call.cursor == null || call.order == null)).toBe(true);
+    expect(calls.some((call) => call.order === 'desc' && call.cursor == null)).toBe(true);
     expect(page.complete).toBe(true);
+    expect(page.partial).toBe(false);
+    service.close();
+  });
+
+  it('traverses source seq CBA across bindings with limit 1 (not time.created sort)', async () => {
+    // ses_old (ordinal lower): source desc page [B created20, C created10]
+    // ses_new: [A created30]
+    // Public ascending walk with limit 1 must be A → B → C (source seq), not time sort tricks.
+    let creates = 0;
+    const pager = createOfficialDescPager({
+      ses_1: [
+        projectionEntry('ses_1', 'msg_B', 20, 'B'),
+        projectionEntry('ses_1', 'msg_C', 10, 'C'),
+      ],
+      ses_2: [
+        projectionEntry('ses_2', 'msg_A', 30, 'A'),
+      ],
+    });
+    const service = setup(root(), {
+      create: async () => ({ data: { id: `ses_${++creates}` } }),
+      messages: pager.list,
+    });
+    const assistant = service.createAssistant({ ...assistantInput, mode: 'stateless' });
+    await service.ensure(assistant.id); // ses_1
+    await service.createNew(assistant.id); // ses_2 live
+    const seen = [];
+    let before;
+    for (let step = 0; step < 5; step++) {
+      const page = await service.historicalMessages(assistant.id, { before, limit: 1 });
+      seen.push(...page.entries.map((entry) => entry.info.id));
+      if (page.complete) break;
+      before = page.nextCursor;
+      expect(before).toEqual(expect.any(String));
+    }
+    expect(seen).toEqual(['msg_A', 'msg_B', 'msg_C']);
+    // Continuations must never send order with cursor.
+    expect(pager.calls.filter((call) => call.cursor).every((call) => call.hasOrder === false)).toBe(true);
+    expect(pager.calls.filter((call) => !call.cursor).every((call) => call.order === 'desc')).toBe(true);
+    service.close();
+  });
+
+  it('pages 8 rows with limit 2 and 3-page budget once each id, finite end (no tip loop)', async () => {
+    const rows = Array.from({ length: 8 }, (_, index) => {
+      const n = 8 - index;
+      return projectionEntry('ses_1', `msg_${n}`, n * 10, `t${n}`);
+    });
+    const pager = createOfficialDescPager({ ses_1: rows });
+    const service = setup(root(), {
+      create: async () => ({ data: { id: 'ses_1' } }),
+      messages: pager.list,
+    });
+    const assistant = service.createAssistant(assistantInput);
+    await service.ensure(assistant.id);
+    const pages = [];
+    let before;
+    let rounds = 0;
+    do {
+      const page = await service.historicalMessages(assistant.id, { before, limit: 2 });
+      rounds += 1;
+      pages.push(page);
+      // Each demand page is ascending within itself.
+      const ids = page.entries.map((entry) => entry.info.id);
+      expect(ids).toEqual([...ids].sort((a, b) => Number(a.slice(4)) - Number(b.slice(4))));
+      before = page.complete ? null : page.nextCursor;
+      expect(rounds).toBeLessThanOrEqual(8);
+    } while (before);
+    // Infinite-query flatten (oldest page first) yields full chronological seq once.
+    const seen = pages.slice().reverse().flatMap((page) => page.entries.map((entry) => entry.info.id));
+    expect(seen).toEqual(['msg_1', 'msg_2', 'msg_3', 'msg_4', 'msg_5', 'msg_6', 'msg_7', 'msg_8']);
+    expect(new Set(seen).size).toBe(8);
+    // Tip (no cursor) is opened once; later calls only continue via opaque cursor
+    // (page-local skip may re-hit the same upstream page, but never restarts the tip).
+    const tipCalls = pager.calls.filter((call) => call.cursor == null);
+    expect(tipCalls).toHaveLength(1);
+    expect(pages.at(-1)?.complete).toBe(true);
+    service.close();
+  });
+
+  it('marks middle binding 503 as partial with retryable cursor; recovery fills the gap', async () => {
+    let creates = 0;
+    let ses2Fail = true;
+    const service = setup(root(), {
+      create: async () => ({ data: { id: `ses_${++creates}` } }),
+      messages: async ({ sessionID }) => {
+        if (sessionID === 'ses_2' && ses2Fail) return { error: { status: 503 } };
+        return { data: [projectionEntry(sessionID, `msg_${sessionID}`, 1)] };
+      },
+    });
+    const assistant = service.createAssistant({ ...assistantInput, mode: 'stateless' });
+    await service.ensure(assistant.id); // ses_1
+    await service.createNew(assistant.id); // ses_2
+    await service.createNew(assistant.id); // ses_3 live
+    const first = await service.historicalMessages(assistant.id, { limit: 10 });
+    // Newest success delivered; failed middle is not skipped permanently.
+    expect(first.entries.map((entry) => [entry.sessionID, entry.info.id])).toEqual([
+      ['ses_3', 'msg_ses_3'],
+    ]);
+    expect(first.complete).toBe(false);
+    expect(first.partial).toBe(true);
+    expect(first.failed).toEqual([
+      expect.objectContaining({ sessionID: 'ses_2', status: 503 }),
+    ]);
+    expect(first.nextCursor).toEqual(expect.any(String));
+
+    ses2Fail = false;
+    const recovered = [];
+    let before = first.nextCursor;
+    for (let step = 0; step < 5; step++) {
+      const page = await service.historicalMessages(assistant.id, { before, limit: 10 });
+      recovered.push(...page.entries.map((entry) => [entry.sessionID, entry.info.id]));
+      if (page.complete) {
+        expect(page.partial).toBe(false);
+        break;
+      }
+      before = page.nextCursor;
+    }
+    // Public pages stay ascending by binding ordinal (older session first).
+    expect(recovered).toEqual([
+      ['ses_1', 'msg_ses_1'],
+      ['ses_2', 'msg_ses_2'],
+    ]);
     service.close();
   });
 
@@ -151,10 +324,11 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
     await service.createNew(assistant.id);
     const page = await service.historicalMessages(assistant.id, { limit: 10 });
     expect(page.entries.map((entry) => [entry.sessionID, entry.info.id])).toEqual([
-      ['ses_1', 'msg_ses_1'],
       ['ses_3', 'msg_ses_3'],
     ]);
     expect(page.entries.some((entry) => entry.sessionID === 'ses_2')).toBe(false);
+    expect(page.partial).toBe(true);
+    expect(page.complete).toBe(false);
 
     const isolated = setup(root(), {
       create: async () => ({ data: { id: 'ses_only' } }),
@@ -167,7 +341,29 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
     service.close();
   });
 
-  it('uses ticket 03 projection GET /session/:id/message when fetchImpl is provided', async () => {
+  it('projects real user/assistant content synthetic rows from official shape', async () => {
+    const pager = createOfficialDescPager({
+      ses_1: [
+        syntheticContentEntry('ses_1', 'msg_asst', 20, 'assistant', 'assistant-body'),
+        syntheticContentEntry('ses_1', 'msg_user', 10, 'user', 'user-body'),
+      ],
+    });
+    const service = setup(root(), {
+      create: async () => ({ data: { id: 'ses_1' } }),
+      messages: pager.list,
+    });
+    const assistant = service.createAssistant(assistantInput);
+    await service.ensure(assistant.id);
+    const page = await service.historicalMessages(assistant.id, { limit: 10 });
+    expect(page.entries.map((entry) => [entry.info.id, entry.info.role, entry.parts[0]?.text])).toEqual([
+      ['msg_user', 'user', 'user-body'],
+      ['msg_asst', 'assistant', 'assistant-body'],
+    ]);
+    expect(page.complete).toBe(true);
+    service.close();
+  });
+
+  it('uses official GET /api/session/:id/message when fetchImpl is provided', async () => {
     const directory = root();
     const urls = [];
     const service = setup(directory, {
@@ -176,7 +372,10 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
       fetchImpl: async (input) => {
         const url = new URL(String(input));
         urls.push(url);
-        return new Response(JSON.stringify({ data: [projectionEntry('ses_proj', 'msg_fetch', 1)] }), {
+        return new Response(JSON.stringify({
+          data: [projectionEntry('ses_proj', 'msg_fetch', 1)],
+          cursor: { previous: null, next: null },
+        }), {
           status: 200,
           headers: { 'content-type': 'application/json' },
         });
@@ -187,13 +386,61 @@ describe('ticket 11 assistants read from OpenCode projections', () => {
     const page = await service.historicalMessages(assistant.id, { limit: 20 });
     expect(page.entries.map((entry) => entry.info.id)).toEqual(['msg_fetch']);
     expect(urls).toHaveLength(1);
-    expect(urls[0].pathname).toBe('/session/ses_proj/message');
+    expect(urls[0].pathname).toBe('/api/session/ses_proj/message');
     expect(urls[0].searchParams.get('limit')).toBe('20');
     expect(urls[0].searchParams.get('order')).toBe('desc');
+    expect(urls[0].searchParams.has('cursor')).toBe(false);
     expect(urls[0].searchParams.get('directory')).toEqual(expect.any(String));
     service.close();
   });
 
+  it('fetchImpl continuation omits order and only sends cursor', async () => {
+    const rows = [
+      projectionEntry('ses_1', 'msg_2', 2),
+      projectionEntry('ses_1', 'msg_1', 1),
+    ];
+    const urls = [];
+    const service = setup(root(), {
+      create: async () => ({ data: { id: 'ses_1' } }),
+    }, {
+      fetchImpl: async (input) => {
+        const url = new URL(String(input));
+        urls.push(url);
+        const cursor = url.searchParams.get('cursor');
+        if (!cursor) {
+          return new Response(JSON.stringify({
+            data: [rows[0]],
+            cursor: { next: 'opaque_next' },
+          }), { status: 200, headers: { 'content-type': 'application/json' } });
+        }
+        if (cursor === 'opaque_next') {
+          return new Response(JSON.stringify({
+            data: [rows[1]],
+            // Non-empty last page still exposes next; empty follow-up ends.
+            cursor: { next: 'opaque_end' },
+          }), { status: 200, headers: { 'content-type': 'application/json' } });
+        }
+        return new Response(JSON.stringify({
+          data: [],
+          cursor: { next: null },
+        }), { status: 200, headers: { 'content-type': 'application/json' } });
+      },
+    });
+    const assistant = service.createAssistant(assistantInput);
+    await service.ensure(assistant.id);
+    const first = await service.historicalMessages(assistant.id, { limit: 1 });
+    expect(first.entries.map((e) => e.info.id)).toEqual(['msg_2']);
+    expect(first.complete).toBe(false);
+    const second = await service.historicalMessages(assistant.id, { before: first.nextCursor, limit: 1 });
+    expect(second.entries.map((e) => e.info.id)).toEqual(['msg_1']);
+    expect(urls[0].searchParams.get('order')).toBe('desc');
+    expect(urls[0].searchParams.has('cursor')).toBe(false);
+    const cont = urls.filter((url) => url.searchParams.has('cursor'));
+    expect(cont.length).toBeGreaterThanOrEqual(1);
+    expect(cont.every((url) => !url.searchParams.has('order'))).toBe(true);
+    service.close();
+  });
+
   it('exposes V2 sharing as unavailable and never reads mirrors to fake a share', async () => {
     const service = setup();
     expect(await service.capability()).toMatchObject({ sharingAvailable: false, archiveMetadataAvailable: false, sessionMetadataAvailable: false });

package/server/lib/assistants/routes.js

@@ -20,6 +20,8 @@ export const registerAssistantRoutes = (app, dependencies) => {
     ensureTempDirectory: ensureLlmTempDirectory,
     // Attachment-session generate may subscribe for session.text.delta (contact harness).
     globalEventHub: input?.globalEventHub ?? dependencies.globalEventHub,
+    persistSessionMetadata: dependencies.persistSessionMetadata,
+    onSystemSessionPersisted: dependencies.onSystemSessionPersisted,
   });
   const service = createAssistantsService({
     dbPath: dependencies.dbPath,
@@ -38,6 +40,10 @@ export const registerAssistantRoutes = (app, dependencies) => {
     onRevisionTip: dependencies.onRevisionTip,
     onContactTurnEvent: dependencies.onContactTurnEvent,
     onContactTurnComplete: dependencies.onContactTurnComplete,
+    archiveSessionHost: dependencies.archiveSessionHost,
+    forgetSessionHost: dependencies.forgetSessionHost,
+    persistSessionMetadata: dependencies.persistSessionMetadata,
+    onSystemSessionPersisted: dependencies.onSystemSessionPersisted,
     createChatCompletion: boundCompletion,
   });
   setAssignedSessionSettleHandler(({ sessionId, status }) => service.reportAssignedSessionSettle(sessionId, status));