dsh-plugin-mobile-gateway 0.7.1 → 0.7.3

package/lib/index.mjs

@@ -45,6 +45,12 @@
 //                     { "type": "directory-create", "path", "name" } -> create one child directory
 //                     { "type": "workspace-create", "path" }       -> create workspace over a dir
 //                     { "type": "fork", "sessionId", "atSeq"? }    -> branch a new session from a completed turn
+//                     { "type": "session-cancel", "sessionId" }     -> stop the active turn and retain queued work
+//                     { "type": "queue-update", "sessionId", "itemId",
+//                       "action": "edit"|"remove"|"steer", "text"? }
+//                        -> edit/remove one pending item or move it into the current turn
+//                     { "type": "session-archive", "sessionId" }    -> hide a session from workspace surfaces
+//                     { "type": "session-rename", "sessionId", "title" } -> persist a user-owned session title
 //                     { "type": "models", "sessionId"? }           -> per-session catalog (with sessionId) or global (without)
 //                     { "type": "providers" }                       -> configurable provider list (live/dormant)
 //                     { "type": "commands", "sessionId" }          -> slash-command catalog for this session
@@ -68,7 +74,7 @@
 //                     { "type": "question-cancel", "rpcId", "sessionId" }
 //                     { "type": "approval-response", "rpcId", "sessionId", "approvalId",
 //                       "outcome": "allowed-once"|"rejected" }
-//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "file-downloads"],
+//   server -> client: { "kind": "hello", "protocol": 3, "capabilities": ["images", "commands", "tasks", "goals", "session-cancel", "queue-control", "session-archive", "session-rename", "file-downloads"],
 //                       "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
@@ -88,6 +94,14 @@
 //                       "path", "name", "mediaType", "size", "chunkBytes" }
 //                     { "kind": "file-download-chunk", "transferId", "offset", "data", "eof", "sha256"? }
 //                     { "kind": "file-download-cancelled", "transferId" }
+//                     { "kind": "session-cancelled", "sessionId", "accepted": true }
+//                     { "kind": "queue-item-updated", "sessionId", "itemId", "action", "accepted": true }
+//                     { "kind": "session-queues", "queues": { "<sessionId>": [...] } }
+//                     { "kind": "session-queue", "sessionId", "items": [...] }
+//                     { "kind": "session-archived", "sessionId", "archivedSessionIds" }
+//                     { "kind": "session-renamed", "sessionId", "title", "seq" }
+//                     { "kind": "session-archives", "archivedSessionIds" }
+//                     { "kind": "session-title-changed", "sessionId", "title", "seq", "time", "source"? }
 //                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
 //                     { "kind": "tasks", "sessionId", "asOfSeq", "todos" }
@@ -115,6 +129,7 @@ import Schema from '@deepseek-ai/schemastery'
 import { WebSocketServer } from 'ws'
 import devicesModule from './devices.js'
 import { createDshHostAdapter } from './dsh-host-adapter.mjs'
+import { createGatewayState, GATEWAY_MODES } from './gateway-state.mjs'
 import QRCode from 'qrcode'
 
 const { createRegistry } = devicesModule
@@ -187,6 +202,10 @@ const Config = Schema.object({
   path: Schema.string().default(DEFAULT_WS_PATH),
   requireAuth: Schema.boolean().default(true),
   gatewayEnabled: Schema.boolean().default(false),
+  gatewayMode: Schema.union(GATEWAY_MODES),
+  gatewayStateFile: Schema.string().default(''),
+  gatewayName: Schema.string().default(''),
+  endpoints: Schema.array(Schema.string()).default([]),
   gatewayWaitTimeoutMs: Schema.natural().min(30_000).max(30 * 60 * 1000).default(DEFAULT_GATEWAY_WAIT_TIMEOUT_MS),
   maxPayloadBytes: Schema.natural().min(1024 * 1024).max(160 * 1024 * 1024).default(DEFAULT_MAX_WS_PAYLOAD_BYTES),
   fileDownloadsEnabled: Schema.boolean().default(true),
@@ -284,6 +303,14 @@ function buildWireEvent(session, event) {
         event: { type: 'assistant/message', turn: d.turn, step: d.step, text, reasoning, toolCalls, ...(images.length ? { images } : {}) },
       })
     }
