dsh-plugin-weapp-gateway 0.8.13 → 0.8.23

package/lib/context-bridge.mjs

@@ -0,0 +1,1715 @@
+/**
+ * Context dashboard bridge for the mobile gateway.
+ *
+ * Registers one pure session projection (`mobileContext`) that folds a session's
+ * durable event log into the composition / request-trend / event data the mini
+ * program's 「上下文」 tab renders, and serves it over a single mobile query:
+ *
+ *   { type: 'context-dashboard', sessionId } ->
+ *   { kind: 'context-dashboard', sessionId, asOfSeq, value: { ...mobileContext, breakdown, usage, stats } }
+ *
+ * Token pricing and the surface-replacement rules mirror DSH's own token meter
+ * (`@deepseek-ai/dsh-token-meter`, fixed-density heuristic + planner), so the
+ * folded `systemTokens` / `toolsTokens` / message total match the harness's
+ * `contextBreakdown` projection exactly. Category classification and the
+ * request/event tallies follow `dsh-context` (Apache-2.0, bowenliang123).
+ *
+ * Wire v2 (docs/context-dashboard.md §8.1/§8.2) adds the desktop dashboard's
+ * missing data as additive-optional fields: per-category activity counters
+ * (`activity`), the six-way duration split plus its timeline (`timing`/`spans`),
+ * per-request surface item counts and provider-reported usage
+ * (`requests[].items/prompt/output`), the newest answer preview (`lastAnswer`),
+ * and, for `context-fleet`, the host `agentTeam` roster/task board (`team`) plus
+ * each agent's `lastAnswer`/`phase`. The embedded assistant `data.stream`
+ * decoders under "Assistant stream decoding" are ported from
+ * `dsh-context/src/host/logShapes.ts` (Apache-2.0) so the split matches the
+ * desktop plugin's semantics.
+ *
+ * The fold state is plain JSON and bounded so the harness projection cache can
+ * checkpoint it: at most MAX_SURFACE nodes, MAX_REQUESTS request records,
+ * MAX_EVENTS context events and MAX_SPANS timeline segments. `init`/`apply`/
+ * `view` are copied on every change (never mutated in place) because the
+ * registry shares the previous state with the persisted cache.
+ */
+
+const CHARS_PER_TOKEN = 4
+const BLOCK_OVERHEAD = 4
+const ROLE_OVERHEAD = 4
+
+const SURFACE_TYPES = new Set(['system/message', 'developer/message', 'user/message', 'assistant/message', 'tool/result'])
+const MESSAGE_CATS = ['user', 'inject', 'skill', 'assistant', 'tool']
+
+const MAX_SURFACE = 4000
+const MAX_ARCHIVE_NODES = 400
+const MAX_HEADER_EPOCHS = 100
+const MAX_FILE_OPS = 400
+const MAX_REQUESTS = 200
+const MAX_EVENTS = 120
+const MAX_TOOL_NAMES = 20
+const MAX_CALL_NAMES = 2000
+const MAX_SPANS = 600
+const MAX_STEP_SPANS = 2000
+const MAX_LAST_ANSWER = 240
+const MAX_TEAM_ROWS = 20
+
+// Timeline span kinds on the wire (docs §8.1): the client colors the strip by
+// these indices, so the vocabulary is frozen here.
+const SPAN_WAIT = 0
+const SPAN_REASONING = 1
+const SPAN_TEXT = 2
+const SPAN_TOOLARG = 3
+const SPAN_TOOLS = 4
+const SPAN_OTHER = 5
+const DECODE_SPAN_KINDS = { reasoning: SPAN_REASONING, text: SPAN_TEXT, toolarg: SPAN_TOOLARG }
+const TEAM_PHASES = new Set(['provisioning', 'active', 'failed'])
+
+// Activity classification of a PAIRED tool call by its durable tool name
+// (docs §8.1). Prefixes stay permissive for read*/write*/search* variants while
+// the explicit names cover the harness's editor/search tools.
+const WRITE_TOOL_NAMES = new Set(['edit', 'apply_patch', 'str_replace_editor'])
+const SEARCH_TOOL_NAMES = new Set(['grep', 'glob', 'list', 'search', 'web_search', 'ripgrep', 'search_files'])
+
+function toolActivityOf(name) {
+  if (typeof name !== 'string' || name === '') return ''
+  if (name.startsWith('read')) return 'reads'
+  if (name.startsWith('write') || WRITE_TOOL_NAMES.has(name)) return 'writes'
+  if (SEARCH_TOOL_NAMES.has(name) || name.startsWith('search')) return 'searches'
+  return ''
+}
+
+// A plain object with the only method the projection registry calls. Keeping the
+// bridge free of a zod dependency lets the same module load in the host plugin
+// and in plain-Node unit tests.
+const passthroughSchema = Object.freeze({
+  parse: value => value,
+  safeParse: value => ({ success: true, data: value }),
+  // Older registries may validate through the Standard Schema face instead of
+  // calling parse(); accept every plain-JSON fold state there too.
+  '~standard': Object.freeze({
+    version: 1,
+    vendor: 'mobile-gateway',
+    validate: value => ({ value }),
+  }),
+})
+
+export const CONTEXT_REQUEST_TYPES = new Set(['context-dashboard', 'context-fleet', 'context-content'])
+
+// ---------------------------------------------------------------------------
+// Token pricing (DSH token-meter fixed-density heuristic)
+// ---------------------------------------------------------------------------
+
+function estimateStructuralBlock(block) {
+  if (block !== null && typeof block === 'object' && block.type === 'image') {
+    const reference = { ...block }
+    delete reference.offloaded
+    return BLOCK_OVERHEAD + Math.ceil(JSON.stringify(reference).length / CHARS_PER_TOKEN)
+  }
+  return BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN)
+}
+
+function estimateSystemMessage(message) {
+  const blocks = Array.isArray(message && message.content) ? message.content : []
+  if (blocks.length === 0) return 0
+  let characters = 0
+  for (const block of blocks) {
+    if (block !== null && typeof block === 'object' && block.type === 'text') {
+      characters += typeof block.text === 'string' ? block.text.length : 0
+    } else {
+      characters += JSON.stringify(block).length
+    }
+  }
+  return Math.ceil(characters / CHARS_PER_TOKEN) + ROLE_OVERHEAD
+}
+
+function estimateContent(blocks) {
+  let tokens = 0
+  if (!Array.isArray(blocks)) return tokens
+  for (const block of blocks) {
+    if (block === null || typeof block !== 'object') {
+      tokens += estimateStructuralBlock(block)
+      continue
+    }
+    switch (block.type) {
+      case 'text':
+      case 'reasoning':
+        tokens += Math.ceil((typeof block.text === 'string' ? block.text : '').length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+        break
+      case 'tool-call':
+        tokens += Math.ceil((typeof block.name === 'string' ? block.name : '').length / CHARS_PER_TOKEN)
+          + Math.ceil((typeof block.arguments === 'string' ? block.arguments : '').length / CHARS_PER_TOKEN)
+          + BLOCK_OVERHEAD
+        break
+      default:
+        tokens += estimateStructuralBlock(block)
+    }
+  }
+  return tokens
+}
+
+function estimateMessage(message) {
+  if (message === null || message === undefined) return 0
+  if (message.role === 'system') return estimateSystemMessage(message)
+  return estimateContent(message.content) + ROLE_OVERHEAD
+}
+
+function canonicalHeader(header) {
+  if (header === null || typeof header !== 'object') return {}
+  const adapterDefaults = header.adapterDefaults
+  return {
+    config: header.config,
+    ...(adapterDefaults && (adapterDefaults.reasoningEffort === true || adapterDefaults.maxTokens === true)
+      ? { adapterDefaults }
+      : {}),
+    ...(Array.isArray(header.tools) && header.tools.length > 0 ? { tools: header.tools } : {}),
+  }
+}
+
+function estimateToolsTokens(header) {
+  const canonical = canonicalHeader(header)
+  if (!Array.isArray(canonical.tools) || canonical.tools.length === 0) return 0
+  return Math.ceil(JSON.stringify(canonical.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+}
+
+// ---------------------------------------------------------------------------
+// Assistant stream decoding (ported from dsh-context/src/host/logShapes.ts,
+// Apache-2.0, bowenliang123) — total over untrusted input; unknown chunks,
+// missing times and non-array streams are skipped rather than thrown.
+// ---------------------------------------------------------------------------
+
+/** Whether a raw stream chunk carries a token delta (mirrors dsh-llm's `isTokenDelta`). */
+function isTokenChunk(chunk) {
+  if (chunk === null || typeof chunk !== 'object') return false
+  switch (chunk.type) {
+    case 'text-delta':
+    case 'reasoning-delta':
+      return typeof chunk.text === 'string' && chunk.text !== ''
+    case 'tool-call-delta':
+      return (typeof chunk.argumentsDelta === 'string' && chunk.argumentsDelta !== '') || chunk.name !== undefined
+    default:
+      return false
+  }
+}
+
+/** The decode bucket a `block-start.blockType` names, or undefined for a marker we cannot price. */
+function decodeKindOfBlock(blockType) {
+  if (blockType === 'reasoning') return 'reasoning'
+  if (blockType === 'text') return 'text'
+  if (blockType === 'tool-call') return 'toolarg'
+  return undefined
+}
+
+/**
+ * Decode spans and `block-start` counts inside one embedded assistant stream.
+ * Each marker owns the interval up to the next one; the last one owns up to
+ * `endTime`. Unknown markers leave their interval unpriced.
+ *
+ * @param {unknown} stream
+ * @param {number} endTime
+ * @returns {{spans: {reasoning:number,text:number,toolarg:number}, blocks: {reasoning:number,text:number,toolarg:number}}}
+ */
+function decodeTallyOfStream(stream, endTime) {
+  const tally = {
+    spans: { reasoning: 0, text: 0, toolarg: 0 },
+    blocks: { reasoning: 0, text: 0, toolarg: 0 },
+  }
+  if (!Array.isArray(stream) || !Number.isFinite(endTime)) return tally
+  let kind
+  let since = 0
+  for (const record of stream) {
+    if (record === null || typeof record !== 'object') continue
+    if (record.type !== 'chunk' || record.chunk === null || typeof record.chunk !== 'object') continue
+    const chunk = record.chunk
+    if (chunk.type !== 'block-start') continue
+    const time = record.time
+    if (typeof time !== 'number' || !Number.isFinite(time)) continue
+    if (kind !== undefined) tally.spans[kind] += Math.max(0, time - since)
+    kind = decodeKindOfBlock(chunk.blockType)
+    if (kind !== undefined) tally.blocks[kind] += 1
+    since = time
+  }
+  if (kind !== undefined) tally.spans[kind] += Math.max(0, endTime - since)
+  return tally
+}
+
+/** The ORDERED decode spans of one embedded assistant stream (same ownership rule as the tally). */
+function decodeSpansOfStream(stream, endTime) {
+  const spans = []
+  if (!Array.isArray(stream) || !Number.isFinite(endTime)) return spans
+  let kind
+  let since = 0
+  const close = to => {
+    if (kind !== undefined && to > since) spans.push({ kind, start: since, end: to })
+  }
+  for (const record of stream) {
+    if (record === null || typeof record !== 'object') continue
+    if (record.type !== 'chunk' || record.chunk === null || typeof record.chunk !== 'object') continue
+    const chunk = record.chunk
+    if (chunk.type !== 'block-start') continue
+    const time = record.time
+    if (typeof time !== 'number' || !Number.isFinite(time)) continue
+    close(time)
+    kind = decodeKindOfBlock(chunk.blockType)
+    since = time
+  }
+  close(endTime)
+  return spans
+}
+
+/** The first token's instant inside one packed delta run, or undefined. */
+function runFirstTokenTime(record) {
+  const time0 = record.time0
+  if (typeof time0 !== 'number' || !Number.isFinite(time0)) return undefined
+  if (record.type === 'tool-call-chunks' && record.name !== undefined) return time0
+  const fragments = record.type === 'tool-call-chunks' ? record.args : record.texts
+  if (!Array.isArray(fragments)) return undefined
+  const dt = Array.isArray(record.dt) ? record.dt : []
+  let time = time0
+  for (let index = 0; index < fragments.length; index += 1) {
+    if (index > 0) {
+      const step = dt[index - 1]
+      if (typeof step !== 'number' || !Number.isFinite(step)) return undefined
+      time += step
+    }
+    if (typeof fragments[index] === 'string' && fragments[index] !== '') return time
+  }
+  return undefined
+}
+
+/** The first token's instant inside an embedded assistant stream, or undefined when it carries no token. */
+function firstTokenTimeOfStream(stream) {
+  if (!Array.isArray(stream)) return undefined
+  for (const record of stream) {
+    if (record === null || typeof record !== 'object') continue
+    if (record.type === 'chunk') {
+      const time = record.time
+      if (typeof time === 'number' && Number.isFinite(time) && isTokenChunk(record.chunk)) return time
+      continue
+    }
+    const time = runFirstTokenTime(record)
+    if (time !== undefined) return time
+  }
+  return undefined
+}
+
+/** One provider-reported usage bucket as a non-negative integer, or null when unreadable. */
+function tokenCountOf(value) {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? Math.max(0, Math.round(value)) : null
+  }
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? Math.max(0, Math.round(parsed)) : null
+  }
+  return null
+}
+
+/** A non-negative duration between two instants; 0 for non-finite input. */
+function durOf(from, to) {
+  if (typeof from !== 'number' || typeof to !== 'number' || !Number.isFinite(from) || !Number.isFinite(to)) return 0
+  return Math.max(0, to - from)
+}
+
+/** Image blocks inside one user message (the activity ledger's `images`, unclipped). */
+function countImageBlocks(message) {
+  if (message === null || typeof message !== 'object' || !Array.isArray(message.content)) return 0
+  let count = 0
+  for (const block of message.content) {
+    if (block !== null && typeof block === 'object' && block.type === 'image') count += 1
+  }
+  return count
+}
+
+function parseCallArgs(raw) {
+  if (typeof raw !== 'string' || raw === '') return null
+  try {
+    const value = JSON.parse(raw)
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
+  } catch (_) { return null }
+}
+
+function fileCallMeta(name, raw) {
+  const args = parseCallArgs(raw)
+  if (args === null) return null
+  let kind = ''
+  if (name === 'read' || name === 'read_image') kind = 'read'
+  else if (name === 'write' || name === 'edit') kind = 'write'
+  else if (name === 'grep' || name === 'glob') kind = 'search'
+  else if (name === 'str_replace_editor') kind = args.command === 'view' ? 'read' : 'write'
+  if (kind === '') return null
+  let path = ''
+  if ((name === 'grep' || name === 'glob') && typeof args.path !== 'string') {
+    path = typeof args.pattern === 'string' ? args.pattern : ''
+  } else {
+    for (const key of ['file_path', 'filePath', 'path']) {
+      if (typeof args[key] === 'string' && args[key] !== '') { path = args[key]; break }
+    }
+  }
+  if (!path) return null
+  const added = name === 'write' ? lineCount(args.content)
+    : name === 'edit' ? lineCount(args.new_string)
+      : name === 'str_replace_editor' && ['str_replace', 'insert', 'create'].includes(args.command)
+        ? lineCount(args.command === 'create' ? args.file_text : args.new_str) : 0
+  const removed = name === 'edit' ? lineCount(args.old_string)
+    : name === 'str_replace_editor' && args.command === 'str_replace' ? lineCount(args.old_str) : 0
+  return {
+    kind, path: path.slice(0, 2000), added, removed,
+    ...(kind === 'search' && !(typeof args.path === 'string' && args.path !== '') ? { pattern: true } : {}),
+    ...(kind === 'read' && Number.isFinite(args.limit) && args.limit > 0 ? { readCount: Math.floor(args.limit) } : {}),
+  }
+}
+
+function lineCount(value) {
+  if (typeof value !== 'string' || value === '') return 0
+  const breaks = (value.match(/\n/g) || []).length
+  return value.endsWith('\n') ? breaks : breaks + 1
+}
+
+function fileOpsOf(event, message, pending) {
+  const meta = pending && pending.file
+  if (!meta) return []
+  const common = {
+    seq: event.seq, time: timeOf(event), path: meta.path, kind: meta.kind,
+    tool: pending.name, err: !!(message && message.isError === true),
+    added: meta.added, removed: meta.removed,
+    ...(meta.pattern === true ? { pattern: true } : {}),
+    ...(meta.readCount !== undefined ? { readCount: meta.readCount } : {}),
+  }
+  const eventMeta = event && event.data && event.data.meta
+  const resultMeta = message && message.meta !== null && typeof message.meta === 'object'
+    ? message.meta : eventMeta !== null && typeof eventMeta === 'object' ? eventMeta : null
+  if (meta.kind === 'search' && resultMeta && resultMeta.truncated === false) {
+    const found = []
+    if (resultMeta.shape === 'matches' && Array.isArray(resultMeta.files)) {
+      for (const row of resultMeta.files.slice(0, 100)) {
+        if (row && typeof row.path === 'string' && Array.isArray(row.matches)) found.push({ path: row.path.slice(0, 2000), hits: row.matches.length })
+      }
+    } else if (resultMeta.shape === 'paths' && Array.isArray(resultMeta.paths)) {
+      for (const path of resultMeta.paths.slice(0, 100)) if (typeof path === 'string') found.push({ path: path.slice(0, 2000), hits: 0 })
+    }
+    if (found.length > 0) return found.map(file => ({ ...common, ...file, pattern: false }))
+  }
+  if (meta.kind === 'read' && resultMeta && typeof resultMeta.offset === 'number'
+    && Array.isArray(resultMeta.lines) && resultMeta.lines.length > 0) {
+    common.readStart = Math.max(1, Math.floor(resultMeta.offset))
+    common.readCount = resultMeta.lines.length
+  }
+  return [common]
+}
+
+// ---------------------------------------------------------------------------
+// Fold state
+// ---------------------------------------------------------------------------
+
+function emptyTiming() {
+  return {
+    ttftMs: 0,
+    reasoningMs: 0,
+    textMs: 0,
+    toolArgMs: 0,
+    toolsMs: 0,
+    waitCount: 0,
+    reasoningCount: 0,
+    textCount: 0,
+    toolArgCount: 0,
+    toolCount: 0,
+    speedTokens: 0,
+    speedMs: 0,
+  }
+}
+
+function emptyActivity() {
+  return { reads: 0, writes: 0, searches: 0, images: 0 }
+}
+
+function emptySurfaceCounts() {
+  return { user: 0, inject: 0, skill: 0, assistant: 0, tool: 0 }
+}
+
+/** A bounded, plain-JSON fold state (see the module header). */
+export function createState() {
+  return {
+    surface: [],
+    archive: [],
+    headerEpochs: [],
+    fileOps: [],
+    sums: { user: 0, inject: 0, skill: 0, assistant: 0, tool: 0 },
+    systemTokens: 0,
+    toolsTokens: 0,
+    toolDefs: 0,
+    counts: { humanInputs: 0, answers: 0, skillLoads: 0, injects: 0, compactions: 0, prunes: 0, toolCalls: 0 },
+    activity: emptyActivity(),
+    timing: emptyTiming(),
+    surfaceCounts: emptySurfaceCounts(),
+    toolNames: {},
+    wallMs: 0,
+    callNames: {},
+    requests: [],
+    events: [],
+    spans: [],
+    truncated: { requests: false, events: false, surface: false },
+  }
+}
+
+function cloneState(state) {
+  return {
+    surface: [...state.surface],
+    archive: Array.isArray(state.archive) ? [...state.archive] : [],
+    ...(Number.isFinite(state.archiveFloor) ? { archiveFloor: state.archiveFloor } : {}),
+    headerEpochs: Array.isArray(state.headerEpochs) ? [...state.headerEpochs] : [],
+    fileOps: Array.isArray(state.fileOps) ? [...state.fileOps] : [],
+    ...(Number.isFinite(state.fileOpsFloor) ? { fileOpsFloor: state.fileOpsFloor } : {}),
+    sums: { ...state.sums },
+    systemTokens: state.systemTokens,
+    toolsTokens: state.toolsTokens,
+    toolDefs: safeInt(state.toolDefs),
+    ...(state.model !== undefined ? { model: state.model } : {}),
+    ...(state.provider !== undefined ? { provider: state.provider } : {}),
+    ...(state.contextWindow !== undefined ? { contextWindow: state.contextWindow } : {}),
+    counts: { ...state.counts },
+    activity: { ...emptyActivity(), ...(state.activity !== null && typeof state.activity === 'object' ? state.activity : {}) },
+    timing: { ...emptyTiming(), ...(state.timing !== null && typeof state.timing === 'object' ? state.timing : {}) },
+    surfaceCounts: { ...emptySurfaceCounts(), ...(state.surfaceCounts !== null && typeof state.surfaceCounts === 'object' ? state.surfaceCounts : {}) },
+    toolNames: { ...state.toolNames },
+    wallMs: state.wallMs,
+    callNames: { ...state.callNames },
+    requests: [...state.requests],
+    events: [...state.events],
+    // Shared copy-on-write: only `step/end` appends, and it re-slices before
+    // touching the array, so a shared reference can never be mutated.
+    spans: Array.isArray(state.spans) ? state.spans : [],
+    truncated: { ...state.truncated },
+    ...(typeof state.lastAnswer === 'string' && state.lastAnswer !== '' ? { lastAnswer: state.lastAnswer } : {}),
+    ...(state.stepStart !== undefined
+      ? {
+        stepStart: {
+          time: state.stepStart.time,
+          waits: Array.isArray(state.stepStart.waits) ? [...state.stepStart.waits] : [],
+          ...(typeof state.stepStart.firstToken === 'number' && Number.isFinite(state.stepStart.firstToken)
+            ? { firstToken: state.stepStart.firstToken }
+            : {}),
+        },
+      }
+      : {}),
+    ...(Array.isArray(state.stepSpans) ? { stepSpans: state.stepSpans.map(span => [span[0], span[1], span[2]]) } : {}),
+    ...(state.approvals !== undefined ? { approvals: { ...state.approvals } } : {}),
+  }
+}
+
+function deriveEventMessage(event) {
+  const data = event && event.data
+  if (data === null || typeof data !== 'object') return null
+  switch (event.type) {
+    case 'user/message':
+      return data
+    case 'system/message':
+    case 'developer/message':
+    case 'assistant/message': {
+      const message = data.message
+      if (message === null || typeof message !== 'object') return null
+      if (!Array.isArray(message.content) || message.content.length === 0) return null
+      return message
+    }
+    case 'tool/result':
+      return data.message !== null && typeof data.message === 'object' ? data.message : null
+    default:
+      return null
+  }
+}
+
+function isSurfaceEvent(event) {
+  return SURFACE_TYPES.has(event.type) && event.surfaceOp !== undefined
+}
+
+/** {start,end} for a replacement event, or null for an append / legacy spelling. */
+function replaceRangeOf(surfaceOp) {
+  if (surfaceOp === null || typeof surfaceOp !== 'object') return null
+  if (surfaceOp.op !== 'replace') return null
+  const start = surfaceOp.startSeq
+  const end = surfaceOp.endSeq
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null
+  return { start, end }
+}
+
+function addNodeSums(state, node) {
+  if (node.cat === 'system') return
+  if (MESSAGE_CATS.includes(node.cat)) {
+    state.sums[node.cat] += node.tokens
+    state.surfaceCounts[node.cat] = (state.surfaceCounts[node.cat] || 0) + 1
+  }
+}
+
+function removeNodeSums(state, node) {
+  if (node.cat === 'system') return
+  if (MESSAGE_CATS.includes(node.cat)) {
+    state.sums[node.cat] = Math.max(0, state.sums[node.cat] - node.tokens)
+    state.surfaceCounts[node.cat] = Math.max(0, (state.surfaceCounts[node.cat] || 0) - 1)
+  }
+}
+
+function recomputeSystemTokens(state) {
+  for (let i = state.surface.length - 1; i >= 0; i -= 1) {
+    const node = state.surface[i]
+    if (node.cat === 'system' && node.tokens > 0) {
+      state.systemTokens = node.tokens
+      return
+    }
+  }
+  state.systemTokens = 0
+}
+
+function applySurface(state, event, cat, message) {
+  const node = { seq: event.seq, cat, tokens: estimateMessage(message) }
+  const eventTime = timeOf(event)
+  if (eventTime > 0) node.time = eventTime
+  const source = message !== null && typeof message === 'object' ? message.source : null
+  if (source !== null && typeof source === 'object') {
+    if (typeof source.form === 'string' && source.form !== '') node.form = source.form
+    if (typeof source.name === 'string' && source.name !== '') node.name = source.name.slice(0, 160)
+  }
+  if (cat === 'assistant') {
+    const answer = firstText(Array.isArray(message && message.content) ? message.content : [])
+    if (answer !== '') node.text = answer.replace(/\s+/g, ' ').trim().slice(0, MAX_LAST_ANSWER)
+    else {
+      const calls = Array.isArray(message && message.content)
+        ? message.content.filter(block => block && typeof block === 'object' && block.type === 'tool-call')
+          .map(block => typeof block.name === 'string' ? block.name.slice(0, 100) : '')
+          .filter(Boolean).slice(0, 3)
+        : []
+      if (calls.length > 0) node.calls = calls
+    }
+  } else if (cat === 'tool') {
+    const callId = source && typeof source.callId === 'string' ? source.callId : ''
+    const call = callId !== '' ? state.callNames[callId] : null
+    if (call && typeof call.name === 'string') node.tool = call.name.slice(0, 100)
+    if (message && message.isError === true) node.err = true
+  }
+  const images = countImageBlocks(message)
+  if (images > 0) node.imgs = images
+  const range = replaceRangeOf(event.surfaceOp)
+  if (range !== null) {
+    let startIndex = -1
+    let endIndex = -1
+    for (let i = 0; i < state.surface.length; i += 1) {
+      if (startIndex < 0 && state.surface[i].seq === range.start) startIndex = i
+      if (state.surface[i].seq === range.end) {
+        endIndex = i
+        break
+      }
+    }
+    if (startIndex >= 0 && endIndex >= startIndex) {
+      const removed = state.surface.splice(startIndex, endIndex - startIndex + 1, node)
+      for (const old of removed) {
+        removeNodeSums(state, old)
+        state.archive.push({ ...old, gone: event.seq })
+        for (let index = 0; index < state.fileOps.length; index += 1) {
+          const op = state.fileOps[index]
+          if (op.seq === old.seq && op.gone === undefined) state.fileOps[index] = { ...op, gone: event.seq }
+        }
+      }
+      addNodeSums(state, node)
+      if (cat === 'system') recomputeSystemTokens(state)
+      trimState(state)
+      return node
+    }
+  }
+  state.surface.push(node)
+  addNodeSums(state, node)
+  if (cat === 'system') recomputeSystemTokens(state)
+  return node
+}
+
+function trimState(state) {
+  if (state.surface.length > MAX_SURFACE) {
+    const drop = state.surface.length - MAX_SURFACE
+    const removed = state.surface.splice(0, drop)
+    for (const old of removed) removeNodeSums(state, old)
+    state.truncated.surface = true
+    recomputeSystemTokens(state)
+  }
+  if (state.requests.length > MAX_REQUESTS) {
+    state.requests.splice(0, state.requests.length - MAX_REQUESTS)
+    state.truncated.requests = true
+  }
+  if (state.events.length > MAX_EVENTS) {
+    state.events.splice(0, state.events.length - MAX_EVENTS)
+    state.truncated.events = true
+  }
+  if (Array.isArray(state.spans) && state.spans.length > MAX_SPANS) {
+    state.spans = state.spans.slice(state.spans.length - MAX_SPANS)
+  }
+  if (Array.isArray(state.archive) && state.archive.length > MAX_ARCHIVE_NODES) {
+    const removed = state.archive.splice(0, state.archive.length - MAX_ARCHIVE_NODES)
+    for (const node of removed) state.archiveFloor = Math.max(state.archiveFloor || 0, safeInt(node.gone))
+  }
+  if (Array.isArray(state.headerEpochs) && state.headerEpochs.length > MAX_HEADER_EPOCHS) {
+    state.headerEpochs.splice(0, state.headerEpochs.length - MAX_HEADER_EPOCHS)
+  }
+  if (Array.isArray(state.fileOps) && state.fileOps.length > MAX_FILE_OPS) {
+    const removed = state.fileOps.splice(0, state.fileOps.length - MAX_FILE_OPS)
+    for (const op of removed) state.fileOpsFloor = Math.max(state.fileOpsFloor || 0, safeInt(op.seq))
+  }
+  if (Object.keys(state.callNames).length > MAX_CALL_NAMES) {
+    const keys = Object.keys(state.callNames)
+    for (const key of keys.slice(0, keys.length - MAX_CALL_NAMES)) delete state.callNames[key]
+  }
+}
+
+/**
+ * Buffer one span of the open step (`[kind, start, end]`, absolute ms). The
+ * buffer is bounded: a hostile stream or replay cannot grow the persisted state,
+ * and a dropped span simply becomes part of the step/end residue.
+ */
+function pushStepSpan(state, span) {
+  if (!Array.isArray(span)) return
+  const start = span[1]
+  const end = span[2]
+  if (typeof start !== 'number' || !Number.isFinite(start)) return
+  if (typeof end !== 'number' || !Number.isFinite(end) || end <= start) return
+  if (!Array.isArray(state.stepSpans)) state.stepSpans = []
+  if (state.stepSpans.length >= MAX_STEP_SPANS) return
+  state.stepSpans.push([span[0], start, end])
+}
+
+/** A non-negative integer for the wire; non-finite/hostile input degrades to 0. */
+function safeInt(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : 0
+}
+
+function firstText(blocks) {
+  if (!Array.isArray(blocks)) return ''
+  for (const block of blocks) {
+    if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string' && block.text.trim() !== '') {
+      return block.text
+    }
+  }
+  return ''
+}
+
+function skillNameOf(message) {
+  if (message === null || typeof message !== 'object') return ''
+  const text = firstText(Array.isArray(message.content) ? message.content : [])
+  const match = text.match(/<skill_content\s+name="([^"]+)"/)
+  return match === null ? '' : match[1]
+}
+
+function isInjectionSource(source) {
+  if (source === null || source === undefined || typeof source !== 'object') return false
+  return (typeof source.kind === 'string' && source.kind !== '' && source.kind !== 'user') || typeof source.form === 'string'
+}
+
+function injectionSourceName(source) {
+  if (source === null || source === undefined || typeof source !== 'object') return ''
+  if (source.kind === 'agent-instructions' && Array.isArray(source.changes)) {
+    const paths = []
+    for (const change of source.changes) {
+      const path = change && typeof change.path === 'string' ? change.path : ''
+      if (path !== '' && !paths.includes(path)) paths.push(path)
+    }
+    if (paths.length > 0) return paths.join(', ')
+  }
+  if (typeof source.plugin === 'string' && source.plugin !== '') return source.plugin
+  if (typeof source.kind === 'string' && source.kind !== '') return source.kind
+  return ''
+}
+
+function clampWaitMs(stepStart, endTime) {
+  const waits = Array.isArray(stepStart.waits) ? stepStart.waits : []
+  if (waits.length === 0) return 0
+  const spans = waits
+    .map(wait => ({ start: Math.max(stepStart.time, wait.start), end: Math.min(endTime, wait.end) }))
+    .filter(span => span.end > span.start)
+    .sort((a, b) => (a.start - b.start) || (a.end - b.end))
+  let total = 0
+  let cursor = -Infinity
+  for (const span of spans) {
+    const start = Math.max(span.start, cursor)
+    if (span.end > start) {
+      total += span.end - start
+      cursor = span.end
+    }
+  }
+  return total
+}
+
+/**
+ * Fold one committed session event. Returns the same state reference when the
+ * event cannot change the served value (the registry's change feed relies on
+ * `Object.is`), otherwise a fresh bounded state.
+ *
+ * @param {object} state previous `createState()`-shaped state
+ * @param {{type:string,seq:number,time?:number,data?:object,surfaceOp?:unknown}} event
+ * @returns {object} next state
+ */
+export function applyContextEvent(state, event) {
+  if (state === null || typeof state !== 'object') state = createState()
+  if (event === null || typeof event !== 'object' || typeof event.type !== 'string') return state
+  const data = event.data !== null && typeof event.data === 'object' ? event.data : undefined
+  try {
+    switch (event.type) {
+      case 'request/header': {
+        const header = data && data.header !== null && typeof data.header === 'object' ? data.header : undefined
+        const next = cloneState(state)
+        next.toolsTokens = estimateToolsTokens(header)
+        next.toolDefs = header !== undefined && Array.isArray(header.tools) ? header.tools.length : 0
+        if (header !== undefined) {
+          const tools = Array.isArray(header.tools) ? header.tools.slice(0, 100).map(tool => {
+            const item = tool !== null && typeof tool === 'object' ? tool : {}
+            return { name: typeof item.name === 'string' ? item.name.slice(0, 120) : '?' }
+          }) : []
+          next.headerEpochs.push({ seq: event.seq, time: timeOf(event), tools })
+        }
+        const config = header && header.config !== null && typeof header.config === 'object' ? header.config : undefined
+        if (config && typeof config.model === 'string') next.model = config.model
+        if (config && typeof config.provider === 'string') next.provider = config.provider
+        return next
+      }
+      case 'request/context': {
+        if (data === undefined) return state
+        let next
+        if (typeof data.contextWindow === 'number') {
+          next = next || cloneState(state)
+          next.contextWindow = data.contextWindow
+        }
+        if (typeof data.model === 'string') {
+          next = next || cloneState(state)
+          next.model = data.model
+        }
+        if (typeof data.provider === 'string') {
+          next = next || cloneState(state)
+          next.provider = data.provider
+        }
+        return next || state
+      }
+      case 'system/message': {
+        if (!isSurfaceEvent(event)) return state
+        const next = cloneState(state)
+        applySurface(next, event, 'system', deriveEventMessage(event))
+        trimState(next)
+        return next
+      }
+      case 'user/message':
+      case 'developer/message': {
+        const message = deriveEventMessage(event)
+        // The image tally is independent of the CURRENT surface: the desktop
+        // activity card counts every user upload in the log, including ones a
+        // later compaction replaced (docs §8.1).
+        const images = event.type === 'user/message' ? countImageBlocks(message) : 0
+        if (!isSurfaceEvent(event)) {
+          if (images === 0) return state
+          const next = cloneState(state)
+          next.activity.images += images
+          return next
+        }
+        const source = message && message.source
+        // Skill machinery is its own bucket: skill invocations and the
+        // available-skills catalog are durable user/message injections that the
+        // plain injected-context check would absorb.
+        const isSkillSource = source !== undefined && source !== null
+          && (source.kind === 'skill-invocation' || source.kind === 'skill-catalog')
+        const cat = event.type === 'developer/message' || isInjectionSource(source)
+          ? (isSkillSource ? 'skill' : 'inject')
+          : 'user'
+        const next = cloneState(state)
+        if (images > 0) next.activity.images += images
+        applySurface(next, event, cat, message)
+        if (event.type === 'developer/message' || isInjectionSource(source)) {
+          const source = message && message.source
+          const record = { seq: event.seq, time: timeOf(event), kind: 'inject' }
+          const form = source && typeof source.form === 'string' && source.form !== '' ? source.form : 'context'
+          record.form = form
+          if (source && source.kind === 'skill-invocation') {
+            record.sub = 'skill'
+            record.name = typeof source.name === 'string' ? source.name : '?'
+            next.counts.skillLoads += 1
+          } else if (message !== null) {
+            const label = injectionSourceName(source)
+            if (label !== '') record.name = label
+          }
+          next.events.push(record)
+          next.counts.injects += 1
+        } else {
+          next.counts.humanInputs += 1
+        }
+        trimState(next)
+        return next
+      }
+      case 'assistant/message': {
+        const message = deriveEventMessage(event)
+        const eventTime = timeOf(event)
+        const usage = data && data.usage !== null && typeof data.usage === 'object' ? data.usage : null
+        // `null` means "no readable output bucket", not a fabricated 0 (see the
+        // output-speed rule: it only counts when provider usage is readable).
+        const output = usage !== null ? tokenCountOf(usage.outputTokens) : null
+        const answerText = firstText(message && message.content)
+        const next = cloneState(state)
+        // The request record is the prompt this response was assembled for:
+        // capture it BEFORE the response joins the surface.
+        const record = {
+          seq: event.seq,
+          time: eventTime,
+          ...(data && Number.isFinite(data.turn) ? { turn: data.turn } : {}),
+          ...(data && Number.isFinite(data.step) ? { step: data.step } : {}),
+          system: next.systemTokens,
+          tools: next.toolsTokens,
+          total: next.systemTokens + next.toolsTokens
+            + next.sums.user + next.sums.inject + next.sums.skill + next.sums.assistant + next.sums.tool,
+        }
+        for (const cat of MESSAGE_CATS) {
+          if (next.sums[cat] > 0) record[cat] = next.sums[cat]
+        }
+        // v2 request detail (docs §8.1): the surface node counts the request was
+        // assembled from (`system` is always the one live system prompt, `tools`
+        // the current header's tool definition count) and the provider-reported
+        // billed prompt / output buckets.
+        const items = { system: 1, tools: next.toolDefs }
+        for (const cat of MESSAGE_CATS) {
+          if (next.surfaceCounts[cat] > 0) items[cat] = next.surfaceCounts[cat]
+        }
+        record.items = items
+        if (usage !== null) {
+          const input = tokenCountOf(usage.inputTokens)
+          const cacheRead = tokenCountOf(usage.cacheReadTokens)
+          const cacheWrite = tokenCountOf(usage.cacheWriteTokens)
+          if (input !== null || cacheRead !== null || cacheWrite !== null || output !== null) {
+            record.prompt = (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0)
+            if (output !== null) record.output = output
+          }
+        }
+        next.requests.push(record)
+        // v2 last answer: the newest assistant text, whitespace-collapsed and
+        // bounded; tool-only steps leave the previous preview in place.
+        if (answerText !== '') {
+          const compressed = answerText.replace(/\s+/g, ' ').trim()
+          if (compressed !== '') {
+            next.lastAnswer = compressed.length > MAX_LAST_ANSWER ? compressed.slice(0, MAX_LAST_ANSWER) : compressed
+          }
+        }
+        // v2 timing split (docs §8.1): only an open step with an observable
+        // first token is priced; an unattributed stream lands in the card's
+        // `other` residue instead of charging the wait.
+        const stepStart = state.stepStart
+        if (stepStart !== undefined && Number.isFinite(stepStart.time)) {
+          const stream = data && data.stream
+          const firstToken = typeof stepStart.firstToken === 'number'
+            ? stepStart.firstToken
+            : firstTokenTimeOfStream(stream)
+          if (firstToken !== undefined) {
+            const decodeSpans = decodeSpansOfStream(stream, eventTime)
+            let decodeStart = firstToken
+            for (const span of decodeSpans) decodeStart = Math.min(decodeStart, span.start)
+            next.timing.ttftMs += durOf(stepStart.time, decodeStart)
+            next.timing.waitCount += 1
+            pushStepSpan(next, [SPAN_WAIT, stepStart.time, decodeStart])
+            // The decode blocks tile [decodeStart, eventTime] in stream order; the
+            // first block reaches back to the wait boundary, later ones keep their
+            // own start so the rows and the strip read the same window.
+            let pushedAny = false
+            for (const span of decodeSpans) {
+              const to = Math.min(eventTime, span.end)
+              if (to <= span.start) continue
+              const start = pushedAny ? span.start : decodeStart
+              if (to > start) {
+                pushStepSpan(next, [DECODE_SPAN_KINDS[span.kind], start, to])
+                pushedAny = true
+              }
+            }
+            const tally = decodeTallyOfStream(stream, eventTime)
+            next.timing.reasoningMs += tally.spans.reasoning
+            next.timing.reasoningCount += tally.blocks.reasoning
+            next.timing.textMs += tally.spans.text
+            next.timing.textCount += tally.blocks.text
+            next.timing.toolArgMs += tally.spans.toolarg
+            next.timing.toolArgCount += tally.blocks.toolarg
+            // Output speed pairs the first-token anchor with the provider's own
+            // output count; it only counts when both are known.
+            if (output !== null) {
+              next.timing.speedMs += durOf(firstToken, eventTime)
+              next.timing.speedTokens += output
+            }
+          }
+        }
+        if (isSurfaceEvent(event)) {
+          const node = applySurface(next, event, 'assistant', message)
+          if (node.tokens > 0 && answerText !== '') next.counts.answers += 1
+        }
+        trimState(next)
+        return next
+      }
+      case 'assistant/attempt': {
+        // An attempt that committed no surface message can still carry the
+        // step's first token (a retried / aborted call): stamp it on the open
+        // step so TTFT stays real instead of falling into the residue.
+        const start = state.stepStart
+        if (start === undefined || typeof start.firstToken === 'number') return state
+        const first = firstTokenTimeOfStream(data && data.stream)
+        if (first === undefined) return state
+        const next = cloneState(state)
+        next.stepStart.firstToken = first
+        return next
+      }
+      case 'tool/call': {
+        const callId = data && typeof data.callId === 'string' ? data.callId : ''
+        const name = data && typeof data.name === 'string' ? data.name : ''
+        if (callId === '' || name === '') return state
+        const next = cloneState(state)
+        const file = fileCallMeta(name, data && data.arguments)
+        next.callNames[callId] = { name, start: timeOf(event), ...(file !== null ? { file } : {}) }
+        trimState(next)
+        return next
+      }
+      case 'tool/result': {
+        const message = deriveEventMessage(event)
+        const source = message && message.source !== null && typeof message.source === 'object' ? message.source : undefined
+        const callId = source && typeof source.callId === 'string' ? source.callId : ''
+        const pending = callId !== '' ? state.callNames[callId] : undefined
+        const eventTime = timeOf(event)
+        if (!isSurfaceEvent(event)) {
+          if (pending === undefined) return state
+          const ops = fileOpsOf(event, message, pending)
+          if (ops.length === 0) return state
+          const next = cloneState(state)
+          next.fileOps.push(...ops)
+          if (callId !== '') delete next.callNames[callId]
+          trimState(next)
+          return next
+        }
+        const next = cloneState(state)
+        const node = applySurface(next, event, 'tool', message)
+        if (pending !== undefined) {
+          next.fileOps.push(...fileOpsOf(event, message, pending))
+          next.counts.toolCalls += 1
+          next.toolNames[pending.name] = (next.toolNames[pending.name] || 0) + 1
+          // v2 activity: classify the paired run by its durable tool name.
+          const activityKey = toolActivityOf(pending.name)
+          if (activityKey !== '') next.activity[activityKey] += 1
+          // v2 tool timing: the paired run's wall slice, priced on the same
+          // call/result pairing the tool tallies use.
+          next.timing.toolsMs += durOf(pending.start, eventTime)
+          next.timing.toolCount += 1
+          pushStepSpan(next, [SPAN_TOOLS, pending.start, eventTime])
+          if (pending.name === 'ask_user_question' && next.stepStart !== undefined) {
+            next.stepStart.waits.push({ start: pending.start, end: eventTime })
+          }
+          if (callId !== '') delete next.callNames[callId]
+          // A skill tool's result is harness-injected skill content: give it the
+          // skill bucket instead of burying it among ordinary tool results.
+          if (pending.name === 'skill') {
+            const skillName = skillNameOf(message)
+            if (skillName !== '') {
+              next.sums.tool = Math.max(0, next.sums.tool - node.tokens)
+              node.cat = 'skill'
+              next.sums.skill += node.tokens
+              next.surfaceCounts.tool = Math.max(0, next.surfaceCounts.tool - 1)
+              next.surfaceCounts.skill += 1
+              next.counts.skillLoads += 1
+              next.events.push({ seq: event.seq, time: eventTime, kind: 'inject', form: 'instructions', sub: 'skill', name: skillName })
+              next.counts.injects += 1
+            }
+          }
+        } else if (node.tool !== undefined) {
+          // No paired call (a trimmed window): still count the tool run.
+          next.counts.toolCalls += 1
+          next.toolNames[node.tool] = (next.toolNames[node.tool] || 0) + 1
+        }
+        trimState(next)
+        return next
+      }
+      case 'step/start': {
+        const next = cloneState(state)
+        next.stepStart = { time: timeOf(event), waits: [] }
+        // A superseded step's span buffer belongs to the old window.
+        delete next.stepSpans
+        return next
+      }
+      case 'step/end': {
+        if (state.stepStart === undefined) return state
+        const next = cloneState(state)
+        const start = state.stepStart
+        const endTime = timeOf(event)
+        const duration = Math.max(0, endTime - start.time)
+        next.wallMs = state.wallMs + Math.max(0, duration - clampWaitMs(start, endTime))
+        // Tile the step's span buffer across [step start, step end]: first-wins
+        // de-overlap so parallel tool runs paint their union once, and every hole
+        // is filled with the `other` residue so the strip stays gapless.
+        const painted = []
+        for (const span of Array.isArray(state.stepSpans) ? state.stepSpans : []) {
+          const from = Math.max(start.time, span[1])
+          const to = Math.min(endTime, span[2])
+          if (to > from) painted.push([span[0], from, to])
+        }
+        painted.sort((left, right) => (left[1] - right[1]) || (left[2] - right[2]))
+        next.spans = state.spans.slice()
+        let cursor = start.time
+        for (const span of painted) {
+          const from = Math.max(cursor, span[1])
+          if (span[2] <= from) continue
+          if (from > cursor) next.spans.push([SPAN_OTHER, cursor, from])
+          next.spans.push([span[0], from, span[2]])
+          cursor = span[2]
+        }
+        if (endTime > cursor) next.spans.push([SPAN_OTHER, cursor, endTime])
+        if (next.spans.length > MAX_SPANS) next.spans = next.spans.slice(next.spans.length - MAX_SPANS)
+        delete next.stepStart
+        delete next.stepSpans
+        if (next.approvals !== undefined && Object.keys(next.approvals).length === 0) delete next.approvals
+        return next
+      }
+      case 'approval/asked': {
+        if (state.stepStart === undefined) return state
+        const id = data && typeof data.id === 'string' ? data.id : ''
+        if (id === '') return state
+        const next = cloneState(state)
+        next.approvals = { ...(next.approvals || {}), [id]: timeOf(event) }
+        return next
+      }
+      case 'approval/decided': {
+        const id = data && typeof data.id === 'string' ? data.id : ''
+        const askedAt = id !== '' && state.approvals !== undefined ? state.approvals[id] : undefined
+        if (askedAt === undefined || state.stepStart === undefined) return state
+        const next = cloneState(state)
+        next.stepStart.waits.push({ start: askedAt, end: timeOf(event) })
+        delete next.approvals[id]
+        return next
+      }
+      case 'compaction/summary':
+      case 'compaction/prune': {
+        const next = cloneState(state)
+        const compaction = event.type === 'compaction/summary'
+        next.events.push({
+          seq: event.seq,
+          time: timeOf(event),
+          kind: compaction ? 'compaction' : 'prune',
+          ...(data && Number.isFinite(data.shadowedTokenCount) ? { tokens: data.shadowedTokenCount } : {}),
+          ...(compaction && data && Array.isArray(data.shadowedSeqs) ? { count: data.shadowedSeqs.length } : {}),
+        })
+        if (compaction) next.counts.compactions += 1
+        else next.counts.prunes += 1
+        trimState(next)
+        return next
+      }
+      default:
+        return state
+    }
+  } catch (_) {
+    // Durable logs are untrusted input and the registry drives this fold with
+    // no error boundary: drop a malformed event whole instead of stalling.
+    return state
+  }
+}
+
+function timeOf(event) {
+  return typeof event.time === 'number' && Number.isFinite(event.time) ? event.time : 0
+}
+
+function sortedToolNames(state) {
+  return Object.entries(state.toolNames)
+    .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0]))
+    .slice(0, MAX_TOOL_NAMES)
+    .map(([name, count]) => ({ name, count }))
+}
+
+/** The projection's wire value: a detached, bounded, lossless JSON snapshot. */
+export function contextView(state) {
+  const current = {
+    system: state.systemTokens,
+    tools: state.toolsTokens,
+    user: state.sums.user,
+    inject: state.sums.inject,
+    skill: state.sums.skill,
+    assistant: state.sums.assistant,
+    tool: state.sums.tool,
+  }
+  current.total = current.system + current.tools + current.user + current.inject + current.skill + current.assistant + current.tool
+  const activity = state.activity !== null && typeof state.activity === 'object' ? state.activity : {}
+  const timingRaw = state.timing !== null && typeof state.timing === 'object' ? state.timing : {}
+  // The six-way split: the five measured buckets plus the residue, so the card's
+  // percentages always add up and `otherMs` is never negative (docs §8.1).
+  const wallMs = safeInt(state.wallMs)
+  const ttftMs = safeInt(timingRaw.ttftMs)
+  const reasoningMs = safeInt(timingRaw.reasoningMs)
+  const textMs = safeInt(timingRaw.textMs)
+  const toolArgMs = safeInt(timingRaw.toolArgMs)
+  const toolsMs = safeInt(timingRaw.toolsMs)
+  const measuredMs = ttftMs + reasoningMs + textMs + toolArgMs + toolsMs
+  return {
+    v: 1,
+    ...(state.model !== undefined ? { model: state.model } : {}),
+    ...(state.provider !== undefined ? { provider: state.provider } : {}),
+    ...(state.contextWindow !== undefined ? { contextWindow: state.contextWindow } : {}),
+    current,
+    counts: {
+      humanInputs: state.counts.humanInputs,
+      answers: state.counts.answers,
+      toolCalls: state.counts.toolCalls,
+      skillLoads: state.counts.skillLoads,
+      injects: state.counts.injects,
+      compactions: state.counts.compactions,
+      prunes: state.counts.prunes,
+    },
+    // v2 activity ledger (docs §8.1): `userInputs` mirrors the v1 `humanInputs`.
+    activity: {
+      userInputs: state.counts.humanInputs,
+      reads: safeInt(activity.reads),
+      writes: safeInt(activity.writes),
+      searches: safeInt(activity.searches),
+      images: safeInt(activity.images),
+    },
+    tools: { total: state.counts.toolCalls, names: sortedToolNames(state) },
+    timing: {
+      wallMs,
+      ttftMs,
+      reasoningMs,
+      textMs,
+      toolArgMs,
+      toolsMs,
+      otherMs: Math.max(0, wallMs - measuredMs),
+      waitCount: safeInt(timingRaw.waitCount),
+      reasoningCount: safeInt(timingRaw.reasoningCount),
+      textCount: safeInt(timingRaw.textCount),
+      toolArgCount: safeInt(timingRaw.toolArgCount),
+      toolCount: safeInt(timingRaw.toolCount),
+      speedTokens: safeInt(timingRaw.speedTokens),
+      speedMs: safeInt(timingRaw.speedMs),
+    },
+    // v2 timeline: newest MAX_SPANS segments, each [kind, start, end].
+    spans: (Array.isArray(state.spans) ? state.spans : []).map(span => [span[0], span[1], span[2]]),
+    // Slim browser index; full message/header bodies are fetched only when a row is opened.
+    surface: (Array.isArray(state.surface) ? state.surface : []).map(node => ({ ...node })),
+    archive: (Array.isArray(state.archive) ? state.archive : []).map(node => ({ ...node })),
+    headerEpochs: (Array.isArray(state.headerEpochs) ? state.headerEpochs : []).map(epoch => ({
+      ...epoch,
+      tools: Array.isArray(epoch.tools) ? epoch.tools.map(tool => ({ ...tool })) : [],
+    })),
+    fileOps: (Array.isArray(state.fileOps) ? state.fileOps : []).map(op => ({ ...op })),
+    ...(Number.isFinite(state.archiveFloor) ? { archiveFloor: state.archiveFloor } : {}),
+    ...(Number.isFinite(state.fileOpsFloor) ? { fileOpsFloor: state.fileOpsFloor } : {}),
+    ...(typeof state.lastAnswer === 'string' && state.lastAnswer !== '' ? { lastAnswer: state.lastAnswer } : {}),
+    requests: state.requests.map(record => ({
+      ...record,
+      ...(record.items !== undefined && record.items !== null ? { items: { ...record.items } } : {}),
+    })),
+    events: state.events.map(record => ({ ...record })),
+    truncated: { ...state.truncated },
+  }
+}
+
+/** The `mobileContext` projection definition registered on `ctx.sessionProjections`. */
+export const contextProjectionDefinition = {
+  key: 'mobileContext',
+  // v4 adds bounded file-operation records; older cache rows refold to populate File Activity.
+  stateVersion: 4,
+  stateSchema: passthroughSchema,
+  init: () => createState(),
+  apply: (state, event) => applyContextEvent(state, event),
+  wire: { viewSchema: passthroughSchema, view: state => contextView(state) },
+}
+
+
+// ---------------------------------------------------------------------------
+// Fleet (agent family) data
+// ---------------------------------------------------------------------------
+
+/** Harness services captured from the plugin context (absent on older hosts). */
+let hostSessions = null
+let hostProjections = null
+let hostAgents = null
+
+/**
+ * Capture the host services the fleet query needs. Registration is optional and
+ * lifecycle-bound: when a service is absent the query answers context-unavailable.
+ *
+ * @param {object} ctx gateway plugin context
+ * @returns {boolean} whether an injection was attempted
+ */
+export function registerContextServices(ctx) {
+  if (ctx === null || typeof ctx !== 'object' || typeof ctx.inject !== 'function') return false
+  try {
+    ctx.inject(['sessions', 'sessionProjections'], (sub) => {
+      if (!sub || !sub.sessions || !sub.sessionProjections) return
+      hostSessions = sub.sessions
+      hostProjections = sub.sessionProjections
+      sub.effect(() => () => {
+        hostSessions = null
+        hostProjections = null
+      })
+    })
+  } catch (_) { /* optional service */ }
+  try {
+    ctx.inject(['agents'], (sub) => {
+      if (!sub || !sub.agents) return
+      hostAgents = sub.agents
+      sub.effect(() => () => { hostAgents = null })
+    })
+  } catch (_) { /* optional service */ }
+  return true
+}
+
+const MAX_FLEET_AGENTS = 40
+
+function fleetNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0
+}
+
+/**
+ * Bound one host `agentTeam` projection value to the wire shape docs §8.2
+ * names: at most MAX_TEAM_ROWS members and MAX_TEAM_ROWS tasks, minimal fields,
+ * always a plain-JSON object. Returns null when the value carries no roster.
+ */
+function teamOf(agentTeam) {
+  if (agentTeam === null || typeof agentTeam !== 'object' || Array.isArray(agentTeam)) return null
+  if (!Array.isArray(agentTeam.members) && !Array.isArray(agentTeam.tasks)) return null
+  const members = []
+  for (const member of Array.isArray(agentTeam.members) ? agentTeam.members : []) {
+    if (members.length >= MAX_TEAM_ROWS) break
+    if (member === null || typeof member !== 'object') continue
+    if (typeof member.id !== 'string' || member.id === '') continue
+    const entry = {
+      id: member.id,
+      name: typeof member.name === 'string' ? member.name : '',
+      role: member.role === 'lead' ? 'lead' : 'teammate',
+      phase: TEAM_PHASES.has(member.phase) ? member.phase : 'active',
+    }
+    if (typeof member.error === 'string' && member.error !== '') entry.error = member.error
+    members.push(entry)
+  }
+  const tasks = []
+  for (const task of Array.isArray(agentTeam.tasks) ? agentTeam.tasks : []) {
+    if (tasks.length >= MAX_TEAM_ROWS) break
+    if (task === null || typeof task !== 'object') continue
+    if (typeof task.id !== 'string' || task.id === '') continue
+    const entry = {
+      id: task.id,
+      subject: typeof task.subject === 'string' ? task.subject : '',
+      status: typeof task.status === 'string' ? task.status : 'pending',
+    }
+    if (typeof task.ownerName === 'string' && task.ownerName !== '') entry.ownerName = task.ownerName
+    if (typeof task.ownerId === 'string' && task.ownerId !== '') entry.ownerId = task.ownerId
+    tasks.push(entry)
+  }
+  return {
+    members,
+    tasks,
+    failure: typeof agentTeam.failure === 'string' ? agentTeam.failure : '',
+  }
+}
+
+/**
+ * Pure fleet payload builder: `records` are session headers
+ * `{id, parentSessionId, origin, createdAt, title?}`; `snapshotOf(id)` returns
+ * one session's projection values (or null); `runningOf(id)` returns whether
+ * that agent is live.
+ *
+ * @param {string} currentSessionId
+ * @param {Array<object>} records
+ * @param {(id: string) => (object|null)} snapshotOf
+ * @param {(id: string) => boolean} [runningOf]
+ * @returns {object} context-fleet value
+ */
+export function buildFleetValue(currentSessionId, records, snapshotOf, runningOf) {
+  const byId = new Map()
+  for (const record of Array.isArray(records) ? records : []) {
+    if (record === null || typeof record !== 'object' || typeof record.id !== 'string' || record.id === '') continue
+    if (!byId.has(record.id)) byId.set(record.id, record)
+  }
+  const current = typeof currentSessionId === 'string' ? currentSessionId : ''
+  const resolve = typeof snapshotOf === 'function' ? snapshotOf : () => null
+  const isRunning = typeof runningOf === 'function' ? runningOf : () => false
+
+  // Ancestor chain (current -> root); guards against a cyclic or damaged header chain.
+  const chain = []
+  const chainSeen = new Set()
+  const ancestorLimit = MAX_FLEET_AGENTS * 5
+  let cursor = current
+  while (cursor !== '' && byId.has(cursor) && !chainSeen.has(cursor) && chain.length < ancestorLimit) {
+    chainSeen.add(cursor)
+    const record = byId.get(cursor)
+    chain.push(record)
+    cursor = typeof record.parentSessionId === 'string' ? record.parentSessionId : ''
+  }
+  const ancestors = chain.slice().reverse()
+  const rootId = ancestors.length > 0 ? ancestors[0].id : (byId.has(current) ? current : '')
+
+  // Subagent edges only: a fork shares the lineage field but is an independent conversation.
+  const childrenOf = new Map()
+  for (const record of byId.values()) {
+    const parent = record.parentSessionId
+    if (typeof parent !== 'string' || parent === '' || !byId.has(parent)) continue
+    if (record.origin !== 'subagent') continue
+    if (!childrenOf.has(parent)) childrenOf.set(parent, [])
+    childrenOf.get(parent).push(record)
+  }
+  for (const children of childrenOf.values()) {
+    children.sort((left, right) => (fleetNumber(left.createdAt) - fleetNumber(right.createdAt))
+      || String(left.id).localeCompare(String(right.id)))
+  }
+
+  const order = []
+  const visited = new Set()
+  const walk = (id, depth) => {
+    if (order.length >= MAX_FLEET_AGENTS || visited.has(id)) return
+    const record = byId.get(id)
+    if (record === undefined) return
+    visited.add(id)
+    order.push({ record, depth })
+    for (const child of childrenOf.get(id) || []) walk(child.id, depth + 1)
+  }
+  if (rootId !== '') walk(rootId, 0)
+  // The current session may be a fork (not a subagent edge): keep the ancestor
+  // chain visible after the subagent tree so the current card always renders.
+  for (let i = 0; i < ancestors.length && order.length < MAX_FLEET_AGENTS; i += 1) {
+    if (!visited.has(ancestors[i].id)) {
+      visited.add(ancestors[i].id)
+      order.push({ record: ancestors[i], depth: i })
+    }
+  }
+  // A family deeper than the bound must still show where the user is right now:
+  // trade the last tree row for the current agent.
+  if (!visited.has(current) && byId.has(current)) {
+    if (order.length >= MAX_FLEET_AGENTS) order.pop()
+    order.push({ record: byId.get(current), depth: Math.max(0, ancestors.length - 1) })
+  }
+
+  // Resolve every family snapshot once: the team roster comes from the ROOT
+  // session's `agentTeam` projection (each session's team projection is scoped
+  // to itself), and the per-agent cards read from the same snapshot.
+  const resolved = order.map(item => {
+    try {
+      return resolve(item.record.id)
+    } catch (_) {
+      return null
+    }
+  })
+  const valuesOf = index => resolved[index] !== null && typeof resolved[index] === 'object' ? resolved[index] : {}
+  let team = null
+  let teamPhaseById = null
+  const teamCandidateOrder = []
+  const rootIndex = order.findIndex(item => item.record.id === rootId)
+  if (rootIndex >= 0) teamCandidateOrder.push(rootIndex)
+  for (let index = 0; index < order.length; index += 1) if (index !== rootIndex) teamCandidateOrder.push(index)
+  for (const index of teamCandidateOrder) {
+    const candidate = teamOf(valuesOf(index).agentTeam)
+    if (candidate !== null) {
+      team = candidate
+      break
+    }
+  }
+  if (team !== null) {
+    teamPhaseById = new Map()
+    for (const member of team.members) teamPhaseById.set(member.id, member.phase)
+  }
+
+  const agents = []
+  let running = 0
+  let subagents = 0
+  for (let index = 0; index < order.length; index += 1) {
+    const item = order[index]
+    const record = item.record
+    const v = valuesOf(index)
+    const subagent = v.subagent !== null && typeof v.subagent === 'object' ? v.subagent : null
+    const pressure = v.contextPressure !== null && typeof v.contextPressure === 'object' ? v.contextPressure : null
+    const usage = v.tokenUsage !== null && typeof v.tokenUsage === 'object' ? v.tokenUsage : null
+    const stats = v.sessionStats !== null && typeof v.sessionStats === 'object' ? v.sessionStats : null
+    const context = v.mobileContext !== null && typeof v.mobileContext === 'object' ? v.mobileContext : null
+    const compositionSource = context !== null && context.current !== null && typeof context.current === 'object' ? context.current : null
+    const composition = {
+      system: fleetNumber(compositionSource && compositionSource.system),
+      tools: fleetNumber(compositionSource && compositionSource.tools),
+      user: fleetNumber(compositionSource && compositionSource.user),
+      inject: fleetNumber(compositionSource && compositionSource.inject),
+      skill: fleetNumber(compositionSource && compositionSource.skill),
+      assistant: fleetNumber(compositionSource && compositionSource.assistant),
+      tool: fleetNumber(compositionSource && compositionSource.tool),
+    }
+    composition.total = composition.system + composition.tools + composition.user + composition.inject
+      + composition.skill + composition.assistant + composition.tool
+    const isAgentRunning = isRunning(record.id) === true
+    if (isAgentRunning) running += 1
+    if (record.origin === 'subagent') subagents += 1
+    const title = typeof v.title === 'string' && v.title.trim() !== ''
+      ? v.title.trim()
+      : (typeof record.title === 'string' && record.title.trim() !== '' ? record.title.trim() : record.id)
+    const entry = {
+      sessionId: record.id,
+      title,
+      depth: item.depth,
+      isCurrent: record.id === current,
+      isRoot: record.id === rootId,
+      running: isAgentRunning,
+      createdAt: fleetNumber(record.createdAt),
+      composition,
+    }
+    if (typeof record.parentSessionId === 'string' && record.parentSessionId !== '') entry.parentSessionId = record.parentSessionId
+    if (subagent !== null && (subagent.mode === 'one-shot' || subagent.mode === 'continuable')) entry.mode = subagent.mode
+    if (subagent !== null && typeof subagent.label === 'string' && subagent.label !== '') entry.label = subagent.label
+    if (context !== null && typeof context.model === 'string') entry.model = context.model
+    if (context !== null && typeof context.provider === 'string') entry.provider = context.provider
+    if (pressure !== null && typeof pressure.contextWindow === 'number' && pressure.contextWindow > 0) entry.contextWindow = pressure.contextWindow
+    if (pressure !== null && typeof pressure.pressureTokens === 'number' && pressure.pressureTokens >= 0) entry.pressureTokens = pressure.pressureTokens
+    if (usage !== null) {
+      const total = fleetNumber(usage.uncachedInputTokens) + fleetNumber(usage.cacheReadTokens)
+        + fleetNumber(usage.cacheWriteTokens) + fleetNumber(usage.outputTokens)
+      if (total > 0) entry.tokensTotal = total
+    }
+    if (stats !== null && Number.isFinite(stats.turns)) entry.turns = stats.turns
+    if (stats !== null && Number.isFinite(stats.steps)) entry.steps = stats.steps
+    const timing = v.subagentTiming !== null && typeof v.subagentTiming === 'object' ? v.subagentTiming : null
+    if (timing !== null) {
+      const active = timing.active !== null && typeof timing.active === 'object' ? timing.active : null
+      const activeMs = fleetNumber(timing.settledMs)
+        + (active !== null ? Math.max(0, fleetNumber(active.through) - fleetNumber(active.since)) : 0)
+      if (activeMs > 0) entry.activeMs = activeMs
+    } else if (context !== null && context.timing !== null && typeof context.timing === 'object') {
+      const wallMs = fleetNumber(context.timing.wallMs)
+      if (wallMs > 0) entry.activeMs = wallMs
+    }
+    // v2 fleet card fields (docs §8.2): the newest answer preview and the team
+    // member phase; the current session defaults to `active` when the roster
+    // exists but does not list it.
+    if (context !== null && typeof context.lastAnswer === 'string' && context.lastAnswer !== '') {
+      entry.lastAnswer = context.lastAnswer
+    }
+    if (teamPhaseById !== null) {
+      const phase = teamPhaseById.get(record.id)
+      if (typeof phase === 'string' && TEAM_PHASES.has(phase)) entry.phase = phase
+      else if (record.id === current) entry.phase = 'active'
+    }
+    agents.push(entry)
+  }
+
+  return {
+    rootSessionId: rootId,
+    currentSessionId: current,
+    agents,
+    ...(team !== null ? { team } : {}),
+    counts: { agents: agents.length, running, subagents },
+  }
+}
+
+/**
+ * Serve one `context-fleet` request: list the host's sessions, walk the current
+ * agent's family, and summarize each member from its projection snapshot.
+ *
+ * @param {{type:string,sessionId?:string}} msg mobile request frame
+ * @returns {Promise<object>} wire frame
+ */
+export async function handleContextFleet(msg) {
+  const requestType = msg && msg.type
+  const sessionId = msg && typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+  if (sessionId === null) {
+    return { kind: 'error', code: 'bad-request', requestType, message: 'context-fleet requires a sessionId' }
+  }
+  if (hostSessions === null || hostProjections === null || typeof hostSessions.list !== 'function'
+    || typeof hostProjections.snapshot !== 'function') {
+    return unavailable(requestType, sessionId, 'Session services are unavailable on this host')
+  }
+  try {
+    const sessions = hostSessions.list()
+    const list = Array.isArray(sessions) ? sessions : []
+    const byId = new Map()
+    const records = []
+    for (const session of list) {
+      if (session === null || typeof session !== 'object') continue
+      const header = session.header !== null && typeof session.header === 'object' ? session.header : {}
+      const id = typeof session.id === 'string' && session.id !== '' ? session.id : (typeof header.id === 'string' ? header.id : '')
+      if (id === '' || byId.has(id)) continue
+      byId.set(id, session)
+      records.push({
+        id,
+        parentSessionId: typeof header.parentSession === 'string' ? header.parentSession : '',
+        origin: header.origin === 'subagent' ? 'subagent' : '',
+        createdAt: fleetNumber(header.createdAt),
+      })
+    }
+    const value = buildFleetValue(sessionId, records, (id) => {
+      const session = byId.get(id)
+      if (session === undefined) return null
+      const snapshot = hostProjections.snapshot(session)
+      return snapshot !== null && typeof snapshot === 'object' && snapshot.values !== null && typeof snapshot.values === 'object'
+        ? snapshot.values
+        : null
+    }, (id) => {
+      try {
+        return !!(hostAgents && typeof hostAgents.get === 'function' && hostAgents.get(id) && hostAgents.get(id).status === 'running')
+      } catch (_) {
+        return false
+      }
+    })
+    return { kind: 'context-fleet', sessionId, value }
+  } catch (_) {
+    return unavailable(requestType, sessionId, 'Unable to read the agent family')
+  }
+}
+
+/**
+ * Register the projection on the host's session-projection registry. Optional:
+ * hosts without the registry (older DSH) keep the gateway working, and the
+ * `context-dashboard` query then answers `context-unavailable`.
+ *
+ * @param {object} ctx gateway plugin context
+ * @returns {boolean} whether an injection was attempted
+ */
+export function registerContextProjection(ctx) {
+  if (ctx === null || typeof ctx !== 'object' || typeof ctx.inject !== 'function') return false
+  try {
+    ctx.inject(['sessionProjections'], (sub) => {
+      if (!sub || !sub.sessionProjections || typeof sub.sessionProjections.register !== 'function') return
+      sub.sessionProjections.register(contextProjectionDefinition)
+    })
+    return true
+  } catch (_) {
+    return false
+  }
+}
+
+function unavailable(requestType, sessionId, message) {
+  return { kind: 'error', code: 'context-unavailable', requestType, sessionId, message }
+}
+
+function boundedContextText(value, max, meta) {
+  if (typeof value !== 'string') return ''
+  if (value.length > max && meta) meta.truncated = true
+  return value.slice(0, max)
+}
+
+function eventContentText(event, meta) {
+  const data = event && event.data && typeof event.data === 'object' ? event.data : {}
+  if (event.type === 'request/header') {
+    const header = data.header && typeof data.header === 'object' ? data.header : {}
+    const tools = Array.isArray(header.tools) ? header.tools.slice(0, 100) : []
+    const lines = []
+    const config = header.config && typeof header.config === 'object' ? header.config : {}
+    if (typeof config.provider === 'string' || typeof config.model === 'string') {
+      lines.push(`Provider: ${config.provider || '—'} · Model: ${config.model || '—'}`)
+    }
+    for (const tool of tools) {
+      if (tool === null || typeof tool !== 'object') continue
+      const name = typeof tool.name === 'string' ? tool.name : 'Tool'
+      lines.push(`\n${name}${typeof tool.description === 'string' && tool.description !== '' ? `\n${tool.description}` : ''}`)
+      if (tool.parameters !== undefined || tool.inputSchema !== undefined || tool.schema !== undefined) {
+        let schema
+        try { schema = JSON.stringify(tool.parameters ?? tool.inputSchema ?? tool.schema) } catch (_) { schema = '' }
+        if (schema) lines.push(`\nSchema: ${boundedContextText(schema, 5000, meta)}`)
+      }
+    }
+    return lines.join('\n')
+  }
+  if (event.type === 'request/context') {
+    return [
+      `Model: ${typeof data.model === 'string' ? data.model : '—'}`,
+      `Provider: ${typeof data.provider === 'string' ? data.provider : '—'}`,
+      `Context window: ${Number.isFinite(data.contextWindow) ? data.contextWindow : '—'}`,
+    ].join('\n')
+  }
+  const message = event.type === 'user/message' ? data
+    : data.message !== null && typeof data.message === 'object' ? data.message : null
+  const blocks = message && Array.isArray(message.content) ? message.content : []
+  const lines = []
+  for (const block of blocks) {
+    if (block === null || typeof block !== 'object') continue
+    if ((block.type === 'text' || block.type === 'reasoning') && typeof block.text === 'string') {
+      lines.push(block.text)
+    } else if (block.type === 'tool-call') {
+      const name = typeof block.name === 'string' ? block.name : 'tool'
+      lines.push(`[${name}]${typeof block.arguments === 'string' && block.arguments !== '' ? `\n${boundedContextText(block.arguments, 8000, meta)}` : ''}`)
+    } else if (block.type === 'image') {
+      lines.push('[image attachment]')
+    } else {
+      let summary
+      try { summary = JSON.stringify(block) } catch (_) { summary = '' }
+      if (summary) lines.push(boundedContextText(summary, 1000, meta))
+    }
+  }
+  return lines.join('\n\n')
+}
+
+/** Fetch one durable event body only when the user opens that row in the browser. */
+export async function handleContextContent(api, msg) {
+  const requestType = msg && msg.type
+  const sessionId = msg && typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+  const seq = msg && Number.isSafeInteger(msg.seq) && msg.seq >= 0 ? msg.seq : null
+  if (sessionId === null || seq === null) {
+    return { kind: 'error', code: 'bad-request', requestType, ...(sessionId !== null ? { sessionId } : {}), message: 'context-content requires a sessionId and seq' }
+  }
+  if (!api || !api.sessions || typeof api.sessions.history !== 'function') {
+    return unavailable(requestType, sessionId, 'Session history is unavailable on this host')
+  }
+  try {
+    const history = await api.sessions.history({ sessionId, throughSeq: seq, beforeSeq: seq + 1, maxMessages: 1 })
+    if (history && history.kind === 'error') return { ...history, requestType, sessionId }
+    const entries = history && Array.isArray(history.events) ? history.events : []
+    let found = null
+    for (const entry of entries) {
+      const candidate = entry && typeof entry === 'object' && entry.event && typeof entry.event === 'object'
+        ? entry.event : entry
+      if (candidate && candidate.seq === seq && typeof candidate.type === 'string') { found = candidate; break }
+    }
+    if (found === null) return unavailable(requestType, sessionId, 'The selected context item is no longer available')
+    const allowed = new Set(['system/message', 'developer/message', 'user/message', 'assistant/message', 'tool/result', 'request/header', 'request/context'])
+    if (!allowed.has(found.type)) return { kind: 'error', code: 'bad-request', requestType, sessionId, message: 'The selected event is not a context item' }
+    const textMeta = { truncated: false }
+    const text = boundedContextText(eventContentText(found, textMeta), 24000, textMeta)
+    return {
+      kind: 'context-content', sessionId, seq,
+      value: { seq, time: timeOf(found), type: found.type, text, ...(textMeta.truncated ? { truncated: true } : {}) },
+    }
+  } catch (_) {
+    return unavailable(requestType, sessionId, 'Unable to read the selected context item')
+  }
+}
+
+/**
+ * Serve one `context-dashboard` request: read the session's projection snapshot
+ * (which carries every registered wire unit) and augment `mobileContext` with
+ * the harness's official breakdown / usage / stats projections.
+ *
+ * @param {object} api DSH host adapter (needs `sessions.history`)
+ * @param {{type:string,sessionId?:string}} msg mobile request frame
+ * @returns {Promise<object>} wire frame
+ */
+export async function handleContextQuery(api, msg) {
+  const requestType = msg && msg.type
+  const sessionId = msg && typeof msg.sessionId === 'string' && msg.sessionId.trim() !== '' ? msg.sessionId.trim() : null
+  if (sessionId === null) {
+    return { kind: 'error', code: 'bad-request', requestType, message: 'context-dashboard requires a sessionId' }
+  }
+  if (!api || !api.sessions || typeof api.sessions.history !== 'function') {
+    return unavailable(requestType, sessionId, 'Session history is unavailable on this host')
+  }
+  try {
+    // The host adapter returns the raw `session/follow` snapshot (no `kind`):
+    // only the gateway's proxyQuery helper stamps a kind. Accept both shapes so
+    // the handler works with the adapter directly and with legacy mocks.
+    const history = await api.sessions.history({ sessionId, maxMessages: 1 })
+    if (history && history.kind === 'error') {
+      return { ...history, requestType, sessionId }
+    }
+    const projections = history !== null && typeof history === 'object'
+      && history.projections !== null && typeof history.projections === 'object'
+      ? history.projections
+      : undefined
+    if (projections === undefined) {
+      return unavailable(requestType, sessionId, 'The session projection snapshot is unavailable')
+    }
+    const values = projections && projections.values !== null && typeof projections.values === 'object' ? projections.values : {}
+    const context = values.mobileContext
+    if (context === null || typeof context !== 'object') {
+      return unavailable(requestType, sessionId, 'The context projection is not registered on this host')
+    }
+    const usage = values.tokenUsage !== null && typeof values.tokenUsage === 'object' ? values.tokenUsage : null
+    const stats = values.sessionStats !== null && typeof values.sessionStats === 'object' ? values.sessionStats : null
+    const breakdown = values.contextBreakdown !== null && typeof values.contextBreakdown === 'object' ? values.contextBreakdown : null
+    return {
+      kind: 'context-dashboard',
+      sessionId,
+      asOfSeq: projections ? projections.asOfSeq : undefined,
+      value: {
+        ...context,
+        breakdown,
+        usage,
+        stats,
+      },
+    }
+  } catch (_) {
+    return unavailable(requestType, sessionId, 'Unable to read the context projection')
+  }
+}