Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts:
#	apps/cli/src/web.ts
#	apps/web/tests/smoke-fixture.e2e.ts
#	docs/architecture.i18n.yaml
#	packages/client/connection/src/client/fixture.ts
#	packages/client/runtime/src/client/sessions/conversation.ts
#	packages/client/runtime/src/client/sessions/session.ts
#	packages/client/ui-conversation/package.json
#	packages/client/ui-conversation/src/client/contract/slots.ts
#	packages/client/ui-conversation/src/client/index.ts
#	packages/client/ui-conversation/src/client/service.ts
#	packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx
#	packages/client/ui-conversation/tests/apply-inject.spec.tsx
#	packages/client/ui-conversation/tests/service-orchestration.spec.ts
#	packages/host/runtime/src/api-proxy.ts
#	packages/host/runtime/src/boot.ts
#	packages/host/webserver/tests/webserver.spec.ts
#	pnpm-lock.yaml

packages/host/apiproxy/README.md

@@ -8,6 +8,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ
 
 The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
 
+The mux stream projects the latest log-backed title as a validated `session/title` control frame after each attached-session subscription baseline and immediately after the corresponding live raw title event. This projection does not add titles to `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs.
+
 ## Carrier layer (`/client` + root)
 
 `AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.

packages/host/apiproxy/src/api/events.schema.ts

@@ -17,6 +17,7 @@ export const askUserQuestionItemSchema = z.object({
   id: z.string(),
   question: z.string(),
   header: z.string().optional(),
+  detail: z.string().optional(),
   options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
   multiSelect: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<AskUserQuestionItem>>
@@ -25,9 +26,13 @@ export const askUserQuestionItemSchema = z.object({
 export const muxFrameSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
   z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
+  z.object({ type: z.literal('session/title'), sessionId: sessionIdSchema, title: z.string().min(1), eventSeq: z.number().int().nonnegative(), updatedAt: z.number() }),
   z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
   z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
-  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema) }),
+  // Non-empty by wire contract: the user-interaction service rejects empty
+  // batches at ask() (EMPTY_QUESTIONS), so an empty frame is host breakage
+  // and must fail loud here, not reach the composer.
+  z.object({ type: z.literal('question/requested'), sessionId: sessionIdSchema, questions: z.array(askUserQuestionItemSchema).min(1) }),
   z.object({ type: z.literal('question/resolved'), sessionId: sessionIdSchema, questionRpcId: rpcIdSchema, outcome: z.union([z.literal('answered'), z.literal('cancelled')]) }),
   z.object({ type: z.literal('stream/error'), error: rpcErrorSchema }),
 ]) as unknown as z.ZodType<MuxFrame>

packages/host/apiproxy/src/api/events.ts