+    case 'session/title':
+      return Object.assign(base, {
+        event: {
+          type: 'session/title',
+          title: d.title,
+          ...(d.source ? { source: d.source } : {}),
+        },
+      })
     case 'tool/call':
       return Object.assign(base, {
         event: { type: 'tool/call', turn: d.turn, step: d.step, callId: d.callId, name: d.name, arguments: d.arguments },
@@ -1228,6 +1255,19 @@ async function selectCommandOption(api, host, command, sessionId, optionId) {
 
 // Dispatch one mobile query frame; returns the wire frame to send back.
 async function handleQuery(api, host, agentDefaultModel, msg) {
+  if (msg.type === 'session-create') {
+    if (typeof msg.requestId !== 'string' || !msg.requestId.trim()) {
+      return { kind: 'error', code: 'bad-request', message: 'session-create requires a requestId', requestType: 'session-create' }
+    }
+    const payload = {}
+    if (typeof msg.workspaceId === 'string' && msg.workspaceId.trim()) {
+      payload.workspaceId = msg.workspaceId.trim()
+    } else if (typeof msg.cwd === 'string' && msg.cwd.trim()) {
+      payload.cwd = msg.cwd.trim()
+    }
+    const frame = await proxyQuery(api, 'session-created', api.sessions.create.bind(api.sessions), payload)
+    return { ...frame, ...(frame.kind === 'error' ? { requestType: 'session-create' } : {}), requestId: msg.requestId }
+  }
   if (msg.type === 'workspaces') {
     return proxyQuery(api, 'workspaces', api.workspace.list.bind(api.workspace), {})
   }
@@ -1331,6 +1371,96 @@ async function handleQuery(api, host, agentDefaultModel, msg) {
     }
     return frame
   }
+  if (msg.type === 'session-cancel') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const frame = await proxyQuery(
+      api,
+      'session-cancel',
+      api.sessions.cancel.bind(api.sessions),
+      { sessionId: sessionId.value },
+    )
+    if (frame.kind === 'error') return { ...frame, sessionId: sessionId.value }
+    return { ...frame, kind: 'session-cancelled', sessionId: sessionId.value }
+  }
+  if (msg.type === 'queue-update') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const itemId = typeof msg.itemId === 'string' && msg.itemId.trim() ? msg.itemId.trim() : null
+    const actionKind = typeof msg.action === 'string' ? msg.action.trim() : ''
+    if (!itemId || !['edit', 'remove', 'steer'].includes(actionKind)) {
+      return {
+        kind: 'error',
+        code: 'bad-request',
+        message: 'queue-update requires itemId and action edit, remove, or steer',
+        requestType: 'queue-update',
+        sessionId: sessionId.value,
+      }
+    }
+    let action
+    if (actionKind === 'edit') {
+      if (typeof msg.text !== 'string' || !msg.text.trim()) {
+        return {
+          kind: 'error',
+          code: 'bad-request',
+          message: 'queue-update edit requires non-empty text',
+          requestType: 'queue-update',
+          sessionId: sessionId.value,
+          itemId,
+        }
+      }
+      action = { kind: 'edit', content: [{ type: 'text', text: msg.text }] }
+    } else {
+      action = { kind: actionKind }
+    }
+    const frame = await proxyQuery(
+      api,
+      'queue-update',
+      api.sessions.updateQueue.bind(api.sessions),
+      { sessionId: sessionId.value, itemId, action },
+    )
+    if (frame.kind === 'error') return { ...frame, sessionId: sessionId.value, itemId }
+    return {
+      ...frame,
+      kind: 'queue-item-updated',
+      sessionId: sessionId.value,
+      itemId,
+      action: actionKind,
+    }
+  }
+  if (msg.type === 'session-archive') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    const frame = await proxyQuery(
+      api,
+      'session-archive',
+      api.workspace.archiveSession.bind(api.workspace),
+      { sessionId: sessionId.value },
+    )
+    if (frame.kind === 'error') return { ...frame, sessionId: sessionId.value }
+    return { ...frame, kind: 'session-archived', sessionId: sessionId.value }
+  }
+  if (msg.type === 'session-rename') {
+    const sessionId = requireSessionId(msg)
+    if (sessionId.error) return sessionId.error
+    if (typeof msg.title !== 'string' || !msg.title.trim()) {
+      return {
+        kind: 'error',
+        code: 'bad-request',
+        message: 'session-rename requires a non-empty title',
+        requestType: 'session-rename',
+        sessionId: sessionId.value,
+      }
+    }
+    const frame = await proxyQuery(
+      api,
+      'session-rename',
+      api.sessions.rename.bind(api.sessions),
+      { sessionId: sessionId.value, title: msg.title },
+    )
+    if (frame.kind === 'error') return { ...frame, sessionId: sessionId.value }
+    return { ...frame, kind: 'session-renamed', sessionId: sessionId.value }
+  }
   if (msg.type === 'workspace-create') {
     const wsPath = typeof msg.path === 'string' && msg.path.trim() !== '' ? msg.path.trim() : null
     if (!wsPath) {
@@ -1720,11 +1850,13 @@ function normalizePublicUrl(value, req, wsPath) {
     const host = req.headers.host || `127.0.0.1`
     raw = `${req.socket && req.socket.encrypted ? 'wss' : 'ws'}://${host}${wsPath}`
   }
-  const url = new URL(raw)
+  let url
+  try { url = new URL(raw) } catch { throw badRequest('invalid WebSocket endpoint URL') }
   if (url.protocol === 'https:') url.protocol = 'wss:'
   if (url.protocol === 'http:') url.protocol = 'ws:'
   if (url.protocol !== 'ws:' && url.protocol !== 'wss:') throw badRequest('publicUrl must use wss:// (ws:// is allowed only for localhost and private LAN addresses)')
   if (url.username || url.password || url.search || url.hash) throw badRequest('publicUrl must not contain credentials, query parameters, or a fragment')
+  if (['0.0.0.0', '[::]', '::'].includes(url.hostname)) throw badRequest('endpoint must not use an unspecified listen address')
   if (url.protocol === 'ws:' && !isPrivateNetworkHostname(url.hostname)) throw badRequest('publicUrl must use wss:// outside localhost or a private LAN')
   return url.toString()
 }
@@ -1757,8 +1889,12 @@ function readBody(req) {
         reject(error)
         return
       }
-      try { resolve(data === '' ? {} : JSON.parse(data)) } catch (cause) {
-        const error = new Error('request body must be valid JSON', { cause })
+      try {
+        const body = data === '' ? {} : JSON.parse(data)
+        if (!body || typeof body !== 'object' || Array.isArray(body)) throw new TypeError('expected an object')
+        resolve(body)
+      } catch (cause) {
+        const error = new Error('request body must be a JSON object', { cause })
         error.status = 400
         reject(error)
       }
@@ -1849,6 +1985,9 @@ const plugin = {
       path: DEFAULT_WS_PATH,
       requireAuth: true,
       gatewayEnabled: false,
+      gatewayStateFile: '',
+      gatewayName: '',
+      endpoints: [],
       gatewayWaitTimeoutMs: DEFAULT_GATEWAY_WAIT_TIMEOUT_MS,
       maxPayloadBytes: DEFAULT_MAX_WS_PAYLOAD_BYTES,
       fileDownloadsEnabled: true,
@@ -1881,6 +2020,17 @@ const plugin = {
     let requireAuth = options.requireAuth !== false
     const adminLoopbackOnly = options.adminLoopbackOnly !== false
     const deviceFile = options.deviceFile || path.join(os.homedir(), '.dsh', 'mobile-gateway-devices.json')
+    if (options.gatewayMode !== undefined && !GATEWAY_MODES.includes(options.gatewayMode)) throw new Error('invalid gatewayMode')
+    if (typeof options.gatewayName !== 'string' || options.gatewayName.trim().length > 80) throw new Error('gatewayName must be at most 80 characters')
+    const normalizeEndpoints = (values) => {
+      if (!Array.isArray(values) || values.length > 16 || values.some((value) => typeof value !== 'string' || !value.trim() || value.length > 2048)) {
+        throw badRequest('endpoints must be an array of at most 16 nonempty URLs (2048 characters each)')
+      }
+      return [...new Set(values.map((value) => normalizePublicUrl(value, { headers: {} }, wsPath)))]
+    }
+    const configuredEndpoints = normalizeEndpoints(options.endpoints)
+    const gatewayState = createGatewayState(options.gatewayStateFile || `${deviceFile}.gateway.json`)
+    const gatewayIdentity = { gatewayId: gatewayState.gatewayId, gatewayName: options.gatewayName.trim() || os.hostname().slice(0, 80) }
     const registry = createRegistry(deviceFile, { pairingTtlMs: options.pairingTtlMs })
     const wss = new WebSocketServer({
       noServer: true,
@@ -1900,9 +2050,12 @@ const plugin = {
         log(`file download expiry failed: ${error && error.message ? error.message : String(error)}`)
       })
     }, Math.min(options.fileDownloadIdleMs, 30_000))
-    const controlStreamAbort = new AbortController()
+    const backgroundStreamAbort = new AbortController()
+    let archivedSessionIds = null
+    let sessionQueues = null
     let counter = 0
-    let gatewayEnabled = options.gatewayEnabled === true
+    let gatewayMode = gatewayState.mode ?? options.gatewayMode ?? (options.gatewayEnabled === true ? 'persistent' : 'disabled')
+    let gatewayEnabled = gatewayMode !== 'disabled'
     let waitExpiresAt = null
     let waitTimer = null
     let connectedSinceEnabled = false
@@ -1926,25 +2079,44 @@ const plugin = {
       }
     }
 
-    const setGatewayEnabled = (enabled, reason) => {
+    const advertisedEndpoints = (primary, extra = []) => {
+      const publicUrl = configuredPublicUrl()
+      return normalizeEndpoints([...new Set([
+        ...(primary ? [primary] : []),
+        ...extra,
+        ...configuredEndpoints,
+        ...(publicUrl ? [publicUrl] : []),
+        ...(lanListening ? lanWebSocketUrls(options, wsPath, lanBoundPort) : []),
+      ])])
+    }
+
+    const setGatewayMode = (mode, reason, persist = true) => {
+      if (!GATEWAY_MODES.includes(mode)) throw badRequest('mode must be disabled, temporary, or persistent')
+      // Commit before changing the live service, so a failed save never reports success.
+      if (persist) gatewayState.setMode(mode)
       if (waitTimer) clearTimeout(waitTimer)
       waitTimer = null
-      gatewayEnabled = enabled
+      gatewayMode = mode
+      gatewayEnabled = mode !== 'disabled'
       waitExpiresAt = null
-      connectedSinceEnabled = false
-      if (enabled) {
+      connectedSinceEnabled = [...clients].some((client) => client.readyState === 1)
+      if (mode === 'temporary' && !connectedSinceEnabled) {
         waitExpiresAt = Date.now() + options.gatewayWaitTimeoutMs
         waitTimer = setTimeout(() => {
           waitTimer = null
-          if (!gatewayEnabled || connectedSinceEnabled || clients.size > 0) return
+          if (!gatewayEnabled || connectedSinceEnabled || [...clients].some((client) => client.readyState === 1)) return
           gatewayEnabled = false
+          gatewayMode = 'disabled'
           waitExpiresAt = null
+          try { gatewayState.setMode('disabled') } catch (error) {
+            log(`failed to persist automatic gateway disable: ${error.message}`)
+          }
           log('mobile gateway automatically disabled: no device connected before timeout')
         }, options.gatewayWaitTimeoutMs)
-      } else {
+      } else if (mode === 'disabled') {
         for (const client of clients) client.close(4004, 'mobile gateway disabled')
       }
-      log(`mobile gateway ${enabled ? 'enabled' : 'disabled'}${reason ? `: ${reason}` : ''}`)
+      log(`mobile gateway mode=${mode}${reason ? `: ${reason}` : ''}`)
     }
 
     const logAuthRejected = (req) => {
@@ -1984,12 +2156,25 @@ const plugin = {
     const broadcastInteractionFrame = (frame) => {
       const wire = JSON.stringify(frame)
       for (const client of clients) {
+        if (client.mobileChannel === 'conversation') continue
         if (client.filterSessionId && client.filterSessionId !== frame.sessionId) continue
         if (client.readyState === 1) client.send(wire)
       }
     }
 
+    // Session-list metadata must reach every connected client even when it is
+    // subscribed to one conversation. Subscriptions only scope the heavier
+    // conversation and interaction streams.
+    const broadcastSessionMetadataFrame = (frame) => {
+      const wire = JSON.stringify(frame)
+      for (const client of clients) {
+        if (client.mobileChannel === 'conversation') continue
+        if (client.readyState === 1) client.send(wire)
+      }
+    }
+
     const replayPendingInteractions = (ws, trigger) => {
+      if (ws.mobileChannel === 'conversation') return { questionCount: 0, approvalCount: 0 }
       let questionCount = 0
       let approvalCount = 0
       for (const pending of pendingQuestions.values()) {
@@ -2008,6 +2193,7 @@ const plugin = {
 
     const hasInteractionClient = (sessionId) => [...clients].some((client) => (
       client.readyState === 1
+      && client.mobileChannel !== 'conversation'
       && (!client.filterSessionId || client.filterSessionId === sessionId)
     ))
 
@@ -2162,12 +2348,8 @@ const plugin = {
       }
     }
 
-    // Startup-config enablement (gatewayEnabled: true in cordis.patch.yml) is a
-    // standing-service decision made by the operator: do NOT arm the no-device
-    // auto-close. That safety net stays attached to the ephemeral panel toggle,
-    // where it belongs. gatewayEnabled is already true from options at this point,
-    // so nothing else is needed here beyond the log line.
-    if (gatewayEnabled) log('mobile gateway enabled by startup config: standing mode, no auto-close timer')
+    // Saved user choice wins; a temporary startup gets a fresh first-connection window.
+    setGatewayMode(gatewayMode, 'startup', false)
 
     log(`applying: version=${PLUGIN_VERSION} interactionProtocol=${INTERACTION_PROTOCOL_REVISION} path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
 
@@ -2192,6 +2374,9 @@ const plugin = {
               version: PLUGIN_VERSION,
               requireAuth,
               gatewayEnabled,
+              gatewayMode,
+              ...gatewayIdentity,
+              endpoints: advertisedEndpoints(),
               waitExpiresAt,
               connectedClients: clients.size,
               webPort: webServer.port,
@@ -2223,9 +2408,10 @@ const plugin = {
             sendJson(res, 200, result)
           } else if (req.method === 'POST' && p === '/mgw/gateway') {
             const body = await readBody(req)
-            if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
-            setGatewayEnabled(body.enabled, 'changed from management UI')
-            sendJson(res, 200, { gatewayEnabled, waitExpiresAt, connectedClients: clients.size })
+            if (body.mode !== undefined && body.enabled !== undefined) throw badRequest('provide mode or enabled, not both')
+            if (body.mode === undefined && typeof body.enabled !== 'boolean') throw badRequest('mode or boolean enabled is required')
+            setGatewayMode(body.mode !== undefined ? body.mode : (body.enabled ? 'temporary' : 'disabled'), 'changed from management UI')
+            sendJson(res, 200, { gatewayEnabled, gatewayMode, waitExpiresAt, connectedClients: clients.size })
           } else if (req.method === 'POST' && p === '/mgw/auth') {
             const body = await readBody(req)
             if (typeof body.enabled !== 'boolean') throw badRequest('enabled must be a boolean')
@@ -2252,12 +2438,15 @@ const plugin = {
             const body = await readBody(req)
             const name = typeof body.name === 'string' ? body.name : undefined
             const publicUrl = normalizePublicUrl(body.publicUrl || configuredPublicUrl(), req, wsPath)
+            const endpoints = advertisedEndpoints(publicUrl, normalizeEndpoints(body.endpoints ?? []))
             const pairing = registry.createPairing(name)
             const payload = {
               version: 2,
               publicUrl,
               pairingCode: pairing.code,
               expiresAt: pairing.expiresAt,
+              ...gatewayIdentity,
+              endpoints,
             }
             // QR/manual pairing has one canonical wire representation: the
             // UTF-8 JSON payload encoded as unpadded Base64URL. Base64URL is
@@ -2337,6 +2526,8 @@ const plugin = {
         wss.handleUpgrade(req, socket, head, (ws) => {
           const id = ++counter
           ws.filterSessionId = undefined
+          const requestedChannel = req.headers['x-dsh-channel']
+          ws.mobileChannel = ['control', 'conversation'].includes(requestedChannel) ? requestedChannel : 'legacy'
           ws.deviceId = device && device.id
           clients.add(ws)
           if (device) registry.connected(device.id)
@@ -2357,6 +2548,12 @@ const plugin = {
               return
             }
             if (!msg || typeof msg.type !== 'string') return
+            const conversationRequest = ['message', 'history', 'subscribe', 'unsubscribe'].includes(msg.type)
+            if ((ws.mobileChannel === 'control' && conversationRequest) ||
+                (ws.mobileChannel === 'conversation' && !conversationRequest && msg.type !== 'ping')) {
+              ws.send(JSON.stringify({ kind: 'error', code: 'wrong-channel', requestType: msg.type, message: 'Request belongs to the other mobile channel' }))
+              return
+            }
 
             if (msg.type === 'ping') {
               ws.send(JSON.stringify({ kind: 'pong', at: Date.now() }))
@@ -2386,12 +2583,13 @@ const plugin = {
               })
             } else if (msg.type === 'workspaces' || msg.type === 'sessions' || msg.type === 'history' || msg.type === 'attachment' ||
                        msg.type === 'search' || msg.type === 'host' || msg.type === 'directories' || msg.type === 'directory-create' ||
-                       msg.type === 'workspace-create' || msg.type === 'models' || msg.type === 'commands' || msg.type === 'command-execute' ||
+                       msg.type === 'workspace-create' || msg.type === 'session-create' || msg.type === 'models' || msg.type === 'commands' || msg.type === 'command-execute' ||
                        msg.type === 'command-options' || msg.type === 'command-select' || msg.type === 'select-model' ||
                        msg.type === 'permission-options' || msg.type === 'permission' || msg.type === 'context-usage' ||
                        msg.type === 'agent-presets' || msg.type === 'defaults' || msg.type === 'set-default' ||
                        msg.type === 'session-stats' || msg.type === 'default-model' ||
-                       msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'providers' ||
+                       msg.type === 'save-default-model' || msg.type === 'fork' || msg.type === 'session-cancel' || msg.type === 'queue-update' ||
+                       msg.type === 'session-archive' || msg.type === 'session-rename' || msg.type === 'providers' ||
                        msg.type === 'tasks' || msg.type === 'goal' || msg.type === 'goal-edit' ||
                        msg.type === 'goal-pause' || msg.type === 'goal-resume' || msg.type === 'goal-clear') {
               handleQuery(api, host, agentDefaultModel, msg).then((frame) => {
@@ -2418,17 +2616,37 @@ const plugin = {
               kind: 'paired',
               token: paired.token,
               device: paired.device,
+              ...gatewayIdentity,
             }))
           }
           ws.send(JSON.stringify({
             kind: 'hello',
+            ...gatewayIdentity,
             protocol: 3,
-            capabilities: ['images', 'commands', 'tasks', 'goals', ...(options.fileDownloadsEnabled ? ['file-downloads'] : [])],
+            capabilities: [
+              'split-channels',
+              'images',
+              'session-create',
+              'commands',
+              'tasks',
+              'goals',
+              'session-cancel',
+              'queue-control',
+              'session-archive',
+              'session-rename',
+              ...(options.fileDownloadsEnabled ? ['file-downloads'] : []),
+            ],
             port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,
             ...(device ? { device: { id: device.id, name: device.name } } : {}),
           }))
+          if (ws.mobileChannel !== 'conversation' && archivedSessionIds !== null) {
+            ws.send(JSON.stringify({ kind: 'session-archives', archivedSessionIds }))
+          }
+          if (ws.mobileChannel !== 'conversation' && sessionQueues !== null) {
+            ws.send(JSON.stringify({ kind: 'session-queues', queues: Object.fromEntries(sessionQueues) }))
+          }
           replayPendingInteractions(ws, 'connect')
         })
     }
@@ -2486,8 +2704,19 @@ const plugin = {
       if (clients.size === 0) return
       const wire = buildWireEvent(session, event)
       if (!wire) return
+      if (event.type === 'session/title' && typeof event.data?.title === 'string') {
+        broadcastSessionMetadataFrame({
+          kind: 'session-title-changed',
+          sessionId: String(session.id),
+          title: event.data.title,
+          seq: event.seq,
+          time: event.time,
+          ...(event.data.source ? { source: event.data.source } : {}),
+        })
+      }
       const payload = JSON.stringify(wire)
       for (const client of clients) {
+        if (client.mobileChannel === 'control') continue
         if (client.filterSessionId && client.filterSessionId !== String(session.id)) continue
         if (client.readyState === 1) client.send(payload)
       }
@@ -2548,50 +2777,138 @@ const plugin = {
       })
     }, { prepend: true })
 
-    const projectionTask = (async () => {
-      while (!controlStreamAbort.signal.aborted) {
+    const waitForBackgroundRetry = () => new Promise((resolve) => {
+      if (backgroundStreamAbort.signal.aborted) {
+        resolve()
+        return
+      }
+      const finish = () => {
+        clearTimeout(timer)
+        backgroundStreamAbort.signal.removeEventListener('abort', finish)
+        resolve()
+      }
+      const timer = setTimeout(finish, 1_000)
+      backgroundStreamAbort.signal.addEventListener('abort', finish, { once: true })
+    })
+
+    const installArchivedSessionIds = (value) => {
+      if (!Array.isArray(value)) throw new Error('workspace/follow returned invalid archivedSessionIds')
+      const next = value.map((sessionId) => String(sessionId))
+      if (archivedSessionIds !== null
+        && archivedSessionIds.length === next.length
+        && archivedSessionIds.every((sessionId, index) => sessionId === next[index])) return
+      archivedSessionIds = next
+      broadcastSessionMetadataFrame({ kind: 'session-archives', archivedSessionIds: next })
+      log(`session archive state forwarded: count=${next.length}`)
+    }
+
+    const normalizeQueueItems = (value, endpoint) => {
+      if (!Array.isArray(value)) throw new Error(`${endpoint} returned invalid queue items`)
+      return value.map((candidate) => {
+        const message = candidate && typeof candidate === 'object' && !Array.isArray(candidate)
+          ? candidate.message
+          : null
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)
+          || typeof candidate.id !== 'string' || !candidate.id
+          || !['queued', 'steering', 'context'].includes(candidate.placement)
+          || !message || typeof message !== 'object' || Array.isArray(message)
+          || typeof message.id !== 'string' || !message.id
+          || !Array.isArray(message.content)
+          || (candidate.rpcId !== undefined && typeof candidate.rpcId !== 'string')) {
+          throw new Error(`${endpoint} returned an invalid queue item`)
+        }
+        return {
+          id: candidate.id,
+          placement: candidate.placement,
+          ...(candidate.rpcId === undefined ? {} : { rpcId: candidate.rpcId }),
+          message: { id: message.id, content: message.content },
+        }
+      })
+    }
+
+    const installSessionQueueBaseline = (value) => {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('session/control baseline returned invalid queues')
+      }
+      const next = new Map()
+      for (const [sessionId, items] of Object.entries(value)) {
+        next.set(sessionId, normalizeQueueItems(items, 'session/control baseline'))
+      }
+      sessionQueues = next
+      broadcastSessionMetadataFrame({ kind: 'session-queues', queues: Object.fromEntries(next) })
+      log(`session queue baseline forwarded: sessions=${next.size}`)
+    }
+
+    const installSessionQueue = (sessionIdValue, itemsValue) => {
+      const sessionId = typeof sessionIdValue === 'string' && sessionIdValue ? sessionIdValue : null
+      if (!sessionId) throw new Error('session/control returned an invalid queue sessionId')
+      const items = normalizeQueueItems(itemsValue, 'session/control queue')
+      if (sessionQueues === null) sessionQueues = new Map()
+      sessionQueues.set(sessionId, items)
+      broadcastSessionMetadataFrame({ kind: 'session-queue', sessionId, items })
+      log(`session queue forwarded: session=${sessionId} items=${items.length}`)
+    }
+
+    const workspaceTask = (async () => {
+      while (!backgroundStreamAbort.signal.aborted) {
         try {
-          const stream = await api.openControlStream(controlStreamAbort.signal)
+          const stream = await api.openWorkspaceStream(backgroundStreamAbort.signal)
           for await (const frame of stream) {
-            if (frame?.type !== 'projection' || (frame.key !== 'todos' && frame.key !== 'goal')) continue
-            const sessionId = String(frame.sessionId)
-            const kind = frame.key === 'todos' ? 'tasks-updated' : 'goal-updated'
-            const valueKey = frame.key === 'todos' ? 'todos' : 'goal'
-            broadcastInteractionFrame({
-              kind,
-              sessionId,
-              asOfSeq: frame.seq,
-              [valueKey]: frame.value,
-            })
-            log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
+            if (frame?.type === 'baseline') {
+              installArchivedSessionIds(frame.value?.archivedSessionIds)
+            } else if (frame?.type === 'archived') {
+              installArchivedSessionIds(frame.archivedSessionIds)
+            }
           }
-          if (!controlStreamAbort.signal.aborted) log('session control stream ended; retrying')
+          if (!backgroundStreamAbort.signal.aborted) log('workspace stream ended; retrying')
         } catch (error) {
-          if (!controlStreamAbort.signal.aborted) {
-            log(`session control stream failed; retrying: ${error && error.message ? error.message : String(error)}`)
+          if (!backgroundStreamAbort.signal.aborted) {
+            log(`workspace stream failed; retrying: ${error && error.message ? error.message : String(error)}`)
           }
         }
-        if (controlStreamAbort.signal.aborted) break
-        await new Promise((resolve) => {
-          const onAbort = () => {
-            clearTimeout(timer)
-            resolve()
+        if (!backgroundStreamAbort.signal.aborted) await waitForBackgroundRetry()
+      }
+    })()
+    void workspaceTask
+
+    const controlTask = (async () => {
+      while (!backgroundStreamAbort.signal.aborted) {
+        try {
+          const stream = await api.openControlStream(backgroundStreamAbort.signal)
+          for await (const frame of stream) {
+            if (frame?.type === 'baseline') {
+              installSessionQueueBaseline(frame.value?.queues)
+            } else if (frame?.type === 'queue') {
+              installSessionQueue(frame.sessionId, frame.items)
+            } else if (frame?.type === 'projection' && (frame.key === 'todos' || frame.key === 'goal')) {
+              const sessionId = String(frame.sessionId)
+              const kind = frame.key === 'todos' ? 'tasks-updated' : 'goal-updated'
+              const valueKey = frame.key === 'todos' ? 'todos' : 'goal'
+              broadcastInteractionFrame({
+                kind,
+                sessionId,
+                asOfSeq: frame.seq,
+                [valueKey]: frame.value,
+              })
+              log(`projection forwarded: key=${frame.key} session=${sessionId} seq=${frame.seq}`)
+            }
           }
-          const timer = setTimeout(() => {
-            controlStreamAbort.signal.removeEventListener('abort', onAbort)
-            resolve()
-          }, 1_000)
-          controlStreamAbort.signal.addEventListener('abort', onAbort, { once: true })
-        })
+          if (!backgroundStreamAbort.signal.aborted) log('session control stream ended; retrying')
+        } catch (error) {
+          if (!backgroundStreamAbort.signal.aborted) {
+            log(`session control stream failed; retrying: ${error && error.message ? error.message : String(error)}`)
+          }
+        }
+        if (!backgroundStreamAbort.signal.aborted) await waitForBackgroundRetry()
       }
     })()
-    void projectionTask
-    log('Host waterfall interaction listeners and session control stream attached')
+    void controlTask
+    log('Host waterfall interaction listeners, workspace stream, and session control stream attached')
 
     ctx.effect(() => () => {
       if (waitTimer) clearTimeout(waitTimer)
       clearInterval(fileTransferExpiryTimer)
-      controlStreamAbort.abort()
+      backgroundStreamAbort.abort()
       for (const pending of [...pendingQuestions.values()]) fallbackQuestion(pending)
       for (const pending of [...pendingApprovals.values()]) fallbackApproval(pending)
       fileTransfers.dispose().catch((error) => {