npm - @openchambery/web - Versions diffs - 1.19.13 → 1.19.15-beta.1 - Mend

@openchambery/web 1.19.13 → 1.19.15-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (120) hide show

package/dist/index.html CHANGED Viewed

@@ -552,7 +552,7 @@
         opacity: 0.72;
       }
     </style>
-    <script type="module" crossorigin src="/assets/main-Ci3JmtpW.js"></script>
+    <script type="module" crossorigin src="/assets/main-CnY0LWNc.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-auth-D66yq6ie.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-switch-LvWDU-SL.js">
@@ -563,17 +563,17 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-YbQKzHUQ.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-DILvrAok.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-t8asCr3m.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-DwRBC4zl.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-B052a4UK.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-OjKNXr10.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/platform-DzsGqlGW.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-noa4Cdbh.js">
+    <link rel="modulepreload" crossorigin href="/assets/platform-DQ5_LNKO.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-CfgOfnZk.js">
     <link rel="modulepreload" crossorigin href="/assets/types-BuiqMmh_.js">
     <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-DCowZ2ab.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DI8l0VyZ.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-AA-5nXsF.css">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-utWzrDwa.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-CFUi4riW.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <!-- Keep the startup layer outside #root. React replaces every child of

package/dist/mini-chat.html CHANGED Viewed

@@ -74,7 +74,7 @@
       }
     </style>
-    <script type="module" crossorigin src="/assets/miniChat-BYrjYEXJ.js"></script>
+    <script type="module" crossorigin src="/assets/miniChat-B0pw_mUs.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-auth-D66yq6ie.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-switch-LvWDU-SL.js">
@@ -85,17 +85,17 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-YbQKzHUQ.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-DILvrAok.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-t8asCr3m.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-DwRBC4zl.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-B052a4UK.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-OjKNXr10.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/platform-DzsGqlGW.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-noa4Cdbh.js">
+    <link rel="modulepreload" crossorigin href="/assets/platform-DQ5_LNKO.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-CfgOfnZk.js">
     <link rel="modulepreload" crossorigin href="/assets/types-BuiqMmh_.js">
     <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-DCowZ2ab.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DI8l0VyZ.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-AA-5nXsF.css">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-utWzrDwa.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-CFUi4riW.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <div id="root" class="h-full">

package/dist/mobile.html CHANGED Viewed

@@ -63,7 +63,7 @@
       })();
     </script>
-    <script type="module" crossorigin src="/assets/mobile-BVMNnPK2.js"></script>
+    <script type="module" crossorigin src="/assets/mobile-BKHmxwXz.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-auth-D66yq6ie.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-switch-LvWDU-SL.js">
@@ -74,17 +74,17 @@
     <link rel="modulepreload" crossorigin href="/assets/vendor-pathe-vBmvQE8f.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-react-DLPElpoQ.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-tanstack-query-core-BWz0ose6.js">
-    <link rel="modulepreload" crossorigin href="/assets/persistence-YbQKzHUQ.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-DILvrAok.js">
-    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-t8asCr3m.js">
+    <link rel="modulepreload" crossorigin href="/assets/persistence-DwRBC4zl.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopHosts-B052a4UK.js">
+    <link rel="modulepreload" crossorigin href="/assets/desktopRelayRestore-OjKNXr10.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-opencode-sdk-C07HQypa.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-aparajita-capacitor-secure-storage-CjQdwfjS.js">
-    <link rel="modulepreload" crossorigin href="/assets/platform-DzsGqlGW.js">
-    <link rel="modulepreload" crossorigin href="/assets/terminalApi-noa4Cdbh.js">
+    <link rel="modulepreload" crossorigin href="/assets/platform-DQ5_LNKO.js">
+    <link rel="modulepreload" crossorigin href="/assets/terminalApi-CfgOfnZk.js">
     <link rel="modulepreload" crossorigin href="/assets/types-BuiqMmh_.js">
     <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-DCowZ2ab.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-DI8l0VyZ.js">
-    <link rel="stylesheet" crossorigin href="/assets/src-AA-5nXsF.css">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-utWzrDwa.js">
+    <link rel="stylesheet" crossorigin href="/assets/src-CFUi4riW.css">
   </head>
   <body class="h-full bg-background text-foreground">
     <div id="root" class="h-full"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/web",
-  "version": "1.19.13",
+  "version": "1.19.15-beta.1",
   "private": false,
   "type": "module",
   "main": "./server/index.js",

package/server/index.js CHANGED Viewed