@@ -33,8 +33,9 @@ export type ToolEventView =
 export interface EventsApi {
   /**
    * All-session aggregated mux stream. On open, emits a subscribed control frame for every
-   * attached session and replays each session's still-pending approval/question requested
-   * frames (rpcId reused verbatim — the refresh-recovery baseline).
+   * attached session followed by its optional latest title snapshot, then replays each
+   * session's still-pending approval/question requested frames (rpcId reused verbatim — the
+   * refresh-recovery baseline).
    * since: resume seam, unimplemented in v1 (ignored if passed); reconnection = reopen the
    * stream + refetch history.
    */
@@ -54,6 +55,7 @@ export interface EventsApi {
 export type MuxFrame =
   | { type: 'session/event'; sessionId: SessionId; event: SessionEvent; view?: ToolEventView }
   | { type: 'session/subscribed'; sessionId: SessionId; lastSeq: number }
+  | { type: 'session/title'; sessionId: SessionId; title: string; eventSeq: number; updatedAt: number }
   | { type: 'approval/requested'; sessionId: SessionId; approvalId: ApprovalRequestId; toolName: string; callId?: CallId; reason?: string }
   | { type: 'approval/resolved'; sessionId: SessionId; approvalId: ApprovalRequestId; outcome: ApprovalOutcome }
   | { type: 'question/requested'; sessionId: SessionId; questions: AskUserQuestionItem[] }

packages/host/apiproxy/src/api/index.ts

@@ -39,7 +39,7 @@ export type {
 } from './rpc.ts'
 
 // ---- Errors and ids ----
-export { RpcId } from './rpc.ts'
+export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
 
 // ---- Method registry and derived generics ----

packages/host/apiproxy/src/api/rpc.schema.ts

@@ -33,6 +33,7 @@ export const rpcIdSchema = z.string() as unknown as z.ZodType<RpcId>
 /** Error body: discriminated by code, per-branch details aligned to RpcErrorDetailsMap; details is required. */
 export const rpcErrorSchema: z.ZodType<RpcError> = z.discriminatedUnion('code', [
   z.object({ code: z.literal('bad-request'), message: z.string(), details: z.object({ issues: z.array(z.custom<ZodIssue>()) }) }),
+  z.object({ code: z.literal('cancelled'), message: z.string(), details: z.object({}) }),
   z.object({ code: z.literal('session-not-found'), message: z.string(), details: z.object({ sessionId: z.string() }) }),
   z.object({ code: z.literal('agent-busy'), message: z.string(), details: z.object({ reason: z.string() }) }),
   z.object({ code: z.literal('attachment-error'), message: z.string(), details: z.object({ reason: z.string() }) }),

packages/host/apiproxy/src/api/rpc.ts

@@ -30,6 +30,7 @@ export function RpcId(id: string): RpcId {
 /** Error code → details type map (a second table isomorphic to RpcMethodMap). New code = one row here + one branch in the error schema. */
 export interface RpcErrorDetailsMap {
   'bad-request': { issues: ZodIssue[] }
+  'cancelled': {}
   'session-not-found': { sessionId: SessionId }
   'agent-busy': { reason: string }
   'attachment-error': { reason: string }
@@ -50,6 +51,20 @@ export type RpcError = {
 /** Business success/failure result: the result slot of a unary response; methods never throw business errors. */
 export type RpcResult<T> = { ok: true; value: T } | { ok: false; error: RpcError }
 
+/**
+ * Fold a transport exception into the RpcResult error branch (unified error
+ * surface; 'internal' as the catch-all code). Lives with RpcResult so every
+ * carrier consumer folds the same way.
+ * @param error - the thrown value from the carrier.
+ * @returns the error branch of an RpcResult.
+ */
+export function transportError<T>(error: unknown): RpcResult<T> {
+  return {
+    ok: false,
+    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },
+  }
+}
+
 /**
  * Signature-layer narrow form, request side (domain-interface view, shared by
  * both directions): rpcId is explicit in the signature, never mixed into the

packages/host/apiproxy/tests/rpc-schemas.spec.ts

@@ -30,6 +30,7 @@ describe('RpcId', () => {
 describe('rpcErrorSchema', () => {
   it('accepts every code branch with its required details', () => {
     expect(rpcErrorSchema.parse({ code: 'bad-request', message: 'm', details: { issues: [] } }).code).toBe('bad-request')
+    expect(rpcErrorSchema.parse({ code: 'cancelled', message: 'm', details: {} }).code).toBe('cancelled')
     expect(rpcErrorSchema.parse({ code: 'session-not-found', message: 'm', details: { sessionId: 's' } }).code).toBe('session-not-found')
     expect(rpcErrorSchema.parse({ code: 'agent-busy', message: 'm', details: { reason: 'r' } }).code).toBe('agent-busy')
     expect(rpcErrorSchema.parse({ code: 'attachment-error', message: 'm', details: { reason: 'r' } }).code).toBe('attachment-error')
@@ -138,6 +139,7 @@ describe('events frame schemas', () => {
     const frames = [
       { type: 'session/event', sessionId: 's', event: { type: 't', seq: 0, time: 1, data: null } },
       { type: 'session/subscribed', sessionId: 's', lastSeq: -1 },
+      { type: 'session/title', sessionId: 's', title: 'Durable title', eventSeq: 2, updatedAt: 3 },
       { type: 'approval/requested', sessionId: 's', approvalId: 'a', toolName: 'bash', callId: 'c', reason: 'r' },
       { type: 'approval/resolved', sessionId: 's', approvalId: 'a', outcome: 'allowed-once' },
       { type: 'question/requested', sessionId: 's', questions: [{ id: 'q', question: 'Q?', options: [{ label: 'L' }], multiSelect: true }] },
@@ -146,9 +148,20 @@ describe('events frame schemas', () => {
     ]
     for (const frame of frames) expect(muxFrameSchema.parse(frame)).toMatchObject({ type: frame.type })
     expect(() => muxFrameSchema.parse({ type: 'unknown/frame' })).toThrow()
+    for (const invalid of [
+      { type: 'session/title', sessionId: 's', title: '', eventSeq: 0, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: -1, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0.5, updatedAt: 1 },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: 'now' },
+      { type: 'session/title', sessionId: 's', title: 'x', eventSeq: 0, updatedAt: Number.NaN },
+    ]) expect(() => muxFrameSchema.parse(invalid)).toThrow()
     expect(askUserQuestionItemSchema.parse({ id: 'q', question: 'Q?' }).id).toBe('q')
   })
 
+  it('rejects an empty question batch (ask() guarantees at least one, so an empty frame is host breakage)', () => {
+    expect(() => muxFrameSchema.parse({ type: 'question/requested', sessionId: 's', questions: [] })).toThrow()
+  })
+
   it('accepts every host frame branch', () => {
     const frames = [
       { type: 'host/session-added', sessionId: 's', parentSessionId: 'p' },

packages/host/runtime/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-host-runtime
 
-Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence, system prompt, tools, agents, agent loop, workspace instructions, local bash), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
+Host runtime assembly for `dsh`: `bootHost` composes the core plugin spine (LLM service + DeepSeek adapter, sessions with JSONL persistence and immediate fallback titles, optional first-message model summaries, system prompt, tools, agents, agent loop, workspace instructions, local bash, and the provider-neutral user-interaction service), `createApiProxy` implements the [`dsh-host-apiproxy`](../apiproxy/README.md) contract over that composition, and `startHost` is the one-step shell seam returning `{ api, handler, defaults, ctx, dispose }`.
 
 Which plugins mount and with what defaults is decided only here — shells must not `ctx.plugin` to alter the assembly. `RunningHost.ctx` is a formal seam with exactly two sanctioned uses: mounting protocol front-door plugins (e.g. a future `dsh acp`) and headless session-event subscription; consuming clients must not bypass `api` through it.
 
@@ -12,21 +12,24 @@ Which plugins mount and with what defaults is decided only here — shells must
 | `workspaceContext` | (required) | [`AGENTS.md`/`CLAUDE.md` loader](../../context/workspace-context/README.md) config with an explicit `maxBytes`, or `false` to disable it. |
 | `provider` | `'deepseek'` | Default provider route injected as agentOptions on create/resume and reported by `host.describe`. |
 | `model` | `'deepseek-v4-flash'` | Default model id, same single source as `provider`. |
+| `cwd` | `process.cwd()` | Default project directory for a session whose create request omits `cwd`. |
+| `sessionTitle` | 5 words / 40 fallback bytes / 80 accepted bytes | Deterministic fallback and accepted-title limits. |
+| `sessionTitleLlm` | disabled | `true` enables the 5-word / 10-CJK-character, 4,096-input-byte, 64-output-token, 60-second first-message policy; an explicit config overrides it. An omitted route inherits the logged main-request provider and model. |
 
 ## ApiProxy implementation notes
 
-Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session on open; the host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
+Unary methods take the narrow `RpcRequest<P>` and echo `request.rpcId`; a prompt's rpcId rides `MessageSource` into the `user/message` event so clients can promote optimistic echoes. `history`/`prompt` on a cold session implicitly resume it, deduplicating concurrent calls through an in-flight table; `history` paginates backwards on message boundaries (never mid-message). The mux stream replays a `session/subscribed` baseline per attached session and every still-pending question with its original rpcId. Question responses, including blank per-item answers, are validated against the owning session and exact request before an atomic first-wins claim; answer, whole-request cancellation, owner abort, and provider disposal broadcast `question/resolved`. The host stream carries session lifecycle, running flips, and `agent/error` as the only outlet for live failures with no turn position.
 
 ## Model Experience
 
-Indirectly, through the model-facing plugins bootHost mounts and the provider/model defaults injected into created and resumed agents. When `workspaceContext` is enabled, each agent-loop instance freezes the applicable workspace instructions into its logged request prefix; the owning package documents the exact [model-visible framing](../../context/workspace-context/README.md#prompt-shape).
+Indirectly, through the non-blocking first-message title request owned by [`dsh-session-title-llm`](../../session-title/session-title-llm/README.md) when `sessionTitleLlm` is enabled, the provider/model defaults injected into created and resumed agents, the other model-facing plugins `bootHost` mounts, and the logged [workspace-instruction prefix](../../context/workspace-context/README.md#prompt-shape) when `workspaceContext` is enabled.
 
 #### KV Cache effect
 
-No direct invalidation; the mounted model-facing plugins own their request-prefix changes.
+No main-request invalidation; when enabled, the auxiliary title request has its own cache behavior and leaves the conversation prefix unchanged.
 
 ## Known Limitations and Deferred Work
 
-- **`respond` is a stub** — it always returns `not-pending`; the approval/question pending registry (stable-rpcId mint on accept, baseline replay on stream reopen, wire answerer) is the next host-side step.
+- **Question waits are process-memory state** — browser reconnects recover them, but a host process restart aborts the owning tool call instead of restoring the wait from persistence.
 - **`host.describe.version` is a placeholder** — it does not yet report the `apps/cli` package version.
 - **The assembly is fixed** — per-deployment plugin selection (user profile, log sinks, alternative persistence) has a documented home here but no configuration surface yet.

packages/host/runtime/package.json

@@ -33,14 +33,6 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-attachment-local": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
-    "@deepseek-ai/dsh-client-connection": "workspace:^",
-    "@deepseek-ai/dsh-client-i18n": "workspace:^",
-    "@deepseek-ai/dsh-client-runtime": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
     "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
@@ -51,6 +43,8 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-skill-local": "workspace:^",
     "@deepseek-ai/dsh-spill-local": "workspace:^",
@@ -71,8 +65,9 @@
     "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tool-workflow": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^"
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^"
   },
   "peerDependencies": {
     "cordis": "^4.0.0-rc.7",

packages/host/runtime/src/api-proxy.ts

@@ -1,8 +1,6 @@
 /**
- * Host-side ApiProxy implementation (minimal-first —
- * describe/list/create/history/prompt/cancel and both streams are real,
- * respond is a stub). Signature discipline: unary takes the narrow
- * RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
+ * Host-side ApiProxy implementation. Signature discipline: unary takes the
+ * narrow RpcRequest<P> and echoes request.rpcId on the RpcResponse<T>.
  */
 
 import { randomUUID } from 'node:crypto'
@@ -14,9 +12,17 @@ import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment-local'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
 import type { JsonValue, Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
-import type { ApiProxy, HistoryEntry, HostFrame, MuxFrame, PromptContentPart, SessionSummary, ToolEventView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+import type {
+  ApiProxy, HistoryEntry, HostFrame, MuxFrame, PromptContentPart, QuestionResponsePayload, SessionSummary, ToolEventView,
+} from '@deepseek-ai/dsh-host-apiproxy/api'
+import { questionResponsePayloadSchema } from '@deepseek-ai/dsh-host-apiproxy/api/questions.schema'
 import type { ClientResponse, RpcError, RpcReceipt, RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type {
+  AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionRequest,
+} from '@deepseek-ai/dsh-user-interaction'
+import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
@@ -29,7 +35,9 @@ function decodeBase64(data: string): Uint8Array {
     throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64')
   }
   const decoded = Buffer.from(data, 'base64')
-  if (decoded.toString('base64') !== data) throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64')
+  if (decoded.toString('base64') !== data) {
+    throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64')
+  }
   return new Uint8Array(decoded)
 }
 
@@ -169,6 +177,28 @@ function frame<F>(payload: F): RpcRequest<F> {
   return { rpcId: RpcId(randomUUID()), payload }
 }
 
+type SessionTitleFrame = Extract<MuxFrame, { type: 'session/title' }>
+
+/** Project the latest durable title without exposing title-generation policy. */
+function titleFrame(session: Session): SessionTitleFrame | undefined {
+  const title = foldSessionTitle(session.events)
+  if (title === undefined) return undefined
+  return {
+    type: 'session/title',
+    sessionId: session.id,
+    title: title.title,
+    eventSeq: title.eventSeq,
+    updatedAt: title.updatedAt,
+  }
+}
+
+/** Queue the subscription baseline followed by its optional title snapshot. */
+function subscribeSession(queue: FrameQueue<RpcRequest<MuxFrame>>, session: Session): void {
+  queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+  const title = titleFrame(session)
+  if (title !== undefined) queue.push(frame(title))
+}
+
 /** SessionSummary projection for attached (in-memory) sessions. */
 function summarize(session: Session, running: boolean): SessionSummary {
   return {
@@ -220,6 +250,35 @@ interface ToolCallData { callId: string; name: string; arguments: string }
 /** The tool/result payload fields the presenter path reads. */
 interface ToolResultData { callId: string; content: ContentBlock[]; isError: boolean; meta?: JsonValue }
 
+/** One host-owned question wait, addressed by the stable server-request id. */
+interface PendingQuestion {
+  rpcId: RpcId
+  sessionId: SessionId
+  questions: AskUserQuestionItem[]
+  resolve: (answer: AskUserQuestionAnswer) => void
+  reject: (error: UserInteractionError) => void
+  signal?: AbortSignal
+  onAbort?: () => void
+}
+
+/** Validate one answer batch against the exact question request it resolves. */
+function matchesQuestions(payload: QuestionResponsePayload, pending: PendingQuestion): boolean {
+  if (payload.sessionId !== pending.sessionId) return false
+  const answers = payload.answer.answers
+  if (answers.length !== pending.questions.length) return false
+  return answers.every((answer, index) => {
+    const question = pending.questions[index] as AskUserQuestionItem
+    if (answer.id !== question.id) return false
+    if (new Set(answer.selected).size !== answer.selected.length) return false
+    const custom = answer.custom?.trim()
+    if (custom !== undefined && custom === '') return false
+    if (custom !== undefined && answer.selected.length > 0) return false
+    if (question.multiSelect !== true && answer.selected.length > 1) return false
+    const labels = new Set(question.options?.map(option => option.label) ?? [])
+    return answer.selected.every(label => labels.has(label))
+  })
+}
+
 /**
  * Compute the render intent for a tool/call or tool/result event through the
  * presenters registered at this moment; every other event type gets none. A
@@ -284,12 +343,70 @@ class SessionNotFound extends Error {}
  * @param ctx - the root context returned by bootHost (sessions/agents services mounted).
  * @param defaults - host-level default provider/model: injected as
  * agentOptions on create/resume, reported by describe from the same source.
- * @returns the ApiProxy implementation (minimal-first; stubs noted per method).
+ * @returns the ApiProxy implementation.
  */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
   const agentOptions = { provider: defaults.provider, model: defaults.model }
   /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
   const resumes = new Map<SessionId, Promise<Agent>>()
+  const pendingQuestions = new Map<RpcId, PendingQuestion>()
+  const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
+
+  /** Send one transient frame to every connected mux consumer. */
+  function broadcast(payload: MuxFrame): void {
+    const envelope = frame(payload)
+    for (const queue of muxQueues) queue.push(envelope)
+  }
+
+  /** Remove a wait before settling it: synchronous deletion makes the first claimant win. */
+  function claimQuestion(pending: PendingQuestion, outcome: 'answered' | 'cancelled'): void {
+    pendingQuestions.delete(pending.rpcId)
+    if (pending.signal !== undefined && pending.onAbort !== undefined) {
+      pending.signal.removeEventListener('abort', pending.onAbort)
+    }
+    broadcast({
+      type: 'question/resolved', sessionId: pending.sessionId,
+      questionRpcId: pending.rpcId, outcome,
+    })
+  }
+
+  const disposeProvider = ctx.userInteraction.registerProvider({
+    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
+      const sessionId = request.agent?.id
+      if (sessionId === undefined) {
+        return Promise.reject(new UserInteractionError(
+          'web user interaction requires an agent-owned session', 'ASK_MISSING_AGENT'))
+      }
+      return new Promise<AskUserQuestionAnswer>((resolve, reject) => {
+        const rpcId = RpcId(randomUUID())
+        const pending: PendingQuestion = {
+          rpcId, sessionId, questions: request.questions, resolve, reject,
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+        }
+        const onAbort = (): void => {
+          claimQuestion(pending, 'cancelled')
+          reject(new UserInteractionError(
+            'ask_user_question was aborted before the user answered', 'ASK_ABORTED'))
+        }
+        pending.onAbort = onAbort
+        pendingQuestions.set(rpcId, pending)
+        request.signal?.addEventListener('abort', onAbort, { once: true })
+        const envelope: RpcRequest<MuxFrame> = {
+          rpcId,
+          payload: { type: 'question/requested', sessionId, questions: request.questions },
+        }
+        for (const queue of muxQueues) queue.push(envelope)
+      })
+    },
+  })
+  ctx.effect(() => () => {
+    disposeProvider()
+    for (const pending of [...pendingQuestions.values()]) {
+      claimQuestion(pending, 'cancelled')
+      pending.reject(new UserInteractionError(
+        'web user-interaction provider was disposed', 'ASK_ABORTED'))
+    }
+  }, 'api-proxy: user-interaction provider')
 
   /**
    * Gate the cold path on the store: an id absent from it, or naming a legacy
@@ -404,7 +521,11 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           else agent.send(durable, { source })
         } catch (error: unknown) {
           if (error instanceof AttachmentError) {
-            return err(request, { code: 'attachment-error', message: error.message, details: { reason: error.code } })
+            return err(request, {
+              code: 'attachment-error',
+              message: error.message,
+              details: { reason: error.code },
+            })
           }
           // A synchronous throw from send/steer means disposed or invalid input; surface as agent-busy with the reason attached.
           return err(request, { code: 'agent-busy', message: 'prompt rejected', details: { reason: String(error) } })
@@ -426,12 +547,23 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
         }
         try {
           const stored = await ctx.attachments.readImage(ref)
-          return ok(request, { attachment: stored.ref, data: Buffer.from(stored.data).toString('base64') })
+          return ok(request, {
+            attachment: stored.ref,
+            data: Buffer.from(stored.data).toString('base64'),
+          })
         } catch (error: unknown) {
           if (error instanceof AttachmentError) {
-            return err(request, { code: 'attachment-error', message: error.message, details: { reason: error.code } })
+            return err(request, {
+              code: 'attachment-error',
+              message: error.message,
+              details: { reason: error.code },
+            })
           }
-          return err(request, { code: 'internal', message: 'Unable to read image attachment.', details: {} })
+          return err(request, {
+            code: 'internal',
+            message: 'Unable to read image attachment.',
+            details: {},
+          })
         }
       },
 
@@ -452,7 +584,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
     host: {
       async describe(request) {
-        const activeModel = (await ctx.llm.listModels(defaults.provider)).find(model => model.id === defaults.model)
+        const activeModel = (await ctx.llm.listModels(defaults.provider))
+          .find(model => model.id === defaults.model)
         // TODO(step2): version should read apps/cli's package.json; placeholder for now.
         return ok(request, {
           version: '0.0.1',
@@ -472,8 +605,18 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     events: {
       mux(_request, signal) {
         const queue = new FrameQueue<RpcRequest<MuxFrame>>()
+        muxQueues.add(queue)
         for (const session of ctx.sessions.list()) {
-          queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+          subscribeSession(queue, session)
+        }
+        for (const pending of pendingQuestions.values()) {
+          queue.push({
+            rpcId: pending.rpcId,
+            payload: {
+              type: 'question/requested', sessionId: pending.sessionId,
+              questions: pending.questions,
+            },
+          })
         }
         // Per-session open-call table for result-view pairing. Bounded by the
         // per-turn call count: entries clear on turn/end; a table miss (stream
@@ -496,15 +639,22 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             const view = viewFor(ctx, event, callId =>
               openCalls.get(session.id)?.get(callId) ?? backscanArgs(session.events, callId))
             queue.push(frame({ type: 'session/event', sessionId: session.id, event, ...view === undefined ? {} : { view } }))
+            if (event.type === 'session/title') {
+              // The accepted raw event is already in session.events, so the fold must find it.
+              queue.push(frame(titleFrame(session) as SessionTitleFrame))
+            }
           }),
           ctx.on('session/created', (session: Session) => {
-            queue.push(frame({ type: 'session/subscribed', sessionId: session.id, lastSeq: session.seq - 1 }))
+            subscribeSession(queue, session)
           }),
           ctx.on('session/disposed', (session: Session) => {
             openCalls.delete(session.id)
           }),
         ]
-        return queue.iterate(signal, () => { for (const dispose of disposers) dispose() })
+        return queue.iterate(signal, () => {
+          muxQueues.delete(queue)
+          for (const dispose of disposers) dispose()
+        })
       },
 
       host(_request, signal) {
@@ -532,9 +682,38 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       },
     },
 
-    // TODO(step2): approval/question pending registry (wire answerer + proxy provider).
-    respond(_message: ClientResponse): Promise<RpcReceipt> {
-      return Promise.resolve({ accepted: false, reason: 'not-pending' })
+    respond(message: ClientResponse): Promise<RpcReceipt> {
+      const pending = pendingQuestions.get(message.rpcId)
+      if (pending === undefined) return Promise.resolve({ accepted: false, reason: 'not-pending' })
+      if (!message.result.ok) {
+        if (message.result.error.code !== 'cancelled') {
+          return Promise.resolve({ accepted: false, reason: 'bad-response' })
+        }
+        claimQuestion(pending, 'cancelled')
+        pending.reject(new UserInteractionError(
+          'the user cancelled ask_user_question', 'ASK_CANCELLED'))
+        return Promise.resolve({ accepted: true })
+      }
+      const parsed = questionResponsePayloadSchema.safeParse(message.result.value)
+      if (!parsed.success) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      const payload: QuestionResponsePayload = {
+        sessionId: parsed.data.sessionId,
+        answer: {
+          answers: parsed.data.answer.answers.map(answer => ({
+            id: answer.id,
+            selected: answer.selected,
+            ...(answer.custom === undefined ? {} : { custom: answer.custom }),
+          })),
+        },
+      }
+      if (!matchesQuestions(payload, pending)) {
+        return Promise.resolve({ accepted: false, reason: 'bad-response' })
+      }
+      claimQuestion(pending, 'answered')
+      pending.resolve(payload.answer)
+      return Promise.resolve({ accepted: true })
     },
   }
 }

packages/host/runtime/src/boot.ts

@@ -9,6 +9,9 @@ import Timer from '@cordisjs/plugin-timer'
 import LlmService from '@deepseek-ai/dsh-llm'
 import LocalAttachmentStore from '@deepseek-ai/dsh-attachment-local'
 import SessionStore from '@deepseek-ai/dsh-session'
+import SessionTitleService, { type Config as SessionTitleConfig } from '@deepseek-ai/dsh-session-title'
+import * as SessionTitleFirstMessageLlm from '@deepseek-ai/dsh-session-title-first-message-llm'
+import type { Config as SessionTitleLlmConfig } from '@deepseek-ai/dsh-session-title-first-message-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
@@ -41,6 +44,23 @@ import * as toolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 import * as timeoutPolicy from '@deepseek-ai/dsh-timeout-policy'
 import SpillLocal from '@deepseek-ai/dsh-spill-local'
 import * as spillPolicy from '@deepseek-ai/dsh-spill-policy'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+
+/** Default deterministic title policy for sessions created through the host. */
+const DEFAULT_SESSION_TITLE_CONFIG: SessionTitleConfig = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+}
+
+/** Default first-message model-title policy for sessions created through the host. */
+const DEFAULT_SESSION_TITLE_LLM_CONFIG: SessionTitleLlmConfig = {
+  targetWords: 5,
+  targetCjkCharacters: 10,
+  maxInputBytes: 4_096,
+  maxOutputTokens: 64,
+  timeoutMs: 60_000,
+}
 
 /** Options for bootHost — the assembly-layer composition knobs. */
 export interface BootHostOptions {
@@ -56,6 +76,10 @@ export interface BootHostOptions {
   model?: string
   /** Additional pi-ai provider routes available to visual-capable Web sessions. */
   piAiProviders?: PiAiProviderProfile[]
+  /** Deterministic fallback-title limits. */
+  sessionTitle?: SessionTitleConfig
+  /** Opt-in first-message model-title policy; `true` selects host defaults and an explicit config overrides them. */
+  sessionTitleLlm?: true | SessionTitleLlmConfig
   /**
    * Default project directory for sessions created without an explicit cwd
    * (defaults to the host process working directory). A session's cwd is its
@@ -102,8 +126,16 @@ export async function bootHost(options: BootHostOptions): Promise<HostHandle> {
     ...options.dshHome === undefined ? {} : { dshHome: options.dshHome },
   })
   await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionTitleService, options.sessionTitle ?? DEFAULT_SESSION_TITLE_CONFIG)
+  if (options.sessionTitleLlm !== undefined) {
+    await ctx.plugin(
+      SessionTitleFirstMessageLlm,
+      options.sessionTitleLlm === true ? DEFAULT_SESSION_TITLE_LLM_CONFIG : options.sessionTitleLlm,
+    )
+  }
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(TaskService)
   await ctx.plugin(AgentLoop, { agents: [] })

packages/host/runtime/src/index.ts

@@ -11,4 +11,4 @@ export { createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'
 export { startHost } from './start.ts'
 export type { StartHostOptions, RunningHost } from './start.ts'
-export { mountWebPlugins, WEB_UI_PLUGINS } from './web-plugins.ts'
+export { mountWebPlugins } from './web-plugins.ts'

packages/host/runtime/src/web-plugins.ts

@@ -1,27 +1,16 @@
 /**
- * Web UI plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
- * entry tree listing the eight UI plugin packages (the P-I config-source bar —
- * a cordis.yml file form comes later; install/remove currently means editing
- * this list and restarting). The web plugin registry discovers the entries by
- * their package.json dshClient declarations; node halves are empty applies,
- * so mounting them here costs nothing beyond Loader governance.
+ * Web client plugin assembly: mounts @cordisjs/plugin-loader with an in-memory
+ * entry tree over the caller-supplied client plugin roster. The roster is a
+ * composition decision and lives in the composing app (apps/cli); this module
+ * only owns the mount/settle/fail-loud mechanics. The web plugin registry
+ * discovers fetch-arrival entries among the mounted packages by their
+ * package.json dshClient declarations; node halves are empty applies, so
+ * mounting them here costs nothing beyond Loader governance.
  */
 import { createRequire } from 'node:module'
 import type { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 
-/** The eight UI plugin packages served to the browser (order = manifest order). */
-export const WEB_UI_PLUGINS = [
-  '@deepseek-ai/dsh-client-connection',
-  '@deepseek-ai/dsh-client-runtime',
-  '@deepseek-ai/dsh-client-ui-theme',
-  '@deepseek-ai/dsh-client-i18n',
-  '@deepseek-ai/dsh-client-ui-layout',
-  '@deepseek-ai/dsh-client-ui-sidebar',
-  '@deepseek-ai/dsh-client-ui-conversation',
-  '@deepseek-ai/dsh-client-ui-trajectory',
-] as const
-
 /** What the shell hands the web plugin registry (loader view + module resolution seam). */
 export interface MountedWebPlugins {
   /** Entry enumeration surface of the mounted Loader (registry scan source). */
@@ -31,31 +20,36 @@ export interface MountedWebPlugins {
 }
 
 /**
- * Mount the Loader (when absent) and create one in-memory entry per UI
- * plugin, then wait for the tree to settle. A plugin whose import fails
- * leaves its entry fiber-less — surfaced here as a loud throw listing the
- * failures (misconfiguration must not silently drop a UI plugin).
+ * Mount the Loader (when absent) and create one in-memory entry per client
+ * plugin package, then wait for the tree to settle. A plugin whose import
+ * fails leaves its entry fiber-less — surfaced here as a loud throw listing
+ * the failures (misconfiguration must not silently drop a client plugin).
  * @param ctx - host root context (bootHost product).
+ * @param plugins - client plugin package names to mount (the composition layer's roster).
+ * @param anchor - module URL anchoring bare-specifier resolution (the composing
+ * app's import.meta.url; the roster packages must be dependencies of that app).
  * @returns the loader view and package.json resolver the registry consumes.
  */
-export async function mountWebPlugins(ctx: Context): Promise<MountedWebPlugins> {
+export async function mountWebPlugins(
+  ctx: Context, plugins: readonly string[], anchor: string,
+): Promise<MountedWebPlugins> {
   // The Loader resolves bare specifiers against ctx.baseUrl; without one the
-  // import silently fails and every entry stays fiber-less. This package
-  // depends on all eight UI plugins, so its own URL is the right anchor.
-  ctx.baseUrl ??= import.meta.url
+  // import silently fails and every entry stays fiber-less. The composing app
+  // declares the roster packages as dependencies, so its URL is the right anchor.
+  ctx.baseUrl ??= anchor
   if (ctx.get('loader') === undefined) await ctx.plugin(Loader)
   const existing = new Set([...ctx.loader.entries()].map(entry => entry.options.name))
-  for (const name of WEB_UI_PLUGINS) {
+  for (const name of plugins) {
     if (!existing.has(name)) await ctx.loader.create({ name })
   }
   await ctx.loader.await()
   const dead = [...ctx.loader.entries()]
-    .filter(entry => (WEB_UI_PLUGINS as readonly string[]).includes(entry.options.name))
+    .filter(entry => plugins.includes(entry.options.name))
     .filter(entry => entry.fiber === undefined && !entry.disabled)
   if (dead.length > 0) {
-    throw new Error(`web-plugins: UI plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
+    throw new Error(`web-plugins: client plugin(s) failed to load: ${dead.map(e => e.options.name).join(', ')}`)
   }
-  const require = createRequire(import.meta.url)
+  const require = createRequire(anchor)
   return {
     loader: ctx.loader,
     resolvePkgJson: name => require.resolve(`${name}/package.json`),

packages/host/runtime/tests/api-proxy-cold.spec.ts

@@ -12,6 +12,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
 import type { RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -32,6 +33,7 @@ describe('sessions.list cold merge', () => {
   it('summarizes unattached sessions: log mtime, locate-less and vanished-log createdAt fallbacks, lineage', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(UserInteractionService)
     const root = mkdtempSync(join(tmpdir(), 'dsh-cold-'))
     const logPath = join(root, 'a.log')
     writeFileSync(logPath, 'log-bytes')
@@ -76,6 +78,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp' })
 
     const listed = await api.sessions.list(request({}))

packages/host/runtime/tests/api-proxy-view.spec.ts

@@ -18,6 +18,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type { MuxFrame, RpcRequest } from '@deepseek-ai/dsh-host-apiproxy/api'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { createApiProxy } from '../src/api-proxy.ts'
@@ -39,6 +40,7 @@ async function harness(): Promise<{ ctx: Context }> {
   await ctx.plugin(SessionStore)
   await ctx.plugin(SystemPrompt, { persona: '' })
   await ctx.plugin(ToolRegistry)
+  await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   ctx.tools.register(tool('gen', {
     presentCall: () => ({ card: 'generic', title: 'gen call' }),

packages/host/runtime/tests/host-runtime.spec.ts

@@ -8,6 +8,8 @@ import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock, GenerateOptions, LlmModelInfo, ModelModality, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { SessionId } from '@deepseek-ai/dsh-session'
+import type { Config as SessionTitleConfig } from '@deepseek-ai/dsh-session-title'
+import type { Config as SessionTitleLlmConfig } from '@deepseek-ai/dsh-session-title-first-message-llm'
 import type { HostFrame, MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
 import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -33,6 +35,10 @@ class ScriptedAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if ((options.tools?.length ?? 0) === 0) {
+      yield * textResponse('Durable append-only session titles')
+      return
+    }
     this.requests.push(options)
     const entry = this.script.shift()
     if (!entry) throw new Error('ScriptedAdapter: script exhausted')
@@ -81,6 +87,21 @@ function expectOk<T>(response: RpcResponse<T>): T {
   return response.result.value
 }
 
+async function nextMux(iterator: AsyncIterator<RpcRequest<MuxFrame>>): Promise<RpcRequest<MuxFrame>> {
+  const next = await iterator.next()
+  if (next.done === true) throw new Error('mux ended before the expected frame')
+  return next.value
+}
+
+/** Durably append a title event without mounting title-generation policy. */
+function appendTitle(ctx: Context, agent: Agent, title: string) {
+  return ctx.sessions.appendOutOfBand(agent.session, 'session/title', {
+    title,
+    messageSeqs: [1],
+    source: { kind: 'fallback' },
+  }, { kind: 'session-title' })
+}
+
 let host: RunningHost | undefined
 
 beforeEach(() => {
@@ -93,13 +114,19 @@ afterEach(async () => {
   vi.unstubAllEnvs()
 })
 
-async function boot(script: (StreamChunk[] | 'hang')[] = []): Promise<RunningHost> {
+async function boot(
+  script: (StreamChunk[] | 'hang')[] = [],
+  sessionTitle?: SessionTitleConfig,
+  sessionTitleLlm?: true | SessionTitleLlmConfig,
+): Promise<RunningHost> {
   host = await startHost({
     boot: {
       persistenceRoot: mkdtempSync(join(tmpdir(), 'dsh-host-runtime-')),
       workspaceContext: false,
       provider: 'scripted',
       model: 'test-model',
+      ...(sessionTitle === undefined ? {} : { sessionTitle }),
+      ...(sessionTitleLlm === undefined ? {} : { sessionTitleLlm }),
     },
   })
   host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter(script))
@@ -203,6 +230,23 @@ describe('bootHost / startHost', () => {
     expect(requestText).toContain('Instructions from: AGENTS.md')
     expect(requestText).toContain('host-workspace-context-probe')
   })
+
+  it('keeps model title generation disabled when sessionTitleLlm is omitted', async () => {
+    const running = await boot([textResponse('pong')])
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    expectOk(await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [{ type: 'text' as const, text: 'Explain durable session titles.' }],
+    })))
+    await idle
+
+    expect((await ctx.sessionTitle.refresh(agent.session))?.source).toEqual({ kind: 'fallback' })
+    expect(agent.session.events.some(event => event.type === 'session/title-llm-request')).toBe(false)
+  })
 })
 
 describe('host.describe', () => {
@@ -245,6 +289,94 @@ describe('sessions.create / list', () => {
 })
 
 describe('sessions.prompt / cancel', () => {
+  it.each([
+    { name: 'host default', config: true, target: '5 words', maxTokens: 64 },
+    {
+      name: 'configured policy',
+      config: {
+        targetWords: 3,
+        targetCjkCharacters: 8,
+        maxInputBytes: 2_048,
+        maxOutputTokens: 24,
+        timeoutMs: 2_000,
+      },
+      target: '3 words',
+      maxTokens: 24,
+    },
+  ] satisfies {
+    name: string
+    config: true | SessionTitleLlmConfig
+    target: string
+    maxTokens: number
+  }[])('replaces the fallback with a model-backed first-message title using the $name', async ({ config, target, maxTokens }) => {
+    const modelTitle = 'Durable append-only session titles'
+    const running = await boot([textResponse('pong')], undefined, config)
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const idle = waitForIdle(ctx, agent)
+    expectOk(await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue' as const,
+      content: [{ type: 'text' as const, text: 'Explain why append-only logs make session titles durable.' }],
+    })))
+    await idle
+
+    await vi.waitFor(() => {
+      expect(agent.session.events.filter(event => event.type === 'session/title').map(event => event.data))
+        .toEqual([
+          {
+            title: 'Explain why append-only logs make',
+            messageSeqs: [1],
+            source: { kind: 'fallback' },
+          },
+          {
+            title: modelTitle,
+            messageSeqs: [1],
+            source: {
+              kind: 'provider',
+              provider: 'session-title-first-message-llm',
+              model: { provider: 'scripted', model: 'test-model' },
+            },
+          },
+        ])
+    })
+    const titleRequest = agent.session.events.find(event => event.type === 'session/title-llm-request')
+    expect(titleRequest?.data.system).toContain(target)
+    expect(titleRequest?.data.maxTokens).toBe(maxTokens)
+  })
+
+  it.each([
+    { name: 'host default', config: undefined, expected: 'Show the Web UI durable' },
+    {
+      name: 'configured limit',
+      config: { fallbackMaxWords: 2, fallbackMaxBytes: 40, maxTitleBytes: 80 },
+      expected: 'Show the',
+    },
+  ] satisfies { name: string; config: SessionTitleConfig | undefined; expected: string }[])(
+    'logs a durable fallback title with the $name',
+    async ({ config, expected }) => {
+      const running = await boot([textResponse('pong')], config)
+      const { api, ctx } = running
+      const { sessionId } = expectOk(await api.sessions.create(request({})))
+      const agent = ctx.agents.get(sessionId) as Agent
+      const idle = waitForIdle(ctx, agent)
+      expectOk(await api.sessions.prompt(request({
+        sessionId,
+        mode: 'queue' as const,
+        content: [{ type: 'text' as const, text: 'Show the Web UI durable session title' }],
+      })))
+      await idle
+
+      const title = agent.session.events.find(event => event.type === 'session/title')
+      expect(title?.data).toEqual({
+        title: expected,
+        messageSeqs: [1],
+        source: { kind: 'fallback' },
+      })
+    },
+  )
+
   it('queues a prompt whose rpcId rides into user/message, then the reply lands', async () => {
     const running = await boot([textResponse('pong')])
     const { api, ctx } = running
@@ -556,6 +688,7 @@ describe('sessions.history', () => {
     const idle = waitForIdle(first.ctx, agent)
     agent.send([{ type: 'text', text: 'save me' }])
     await idle
+    const titleEvent = await appendTitle(first.ctx, agent, 'Persisted title')
     await first.dispose()
 
     host = await startHost({
@@ -563,6 +696,8 @@ describe('sessions.history', () => {
     })
     host.ctx.llm.registerAdapter(['scripted'], new ScriptedAdapter([]))
     expect(host.ctx.agents.get(sessionId)).toBeUndefined()
+    const abort = new AbortController()
+    const mux = host.api.events.mux(request({}), abort.signal)[Symbol.asyncIterator]()
     const [a, b] = await Promise.all([
       host.api.sessions.history(request({ sessionId })),
       host.api.sessions.history(request({ sessionId })),
@@ -573,6 +708,11 @@ describe('sessions.history', () => {
     }
     expect(host.ctx.agents.get(sessionId)).toBeDefined()
     expect(host.ctx.agents.list()).toHaveLength(1)
+    expect((await nextMux(mux)).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    expect((await nextMux(mux)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Persisted title', eventSeq: titleEvent.seq,
+    }))
+    abort.abort()
   })
 
   it('errors session-not-found when resume fails, deduplicating concurrent resumes', async () => {
@@ -680,6 +820,43 @@ describe('events streams', () => {
     expect((await stream.next()).done).toBe(true)
   })
 
+  it('mux: projects durable titles after open baselines and immediately after live raw events', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const initial = await appendTitle(ctx, agent, 'Initial title')
+
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId })
+    expect((await nextMux(stream)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Initial title', eventSeq: initial.seq, updatedAt: initial.time,
+    }))
+
+    const revised = await appendTitle(ctx, agent, 'Revised title')
+    let raw: RpcRequest<MuxFrame>
+    do raw = await nextMux(stream)
+    while (!(raw.payload.type === 'session/event' && raw.payload.event.type === 'session/title'))
+    expect(raw.payload).toMatchObject({ type: 'session/event', sessionId, event: { seq: revised.seq } })
+    expect((await nextMux(stream)).payload).toEqual(expect.objectContaining({
+      type: 'session/title', sessionId, title: 'Revised title', eventSeq: revised.seq, updatedAt: revised.time,
+    }))
+    ac.abort()
+  })
+
+  it('mux: emits no title control for untitled subscriptions', async () => {
+    const { api } = await boot()
+    const first = expectOk(await api.sessions.create(request({}))).sessionId
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId: first })
+
+    const second = expectOk(await api.sessions.create(request({}))).sessionId
+    expect((await nextMux(stream)).payload).toMatchObject({ type: 'session/subscribed', sessionId: second })
+    ac.abort()
+  })
+
   it('host: session lifecycle, status flips (disposed suppressed), and agent errors', async () => {
     const running = await boot([textResponse('x')])
     const { api, ctx } = running
@@ -713,10 +890,175 @@ describe('events streams', () => {
   })
 })
 
-describe('respond stub', () => {
-  it('always reports not-pending (step2 registry pending)', async () => {
-    const { api } = await boot()
-    const receipt = await api.respond({ type: 'client-response', rpcId: RpcId('r'), result: { ok: true, value: null } })
-    expect(receipt).toEqual({ accepted: false, reason: 'not-pending' })
+describe('question request / response', () => {
+  const questions = [{
+    id: 'mode', question: 'Choose a mode',
+    options: [
+      { label: 'Fast (Recommended)', description: 'Move quickly.' },
+      { label: 'Careful', description: 'Review first.' },
+    ],
+  }]
+
+  it('waits, replays the same rpcId on reconnect, validates, and resolves first-wins', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const ac = new AbortController()
+    const stream = api.events.mux(request({}), ac.signal)[Symbol.asyncIterator]()
+    await stream.next() // subscribed baseline starts the generator and installs the queue
+
+    const answerPromise = ctx.userInteraction.ask({ questions, agent })
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(requested.payload).toMatchObject({ type: 'question/requested', sessionId, questions })
+
+    const wrongSession = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId: 'session-other', answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    })
+    expect(wrongSession).toEqual({ accepted: false, reason: 'bad-response' })
+    const badChoice = await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Unknown'] }] } },
+      },
+    })
+    expect(badChoice).toEqual({ accepted: false, reason: 'bad-response' })
+    const invalidResults = [
+      { ok: true as const, value: null },
+      { ok: true as const, value: { sessionId, answer: { answers: [] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'wrong', selected: ['Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Fast (Recommended)'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)', 'Careful'] }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: [], custom: '   ' }] } } },
+      { ok: true as const, value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Careful'], custom: 'Other' }] } } },
+      { ok: false as const, error: { code: 'internal' as const, message: 'wrong error', details: {} } },
+    ]
+    for (const result of invalidResults) {
+      expect(await api.respond({
+        type: 'client-response', rpcId: requested.rpcId, result,
+      })).toEqual({ accepted: false, reason: 'bad-response' })
+    }
+
+    const reconnectAbort = new AbortController()
+    const replay = api.events.mux(request({}), reconnectAbort.signal)[Symbol.asyncIterator]()
+    await replay.next()
+    const replayed = (await replay.next()).value as RpcRequest<MuxFrame>
+    expect(replayed.rpcId).toBe(requested.rpcId)
+    expect(replayed.payload).toEqual(requested.payload)
+
+    const response = {
+      type: 'client-response' as const,
+      rpcId: requested.rpcId,
+      result: {
+        ok: true as const,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }] } },
+      },
+    }
+    const [first, duplicate] = await Promise.all([api.respond(response), api.respond(response)])
+    expect([first, duplicate]).toContainEqual({ accepted: true })
+    expect([first, duplicate]).toContainEqual({ accepted: false, reason: 'not-pending' })
+    await expect(answerPromise).resolves.toEqual({
+      answers: [{ id: 'mode', selected: ['Fast (Recommended)'] }],
+    })
+
+    const resolved = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(resolved.payload).toMatchObject({
+      type: 'question/resolved', sessionId, questionRpcId: requested.rpcId, outcome: 'answered',
+    })
+    expect(await api.respond(response)).toEqual({ accepted: false, reason: 'not-pending' })
+
+    const customQuestions = [{ id: 'detail', question: 'What else?' }]
+    const customAnswer = ctx.userInteraction.ask({ questions: customQuestions, agent })
+    const customRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: customRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(customAnswer).resolves.toEqual({
+      answers: [{ id: 'detail', selected: [], custom: 'Keep traces' }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: customRequested.rpcId, outcome: 'answered',
+    })
+
+    const blankAnswer = ctx.userInteraction.ask({ questions, agent })
+    const blankRequested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: blankRequested.rpcId,
+      result: {
+        ok: true,
+        value: { sessionId, answer: { answers: [{ id: 'mode', selected: [] }] } },
+      },
+    })).toEqual({ accepted: true })
+    await expect(blankAnswer).resolves.toEqual({
+      answers: [{ id: 'mode', selected: [] }],
+    })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: blankRequested.rpcId, outcome: 'answered',
+    })
+    ac.abort()
+    reconnectAbort.abort()
+  })
+
+  it('distinguishes user cancellation from owner abort and rejects late responses', async () => {
+    const running = await boot()
+    const { api, ctx } = running
+    const { sessionId } = expectOk(await api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const streamAbort = new AbortController()
+    const stream = api.events.mux(request({}), streamAbort.signal)[Symbol.asyncIterator]()
+    await stream.next()
+
+    const cancelled = ctx.userInteraction.ask({ questions, agent }).catch((error: unknown) => error)
+    const requested = (await stream.next()).value as RpcRequest<MuxFrame>
+    expect(await api.respond({
+      type: 'client-response', rpcId: requested.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'skip', details: {} } },
+    })).toEqual({ accepted: true })
+    await expect(cancelled).resolves.toMatchObject({ code: 'ASK_CANCELLED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', outcome: 'cancelled',
+    })
+
+    const ownerAbort = new AbortController()
+    const aborted = ctx.userInteraction.ask({ questions, agent, signal: ownerAbort.signal })
+      .catch((error: unknown) => error)
+    const abortRequest = (await stream.next()).value as RpcRequest<MuxFrame>
+    ownerAbort.abort()
+    await expect(aborted).resolves.toMatchObject({ code: 'ASK_ABORTED' })
+    expect(((await stream.next()).value as RpcRequest<MuxFrame>).payload).toMatchObject({
+      type: 'question/resolved', questionRpcId: abortRequest.rpcId, outcome: 'cancelled',
+    })
+    expect(await api.respond({
+      type: 'client-response', rpcId: abortRequest.rpcId,
+      result: { ok: false, error: { code: 'cancelled', message: 'late', details: {} } },
+    })).toEqual({ accepted: false, reason: 'not-pending' })
+    streamAbort.abort()
+  })
+
+  it('rejects missing routing and pre-abort, then aborts outstanding waits on disposal', async () => {
+    const running = await boot()
+    const { ctx } = running
+    await expect(ctx.userInteraction.ask({ questions })).rejects.toMatchObject({ code: 'ASK_MISSING_AGENT' })
+    const { sessionId } = expectOk(await running.api.sessions.create(request({})))
+    const agent = ctx.agents.get(sessionId) as Agent
+    const alreadyAborted = new AbortController()
+    alreadyAborted.abort()
+    await expect(ctx.userInteraction.ask({ questions, agent, signal: alreadyAborted.signal }))
+      .rejects.toMatchObject({ code: 'ASK_ABORTED' })
+
+    const outstanding = ctx.userInteraction.ask({ questions, agent })
+    const disposed = running.dispose()
+    host = undefined
+    await expect(outstanding).rejects.toMatchObject({ code: 'ASK_ABORTED' })
+    await disposed
   })
 })

packages/host/runtime/tests/web-plugins.e2e.ts

@@ -1,71 +0,0 @@
-/**
- * Web UI plugin assembly: the in-memory Loader tree mounts all eight UI
- * packages (node halves), and the webserver registry built over it yields the
- * full __DSH_BOOT__ manifest — the P-I config-source bar end to end.
- *
- * The Loader imports plugin packages through their exports maps (lib/), so
- * this is a built-artifact e2e: it skips until the workspace build has run
- * (`pnpm run build`), like the other built-* e2e suites.
- */
-import { existsSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it } from 'vitest'
-import { createHostWebPluginRegistry } from '@deepseek-ai/dsh-host-webserver'
-import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
-
-const nodeRequire = createRequire(import.meta.url)
-const built = WEB_UI_PLUGINS.every((name) => {
-  try {
-    return existsSync(nodeRequire.resolve(name))
-  } catch {
-    return false
-  }
-})
-
-let root: Context | undefined
-
-afterEach(async () => {
-  await root?.fiber.dispose()
-  root = undefined
-})
-
-describe.skipIf(!built)('mountWebPlugins + registry', () => {
-  it('mounts the eight-package in-memory Loader tree and projects the boot manifest', async () => {
-    root = new Context()
-    const mounted = await mountWebPlugins(root)
-    const registry = createHostWebPluginRegistry({
-      ctx: root,
-      loader: mounted.loader,
-      resolvePkgJson: mounted.resolvePkgJson,
-      onError: (err) => { throw err },
-    })
-    const rows = registry.snapshot()
-    expect(rows.map(r => r.id)).toEqual([...WEB_UI_PLUGINS])
-    // The infra four are the early-load group; the UI four are not.
-    const immediate = rows.filter(r => r.immediately === true).map(r => r.id)
-    expect(immediate).toEqual([
-      '@deepseek-ai/dsh-client-connection',
-      '@deepseek-ai/dsh-client-runtime',
-      '@deepseek-ai/dsh-client-ui-theme',
-      '@deepseek-ai/dsh-client-i18n',
-    ])
-    // Every row resolves a client path under its own package lib/.
-    for (const row of rows) {
-      expect(registry.clientPath(row.id)).toMatch(/lib[/\\]client\.js$/)
-      expect(row.url).toBe(`/plugins/${row.id}/client.js`)
-    }
-    registry.dispose()
-  })
-
-  it('is idempotent: a second mount reuses the loader and creates no duplicate entries', async () => {
-    root = new Context()
-    await mountWebPlugins(root)
-    const second = await mountWebPlugins(root)
-    // ctx.loader hands out a fresh traced proxy per access, so loader identity
-    // is not assertable; the observable contract is a single entry per package.
-    const names = [...second.loader.entries()].map(e => e.options.name)
-      .filter(n => (WEB_UI_PLUGINS as readonly string[]).includes(n))
-    expect(names.length).toBe(WEB_UI_PLUGINS.length)
-  })
-})

packages/host/runtime/tests/web-plugins.spec.ts

@@ -1,13 +1,20 @@
 /**
- * mountWebPlugins unit coverage (keyless; the real eight-package walk is the
- * built-artifact e2e). The Loader-facing behavior — baseUrl anchoring, entry
- * creation with idempotent reuse, the fiber-less fail-loud sweep, and the
- * resolver seam — is exercised against a stubbed loader service so it runs
- * without built lib/ artifacts.
+ * mountWebPlugins unit coverage (keyless). The Loader-facing behavior —
+ * baseUrl anchoring, entry creation with idempotent reuse, the fiber-less
+ * fail-loud sweep, and the resolver seam — is exercised against a stubbed
+ * loader service so it runs without built lib/ artifacts. The roster is
+ * caller-supplied now (composition moved to apps/cli), so these tests pass
+ * their own lists.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it } from 'vitest'
-import { WEB_UI_PLUGINS, mountWebPlugins } from '../src/web-plugins.ts'
+import { mountWebPlugins } from '../src/web-plugins.ts'
+
+const ROSTER = [
+  '@deepseek-ai/dsh-plugin-a',
+  '@deepseek-ai/dsh-plugin-b',
+  '@deepseek-ai/dsh-plugin-c',
+] as const
 
 interface FakeEntry {
   options: { name: string }
@@ -47,60 +54,50 @@ function withLoader(entriesList: FakeEntry[], onCreate?: (name: string) => void)
 }
 
 describe('mountWebPlugins (stubbed loader)', () => {
-  it('creates one entry per UI plugin, awaits the tree, and returns the loader view + resolver', async () => {
+  it('creates one entry per roster package, awaits the tree, and returns the loader view + resolver', async () => {
     const entriesList: FakeEntry[] = []
     const { ctx, loader } = withLoader(entriesList, (name) => {
       entriesList.push({ options: { name }, fiber: {}, disabled: false })
     })
-    const mounted = await mountWebPlugins(ctx)
-    expect(loader.created).toEqual([...WEB_UI_PLUGINS])
+    const mounted = await mountWebPlugins(ctx, ROSTER, import.meta.url)
+    expect(loader.created).toEqual([...ROSTER])
     expect(loader.awaited).toBe(1)
-    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...WEB_UI_PLUGINS])
-    // The resolver resolves this package's own manifest through real module resolution.
+    expect([...mounted.loader.entries()].map(e => e.options.name)).toEqual([...ROSTER])
+    // The resolver resolves a real package manifest through real module resolution, anchored at this test file.
     expect(mounted.resolvePkgJson('@deepseek-ai/dsh-host-runtime')).toMatch(/package\.json$/)
     expect(ctx.baseUrl).toBeDefined()
   })
 
   it('reuses existing entries (idempotent mount creates no duplicates)', async () => {
-    const preexisting: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: {}, disabled: false }))
+    const preexisting: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: {}, disabled: false }))
     const { ctx, loader } = withLoader(preexisting)
-    await mountWebPlugins(ctx)
+    await mountWebPlugins(ctx, ROSTER, import.meta.url)
     expect(loader.created).toEqual([])
   })
 
-  it('throws listing every fiber-less entry (silent import failure must not drop a UI plugin)', async () => {
+  it('throws listing every fiber-less entry (silent import failure must not drop a client plugin)', async () => {
     const entriesList: FakeEntry[] = []
     const { ctx } = withLoader(entriesList, (name) => {
-      // First two load; the rest stay fiber-less (import failed silently).
-      entriesList.push({ options: { name }, fiber: entriesList.length < 2 ? {} : undefined, disabled: false })
+      // First one loads; the rest stay fiber-less (import failed silently).
+      entriesList.push({ options: { name }, fiber: entriesList.length < 1 ? {} : undefined, disabled: false })
     })
-    await expect(mountWebPlugins(ctx)).rejects.toThrow(/UI plugin\(s\) failed to load: .*dsh-client-ui-theme/)
+    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url))
+      .rejects.toThrow(/client plugin\(s\) failed to load: .*dsh-plugin-c/)
   })
 
   it('skips disabled entries in the fail-loud sweep (disabled is the one valid fiber-less state)', async () => {
-    const entriesList: FakeEntry[] = WEB_UI_PLUGINS.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
+    const entriesList: FakeEntry[] = ROSTER.map(name => ({ options: { name }, fiber: undefined, disabled: true }))
     const { ctx } = withLoader(entriesList)
-    await expect(mountWebPlugins(ctx)).resolves.toBeDefined()
+    await expect(mountWebPlugins(ctx, ROSTER, import.meta.url)).resolves.toBeDefined()
   })
 
   it('mounts the real Loader when none is present (the ctx.plugin(Loader) branch)', async () => {
     root = new Context()
-    // Environment-dependent outcome: with built lib/ the eight imports load
-    // and the mount resolves; without them every entry stays fiber-less and
-    // the sweep throws its loud list. Either way the branch under test is the
-    // Loader auto-mount. Manual try/catch keeps cordis-traced proxies out of
-    // expect()'s formatting path (pretty-format probes throw on them).
-    // Plain string: the success sentinel and error text share one channel.
-    let outcome: string
-    try {
-      await mountWebPlugins(root)
-      outcome = 'resolved'
-    } catch (error) {
-      outcome = error instanceof Error ? error.message : String(error)
-    }
-    expect(outcome === 'resolved' || /UI plugin\(s\) failed to load/.test(outcome)).toBe(true)
+    // An empty roster keeps this keyless and artifact-free: the branch under
+    // test is only the Loader auto-mount.
+    await mountWebPlugins(root, [], import.meta.url)
     expect(root.get('loader') !== undefined).toBe(true)
-  }, 30_000) // built-env run imports eight real plugin packages through the Loader
+  }, 30_000) // cold-cache import of the real vendored Loader crosses the network-disk 5s default
 
   it('keeps a caller-set baseUrl (anchors only when absent)', async () => {
     const entriesList: FakeEntry[] = []
@@ -108,7 +105,7 @@ describe('mountWebPlugins (stubbed loader)', () => {
       entriesList.push({ options: { name }, fiber: {}, disabled: false })
     })
     ctx.baseUrl = 'file:///caller/anchor/'
-    await mountWebPlugins(ctx)
+    await mountWebPlugins(ctx, ROSTER, import.meta.url)
     expect(ctx.baseUrl).toBe('file:///caller/anchor/')
   })
 })

packages/host/runtime/tsconfig.json

@@ -29,6 +29,12 @@
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../session-title/session-title"
+    },
+    {
+      "path": "../../session-title/session-title-first-message-llm"
+    },
     {
       "path": "../../core/system-prompt"
     },
@@ -68,9 +74,6 @@
     {
       "path": "../../fs/tool-fs-search"
     },
-    {
-      "path": "../../context/workspace-context"
-    },
     {
       "path": "../../llm/token-meter"
     },
@@ -126,28 +129,10 @@
       "path": "../../../vendor/loader"
     },
     {
-      "path": "../../client/connection"
+      "path": "../../context/workspace-context"
     },
     {
-      "path": "../../client/runtime"
-    },
-    {
-      "path": "../../client/ui-theme"
-    },
-    {
-      "path": "../../client/i18n"
-    },
-    {
-      "path": "../../client/ui-layout"
-    },
-    {
-      "path": "../../client/ui-sidebar"
-    },
-    {
-      "path": "../../client/ui-conversation"
-    },
-    {
-      "path": "../../client/ui-trajectory"
+      "path": "../../ui/user-interaction"
     }
   ]
 }

packages/host/webserver/src/index.ts

@@ -13,12 +13,14 @@ import { readFile } from 'node:fs/promises'
 import type { AddressInfo } from 'node:net'
 import { dirname } from 'node:path'
 import { serveStatic } from './static.ts'
-import type { HostWebPluginRegistry } from './web-plugins.ts'
+import { createPluginEventChannel } from './plugin-events.ts'
+import type { HostWebPluginRegistry, WebBootGraph } from './web-plugins.ts'
 
 export { createHostWebPluginRegistry } from './web-plugins.ts'
 export type {
-  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebPluginBootEntry, WebPluginRegistryDeps,
+  HostWebPluginRegistry, LoaderEntryView, LoaderView, WebBootEntry, WebBootGraph, WebPluginRegistryDeps,
 } from './web-plugins.ts'
+export type { PluginEventChannel, PluginEventFrame } from './plugin-events.ts'
 
 /** Options for startWebServer. */
 export interface WebServerOptions {
@@ -36,11 +38,14 @@ export interface WebServerOptions {
   /** Maximum buffered bytes accepted for one `/api/*` request body. */
   maxRequestBodyBytes: number
   /**
-   * Web plugin table. When present, every index.html response carries a
-   * `window.__DSH_BOOT__` manifest script and `/plugins/<id>/client.js` serves
-   * each plugin's client bundle. Absent = both surfaces off (carrier-only use).
+   * Web plugin table. When present, every index.html response carries the
+   * `window.__DSH_BOOT__` entry graph script, `/plugins/<id>/client.js` serves
+   * each fetch entry's client bundle, and `GET /plugins/events` streams graph/
+   * rebuilt frames (SSE) — rebuilt frames ride the registry's own bundle-watch
+   * notifications (`onRebuilt`). Absent = all three surfaces off (carrier-only
+   * use).
    */
-  webPlugins?: Pick<HostWebPluginRegistry, 'snapshot' | 'clientPath'>
+  webPlugins?: Pick<HostWebPluginRegistry, 'graph' | 'clientPath' | 'onRebuilt'>
 }
 
 /** Listening web server handle. */
@@ -75,8 +80,14 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
   const distRoot = dirname(distIndex)
   const renderIndex = webPlugins === undefined ? undefined : async (): Promise<string> => {
     const html = await readFile(distIndex, 'utf8')
-    return injectBootManifest(html, webPlugins.snapshot())
+    return injectBootManifest(html, webPlugins.graph())
   }
+  const pluginEvents = webPlugins === undefined ? undefined : createPluginEventChannel()
+  // Rebuilt frames come from the registry's own bundle watch (dev mode); a
+  // prod registry without watching simply never notifies.
+  const unsubscribeRebuilt = webPlugins !== undefined && pluginEvents !== undefined
+    ? webPlugins.onRebuilt((id, rev) => { pluginEvents.broadcast({ type: 'rebuilt', id, rev }) })
+    : undefined
 
   const handle = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     /* v8 ignore next -- `?? '/'` arm: node:http always sets url on server
@@ -91,6 +102,10 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
       res.end()
       return
     }
+    if (webPlugins !== undefined && pluginEvents !== undefined && rawPath === '/plugins/events') {
+      pluginEvents.connect(res, webPlugins.graph())
+      return
+    }
     if (webPlugins !== undefined && rawPath.startsWith('/plugins/') && rawPath.endsWith('/client.js')) {
       await servePluginBundle(decodeURIComponent(rawPath), res, webPlugins)
       return
@@ -115,6 +130,7 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 
   let closing: Promise<void> | undefined
   const close = (): Promise<void> => (closing ??= new Promise((resolveClose) => {
+    unsubscribeRebuilt?.()
     server.close(() => { resolveClose() })
     server.closeAllConnections()
   }))
@@ -130,15 +146,15 @@ export function startWebServer(options: WebServerOptions, onError: (err: Error)
 }
 
 /**
- * Inject the boot manifest into index.html: `window.__DSH_BOOT__` as the first
- * script in <head> (before the shell bundle reads it). `<` is escaped in the
- * JSON so plugin-controlled strings cannot break out of the script element.
+ * Inject the boot entry graph into index.html: `window.__DSH_BOOT__` as the
+ * first script in <head> (before the shell bundle reads it). `<` is escaped in
+ * the JSON so plugin-controlled strings cannot break out of the script element.
  * @param html - the index.html source.
- * @param plugins - the manifest rows from the registry snapshot.
- * @returns the html with the manifest script injected.
+ * @param graph - the composed entry graph from the registry.
+ * @returns the html with the graph script injected.
  */
-export function injectBootManifest(html: string, plugins: readonly unknown[]): string {
-  const json = JSON.stringify({ plugins }).replaceAll('<', '\\u003c')
+export function injectBootManifest(html: string, graph: WebBootGraph): string {
+  const json = JSON.stringify(graph).replaceAll('<', '\\u003c')
   const script = `<script>window.__DSH_BOOT__ = ${json}</script>`
   const head = html.indexOf('<head>')
   if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`
@@ -146,7 +162,12 @@ export function injectBootManifest(html: string, plugins: readonly unknown[]): s
   return `${script}${html}`
 }
 
-/** Serve one plugin client bundle from the registry table (unknown id = 404; the id may contain a scope slash). */
+/**
+ * Serve one plugin client bundle from the registry table (unknown id = 404;
+ * the id may contain a scope slash). The `?rev=` query is a cache-busting
+ * parameter only — serving ignores it; `no-cache` makes the browser revalidate
+ * so a stale rev never sticks.
+ */
 async function servePluginBundle(
   pathname: string, res: ServerResponse, webPlugins: Pick<HostWebPluginRegistry, 'clientPath'>,
 ): Promise<void> {
@@ -159,7 +180,7 @@ async function servePluginBundle(
   }
   try {
     const body = await readFile(path)
-    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8' })
+    res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' })
     res.end(body)
   } catch {
     // Registered but unreadable (bundle not built yet): loud 404 beats a silent SPA-fallback HTML page.

packages/host/webserver/src/invariant.ts

@@ -15,25 +15,27 @@ export const name = 'host-webserver-invariant'
 export const inject = ['invariants']
 
 /**
- * Owned relation: the web plugin registry's boot manifest must stay
- * self-consistent — every snapshot() row must resolve a clientPath under the
- * same id (the /plugins/<id>/client.js URL it advertises would otherwise 404
- * on a browser that just received the manifest). Checked synchronously on
- * every rescan trigger (cordis 'internal/plugin'): snapshot() and
- * clientPath() read the same table object, so the relation is
- * self-consistent at any instant — no need to wait out the registry's own
- * debounced rescan. The registry arrives through the context key the
- * assembly publishes it under.
+ * Owned relation: the web plugin registry's boot entry graph must stay
+ * self-consistent — every row must resolve a clientPath under the same id
+ * (the /plugins/<id>/client.js URL it advertises would otherwise 404 on a
+ * browser that just received the graph). Checked synchronously on every
+ * rescan trigger (cordis 'internal/plugin'): graph() and clientPath() read
+ * the same table object, so the relation is self-consistent at any instant —
+ * no need to wait out the registry's own debounced rescan. The registry
+ * arrives through the context key the assembly publishes it under.
  */
 const install: InvariantInstaller = (ctx, fail) => {
   ctx.on('internal/plugin', () => {
     const registry = ctx.get('webPlugins') as
-      | { snapshot(): { id: string; url: string }[]; clientPath(id: string): string | undefined }
+      | {
+        graph(): { entries: { id: string; url: string }[] }
+        clientPath(id: string): string | undefined
+      }
       | undefined
     if (registry === undefined) return // carrier-only deployments never publish the registry
-    for (const row of registry.snapshot()) {
+    for (const row of registry.graph().entries) {
       if (registry.clientPath(row.id) === undefined) {
-        fail(`web plugin manifest row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
+        fail(`web plugin graph row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`)
       }
     }
   }, { global: true })

packages/host/webserver/src/plugin-events.ts

@@ -0,0 +1,56 @@
+/**
+ * `/plugins/events` SSE channel: the system-side push surface for the client
+ * entry graph (connect → current graph frame; dev rebuild → rebuilt frame).
+ * Presentation-only wire — frames never enter the session log (distinct from
+ * the /api/* session SSE, which is api-contract territory). Connections are
+ * plain node:http responses held in a set; the server's closeAllConnections
+ * tears them down on shutdown.
+ */
+
+import type { ServerResponse } from 'node:http'
+import type { WebBootGraph } from './web-plugins.ts'
+
+/** One `/plugins/events` frame: the full graph on connect, or one rebuilt bundle notice. */
+export type PluginEventFrame =
+  | { type: 'graph'; graph: WebBootGraph }
+  | { type: 'rebuilt'; id: string; rev: string }
+
+/** Broadcast surface owned by the webserver routing layer. */
+export interface PluginEventChannel {
+  /** Adopt one incoming SSE request: writes the SSE preamble and the current-graph frame, then keeps the response open. */
+  connect(res: ServerResponse, graph: WebBootGraph): void
+  /** Push one frame to every open connection. */
+  broadcast(frame: PluginEventFrame): void
+}
+
+/** Serialize one frame as an SSE data line. */
+function sseData(frame: PluginEventFrame): string {
+  return `data: ${JSON.stringify(frame)}\n\n`
+}
+
+/**
+ * Create the channel (one per running server).
+ * @returns the connect/broadcast surface.
+ */
+export function createPluginEventChannel(): PluginEventChannel {
+  const connections = new Set<ServerResponse>()
+  return {
+    connect(res, graph) {
+      res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        'connection': 'keep-alive',
+      })
+      // Comment line on open so clients/proxies see a live channel even when
+      // no rebuild ever happens; EventSource frame parsing skips it naturally.
+      res.write(': connected\n\n')
+      res.write(sseData({ type: 'graph', graph }))
+      connections.add(res)
+      res.on('close', () => { connections.delete(res) })
+    },
+    broadcast(frame) {
+      const line = sseData(frame)
+      for (const res of connections) res.write(line)
+    },
+  }
+}

packages/host/webserver/src/web-plugins.ts

@@ -1,10 +1,17 @@
 /**
- * HostWebPluginRegistry: discovers web-client plugins among the host Loader's
- * loaded entries by their package.json `dshClient` declaration and resolves
- * each one's client bundle path from `exports["./client"]`. The webserver
- * consumes the table to emit `window.__DSH_BOOT__` and to serve
- * `GET /plugins/<id>/client.js`. Discovery is declaration-only: plugin authors
- * write package.json; no serve() call surface exists.
+ * HostWebPluginRegistry: composes the client entry graph served as
+ * `window.__DSH_BOOT__` ({rev, entries}). Every row is discovered among the
+ * host Loader's loaded entries by its package.json `dshClient` declaration
+ * (all client plugin packages arrive by fetch — one uniform bundle shape),
+ * resolving each one's client bundle path from `exports["./client"]` and
+ * hashing the bundle content into a `rev` (cache busting + HMR diff anchor).
+ * `inject` edges and the `immediately` prefetch mark come from the manifest
+ * (dshClient — the package owns its dependency edges and its boot tier); the
+ * composition layer contributes only the roster. The webserver consumes the
+ * table to emit the boot graph and to serve `GET /plugins/<id>/client.js`;
+ * in dev mode the registry additionally stat-polls each scanned bundle file
+ * and re-hashes + notifies `onRebuilt` subscribers on change (the rebuild
+ * signal is the registry's own observation — no builder protocol exists).
  *
  * The vendored loader emits no "entry loaded" event (only `loader/entry-init`,
  * which fires at Entry construction before import/apply), so the registry
@@ -14,33 +21,59 @@
  * fresh within a process lifetime.
  */
 
-import { readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFileSync, unwatchFile, watchFile } from 'node:fs'
+import type { Stats } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from 'cordis'
 
-/** One `window.__DSH_BOOT__.plugins` row (wire shape of api-contracts v3 §9.2). */
-export interface WebPluginBootEntry {
-  /** Plugin id = package name (may contain a scope slash). */
+/** One composed client entry (`window.__DSH_BOOT__.entries` row). */
+export interface WebBootEntry {
+  /** Entry name == package name. */
   id: string
-  /** Bundle URL served by this webserver (`/plugins/<id>/client.js`). */
+  /** Bundle URL served by this webserver (`/plugins/<id>/client.js?rev=<rev>`). */
   url: string
-  /** Client-half load dependencies (plugin ids), topologically ordered by the client loader. */
-  inject: string[]
-  /** Marks the early-load group: fetched in parallel and applied before all other plugins. */
+  /** Bundle content hash (sha1, shortened). */
+  rev: string
+  /** Package-name dependency edges from the manifest (dshClient.inject), informational (preflight/HMR display). */
+  inject?: string[]
+  /** Boot phase-one prefetch tier: the shell fetches these bundles in parallel before creating entries. */
   immediately?: boolean
 }
 
-/** The web plugin table consumed by the boot injection and the bundle endpoint. */
+/** The composed entry graph: injected into index.html and pushed on /plugins/events connect. */
+export interface WebBootGraph {
+  /** Consistency anchor over all rows: changes whenever any entry row changes. */
+  rev: string
+  /** All composed entries (order carries no semantics; governance ordering is the client Loader's job). */
+  entries: WebBootEntry[]
+}
+
+/** The web plugin table consumed by the boot injection, the bundle endpoint, and the rebuild channel. */
 export interface HostWebPluginRegistry {
-  /** Current manifest rows (stable order: loader entry order). */
-  snapshot(): WebPluginBootEntry[]
+  /** Current composed entry graph (stable object between changes). */
+  graph(): WebBootGraph
   /**
-   * Absolute path of a plugin's client bundle.
-   * @param id - plugin id (package name).
+   * Absolute path of an entry's client bundle.
+   * @param id - entry id (package name).
    * @returns the path, or undefined for an unknown id.
    */
   clientPath(id: string): string | undefined
-  /** Remove the loader subscription. */
+  /**
+   * Re-hash one entry's bundle: updates the row's rev/url and the graph rev.
+   * The dev bundle watch calls this on every observed file change.
+   * @param id - entry id (package name).
+   * @returns the new bundle rev, or undefined for an unknown id.
+   */
+  rebuilt(id: string): string | undefined
+  /**
+   * Subscribe to bundle rebuilds observed by the dev watch (only fires when
+   * the re-hash produced a different rev — an unchanged bundle is silent).
+   * @param listener - receives the entry id and its new bundle rev.
+   * @returns the unsubscriber.
+   */
+  onRebuilt(listener: (id: string, rev: string) => void): () => void
+  /** Remove the loader subscription, all bundle watches, and all rebuild listeners. */
   dispose(): void
 }
 
@@ -72,17 +105,28 @@ export interface WebPluginRegistryDeps {
   resolvePkgJson: (name: string) => string
   /** Sink for rescan failures (the initial scan throws instead — misconfiguration fails loud at load). */
   onError: (err: Error) => void
+  /**
+   * Dev-mode bundle watching: stat-poll every scanned row's client bundle
+   * (fs.watchFile — polling by design: network mounts deliver no inotify
+   * events) and re-hash + notify onRebuilt subscribers on change. Absent =
+   * no watching (prod composition).
+   */
+  watch?: {
+    /** Stat-poll interval in milliseconds; default 500 (the build-side watcher's polling default). */
+    intervalMs?: number
+  }
 }
 
 /** package.json `dshClient` declaration shape (file boundary — validated field by field). */
 interface DshClientDeclaration {
   inject?: string[]
   platform: string
+  /** Boot phase-one prefetch mark; absent means lazy (fetched on demand). */
   immediately?: boolean
 }
 
 interface WebPluginRecord {
-  entry: WebPluginBootEntry
+  entry: WebBootEntry
   clientPath: string
 }
 
@@ -122,15 +166,102 @@ function clientExportOf(name: string, exportsField: unknown): string | undefined
   throw new Error(`web-plugins: ${name} exports["./client"] has an unsupported shape`)
 }
 
+/** sha1 content hash shortened to 12 hex chars (bundle rev / graph rev). */
+function shortHash(input: string | Buffer): string {
+  return createHash('sha1').update(input).digest('hex').slice(0, 12)
+}
+
+/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+function graphRow(id: string, rev: string, inject: string[] | undefined, immediately: boolean): WebBootEntry {
+  return {
+    id,
+    url: `/plugins/${id}/client.js?rev=${rev}`,
+    rev,
+    ...(inject !== undefined ? { inject } : {}),
+    ...(immediately ? { immediately: true } : {}),
+  }
+}
+
+/** Compose the graph value from the current table. */
+function composeGraph(table: Map<string, WebPluginRecord>): WebBootGraph {
+  const entries = [...table.values()].map(record => record.entry)
+  return { rev: shortHash(JSON.stringify(entries)), entries }
+}
+
 /**
  * Build the web plugin registry: scan once synchronously (a malformed
- * declaration throws here — load-time fail loud), then rescan on
- * `internal/plugin`, microtask-debounced (failures go to `deps.onError`).
- * @param deps - loader view, resolution hook, and error sink (see {@link WebPluginRegistryDeps}).
+ * declaration, an unbuilt bundle, or an invalid watch interval throws here —
+ * load-time fail loud), then rescan on `internal/plugin`, microtask-debounced
+ * (failures go to `deps.onError`). With `deps.watch`, every scanned bundle
+ * file is stat-polled and a content change re-hashes the row and notifies
+ * `onRebuilt` subscribers.
+ * @param deps - loader view, resolution hook, error sink, and optional dev watch (see {@link WebPluginRegistryDeps}).
  * @returns the registry handle.
  */
 export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWebPluginRegistry {
+  const watchInterval = deps.watch === undefined ? undefined : deps.watch.intervalMs ?? 500
+  if (watchInterval !== undefined && (!Number.isInteger(watchInterval) || watchInterval <= 0)) {
+    throw new Error(`web-plugins: watch.intervalMs must be a positive integer (got ${String(deps.watch?.intervalMs)})`)
+  }
+
   let table = scan(deps)
+  let graph = composeGraph(table)
+  const rebuildListeners = new Set<(id: string, rev: string) => void>()
+
+  const rebuilt = (id: string): string | undefined => {
+    const record = table.get(id)
+    if (record === undefined) return undefined
+    const rev = shortHash(readFileSync(record.clientPath))
+    record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true)
+    graph = composeGraph(table)
+    return rev
+  }
+
+  // Dev bundle watch: one fs.watchFile stat poll per table row. A torn read
+  // of a half-written bundle self-heals — the ongoing write keeps changing
+  // the stats, so the next poll tick re-hashes the completed file.
+  const watched = new Map<string, { path: string; listener: (curr: Stats, prev: Stats) => void }>()
+  const syncWatches = (): void => {
+    if (watchInterval === undefined) return
+    for (const [id, watch] of watched) {
+      if (table.get(id)?.clientPath === watch.path) continue
+      unwatchFile(watch.path, watch.listener)
+      watched.delete(id)
+    }
+    for (const [id, record] of table) {
+      if (watched.has(id)) continue
+      const listener = (curr: Stats, prev: Stats): void => {
+        // fs.watchFile fires on any stat delta (atime included); only content
+        // signals count. An all-zero curr means the file vanished mid-rebuild
+        // — the completing write fires the next tick, so skipping is safe.
+        if (curr.mtimeMs === prev.mtimeMs && curr.size === prev.size) return
+        if (curr.mtimeMs === 0) return
+        const before = table.get(id)?.entry.rev
+        let rev: string | undefined
+        try {
+          rev = rebuilt(id)
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code
+          if (code === 'ENOENT') return // mid-rename window; the completed write fires the next poll tick
+          deps.onError(error instanceof Error ? error : new Error(String(error)))
+          return
+        }
+        if (rev === undefined || rev === before) return
+        for (const notify of rebuildListeners) {
+          // A throwing subscriber must not escape the fs.watchFile callback
+          // (that would skip later subscribers and can kill the process).
+          try {
+            notify(id, rev)
+          } catch (error) {
+            deps.onError(error instanceof Error ? error : new Error(String(error)))
+          }
+        }
+      }
+      watchFile(record.clientPath, { interval: watchInterval, persistent: false }, listener)
+      watched.set(id, { path: record.clientPath, listener })
+    }
+  }
+  syncWatches()
 
   let pending = false
   const unsubscribe = deps.ctx.on('internal/plugin', () => {
@@ -140,8 +271,10 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
       pending = false
       try {
         table = scan(deps)
+        graph = composeGraph(table)
+        syncWatches()
       } catch (error) {
-        // Keep serving the previous table: a mid-flight rescan failure must not
+        // Keep serving the previous graph: a mid-flight rescan failure must not
         // take down the boot manifest for plugins that were fine.
         deps.onError(error instanceof Error ? error : new Error(String(error)))
       }
@@ -149,13 +282,23 @@ export function createHostWebPluginRegistry(deps: WebPluginRegistryDeps): HostWe
   })
 
   return {
-    snapshot: () => [...table.values()].map(record => record.entry),
+    graph: () => graph,
     clientPath: id => table.get(id)?.clientPath,
-    dispose: () => { unsubscribe() },
+    rebuilt,
+    onRebuilt: (listener) => {
+      rebuildListeners.add(listener)
+      return () => { rebuildListeners.delete(listener) }
+    },
+    dispose: () => {
+      unsubscribe()
+      for (const { path, listener } of watched.values()) unwatchFile(path, listener)
+      watched.clear()
+      rebuildListeners.clear()
+    },
   }
 }
 
-/** One full table build from the loader's current entries. */
+/** One full table build from the loader's current entries (bundle content is hashed here — an unreadable bundle throws). */
 function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
   const table = new Map<string, WebPluginRecord>()
   for (const entry of deps.loader.entries()) {
@@ -170,15 +313,9 @@ function scan(deps: WebPluginRegistryDeps): Map<string, WebPluginRecord> {
     if (clientRel === undefined) {
       throw new Error(`web-plugins: ${name} declares dshClient but exports no "./client" bundle`)
     }
-    table.set(name, {
-      entry: {
-        id: name,
-        url: `/plugins/${name}/client.js`,
-        inject: decl.inject ?? [],
-        ...(decl.immediately === true ? { immediately: true } : {}),
-      },
-      clientPath: join(dirname(pkgPath), clientRel),
-    })
+    const clientPath = join(dirname(pkgPath), clientRel)
+    const rev = shortHash(readFileSync(clientPath))
+    table.set(name, { entry: graphRow(name, rev, decl.inject, decl.immediately === true), clientPath })
   }
   return table
 }

packages/host/webserver/tests/invariant.spec.ts

@@ -1,7 +1,7 @@
 /**
- * Webserver invariant companion: the boot-manifest consistency audit — every
- * registry snapshot row must resolve a clientPath, checked on fiber lifecycle
- * events against the assembly-published 'webPlugins' context key.
+ * Webserver invariant companion: the boot-graph consistency audit — every
+ * fetch-arrival graph row must resolve a clientPath, checked on fiber
+ * lifecycle events against the assembly-published 'webPlugins' context key.
  */
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -9,7 +9,7 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as WebserverInvariant from '../src/invariant.ts'
 
 interface RegistryStub {
-  snapshot(): { id: string; url: string }[]
+  graph(): { entries: { id: string; url: string }[] }
   clientPath(id: string): string | undefined
 }
 
@@ -33,18 +33,18 @@ describe('webserver manifest invariant', () => {
     expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published
 
     const consistent = await setup({
-      snapshot: () => [{ id: 'p1', url: '/plugins/p1/client.js' }],
-      clientPath: () => '/tmp/p1/lib/client.js',
+      graph: () => ({ entries: [{ id: 'p1', url: '/plugins/p1/client.js?rev=abc' }] }),
+      clientPath: id => id === 'p1' ? '/tmp/p1/lib/client.js' : undefined,
     })
     expect(() => { trigger(consistent) }).not.toThrow()
   })
 
-  it('throws on a manifest row whose bundle path no longer resolves', async () => {
+  it('throws on a graph row whose bundle path no longer resolves', async () => {
     const ctx = await setup({
-      snapshot: () => [{ id: 'ghost', url: '/plugins/ghost/client.js' }],
+      graph: () => ({ entries: [{ id: 'ghost', url: '/plugins/ghost/client.js?rev=abc' }] }),
       clientPath: () => undefined,
     })
     expect(() => { trigger(ctx) })
-      .toThrow(/manifest row "ghost".*resolves no client bundle path/)
+      .toThrow(/graph row "ghost".*resolves no client bundle path/)
   })
 })

packages/host/webserver/tests/web-plugins.spec.ts

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
 import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'
 
@@ -25,6 +25,7 @@ interface Fixture {
   entries: LoaderEntryView[]
   errors: Error[]
   ctx: Context
+  root: string
 }
 
 function makeDeps(
@@ -48,32 +49,30 @@ function makeDeps(
     },
     onError: err => void errors.push(err),
   }
-  return { deps, entries, errors, ctx }
+  return { deps, entries, errors, ctx, root }
 }
 
 describe('createHostWebPluginRegistry', () => {
-  it('collects loaded web-declared plugins with url/inject/immediately and client paths', () => {
+  it('discovers dshClient rows with rev-stamped urls, manifest inject edges, and the declared immediately mark', () => {
     const { deps } = makeDeps([
       { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
       { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
       { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
     ])
     const registry = createHostWebPluginRegistry(deps)
-    const rows = registry.snapshot()
-    expect(rows).toEqual([
-      {
-        id: '@deepseek-ai/dsh-client-connection',
-        url: '/plugins/@deepseek-ai/dsh-client-connection/client.js',
-        inject: [],
-        immediately: true,
-      },
-      {
-        id: '@deepseek-ai/dsh-client-ui-layout',
-        url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js',
-        inject: ['@deepseek-ai/dsh-client-runtime'],
-      },
-    ])
-    expect(registry.clientPath('@deepseek-ai/dsh-client-connection')).toMatch(/lib[/\\]client\.js$/)
+    const graph = registry.graph()
+    expect(graph.rev).toMatch(/^[0-9a-f]{12}$/)
+    const connection = graph.entries[0]
+    expect(connection?.id).toBe('@deepseek-ai/dsh-client-connection')
+    expect(connection?.rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(connection?.url).toBe(`/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=${connection?.rev ?? ''}`)
+    expect(connection?.immediately).toBe(true)
+    const layout = graph.entries[1]
+    expect(layout?.id).toBe('@deepseek-ai/dsh-client-ui-layout')
+    expect(layout?.inject).toEqual(['@deepseek-ai/dsh-client-runtime'])
+    expect(layout?.immediately).toBeUndefined()
+    expect(graph.entries).toHaveLength(2)
+    expect(registry.clientPath('@deepseek-ai/dsh-client-ui-layout')).toMatch(/lib[/\\]client\.js$/)
     expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
     registry.dispose()
   })
@@ -85,7 +84,7 @@ describe('createHostWebPluginRegistry', () => {
       { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
     ])
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])
     registry.dispose()
   })
 
@@ -96,6 +95,11 @@ describe('createHostWebPluginRegistry', () => {
     expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
   })
 
+  it('fails loud at build time on a registered bundle that is not built (rev hashing reads the file)', () => {
+    const { deps } = makeDeps([{ name: 'unbuilt', pkg: webDecl(), withBundle: false }])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/ENOENT/)
+  })
+
   it('fails loud on malformed declaration fields', () => {
     for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
       const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
@@ -103,26 +107,74 @@ describe('createHostWebPluginRegistry', () => {
     }
   })
 
-  it('rescans on internal/plugin (debounced) and keeps the old table when a rescan fails', async () => {
+  it('rebuilt(id) re-hashes the bundle, updates the row and graph rev, and keeps the immediately mark', () => {
+    const { deps, root } = makeDeps([{ name: 'hot', pkg: webDecl({ immediately: true }) }])
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph()
+    const beforeRow = before.entries.find(e => e.id === 'hot')
+    writeFileSync(join(root, 'hot', 'lib', 'client.js'), '// rebuilt bundle contents')
+    const rev = registry.rebuilt('hot')
+    expect(rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(rev).not.toBe(beforeRow?.rev)
+    const after = registry.graph()
+    const afterRow = after.entries.find(e => e.id === 'hot')
+    expect(afterRow?.rev).toBe(rev)
+    expect(afterRow?.url).toBe(`/plugins/hot/client.js?rev=${rev ?? ''}`)
+    expect(afterRow?.immediately).toBe(true)
+    expect(after.rev).not.toBe(before.rev)
+    // Unknown ids are not rebuildable.
+    expect(registry.rebuilt('nope')).toBeUndefined()
+    registry.dispose()
+  })
+
+  it('watch mode: a bundle content change re-hashes the row and notifies onRebuilt; dispose stops the watch', async () => {
+    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
+    deps.watch = { intervalMs: 20 }
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph().entries[0]?.rev
+    const rebuilds: { id: string; rev: string }[] = []
+    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
+
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// new bundle contents')
+    await vi.waitFor(() => { expect(rebuilds).toHaveLength(1) }, { timeout: 5000 })
+    expect(rebuilds[0]?.id).toBe('watched')
+    expect(rebuilds[0]?.rev).not.toBe(before)
+    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
+
+    registry.dispose()
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// post-dispose contents')
+    await new Promise((resolve) => { setTimeout(resolve, 100) })
+    expect(rebuilds).toHaveLength(1)
+  })
+
+  it('rejects a non-positive or non-integer watch interval at build time', () => {
+    for (const intervalMs of [0, -5, 1.5]) {
+      const { deps } = makeDeps([{ name: 'p', pkg: webDecl() }])
+      deps.watch = { intervalMs }
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/watch\.intervalMs/)
+    }
+  })
+
+  it('rescans on internal/plugin (debounced) and keeps the old graph when a rescan fails', async () => {
     const { deps, entries, errors, ctx } = makeDeps([
       { name: 'late-loader', pkg: webDecl(), loaded: false },
     ])
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])
 
     // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
     ;(entries[0] as { fiber?: unknown }).fiber = {}
     ctx.emit('internal/plugin', ctx.fiber)
     ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
     await Promise.resolve()
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
 
-    // A failing rescan reports the error and keeps serving the previous table.
+    // A failing rescan reports the error and keeps serving the previous graph.
     entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
     ctx.emit('internal/plugin', ctx.fiber)
     await Promise.resolve()
     expect(errors).toHaveLength(1)
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])
 
     // After dispose, further fiber events no longer rescan.
     registry.dispose()
@@ -134,16 +186,19 @@ describe('createHostWebPluginRegistry', () => {
 })
 
 describe('injectBootManifest', () => {
-  it('injects the manifest as the first script inside <head> and escapes </script> breakouts', () => {
+  it('injects the graph as the first script inside <head> and escapes </script> breakouts', () => {
     const html = '<html><head><script src="app.js"></script></head><body></body></html>'
-    const out = injectBootManifest(html, [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js', inject: [] }])
+    const out = injectBootManifest(html, {
+      rev: 'r1',
+      entries: [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js?rev=r2', rev: 'r2' }],
+    })
     expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
     expect(out).not.toContain('</script><script>alert(1)')
     expect(out).toContain('\\u003c/script')
   })
 
   it('prepends when the page has no <head>', () => {
-    const out = injectBootManifest('<body>x</body>', [])
+    const out = injectBootManifest('<body>x</body>', { rev: 'r0', entries: [] })
     expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
   })
 })
@@ -181,7 +236,7 @@ describe('clientExportOf shapes (through the registry build)', () => {
     entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
     void first
     const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot().filter(r => r.id === 'dup-entry')).toHaveLength(1)
+    expect(registry.graph().entries.filter(r => r.id === 'dup-entry')).toHaveLength(1)
     registry.dispose()
   })
 

packages/host/webserver/tests/webserver.spec.ts

@@ -1,6 +1,6 @@
 import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
 import { request as httpRequest } from 'node:http'
-import { createServer as createNetServer, Server as NetServer, type AddressInfo } from 'node:net'
+import { Server as NetServer } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -8,18 +8,6 @@ import { startWebServer, type RunningWebServer } from '../src/index.ts'
 
 const MAX_REQUEST_BODY_BYTES = 64 * 1024
 
-/** Reserve a loopback port for tests that need to address a second server. */
-function freePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const probe = createNetServer()
-    probe.once('error', reject)
-    probe.listen(0, '127.0.0.1', () => {
-      const port = (probe.address() as AddressInfo).port
-      probe.close(() => { resolve(port) })
-    })
-  })
-}
-
 /** dist fixture: index.html + one asset of each MIME class + a subdir. */
 function makeDist(): { distIndex: string; distRoot: string } {
   const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
@@ -112,9 +100,12 @@ async function boot(
   maxRequestBodyBytes = MAX_REQUEST_BODY_BYTES,
 ): Promise<string> {
   const { distIndex } = makeDist()
-  const port = await freePort()
   server = await startWebServer({
-    host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes,
+    host: '127.0.0.1',
+    port: 0,
+    distIndex,
+    apiHandler: echoingApi,
+    maxRequestBodyBytes,
   }, onError)
   return `http://127.0.0.1:${String(server.port)}`
 }
@@ -134,7 +125,11 @@ describe('startWebServer', () => {
   it('reports the listening port and closes idempotently', async () => {
     const { distIndex } = makeDist()
     server = await startWebServer({
-      host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port: 0,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
     }, () => undefined)
     expect(server.port).toBeGreaterThan(0)
     const first = server.close()
@@ -158,7 +153,11 @@ describe('startWebServer', () => {
     const address = vi.spyOn(NetServer.prototype, 'address').mockReturnValue({ address: host, family: 'IPv4', port })
     try {
       const inertServer = await startWebServer({
-        host, port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        host,
+        port,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
       }, () => undefined)
       expect(listen).toHaveBeenCalledWith(port, host, expect.any(Function))
       await inertServer.close()
@@ -170,12 +169,20 @@ describe('startWebServer', () => {
 
   it('rejects when the port is already taken', async () => {
     const { distIndex } = makeDist()
-    const port = await freePort()
     server = await startWebServer({
-      host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port: 0,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
     }, () => undefined)
+    const { port } = server
     await expect(startWebServer({
-      host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
     }, () => undefined))
       .rejects.toMatchObject({ code: 'EADDRINUSE' })
   })
@@ -219,35 +226,55 @@ describe.skipIf(process.platform === 'win32')('static serving', () => {
   })
 })
 
-describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint)', () => {
-  const rows = [
-    { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js', inject: [], immediately: true },
-    { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  ]
+describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint + events channel)', () => {
+  const FETCH_ID = '@deepseek-ai/dsh-client-ui-layout'
+  const graphValue = {
+    rev: 'graphrev00001',
+    entries: [
+      { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=eeee2222ffff', rev: 'eeee2222ffff', immediately: true },
+      { id: FETCH_ID, url: `/plugins/${FETCH_ID}/client.js?rev=aaaa0000bbbb`, rev: 'aaaa0000bbbb', inject: [] },
+    ],
+  }
 
-  async function bootWithPlugins(): Promise<string> {
+  /** Captures the server's onRebuilt subscription so tests can fire registry notifications by hand. */
+  interface RebuiltHarness {
+    notify: (id: string, rev: string) => void
+    unsubscribed: boolean
+  }
+
+  async function bootWithPlugins(harness?: RebuiltHarness): Promise<string> {
     const { distIndex, distRoot } = makeDist()
     writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
     const webPlugins = {
-      snapshot: () => rows,
-      clientPath: (id: string) => id === rows[0]?.id ? join(distRoot, 'bundle.js') : undefined,
+      graph: () => graphValue,
+      clientPath: (id: string) => id === FETCH_ID ? join(distRoot, 'bundle.js') : undefined,
+      onRebuilt: (listener: (id: string, rev: string) => void) => {
+        if (harness !== undefined) harness.notify = listener
+        return () => {
+          if (harness !== undefined) harness.unsubscribed = true
+        }
+      },
     }
-    const port = await freePort()
     server = await startWebServer(
       {
-        host: '127.0.0.1', port, distIndex, apiHandler: echoingApi,
-        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES, webPlugins,
-      }, () => undefined,
+        host: '127.0.0.1',
+        port: 0,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        webPlugins,
+      },
+      () => undefined,
     )
     return `http://127.0.0.1:${String(server.port)}`
   }
 
-  it('injects window.__DSH_BOOT__ into / and SPA fallbacks; asset requests stay verbatim', async () => {
+  it('injects the window.__DSH_BOOT__ graph into / and SPA fallbacks; asset requests stay verbatim', async () => {
     const base = await bootWithPlugins()
     const index = await (await fetch(`${base}/`)).text()
     expect(index).toContain('window.__DSH_BOOT__')
     const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
-    expect(JSON.parse(manifest ?? '')).toEqual({ plugins: rows })
+    expect(JSON.parse(manifest ?? '')).toEqual(graphValue)
 
     const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
     expect(fallback).toContain('window.__DSH_BOOT__')
@@ -257,11 +284,12 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
     expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
   })
 
-  it('serves registered client bundles and 404s unknown ids (no SPA fallback)', async () => {
+  it('serves registered client bundles with no-cache (rev query ignored) and 404s unknown ids (no SPA fallback)', async () => {
     const base = await bootWithPlugins()
-    const bundle = await fetch(`${base}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const bundle = await fetch(`${base}/plugins/${FETCH_ID}/client.js?rev=whatever`)
     expect(bundle.status).toBe(200)
     expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(bundle.headers.get('cache-control')).toBe('no-cache')
     expect(await bundle.text()).toContain('DSHClientProxy')
 
     expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
@@ -270,27 +298,67 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
   it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
     const { distIndex } = makeDist()
     const webPlugins = {
-      snapshot: () => rows,
+      graph: () => graphValue,
       clientPath: () => '/nonexistent/lib/client.js',
+      onRebuilt: () => () => undefined,
     }
-    const port = await freePort()
     server = await startWebServer(
       {
-        host: '127.0.0.1', port, distIndex, apiHandler: echoingApi,
-        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES, webPlugins,
-      }, () => undefined,
+        host: '127.0.0.1',
+        port: 0,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        webPlugins,
+      },
+      () => undefined,
     )
-    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/${FETCH_ID}/client.js`)
     expect(res.status).toBe(404)
   })
 
-  it('keeps both surfaces off without the webPlugins option', async () => {
+  it('keeps all plugin surfaces off without the webPlugins option', async () => {
     const base = await boot()
     expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
-    // No plugin route: falls through to static SPA fallback semantics.
+    // No plugin routes: fall through to static SPA fallback semantics.
     const res = await fetch(`${base}/plugins/x/client.js`)
     expect(res.status).toBe(200)
     expect(await res.text()).toBe('<html>INDEX</html>')
+    const events = await fetch(`${base}/plugins/events`)
+    expect(await events.text()).toBe('<html>INDEX</html>')
+  })
+
+  it('GET /plugins/events opens SSE with the current graph frame; a registry rebuild notification broadcasts', async () => {
+    const harness: RebuiltHarness = { notify: () => { throw new Error('onRebuilt never subscribed') }, unsubscribed: false }
+    const base = await bootWithPlugins(harness)
+    const events = await fetch(`${base}/plugins/events`)
+    expect(events.status).toBe(200)
+    expect(events.headers.get('content-type')).toBe('text/event-stream')
+    const reader = events.body?.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    async function readUntil(marker: string): Promise<void> {
+      while (!buffer.includes(marker)) {
+        const chunk = await reader?.read()
+        if (chunk?.done !== false) throw new Error('SSE stream ended early')
+        buffer += decoder.decode(chunk.value, { stream: true })
+      }
+    }
+    await readUntil('"type":"graph"')
+    expect(buffer).toContain(': connected')
+    const graphLine = /data: (.*)\n\n/.exec(buffer)?.[1]
+    expect(JSON.parse(graphLine ?? '')).toEqual({ type: 'graph', graph: graphValue })
+
+    // The registry's bundle watch observed a rebuild: the server relays it as an SSE frame.
+    harness.notify(FETCH_ID, 'cccc1111dddd')
+    await readUntil('"type":"rebuilt"')
+    expect(buffer).toContain(JSON.stringify({ type: 'rebuilt', id: FETCH_ID, rev: 'cccc1111dddd' }))
+    await reader?.cancel()
+
+    // Shutdown unsubscribes the relay (no broadcast into a closed channel).
+    await server?.close()
+    server = undefined
+    expect(harness.unsubscribed).toBe(true)
   })
 })