@@ -1596,6 +1596,7 @@ async function main(options = {}) {
     formatSettingsResponse,
     readSettingsFromDisk,
     readSettingsFromDiskMigrated,
+    readSettingsFromDiskStrict,
     persistSettings,
     sanitizeProjects,
     sanitizeSkillCatalogs,

package/server/lib/assistants/DOCUMENTATION.md CHANGED Viewed

@@ -2,45 +2,86 @@
 ## Acceptance criteria
+The contact's default role is personable communication, workspace discovery,
+task delegation, and result follow-up. Substantive implementation runs through
+`assign_session` in the relevant existing OpenCode workspace; simple lookups and
+small, bounded configuration changes can use the contact's pi tools directly.
+This routing preference is prompt policy; the direct tools remain available.
+Contact pi execution uses the configured workspace (its canonical effective path)
+when present. Explicit `workspacePath: null` starts pi in `os.homedir()` for the
+current server OS user, allowing user-global directory lookup. This applies on
+the connected backend for web, desktop, and mobile. Archived OpenCode bindings,
+`managedWorkspacePath`, and `effectiveWorkspacePath` retain their existing
+storage/session meaning. Only the contact pi working directory changes.
+Discovery starts in the configured directory, checks existing session metadata,
+and walks parent directories to locate the nearest relevant workspace; broader
+`list_sessions` lookups can find related conversations. Ambiguous targets need
+clarification. An empty registered catalog still allows discovery; assigning a
+discovered workspace requires its registration through existing Settings.
 Worker submission uses one admission path for new and existing sessions.
 Definite rejection cleans up only a session created by that call. Ambiguous
 admission keeps the worker and confirms the exact message ID before reporting
 success. Attachment deduplication uses ordered content digests; reordering
 attachments is a different request.
-The in-app Assistant is an OpenChamber-owned **contact**. OpenCode is only the LLM gateway (`POST /api/openchamber/llm/chat/completions`) using already-connected `{providerID, modelID}`. Composer send runs `@earendil-works/pi-agent-core` with `thinkingLevel: 'off'`. When the assistant has an effective workspace, the harness attaches pi's four coding tools (`read`, `write`, `edit`, `bash`) via `NodeExecutionEnv` in that directory, applies `defaultPrompt`, and merges skills from `~/.claude/skills`, `~/.agents/skills`, plus the project's `.claude/skills` and `.agents/skills` (project wins on name). OpenChamber API tools remain (`new_conversation`, `clear_chat_history`, `list_projects`, `list_sessions`, `get_assistant_settings`, `update_default_prompt`, `create_assistant`, `schedule_task`, `message_assistant`, `assign_session`). It does not use `SessionPrompt` / `promptAsync` as the conversation engine. The LLM gateway throwaway session still denies OpenCode tools (`session.create` PermissionRuleset deny-all + `promptAsync` tools map + hidden `openchamber-llm` agent `permission: { "*": deny }`); file and shell work runs in-process through pi. The contact system prompt includes **full argument schemas** for both pi coding tools and OpenChamber contact tools. Skill directory entries are instructions loaded via `read`, not native/MCP tool names.
+The in-app Assistant is an OpenChamber-owned **contact**. OpenCode is only the LLM gateway (`POST /api/openchamber/llm/chat/completions`) using already-connected `{providerID, modelID}`. Composer send runs `@earendil-works/pi-agent-core` with `thinkingLevel: 'off'`. When the assistant has an effective workspace, the harness attaches pi's four coding tools (`read`, `write`, `edit`, `bash`) via `NodeExecutionEnv` in that directory, applies `defaultPrompt`, and merges skills from `~/.claude/skills`, `~/.agents/skills`, plus the project's `.claude/skills` and `.agents/skills` (project wins on name). OpenChamber API tools remain (`new_conversation`, `clear_chat_history`, `list_projects`, `list_sessions`, `get_assistant_settings`, `update_default_prompt`, `create_assistant`, `schedule_task`, `message_assistant`, `assign_session`, `watch_session`, `read_session`, `steer_session`, `stop_session`, `archive_session`, `delete_session`). It does not use `SessionPrompt` / `promptAsync` as the conversation engine. The LLM gateway throwaway session still denies OpenCode tools (`session.create` PermissionRuleset deny-all + `promptAsync` tools map + hidden `openchamber-llm` agent `permission: { "*": deny }`); file and shell work runs in-process through pi. The contact system prompt includes **full argument schemas** for both pi coding tools and OpenChamber contact tools. Skill directory entries are instructions loaded via `read`, not native/MCP tool names.
-Contact turns retain all ten OpenChamber operation tools alongside the four
+User contact turns retain all sixteen OpenChamber operation tools alongside the four
 pi tools. Skill discovery contributes instructions to this combined tool set.
-Assignment intent includes “建个会话” and “再建个会话”. The single missed-call
+Assignment intent includes “建个会话” and “再建个会话”. Watch intent includes
+“监听会话”; stop intent includes “停止会话”. The single missed-call
 retry checks for a result from a requested operation tool; a `read` result alone
 leaves an assignment request eligible for retry. A successful contact reset
 retains its terminal semantics. Tool failures count as attempted operations
 and keep their existing error result handling.
+**User interruption is terminal for the current watch**
+- Authoritative OpenCode `MessageAbortedError` on `session.error` or assistant `message.updated` settles the watched card as `cancelled`, not a retryable failure. Reconciliation and a complete/error pre-continuation worker-message check recognize the same error and convert that watch to `cancelled`. Successful `stop_session` also cancels the watch when upstream emits no event.
+- `cancelled` is durable in the existing watch/card records and excluded from in-flight reconciliation. Later idle, busy, and error events cannot rearm it. Only an explicit assign/watch admission overwrites the cancelled watch for a new run. No schema migration is needed: watch/card status is an open string.
+- Pending/running automatic continuations own cancellation controllers. A worker interruption aborts those complete/error continuations, including already queued ones, and does not abort a cancelled interrupt notify already queued for that worker. Duplicate `cancelled` reports (boot reconcile plus timer, or `session.error` plus `message.updated`) stay idempotent on the watch and still let that notify run. A newly admitted user message supersedes that assistant's existing automatic continuations, including a cancelled notify. Other assistants/workers remain independent. Aborted complete/error continuations clear activity and settle with `cancelled` without adding a retry, error bubble, or late response.
+- When the watch **transitions** to `cancelled` from a user abort (event or reconcile), the service schedules the same read-only contact-lane continuation as complete/error. Internal `userText` states `status: cancelled` and `reason: user_interrupted` (manual OpenCode abort / `MessageAbortedError`, not a model failure, not `stop_session`). A cancelled resume that fetches worker messages must still run — it must not re-enter the abort short-circuit. `stop_session` marks `cancelled` without this extra continuation because the assistant already owns that user turn.
+- The signal reaches pi tools and model generation. The stream adapter checks before/after model requests and before protocol retries, preventing a late tool response from executing. An already completed side effect is not rolled back. Cancellation is authoritative runtime state, not a language-model interpretation of “stop”.
+**Workspace response and loop protocol**
+- Protocol correction never replays rejected assistant prose into model history: simulated User/Assistant turns and tool-result records are rejected as fabricated evidence. Known rejected coding calls cannot be skipped with a subsequent `complete` declaration; the model must issue actual calls or report a blocker. Corrections remain bounded and exhaustion is an error, not a completion.
+- A workspace-backed contact keeps running until it emits coding calls or an explicit `openchamber-final` JSON fence with `{ "status": "complete" | "blocked", "text": "..." }`. Final declarations contain the user-facing answer only; missing input/questions use `blocked`. Ordinary conversation can finish without tools using the same declaration. Reading a skill loads instructions and does not itself complete the user's task. Contacts without coding tools retain their plain-text reply contract.
+- Plain progress text is not completion. The stream adapter requests at most two protocol corrections for a rejected response, retaining actual prior calls/results. It emits no bubbles and executes no calls from the rejected response. Exhaustion becomes an upstream error, not a successful reply. This guard enforces the response protocol; a model's explicit completion claim is not independent verification of arbitrary task semantics.
+- `parseContactToolCalls` returns an ordered `toolCalls` array. It accepts application fences, complete generic JSON fences, and bare/embedded call objects. Nested argument objects and quoted markdown fences remain data. An invalid/unavailable/unclosed explicit application call rejects the entire response before any prefix can execute.
+- Multiple coding calls run sequentially through pi (`toolExecution: 'sequential'`), preserving dependencies such as write then read. OpenChamber operation tools must be sent one at a time: mixed/multiple-operation batches are rejected before execution so terminal assign/reset/watch semantics and side-effect gates remain intact.
+- Completion history retains every assistant tool call (name, arguments, generated call ID) and its real tool result, including empty content and `isError`. Results still use gateway-supported user messages labeled `OpenChamber tool result name=... call=...` with a JSON body. Model-written result lookalikes are never executed or admitted as actual tool results. Final JSON text is opaque: quoted tool examples in a final answer cannot execute.
+- Malformed calls or mixed final declarations use the same bounded correction path. Only a validated tool response or final reply reaches the pi stream; protocol corrections do not replay tools already executed. Runtime file/shell cleanup remains in `finally`.
 **Session cards (this PR)**
 - First-class contact parts reuse one slot: `cardType` `session` | `assistant` | `schedule`.
 - Persist in `assistant_contact_message` / `assistant_contact_part`. Survive reload.
-- Cards are **assistant-emitted UI**, not user slash commands. The user never types `/card`. Insert: tool auto-cards (`assign_session`, `create_assistant`, `schedule_task`), and API `POST /:id/contact/cards` for harness/tests. Later project/worktree/watch/PR, inbound pushes, and summon **must** reuse this card slot.
+- Cards are **assistant-emitted UI**, not user slash commands. The user never types `/card`. Insert: tool auto-cards (`assign_session`, `watch_session`, `create_assistant`, `schedule_task`), and API `POST /:id/contact/cards` for harness/tests. Later project/worktree/PR, inbound pushes, and summon **must** reuse this card slot.
 **Assign work (this PR)**
 - `assign_session` is an OpenChamber AgentTool on the contact harness. It creates or reuses a visible OpenCode/OpenChamber session on a **registered project path** (Settings projects / `getAllowedRoots()`), optionally an **existing** Chat worktree/branch via `getWorktrees`, then kicks the coding prompt into that session with `session.create` + `session.promptAsync` (same worker path as `POST /api/openchamber/conversations`).
-- That worker session is the coder. The contact does not code. Assign sessions are **not** archived Assistant bindings and must not use `assistant-workspaces`.
-- **Worker model selection:** optional tool args `providerID` / `modelID` / `model` resolve against the live connected OpenCode catalog (`loadConnectedCatalog` / `GET /provider` + `GET /config/providers`). Explicit selection must match uniquely — missing or ambiguous names fail closed (`model_not_found` / `model_ambiguous`) with **no silent fallback**. Omitting model args on a **new** worker keeps the contact assistant's default provider/model. **Reusing `sessionID` without an explicit model** follows that session's last model (`session.get` → `session.model` `{ providerID, id|modelID }`, else newest user/assistant `info.model`) when it is still an exact providerID+modelID match in the connected catalog (`source: 'session'`); missing session model, catalog miss, or lookup failure **degrades** to the assistant default (`source: 'assistant'`) and never fails assign. Selecting a worker model **never** mutates the contact assistant row.
-- Every contact turn injects a **Connected OpenCode models** block (providerID, modelID, name, acceptsImages) so the model can discover worker targets without another contact tool. Still ten OpenChamber contact tools + four pi coding tools.
+- That worker session owns substantive implementation. The contact owns communication and coordination, with direct pi tools for small, bounded tasks. Assign sessions are **not** archived Assistant bindings and must not use `assistant-workspaces`.
+- **Reuse / continue existing session:** `assign_session` with `sessionID` + coding prompt continues that worker. Before prompt, the service resolves directory/project from **authoritative** session metadata (session index directory → `session.get` payload → registered project match). User-supplied `projectPath`/`directory` are lookup **hints only** and never override scope. Missing/unregistered/failed session lookup **fails closed** (not empty success). Prior worker model/config semantics stay: omit model args to follow the session model when still connected.
+- **`watch_session`:** listen-only attach for an existing session (`sessionID` required). No `promptAsync`. Emits the same session card slot and reuses `assistant_contact_watch` + `reportAssignedSession` / reconcile / resume. Baseline card/watch status comes from live `session.get` (+ messages when needed) via `mapSessionToWatchStatus` so an already-terminal idle is **not** treated as a fresh complete transition (no false resume). In-flight baseline (`busy`/`question`) keeps the watch until real settle. A plain user `@session:id` (or JSON title/sessionID/directory) reference is **context only** — it does not auto-call `watch_session`; the model must hear an explicit listen/watch/monitor intent.
+- **`stop_session`:** calls real OpenCode `session.abort` for `sessionID` after the same authoritative directory resolve. Returns the true abort result — transport/`not_found`/upstream errors stay errors (never claim stopped on failure). Abort is registered in a private per-session inflight map before `await abort` so concurrent SSE `complete`/`error` cannot schedule a `resume=true` continuation ahead of `resume=false`. On successful abort the service marks the watch/card `cancelled` even when upstream emits no idle/error event. Idle/error events still flow through the existing watch reporter when a watch exists.
+- **Worker model selection:** optional tool args `providerID` / `modelID` / `model` resolve against the live connected OpenCode catalog (`loadConnectedCatalog` / `GET /provider` + `GET /config/providers`). Explicit selection must match uniquely — missing or ambiguous names fail closed (`model_not_found` / `model_ambiguous`) with **no silent fallback**. Omitting model args on a **new** worker keeps the contact assistant's default provider/model. **Reusing `sessionID` without an explicit model** follows that session's last model (`session.get` → `session.model` `{ providerID, id|modelID }`, else newest user/assistant `info.model`) when it is still an exact providerID+modelID match in the connected catalog (`source: 'session'`); missing session model, catalog miss, or lookup failure **degrades** to the assistant default (`source: 'assistant'`) and never fails assign once the session itself resolved. Selecting a worker model **never** mutates the contact assistant row.
+- Every user or automatic contact turn reloads the current instance's **Connected OpenCode models** block (exact providerID, modelID, providerName, name, acceptsImages), plus settings-backed favorite models in saved order and recent models newest first. Only connected catalog entries qualify as preference candidates; variants remain separate from model IDs. Catalog and preference read failures remain explicit unknown states, distinct from successful empty lists; either read can succeed independently. The route projects only favoriteModels/recentModels from the strict settings reader, never arbitrary settings or credentials. No catalog is cached across turns or runtime switches. Informal `model` aliases normalize punctuation/spacing and require a unique catalog match; explicit `modelID` stays exact. Ambiguous aliases never silently prefer a favorite/provider. This server-owned context is shared by web, desktop, and mobile clients of that instance.
 - **Current-turn attachments:** server-authoritative `userParts` file parts from this contact turn are forwarded into worker `promptAsync` parts by default (including “just open a session” intents). The model must not base64-encode or invent local paths. History images are **not** unbounded-forwarded. Image parts require a vision-capable catalog entry (`acceptsImages`); otherwise assign fails with `image_not_supported` before create. Sensitive file bodies are never logged.
 - **Create-then-prompt failure:** if `session.create` succeeds and `promptAsync` fails, assign best-effort `session.delete`s the new worker so empty sessions are not left behind. Reused `sessionID` paths never delete on prompt failure.
-- Successful `assign_session` returns `terminate: true` so the pi agent loop does **not** auto-follow-up the LLM (prevents a looping model from re-assigning dozens of times in one turn). Prerequisite tools (`list_projects` / `list_sessions`) may still run before assign in the same turn; multi-operation user intents remain ordered **across turns** after a successful assign.
+- Successful `assign_session` and `watch_session` return `terminate: true` so the pi agent loop does **not** auto-follow-up the LLM (prevents a looping model from re-assigning dozens of times in one turn). 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, 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`. The user-facing outcome is the session card plus any short **spoken** preamble; English tool-result confirms (`Opened a 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`). **No canned settle transcript bubbles** (`oc.settle.complete` / `error` / `question` are not written). On **complete or error** 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). The contact Agent may re-`assign_session` the same sessionID or summarize in the user's language — the user sees that Agent summary, not 「会话已完成/会话失败」. `question` updates the card only (worker waiting on the user). 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.
-- Restart or a missed `session.idle` cannot leave the watch stuck: boot and the existing 60s reconcile timer `listInFlightWatches` and poll OpenCode `session.get` / `session.messages`. 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. 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.
+- 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.
+- Restart or a missed `session.idle` cannot leave the watch stuck: boot and the existing 60s reconcile timer `listInFlightWatches` and poll OpenCode `session.get` / `session.messages`. 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.
-- **Contact active turn (server authoritative):** process-local metadata tracks admission → `queued` → `running` → settled (removed). `AssistantDTO.working` is true only while that assistant has an unsettled contact turn. `AssistantDTO.activeContactTurn` is `{ turnID, messageID, status: 'queued'|'running', admittedAt }` or `null` so APP restart / reconnect can rehydrate list green dots and the contact 3-dot row from the snapshot HTTP GET — local optimistic and SSE preview are temporary only. A server process restart clears in-memory activity (no permanent green; tools are not auto-rerun). Per-assistant lanes isolate turns across assistants/runtimes. Stale `contact-turn-end` for an older `turnID` must not clear a newer active turn.
-- **List latest-message preview (server authoritative):** every `AssistantDTO` path (`snapshot` / `create` / `update` / other `output` rows) carries `latestMessagePreview: { messageID, ordinal, role: 'user'|'assistant', text, fallbackKind: 'image'|'file'|'session'|'assistant'|'schedule'|null } | null`. Source is the contact transcript only (not `defaultPrompt` / `updatedAt`). Order is the same keyset as contact pages: newest `(ordinal DESC, message_id DESC)`. Visible roles are `user`, `assistant`, and `peer` (peer maps to `role: 'user'` because inbound DMs are user-visible). Internal assigned-session settle markers (`oc.settle.*`) are excluded in the SQL candidate probe (and again in `buildContactMessagePreview`). Durable error bubbles keep their real body text. Plain text is sanitized and capped at `CONTACT_PREVIEW_MAX_CHARS` (500) with no data-URL/base64 bodies. File-only rows set `fallbackKind` `image`/`file`; pure cards set `session`/`assistant`/`schedule`. Empty transcript → `null`. **Snapshot cost:** one prepared statement reused per assistant (`assistant_id` + indexed `ORDER BY ordinal DESC, message_id DESC LIMIT candidateLimit`, catalog ≤100) collecting only those bounded candidates, then **one** parts `IN` query — not a window/`ROW_NUMBER` over full multi-assistant history and not HTTP N+1. SQL already drops pure settle tails so they cannot exhaust the LIMIT and hide an older real bubble; remaining non-preview empty rows may still consume a candidate slot within that same LIMIT. Admission, assistant completion, peer DM, card insert, wipe, and clear-memory already bump domain revision / `openchamber:assistants-changed`; clients re-GET snapshot for the new preview. Clear-memory keeps transcript rows so the preview still reflects the last bubble; clear-history / reset remove rows so the preview becomes the wipe confirm (or `null` after a full unbounded wipe with no remaining user).
+- **Contact active turn (server authoritative):** process-local metadata tracks admission → `queued` → `running` → settled (removed). `AssistantDTO.working` is true only while that assistant has an unsettled contact turn. `AssistantDTO.activeContactTurn` is `{ turnID, messageID, status: 'queued'|'running', admittedAt }` or `null` so APP restart / reconnect can rehydrate list green dots and the contact 3-dot row from the snapshot HTTP GET. Spoken bubbles and cards persist to SQLite as soon as they publish (`done:true` / `onCard`) so another device or APP restart can GET them while the turn is still running. Token-level SSE deltas remain live paint only. A server process restart clears in-memory activity (no permanent green; tools are not auto-rerun) but already-published bubbles/cards stay in the transcript. Per-assistant lanes isolate turns across assistants/runtimes. Stale `contact-turn-end` for an older `turnID` must not clear a newer active turn.
+- **List latest-message preview (server authoritative):** every `AssistantDTO` path (`snapshot` / `create` / `update` / other `output` rows) carries `latestMessagePreview: { messageID, ordinal, createdAt, role: 'user'|'assistant', text, fallbackKind: 'image'|'file'|'session'|'assistant'|'schedule'|null } | null`. Source is the contact transcript only (not `defaultPrompt` / `updatedAt`). Order is the same keyset as contact pages: newest `(ordinal DESC, message_id DESC)`. Visible roles are `user`, `assistant`, and `peer` (peer maps to `role: 'user'` because inbound DMs are user-visible). Internal assigned-session settle markers (`oc.settle.*`) are excluded in the SQL candidate probe (and again in `buildContactMessagePreview`). Durable error bubbles keep their real body text. Plain text is sanitized and capped at `CONTACT_PREVIEW_MAX_CHARS` (500) with no data-URL/base64 bodies. File-only rows set `fallbackKind` `image`/`file`; pure cards set `session`/`assistant`/`schedule`. Empty transcript → `null`. **Snapshot cost:** one prepared statement reused per assistant (`assistant_id` + indexed `ORDER BY ordinal DESC, message_id DESC LIMIT candidateLimit`, catalog ≤100) collecting only those bounded candidates, then **one** parts `IN` query — not a window/`ROW_NUMBER` over full multi-assistant history and not HTTP N+1. SQL already drops pure settle tails so they cannot exhaust the LIMIT and hide an older real bubble; remaining non-preview empty rows may still consume a candidate slot within that same LIMIT. Admission, assistant completion, peer DM, card insert, wipe, and clear-memory already bump domain revision / `openchamber:assistants-changed`; clients re-GET snapshot for the new preview. Clear-memory keeps transcript rows so the preview still reflects the last bubble; clear-history / reset remove rows so the preview becomes the wipe confirm (or `null` after a full unbounded wipe with no remaining user).
 - No registered project → clear `project_required` (ask the user to configure a project). Never fall back to managed assistant-workspaces.
 - Assign must not go through the peer DM channel.
 - `assignWork` (service) resolves the worker model via the connected catalog (`capabilities.input.image` preferred), forwards tool `variant` (cross-model drops contact variant), passes AbortSignal into create/prompt/delete/catalog, and supplies `lookupMessage` over real SDK exact lookup (`v2.session.message` → `session.message` → bounded `session.messages`). Ambiguous prompt admission returns `prompt_ambiguous` with `sessionID`/`messageID` and does **not** delete the worker; the contact-turn assign gate retains that identity so a same-args retry reuses the session and cannot blind-create another worker this turn.
@@ -49,7 +90,7 @@ and keep their existing error result handling.
 **Registered projects + sessions (this PR)**
-- Every contact turn injects a **Registered projects** block (`id`, `path`, `label`) from `listProjects()` into the system prompt via `formatRegisteredProjectsPrompt`. The model can fuzzy-match names like "openchamber yee" without a tool call first. It must never claim it cannot see the list; empty catalog → tell the user to add a project in Settings.
+- Every contact turn injects a **Registered projects** block (`id`, `path`, `label`) from `listProjects()` into the system prompt via `formatRegisteredProjectsPrompt`. The model can fuzzy-match names like "openchamber yee" without a tool call first. Empty catalog → discover the relevant existing workspace using sessions and directory lookups, then request registration in Settings before assignment.
 - `list_projects` refreshes/filters that catalog (`query` optional). `list_sessions` searches the existing session-index (`sessionIndexService.snapshot()`) for sessions in a project (`projectPath` / `projectID`, optional title query). Results are bounded (`sessionID`, `title`, `directory`, `updatedAt`). Index/catalog failure is an error, never an empty success.
 - After matching a project, open work with `assign_session` (`projectPath` and/or existing `sessionID`).
@@ -67,8 +108,8 @@ and keep their existing error result handling.
 - `create_assistant` calls the same in-process `createAssistant` (`name`, connected OpenCode `providerID`/`modelID`, `mode: 'continuous'`). It emits an `assistant` card that opens that contact.
 - `schedule_task` calls in-process `projectConfigRuntime.upsertScheduledTask` with the same payload as `PUT /api/projects/:id/scheduled-tasks` (`name`, `schedule.kind/time/timezone`, `execution.prompt` + provider/model) on a registered project, then best-effort `scheduledTasksRuntime.syncProject`. It emits a `schedule` card.
 - Successful `schedule_task` also writes an assistants-owned mapping row in `assistants.sqlite` (`assistant_scheduled_task`: assistantID + projectID + taskID). Project-config execution strips unknown fields, so ownership stays out of the task payload. `GET /api/openchamber/assistants/:id/scheduled-tasks` returns those mappings joined with live `listScheduledTasks` records when possible; failed project lookups keep the mapping with `task: null`.
-- `CONTACT_SYSTEM_PROMPT` + `formatContactToolsPrompt` + `formatPiCodingPrompt` tell the model to call these from natural language (开新对话 / 找项目 / 现有对话 / 查看助手设定·默认提示词 / 改默认提示词·设置人设 / 建助理 / 建会话 / 排定时任务 / 给 X 说一声). Catalog lines include each tool's JSON argument schema (pi `write`/`edit` require `path`+`content` / `path`+`edits[{oldText,newText}]`). A reply without the tool call does nothing; never say 已创建 / 已发送 unless the tool returned. Completions are messages-only (no native tools), so `parseContactToolCalls` accepts a fence, a whole-message JSON object, or a bare `{name, arguments}` object anywhere in the reply. Tool results are re-injected as user turns labeled `OpenChamber tool result name=<tool> call=<id>` so multi-step turns keep call/result association.
-- If the user asked for `new_conversation` / `clear_chat_history` / `list_projects` / `list_sessions` / `get_assistant_settings` / `update_default_prompt` / `create_assistant` / `schedule_task` / `message_assistant` / `assign_session` and the first completion has no tool call, the harness runs **one** follow-up completion whose user content is only `emit the fence now, do not claim success.` If still no tool, the turn replies that it could not complete and does not fake a card. No slash commands. No second store.
+- `CONTACT_SYSTEM_PROMPT` + `formatContactToolsPrompt` + `formatPiCodingPrompt` tell the model to call these from natural language (开新对话 / 找项目 / 现有对话 / 查看助手设定·默认提示词 / 改默认提示词·设置人设 / 建助理 / 建会话·继续会话 / 监听会话 / 停止会话 / 排定时任务 / 给 X 说一声). Catalog lines include each tool's JSON argument schema (pi `write`/`edit` require `path`+`content` / `path`+`edits[{oldText,newText}]`). A reply without the tool call does nothing; never say 已创建 / 已发送 / 已停止 unless the tool returned. Completions are messages-only (no native tools), so `parseContactToolCalls` accepts a fence, a whole-message JSON object, or a bare `{name, arguments}` object anywhere in the reply. Tool results are re-injected as user turns labeled `OpenChamber tool result name=<tool> call=<id>` with JSON `{ isError, content }`; assistant calls and their arguments/IDs are also retained so multi-step turns keep call/result association. The harness replaces every `{{LANGUAGE}}` token — in the built-in prompt and in `defaultPrompt` — with the UI locale sent on the composer payload (`language` field, whitelisted locale code → display name). Background/settle turns recall the last locale seen for that assistant; unknown or missing locales resolve to `the user's interface language`, so the token never leaks into the prompt.
+- If the user asked for `new_conversation` / `clear_chat_history` / `list_projects` / `list_sessions` / `get_assistant_settings` / `update_default_prompt` / `create_assistant` / `schedule_task` / `message_assistant` / `watch_session` / `stop_session` / `assign_session` and the first completion has no tool call, the harness runs **one** follow-up completion whose user content is only `emit the fence now, do not claim success.` If still no tool, the turn replies that it could not complete and does not fake a card. No slash commands. No second store.
 **Clear memory vs clear chat history (this PR)**
@@ -82,7 +123,7 @@ and keep their existing error result handling.
 **Contact LLM window (this PR)**
-- `contactHistoryForLlm` is a short algorithmic window documented in `contact-store.js`: durable context boundary first, then `CONTACT_LLM_MAX_TURNS` (8), `CONTACT_LLM_MAX_CHARS` (6000), `CONTACT_LLM_FETCH_LIMIT` (40), `CONTACT_LLM_FILE_CHAR_WEIGHT` (80). Newest user+assistant text pairs after the watermark are kept; peer / error / pure-card rows are dropped. There is no summarizer and no user-facing compress or continuous/stateless memory control. SQLite and the transcript UI may still scroll older bubbles, including rows before the boundary.
+- `contactHistoryForLlm` is a short algorithmic window documented in `contact-store.js`: durable context boundary first, then `CONTACT_LLM_MAX_TURNS` (32), `CONTACT_LLM_MAX_CHARS` (48000), `CONTACT_LLM_FETCH_LIMIT` (100), `CONTACT_LLM_FILE_CHAR_WEIGHT` (80). Newest user+assistant text pairs after the watermark are kept; peer / error rows are dropped; cards retain structured ID/status context. There is no summarizer and no user-facing compress or continuous/stateless memory control. SQLite and the transcript UI may still scroll older bubbles, including rows before the boundary.
 **Contact attachments (this PR)**
@@ -131,13 +172,47 @@ and keep their existing error result handling.
   `complete: true`. Missing or other-assistant IDs yield `messages: []`.
 - `revision` is the assistants domain tip (same counter as snapshot).
+**Contact unread / shared read watermark (this PR)**
+- Server-authoritative **per-assistant shared** read watermark in `assistant_contact_read_state`
+  (`last_read_ordinal`, `last_read_message_id`, `generation`). Multi-client; not per-device.
+- **Countable unread:** only complete/error `role=assistant` replies and user-facing `role=peer`
+  DMs after the watermark keyset `(ordinal, message_id)` that have ≥1 **visible part** (file,
+  card, or non-empty text that is not an internal `oc.settle.*` marker). Visibility is
+  **per-part** (same rule as the contact UI): a settle marker beside real body/file/card still
+  counts; blank/whitespace-only rows do **not**. User rows and non-visible roles do **not**
+  count. Token-level SSE deltas never create rows. Each published spoken bubble, card, or peer row is persisted immediately and ≡ one unread unit.
+- **Schema v13 migrate:** existing transcript assistants seed watermark to the current tip so
+  legacy history is default-read (`unreadCount: 0`). Messages written after the seed count as unread.
+- **Monotonic mark-read:** `POST /api/openchamber/assistants/:id/contact/read`
+  body `{ generation, ordinal, messageID }` advances only forward in keyset order; late/stale
+  lower cursors are no-ops (`changed: false`, **no** revision bump / no `assistants-changed`).
+  Generation must match live transcript generation or → `contact_generation_conflict` (409).
+  Incoming cursor clamps to the current transcript tip (cannot invent future ids).
+- **Wipe/reset:** `clear_chat_history` / `POST …/contact/reset` bumps generation and resets the
+  read watermark to empty on the new generation so post-wipe confirm bubbles can surface as unread.
+  Stale-generation mark-read fails closed. Clear-memory does **not** touch generation or read state.
+- **AssistantDTO** (every `output` / snapshot path):
+  - `unreadCount: number`
+  - `readWatermark: { generation, ordinal, messageID }` — persisted shared cursor
+  - `readTip: { generation, ordinal, messageID }` — highest safe reportable tip (transcript head)
+  Clients open a contact, observe messages through `readTip`, then POST that tip.
+- **Snapshot cost:** `getContactUnreadSnapshots` batches watermarks + tips + counts for the
+  catalog (≤100) — no per-assistant HTTP N+1. Each assistant's full `(ordinal, message_id)`
+  read watermark is pushed into SQL (VALUES marks CTE + keyset predicate on
+  `assistant_contact_message_page`); `COUNT` aggregates only post-watermark visible candidates
+  so fully-read history does not scan parts. Uses the same domain revision /
+  `openchamber:assistants-changed` tip after a **changed** mark-read (and after new countable
+  messages via existing admit/persist bumps).
+- Response of mark-read: `{ assistantID, changed, unreadCount, readWatermark, readTip, revision }`.
 ## 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 `session.messages` 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.
 `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.
-`GET /api/openchamber/assistants/capability` returns `supported`, the persisted `enabled` switch, domain revision, and relay-derived stable `serverInstanceID`. 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 `promptAsync`); contact history is `GET /:id/contact/messages` (full transcript, including rows before a clear-memory boundary); contact reset wipe is `POST /:id/contact/reset`; 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/capability` returns `supported`, the persisted `enabled` switch, domain revision, and relay-derived stable `serverInstanceID`. 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 `promptAsync`); 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 `promptAsync` 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.
@@ -145,12 +220,14 @@ Snapshots expose the latest 50 `historySessionIDs` in chronological order and `h
 - `POST /api/openchamber/assistants/:id/messages` returns **202** `{ messageID, admitted: true, binding }` as soon as the **user row** is persisted (`status: complete`). It does **not** wait for the LLM turn. Validation errors still fail synchronously with 4xx before admit.
 - After admit: bump revision + `openchamber:assistants-changed`, register active contact turn (`queued`), broadcast `openchamber:contact-turn-start` `{ assistantID, turnID, messageID, occurredAt }` (`turnID` = client `messageID`), then kick `runContactTurn` asynchronously (serialized per assistant). Lane start marks the turn `running`. Lane start marks the turn `running` and bumps revision. Same `messageID`+payload replays admission once (`replayed: true`) without a second lane run; payload mismatch → `idempotency_conflict`. Failures persist a durable assistant `status: error` bubble for query recovery. Catalog/project list loads use a bounded deadline so the lane cannot hang forever.
-- Contact SSE reuses `/api/openchamber/events` (no new endpoint): `openchamber:contact-bubble-delta` `{ assistantID, turnID, bubbleIndex, delta, done, occurredAt }`. Raw completion tokens are **not** painted live — they are often chain-of-thought and would appear then vanish. A short spoken preamble (e.g. 我去找一下) may appear before a tool and is kept. Planning/CoT is stripped. **Transcript bubbles:** confirm-only tools (`new_conversation` / `clear_chat_history` / `get_assistant_settings` / `update_default_prompt`) may use tool result text as the bubble; card/side-effect tools (`assign_session` / `create_assistant` / `schedule_task` / `message_assistant`) keep spoken only — never stack spoken + English toolText, and never paint card-tool English confirms when a card is enough. Missed-tool turns keep any existing spoken/assistant text; the English `MISSED_TOOL_FAILURE_BUBBLE` is only when there is no text at all. No-tool replies emit each stripped bubble as `{ done:true }` after parse, with a short gap between bubbles so they arrive one beat at a time.
-- Turn end: strip/parse/tools (existing), persist **assistant** bubbles + cards only (never re-insert the user row), clear active contact turn, bump + assistants-changed (error paths bump even without assistant rows), broadcast `openchamber:contact-turn-end` `{ assistantID, turnID, status: 'complete'|'error', error?, occurredAt }`. On failure the admitted user row stays; clients must not spin forever. Completing a contact turn also sends the same completion notification path as a normal contact: SMS-style title (assistant name) + body (spoken bubbles), via desktop / UI SSE / push, gated by `notifyOnCompletion`.
+- Contact SSE reuses `/api/openchamber/events` (no new endpoint): `openchamber:contact-bubble-delta` `{ assistantID, turnID, bubbleIndex, delta, done, occurredAt }`. Raw completion tokens are **not** painted live — they are often chain-of-thought and would appear then vanish. A short spoken preamble (e.g. 我去找一下) may appear before a tool and is kept. Planning/CoT is stripped. When a spoken bubble is `{ done:true }`, persist it immediately as `${userMessageID}:bubble:${index+1}` and bump `assistants-changed` so other clients can GET it before the turn ends. Token deltas (`done:false`) stay SSE-only. **Turn-global bubble indices:** the harness fixes the Agent message boundary at turn start (`prior.length`). Every completion and missed-tool retry derives live `bubbleIndex` from already-streamed turn assistant messages (`projectStreamedContactTurnBubbles`) with the same split rules as final `bubbles[]` (spoken preamble and final text both use `splitContactBubbles`; independent messages keep duplicate text). Indices never restart at 0 after a tool. Published mid-turn bubbles are a stable prefix of the final array on normal turns. **Transcript bubbles:** confirm-only tools (`new_conversation` / `clear_chat_history` / `get_assistant_settings` / `update_default_prompt`) may use tool result text as the bubble; card/side-effect tools (`assign_session` / `watch_session` / `stop_session` / `create_assistant` / `schedule_task` / `message_assistant`) keep spoken only — never stack spoken + English toolText, and never paint card-tool English confirms when a card is enough; `read_session` is model-only lookup — keep spoken preamble plus the post-read reply, never the quoted transcript JSON. Missed-tool turns keep any existing spoken/assistant text; the English `MISSED_TOOL_FAILURE_BUBBLE` is only when there is no text at all. No-tool replies emit each stripped bubble as `{ done:true }` after parse, with a short gap between bubbles so they arrive one beat at a time. Tool cards persist on `onCard` (same `${userMessageID}:card:${index+1}` ids) so a session cover is in the transcript while the worker still runs.
+- Turn end: strip/parse/tools (existing), persist any **remaining** assistant bubbles + cards (skip ids already published mid-turn; never re-insert the user row), clear active contact turn, bump + assistants-changed (error paths bump even without assistant rows), broadcast `openchamber:contact-turn-end` `{ assistantID, turnID, status: 'complete'|'error', error?, occurredAt }`. On failure the admitted user row stays; clients must not spin forever. Completing a contact turn also sends the same completion notification path as a normal contact: SMS-style title (assistant name) + body (spoken bubbles), via desktop / UI SSE / push, gated by `notifyOnCompletion`.
+- **Successful `new_conversation` / `clear_chat_history`:** mid-turn spoken/card publishes for that turn are discarded. `persistContactAssistantReply({ reset:true })` deletes this turn's `role=assistant` rows by `assistantID+turnID` (parts first; same delete pattern as contact-store, **not** `deleteContactMessages`) inside the existing write transaction, then inserts the single confirm bubble and bumps revision. Clearing user, queued users, peers, older turns, watches, generation, context boundary, and read watermark stay. Late bubble/card publish after reset success is ignored; `spokenByIndex` and `assignedCards` clear. Failure keeps prior error semantics.
+- **`stop_session` abort race:** before `session.abort`, the service registers a private per-`sessionID` inflight map (shared promise + observed terminal). Concurrent stop calls on the same worker share that promise. While inflight, `reportAssignedSession` only stashes terminals (`cancelled` > `error` > `complete`) and delays watch writes / continuations. Abort success (including silent no-SSE): release map, `cancelAssignedResumes({ sessionID })`, then `reportAssignedSession(cancelled, resume=false)`. Abort throw / 404 / error / `data:false` / signal failure: release map, replay one observed terminal through the normal reporter when present (else watch unchanged), return the real tool failure. `close()` clears the map; late events stay cancelled-idempotent.
 - In-process tests use `whenContactTurnSettled(messageID)` (not part of the HTTP JSON body).
 - Completions: public `POST /llm/chat/completions` still rejects `stream:true`. In-process contact harness passes `onTextDelta` + `globalEventHub` through `boundCompletion` → `createChatCompletion` → throwaway generate for real tokens only.
-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 at turn end. File parts survive `GET /:id/contact/messages`. The harness forwards those file parts to the completions gateway. Image data URLs reach `promptAsync` 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 `promptAsync` 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.
+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 `promptAsync` 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 `promptAsync` 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 `session.messages` 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.
@@ -158,6 +235,27 @@ Queue admission accepts `{ kind: 'assistant', assistantID }`, captures a structu
 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.
-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. 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.
+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.
 Assistant workspaces resolve only under the Assistant workspace root or configured project roots. DTO serialization resolves and creates the managed target through the same containment checks, so project-configured Assistants expose a ready canonical destination for a future managed switch. Managed workspace creation resolves and creates `dataDir/assistant-workspaces/<assistantID>` before a session switch creates its OpenCode session and commits the configuration CAS. Route registration refreshes the authoritative project roots for each request. Each OpenCode session, prompt, message lookup, and skill discovery uses the effective workspace directory, so OpenCode applies its standard workspace skill discovery and configuration. Contact turns additionally merge `~/.claude/skills`, `~/.agents/skills`, and the workspace `.claude/skills` plus `.agents/skills` into the pi system prompt (project wins on name) and append `defaultPrompt`. `skill_roots` is a legacy schema field; migration removes it from `assistant_v2`, and runtime DTOs, input payloads, and writes omit it. `close()` clears the share-retention scheduler and closes SQLite.
+### Session operations from a contact
+Contact tools expose `assign_session` (new or continued session), `steer_session` (insert a user instruction using SDK `promptAsync` 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 context and background notification boundary
+- The model history is bounded to 32 recent turns, 48,000 estimated characters and 100 transcript rows (newest turn remains intact). It is not unlimited memory or a durable summary. Clear-memory still applies its persisted ordinal boundary. User instructions and assistant replies retain chronological ordering; card-only rows now contribute structured card context with exact session ID, directory and current status, instead of disappearing from the next model request. Peer inbox and failed rows remain excluded.
+- Assigned-session settlement is a read-only result notification. The harness filters its tools to project/session/settings lookups and does not create a coding runtime. It cannot restart, assign, steer, archive, delete or write files even if the model attempts to do so. The latest user constraints remain in history.
+- A new admitted user turn cancels running background notifications and durably disables notifications from existing watches (`resume_allowed`). Live card status continues updating truthfully. Explicit assign/watch admission rearms only that watch. This prevents a delayed completion after a stop/new instruction from restarting an obsolete background turn, including after server restart.
+- Contact turns own AbortControllers. The existing session-abort route validates the current binding/generation, cancels active/queued contact turns and background notifications even without a legacy OpenCode binding, propagates the signal into the harness, and discards late generated output. With no active contact work it retains the legacy binding abort behavior. Already committed side effects are not rolled back.
+Assign/watch tools forward the contact AbortSignal into their service calls and discard late cards after cancellation. Assign checks cancellation before creation and again before prompt submission. A session whose create completes after cancellation remains available but receives no prompt; cancellation never implicitly deletes it. Once prompt admission has begun, the existing ambiguous-admission identity and lookup rules remain authoritative.
+### Referenced conversation content
+`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 `session.messages` 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.
+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.