@qvac/core 0.1.1 → 0.1.2

package/tui/app.mjs

@@ -0,0 +1,4179 @@
+// The bare-tui model for the interactive chat demo — split out from
+// index.mjs (which just wires real Core/Client/Harness and runs it) so it
+// can be driven headlessly with injected streams and a fake engine, per
+// bare-tui's CLAUDE.md guidance on testing without a real TTY.
+import tui from 'bare-tui'
+import { spawn } from 'child_process'
+import fs from 'fs'
+import { settingsDimension, TOOLSETS } from '@qvac/harness'
+import os from 'os'
+import path from 'path'
+import process from 'process'
+import {
+  ASANA_MCP_CREDENTIAL_KEY,
+  ASANA_OAUTH_STATE_KEY,
+  connectAsana,
+  connectGoogle,
+  connectNotion,
+  connectSpotify,
+  oauthKeySpec,
+  NOTION_MCP_CREDENTIAL_KEY,
+  NOTION_OAUTH_STATE_KEY,
+  scopedKey,
+  SPOTIFY_CREDENTIAL_KEY,
+  SPOTIFY_OAUTH_STATE_KEY
+} from '../dist-lib/lib/oauth.js'
+import {
+  busyStatus,
+  findPendingApproval,
+  runInFlight,
+  runningAgentTurn,
+  turnsFromChunks
+} from './lib/render.mjs'
+import { exportMarkdown } from './lib/export.mjs'
+import { paintSelection, selectionText } from './lib/select.mjs'
+import { center, splash } from './lib/splash.mjs'
+import { wrapBlock, wrapLine } from './lib/wrap.mjs'
+import { knowledgeCommand } from './lib/knowledge-command.mjs'
+import { saveUniqueFile } from './lib/save-file.mjs'
+import {
+  configureActions,
+  isReady,
+  setupAction,
+  setupActions,
+  setupPlan,
+  statusLabel
+} from './lib/setup.mjs'
+import {
+  firstSelectable,
+  moveRows,
+  nextSelectable,
+  SIDEBAR_COLS,
+  sidebarRows
+} from './lib/sidebar.mjs'
+import { UPLOAD_FRAME_BYTES, writeFrame } from './lib/upload-frames.mjs'
+
+const { batch, quit, key, textinput, tick, viewport, spinner, style } = tui
+
+function filePending(file) {
+  return ['uploading', 'pending', 'running'].includes(file.state)
+}
+
+function fileStatusText(file) {
+  const processor = file.processors.find((entry) => entry.processorId === 'rag')
+  const progress = file.state === 'uploading' ? file.uploadProgress : processor?.progress
+  let text = `${file.fileName.replace(/\s+/g, ' ')} · ${file.readyForChat ? 'ready for chat' : file.state}`
+  if (progress && (file.state === 'uploading' || file.state === 'running')) {
+    const { completed, total, unit } = progress
+    text += total
+      ? ` · ${Math.round((completed / total) * 100)}% (${completed}/${total} ${unit})`
+      : ` · ${completed} ${unit}`
+  }
+  if (file.reason) text += ` · ${file.reason.replace(/\s+/g, ' ')}`
+  return text
+}
+
+// Every entry is dispatched by _command and documented in /help; `palette: true`
+// is the subset the `/` autocomplete advertises. The rest still run when typed in
+// full — they're reachable through the menu (ctrl+p), so they no longer clutter
+// the dropdown. See command-palette.ts, which pins these three lists together.
+const COMMANDS = [
+  { name: 'help', desc: 'list every /command with a one-liner', palette: true },
+  {
+    name: 'menu',
+    desc: 'open the navigable menu (Agent, Chat, Models, Voice, …) — also ctrl+p',
+    palette: true
+  },
+  { name: 'new-chat', desc: 'create and switch to a new chat', palette: true },
+  { name: 'agents', desc: 'switch between your agents (interactive picker)', palette: true },
+  { name: 'agent', desc: 'show, list, create, rename, or switch the active agent' },
+  {
+    name: 'activity',
+    desc: "list the active agent's tool-call activity (allowed/denied/auto/skip-all/blocked)"
+  },
+  { name: 'chats', desc: 'switch between your chats (interactive picker)', palette: true },
+  { name: 'chat', desc: 'show, create, switch, rename, delete a chat, or toggle web search / rag' },
+  {
+    name: 'group',
+    desc: 'list, create, rename, delete chat groups; move a chat in or out of one',
+    palette: true
+  },
+  { name: 'knowledge', desc: 'list, download, or remove knowledge in the active chat' },
+  { name: 'files', desc: 'show file readiness, progress, and failures in this chat' },
+  {
+    name: 'skills',
+    desc: 'browse installed skills; ↑/↓ move, space toggles each on/off',
+    palette: true
+  },
+  { name: 'tools', desc: 'browse installed tools; ↑/↓ move, space toggles each on/off' },
+  { name: 'skill', desc: 'toggle a single skill on/off' },
+  { name: 'tool', desc: 'toggle a single tool on/off' },
+  { name: 'scope', desc: 'switch skills/tools scope between all and selected' },
+  {
+    name: 'permissions',
+    desc: "the agent's approval mode and its toolset switches; space toggles"
+  },
+  { name: 'attach', desc: 'attach one or more local files to this chat by path', palette: true },
+  {
+    name: 'save',
+    desc: 'download the latest (or n-th) attachment to ~/Downloads',
+    palette: true
+  },
+  {
+    name: 'export',
+    desc: 'write the last run (or last n) to a markdown file — thinking, answer, tools',
+    palette: true
+  },
+  { name: 'join', desc: "join another device's mesh with its invite (replaces this one)" },
+  { name: 'cred', desc: 'set a credential value for this agent' },
+  { name: 'connect', desc: 'OAuth-connect a skill for this agent' },
+  {
+    name: 'my-device',
+    desc: 'CPU/GPU inventory for this device (manufacturer, cores, drivers, …)'
+  },
+  { name: 'models', desc: 'browse every model in the SDK registry (optional type filter)' },
+  { name: 'image', desc: 'show or set the agent’s image defaults (model, steps, size)' },
+  { name: 'speak', desc: 'synthesize speech from text to a WAV file (TTS)' },
+  { name: 'speak-stream', desc: 'synthesize speech per sentence over a duplex stream (TTS)' },
+  { name: 'transcribe', desc: 'transcribe a 16kHz mono s16 WAV file to text (STT)' },
+  { name: 'converse', desc: 'hands-free voice conversation via the mic (STT+LLM+TTS)' },
+  { name: 'record', desc: 'record N seconds from the mic (ffmpeg) and transcribe (STT)' }
+]
+
+// whitespace-separated tokens, quoted spans intact — `/attach` paths and the `/group` names
+function splitPaths(input) {
+  const paths = []
+  for (const m of input.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+    paths.push(m[1] ?? m[2] ?? m[3])
+  }
+  return paths
+}
+
+// @qvac/sdk's ModelRegistryEntryAddon values — kept as a set so an unknown
+// `/models <type>` becomes a usage notice instead of a silent empty list.
+const MODEL_TYPES = new Set([
+  'embeddings',
+  'diffusion',
+  'tts',
+  'ocr',
+  'vla',
+  'llm',
+  'whisper',
+  'bci',
+  'nmt',
+  'parakeet',
+  'classification',
+  'vad',
+  'other'
+])
+// Human synonyms — resolved before the SDK addon check so users don't have
+// to know the plugin name.
+const MODEL_TYPE_ALIASES = {
+  transcription: 'parakeet',
+  embedding: 'embeddings',
+  image: 'diffusion'
+}
+
+export function credKey(agentId, key) {
+  return scopedKey(agentId, key)
+}
+
+function openInBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : 'xdg-open'
+  try {
+    spawn(command, [url], { stdio: 'ignore' }).on('error', () => {})
+  } catch {}
+}
+
+// Fixed vertical rows around the transcript viewport (breakdown in the resize
+// handler) — the viewport height must be exactly `terminal.height - CHROME_ROWS`.
+const CHROME_ROWS = 8
+// Below these the styled blocks go non-positive and blow up padLine — clamp
+// and let the terminal truncate instead.
+// the tallest the `/` dropdown may grow — it overlays the transcript's last rows
+const PALETTE_ROWS = 10
+const MIN_WIDTH = 20
+// the transcript's own minimum — below it the sidebar stays hidden rather than
+// squeezing the conversation into a gutter
+const SIDEBAR_MIN_BODY = 40
+const MIN_HEIGHT = CHROME_ROWS + 1
+const MAX_INPUT_ROWS = 5
+const CURSOR_CELL = '\x1b[7m'
+const CURSOR_OFF = '\x1b[27m'
+const WHEEL_ROWS = 3
+// where the transcript's first content cell sits on screen: header (1) + top
+// border (1) down, border (1) + padding (1) across
+const TRANSCRIPT_TOP = 2
+const TRANSCRIPT_LEFT = 2
+// one row per beat while a selection drag is held past the transcript's edge
+const DRAG_SCROLL_MS = 60
+// shift+enter as a CSI-u report; most terminals send a bare CR and cannot say it at all,
+// hence alt+enter and ctrl+j (linefeed) alongside it
+const SHIFT_ENTER = '\x1b[13;2u'
+
+export const fg = {
+  cyan: style().foreground('brightcyan'),
+  dim: style().foreground('gray').italic(true),
+  white: style(),
+  amber: style().foreground('brightyellow'),
+  magenta: style().foreground('brightmagenta').bold(true),
+  err: style().foreground('brightred')
+}
+
+// wraps the engine's raw float32-LE PCM (what speak returns) in a minimal
+// IEEE-float WAV header so the file plays in any player. Mono, format tag 3.
+export function floatPcmToWav(pcm, sampleRate) {
+  const blockAlign = 4
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0, 'ascii')
+  header.writeUInt32LE(36 + pcm.length, 4)
+  header.write('WAVE', 8, 'ascii')
+  header.write('fmt ', 12, 'ascii')
+  header.writeUInt32LE(16, 16)
+  header.writeUInt16LE(3, 20)
+  header.writeUInt16LE(1, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(sampleRate * blockAlign, 28)
+  header.writeUInt16LE(blockAlign, 32)
+  header.writeUInt16LE(32, 34)
+  header.write('data', 36, 'ascii')
+  header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+// continuous 16kHz mono s16le raw PCM from the mic on stdout (macOS avfoundation)
+function micProcess(device) {
+  // prettier-ignore
+  return spawn('ffmpeg', ['-hide_banner', '-loglevel', 'quiet', '-f', 'avfoundation', '-i', device, '-ar', '16000', '-ac', '1', '-f', 's16le', '-'], { stdio: ['ignore', 'pipe', 'ignore'] })
+}
+
+// plays float32-LE mono PCM piped on stdin (what speakStream yields). ffplay has
+// no -ac; raw channel count goes through -ch_layout.
+function playerProcess(sampleRate) {
+  // prettier-ignore
+  return spawn('ffplay', ['-hide_banner', '-loglevel', 'quiet', '-autoexit', '-nodisp', '-f', 'f32le', '-ar', String(sampleRate), '-ch_layout', 'mono', '-i', '-'], { stdio: ['pipe', 'ignore', 'ignore'] })
+}
+
+// energy of an s16le PCM chunk (0..32768) — the conversation VAD's speech signal
+export function rmsS16(buf) {
+  const n = buf.length >> 1
+  if (!n) return 0
+  let sum = 0
+  for (let i = 0; i < n; i++) {
+    const s = buf.readInt16LE(i << 1)
+    sum += s * s
+  }
+  return Math.sqrt(sum / n)
+}
+
+// length of the leading run of COMPLETE sentences (up to the last terminator
+// followed by whitespace or end) — lets conversation mode speak each sentence as
+// the model produces it, leaving a half-typed trailing sentence unsent.
+export function completePrefixLen(text) {
+  let end = 0
+  for (const m of text.matchAll(/[.!?…]["')\]]?(\s|$)/g)) end = m.index + m[0].trimEnd().length
+  return end
+}
+
+// wraps raw s16le mono PCM in a 16kHz WAV header for the (unary) transcriber
+export function pcm16ToWav(pcm, sampleRate) {
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0, 'ascii')
+  header.writeUInt32LE(36 + pcm.length, 4)
+  header.write('WAVE', 8, 'ascii')
+  header.write('fmt ', 12, 'ascii')
+  header.writeUInt32LE(16, 16)
+  header.writeUInt16LE(1, 20)
+  header.writeUInt16LE(1, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(sampleRate * 2, 28)
+  header.writeUInt16LE(2, 32)
+  header.writeUInt16LE(16, 34)
+  header.write('data', 36, 'ascii')
+  header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+// /models overlay: status badge per row, loaded/downloaded first. `type`
+// echoes the active filter in the header so an empty filtered result is
+// distinguishable from an empty registry.
+const rankModel = (row) => (row.isLoaded ? 0 : row.isCached ? 1 : 2)
+export function sortModels(rows) {
+  return [...(rows ?? [])].sort(
+    (a, b) =>
+      rankModel(a) - rankModel(b) || a.type.localeCompare(b.type) || a.name.localeCompare(b.name)
+  )
+}
+
+// `state` (present when the overlay is interactive) carries the highlighted
+// `cursor` row and the agent's `currentModel` — enter on a row makes that the
+// agent's model, and the provider downloads it on the next run.
+export function formatModels(rows, type, state = null) {
+  const filter = type ? ` (type=${type})` : ''
+  if (!rows?.length) {
+    return [fg.dim.render(`(no models in the registry${filter})`)]
+  }
+  const sorted = sortModels(rows)
+  const nameWidth = Math.max(...sorted.map((r) => r.name.length))
+  const typeWidth = Math.max(...sorted.map((r) => r.type.length))
+  const mb = (n) => (n / (1024 * 1024)).toFixed(1) + 'MB'
+  const badge = (row) => {
+    if (row.isLoaded) return fg.magenta.render('● loaded    ')
+    if (row.isCached) return fg.cyan.render('● downloaded')
+    return fg.dim.render('○ not cached')
+  }
+  const hint = state ? '↑/↓ move · enter use (downloads on next run) · esc return' : 'esc to return'
+  const header = fg.dim.render(`Models on this device${filter} (${sorted.length}) — ${hint}`)
+  const lines = sorted.map((row, i) => {
+    const name = fg.white.render(row.name.padEnd(nameWidth))
+    const rowType = fg.dim.render(row.type.padEnd(typeWidth))
+    // absent actualSize arrives as 0 over the RPC (hyperschema's optional-uint
+    // default), so truthiness — not undefined — is the on-disk check
+    const size = row.actualSize
+      ? `${mb(row.actualSize)} / ${mb(row.expectedSize)}`
+      : mb(row.expectedSize)
+    const vision = row.supportsImages ? `  ${fg.cyan.render('◈ vision')}` : ''
+    const inUse = state?.currentModel === row.name ? `  ${fg.magenta.render('▸ in use')}` : ''
+    const point = state && i === state.cursor ? fg.magenta.render('❯ ') : '  '
+    return `${point}${badge(row)}  ${name}  ${rowType}  ${fg.dim.render(size)}${vision}${inUse}`
+  })
+  return [header, '', ...lines]
+}
+
+export const MODE_ROW = 'mode'
+
+// plain-language, one line each — PRD §3.4
+const TOOLSET_HINTS = {
+  'web-search': 'search the web',
+  knowledge: 'search your knowledge base',
+  files: 'read and change files',
+  exec: 'run commands on the device',
+  'http-request': 'call web addresses and APIs',
+  'mcp-call': 'use connected external tools (MCP)'
+}
+
+// full words, not a bare value: this row sits among on/off badges, and a one-word flip reads as
+// "nothing happened". skip-all carries the warning PRD §3.1 requires on selection.
+const MODE_LABEL = {
+  ask: 'ask for approval  ',
+  'skip-all': 'SKIP ALL APPROVALS'
+}
+
+const MODE_HINT = {
+  ask: 'asks before writing or editing anything',
+  'skip-all': '⚠ acts on this device without ever asking'
+}
+
+// /permissions overlay: the approval mode on the first row, then one row per toolset.
+export function formatPermissions(sel) {
+  const { rows, enabled, mode, cursor } = sel
+  const nameWidth = Math.max(...rows.map((name) => name.length))
+  const header = fg.dim.render(
+    'How should QV.AC actions be approved? — ↑/↓ move · space toggle · esc return'
+  )
+  const lines = rows.map((name, i) => {
+    const point = i === cursor ? fg.magenta.render('❯ ') : '  '
+    if (name === MODE_ROW) {
+      const paint = mode === 'skip-all' ? fg.err : fg.cyan
+      const hint =
+        mode === 'skip-all' ? fg.err.render(MODE_HINT[mode]) : fg.dim.render(MODE_HINT[mode])
+      return `${point}${paint.render(MODE_LABEL[mode])}  ${hint}`
+    }
+    const badge = enabled.has(name) ? fg.cyan.render('● on ') : fg.dim.render('○ off')
+    return `${point}${badge}  ${fg.white.render(name.padEnd(nameWidth))}  ${fg.dim.render(TOOLSET_HINTS[name] ?? '')}`
+  })
+  return [header, '', ...lines]
+}
+
+const SKILL_STATUS_PAINT = {
+  ready: 'dim',
+  'needs-setup': 'amber',
+  disconnected: 'amber',
+  outdated: 'amber',
+  failed: 'err',
+  unsupported: 'err',
+  'incompatible-model': 'err',
+  disabled: 'dim'
+}
+
+// /skills and /tools overlay: installed rows with an on/off badge; space toggles membership and
+// flips scope to selected. Skills carry their setup state (`detail`, name → skill) and the
+// highlighted one spells out what setting it up takes, so enabling a skill that needs an
+// account says so instead of silently doing nothing.
+export function formatSelector(sel) {
+  const { kind, rows, enabled, scope, cursor, detail } = sel
+  if (kind === 'permissions') return formatPermissions(sel)
+  const title = kind === 'skills' ? 'Skills' : 'Tools'
+  if (!rows.length) {
+    return [fg.dim.render(`(no ${kind} advertised — provider offline or pre-upgrade)`)]
+  }
+  const nameWidth = Math.max(...rows.map((n) => n.length))
+  const hint = detail
+    ? '↑/↓ move · space toggle · enter configure · esc return'
+    : '↑/↓ move · space toggle · esc return'
+  const header = fg.dim.render(
+    `${title} on this device — scope=${scope} (${rows.length}) — ${hint}`
+  )
+  const lines = rows.map((name, i) => {
+    const point = i === cursor ? fg.magenta.render('❯ ') : '  '
+    const badge = enabled.has(name) ? fg.cyan.render('● on ') : fg.dim.render('○ off')
+    const skill = detail?.get(name)
+    const state = skill
+      ? `  ${fg[SKILL_STATUS_PAINT[skill.status] ?? 'dim'].render(statusLabel(skill.status))}`
+      : ''
+    return `${point}${badge}  ${fg.white.render(name.padEnd(nameWidth))}${state}`
+  })
+  return [header, '', ...lines, ...formatSkillDetail(detail?.get(rows[cursor]))]
+}
+
+// The pane under the list: what the highlighted skill is, and the command enter
+// runs on it — the one that sets it up, or, once it is connected, the one that
+// points it somewhere else.
+function formatSkillDetail(skill) {
+  if (!skill) return []
+  const lines = ['', fg.white.render(`${skill.name} — ${skill.description}`)]
+  const state = statusLabel(skill.status)
+  const runnables = configureActions(skill)
+  if (isReady(skill)) {
+    if (!runnables.length) return [...lines, fg.dim.render(state)]
+    const [first, ...rest] = runnables
+    lines.push(fg.dim.render(`${state} — enter to change it: ${first.label}`))
+    lines.push(fg.cyan.render(`enter → ${first.command ?? `${first.prefill}<value>`}`))
+    for (const other of rest) lines.push(fg.dim.render(`or ${other.label}${runnable(other)}`))
+    return lines
+  }
+  const action = setupAction(skill)
+  if (!action) return [...lines, fg.dim.render(`${state} — nothing to set up here`)]
+  lines.push(fg.amber.render(`${state} — ${action.label}`))
+  if (action.command) lines.push(fg.cyan.render(`enter → ${action.command}`))
+  if (action.prefill) lines.push(fg.cyan.render(`enter → ${action.prefill}<value>`))
+  for (const step of action.steps) lines.push(fg.dim.render(`  • ${step}`))
+  if (action.helpUrl) lines.push(fg.dim.render(`  ${action.helpUrl}`))
+  for (const other of setupPlan(skill).others) {
+    lines.push(fg.dim.render(`or ${other.label}${runnable(other)}`))
+  }
+  return lines
+}
+
+// The navigable menu overlay: a page is { title, entries, cursor } and an entry
+// is { label, hint, submenu? }. A `▸` marks the rows that open a sub-list, so
+// the grouped commands read as one browsable tree instead of a flat palette.
+export function formatMenu(page) {
+  const { title, entries, cursor } = page
+  const labels = entries.map((e) => e.label + (e.submenu ? ' ▸' : ''))
+  const nameWidth = Math.max(...labels.map((l) => l.length))
+  const header = fg.dim.render(`${title} — ↑/↓ move · enter select · esc back`)
+  const lines = entries.map((e, i) => {
+    const point = i === cursor ? fg.magenta.render('❯ ') : '  '
+    const label = fg.white.render(labels[i].padEnd(nameWidth))
+    return `${point}${label}  ${fg.dim.render(e.hint ?? '')}`
+  })
+  return [header, '', ...lines]
+}
+
+// The sidebar pane's lines: a title, then the rows windowed around the cursor
+// so a long chat list scrolls rather than overflowing the frame. Exactly
+// `height` lines, each already cut to `width`.
+export function formatSidebar(rows, cursor, { title, focus, width, height }) {
+  const lines = [fg.dim.render(title)]
+  const room = Math.max(1, height - 1)
+  const start = Math.min(Math.max(0, cursor - (room >> 1)), Math.max(0, rows.length - room))
+  for (const [i, row] of rows.slice(start, start + room).entries()) {
+    lines.push(sidebarLine(row, start + i === cursor && focus, width - 2))
+  }
+  while (lines.length < height) lines.push('')
+  return lines.slice(0, height).map((line) => style.truncate(line, width))
+}
+
+function sidebarLine(row, atCursor, room) {
+  const label =
+    row.label.length > room ? `${row.label.slice(0, Math.max(0, room - 1))}…` : row.label
+  if (row.kind === 'group') return fg.dim.render(`▸ ${label}`)
+  if (row.kind === 'empty') return fg.dim.render(`  ${label}`)
+  const point = atCursor ? fg.magenta.render('❯') : ' '
+  if (row.kind === 'chat') {
+    const paint = row.active ? fg.cyan : fg.white
+    return `${point}${row.active ? '●' : ' '}${paint.render(label)}`
+  }
+  return `${point} ${fg.white.render(label)}`
+}
+
+// The human side is labelled by device name (fallback: short device id) —
+// structurally still user-vs-agent, only the word changes per device.
+// A tool call and its result are one long JSON line each — shown whole they
+// bury the answer, so they render as a preview of TOOL_PREVIEW_ROWS rows with
+// the rest counted. ctrl+o, or a click on the marker, expands every one.
+const TOOL_PREVIEW_ROWS = 3
+export const EXPAND_MARK = '⋯'
+
+function clampTool(text, { expandTools = false, width = 80 } = {}) {
+  if (expandTools) return text
+  const room = Math.max(20, width)
+  const budget = room * TOOL_PREVIEW_ROWS
+  if (text.length <= budget) return text
+  const rest = Math.ceil((text.length - budget) / room)
+  return `${text.slice(0, budget)}… ${EXPAND_MARK} +${rest} rows · ctrl+o`
+}
+
+export function renderTurn(turn, agentName, deviceLabels, opts = {}) {
+  // A requested-but-not-yet-started run has a turn (so busy derives from it)
+  // but nothing to say — the busy line is its visible side.
+  if (turn.from === 'agent' && !turn.segments.length && !turn.status) return ''
+  const userLabel =
+    (turn.deviceId && deviceLabels?.get(turn.deviceId)) || turn.deviceId?.slice(0, 8) || 'you'
+  const label = turn.from === 'user' ? fg.cyan.render(userLabel) : fg.magenta.render(agentName)
+  const lines = [`${label}:`]
+  for (const segment of turn.segments) {
+    if (segment.type === 'thinking') lines.push(fg.dim.render(`  (thinking: ${segment.text})`))
+    else if (segment.type === 'tool-call') {
+      const call = `  → ${segment.detail.name}(${JSON.stringify(segment.detail.arguments)})`
+      lines.push(fg.amber.render(clampTool(call, opts)))
+    } else if (segment.type === 'tool-result') {
+      const result = `  ← ${segment.detail.name}: ${JSON.stringify(segment.detail.result)}`
+      lines.push(fg.dim.render(clampTool(result, opts)))
+    } else if (segment.type === 'attachment') {
+      lines.push(
+        fg.cyan.render(
+          `  [attachment] ${segment.detail.fileName} (${segment.detail.mimeType}, ${segment.detail.byteLength}B)`
+        )
+      )
+    } else if (segment.type === 'sources') {
+      const records = segment.detail.sources
+      if (records.length === 0 && segment.detail.notice) {
+        lines.push(fg.dim.render(`  [sources] ${segment.detail.notice}`))
+      } else {
+        // retrieval returns chunks, so a document repeats — count it rather than
+        // printing the same title over and over
+        const perTitle = new Map()
+        for (const source of records) {
+          perTitle.set(source.title, (perTitle.get(source.title) ?? 0) + 1)
+        }
+        const titles = [...perTitle].map(([title, n]) => (n > 1 ? `${title} ×${n}` : title))
+        lines.push(fg.dim.render(`  [sources] ${titles.join('; ')}`))
+      }
+    } else if (segment.type === 'approval-request') {
+      const { name, arguments: args, resource, status } = segment.detail
+      // The resource descriptor is what the decision is really about — lead
+      // with it when the tool provided one (e.g. the request's hostname).
+      const call = resource
+        ? `${name} → ${resource.kind} ${resource.label}`
+        : `${name}(${JSON.stringify(args)})`
+      if (status === 'pending') lines.push(fg.amber.render(`  allow ${call}? [y/a/n]`))
+      else lines.push(fg.dim.render(`  [${status}] ${call}`))
+    } else lines.push(fg.white.render(`  ${segment.text || '…'}`))
+  }
+  if (turn.status === 'failed') {
+    lines.push(fg.err.render(`  [failed${turn.statusReason ? `: ${turn.statusReason}` : ''}]`))
+  }
+  const metrics = turn.status === 'completed' ? turn.statusDetail?.metrics : null
+  if (metrics) {
+    const parts = [`${metrics.totalTokens} tok`]
+    if (metrics.tokensPerSecond) parts.push(`${metrics.tokensPerSecond.toFixed(1)} tok/s`)
+    if (metrics.timeToFirstToken) parts.push(`ttft ${Math.round(metrics.timeToFirstToken)}ms`)
+    if (metrics.cacheTokens) parts.push(`${metrics.cacheTokens} ctx`)
+    lines.push(fg.dim.render(`  ${parts.join(' · ')}`))
+  }
+  return lines.join('\n')
+}
+
+const CPU_ARCH_NAMES = { 0: 'unknown', 1: 'x86', 2: 'x86_64', 3: 'arm', 4: 'arm64' }
+const GPU_TYPE_NAMES = {
+  0: 'unknown',
+  1: 'integrated',
+  2: 'dedicated',
+  3: 'virtual',
+  4: 'external'
+}
+
+function bytesToGb(bytes) {
+  if (typeof bytes !== 'number' || bytes <= 0) return null
+  return `${(bytes / 1024 ** 3).toFixed(1)} GB`
+}
+
+function hzToGhz(hz) {
+  if (typeof hz !== 'number' || hz <= 0) return null
+  return `${(hz / 1e9).toFixed(2)} GHz`
+}
+
+function enabledFeatures(features) {
+  if (!features || typeof features !== 'object') return []
+  return Object.keys(features)
+    .filter((k) => features[k] === true)
+    .map((k) => k.replace(/^(arm|x86)_/, ''))
+}
+
+function enabledDrivers(drivers) {
+  if (!drivers || typeof drivers !== 'object') return []
+  return Object.keys(drivers).filter((k) => drivers[k] === true)
+}
+
+export function matchCommands(inputValue) {
+  const raw = inputValue ?? ''
+  if (!raw.startsWith('/')) return []
+  const query = raw.slice(1).split(/\s+/, 1)[0].toLowerCase()
+  // arguments after the token mean the command is chosen — exact match only,
+  // so `/skill on x` stops surfacing /skills
+  const committed = /\s/.test(raw.trim())
+  const hits = COMMANDS.filter((c) =>
+    committed ? c.name.toLowerCase() === query : c.name.toLowerCase().startsWith(query)
+  )
+  // the curated few first, then every other command — a bare `/` still opens on
+  // what most people want, and typing reaches everything the TUI dispatches
+  return [...hits.filter((c) => c.palette), ...hits.filter((c) => !c.palette)]
+}
+
+// The dropdown never grows past PALETTE_ROWS — with every command matchable, a
+// bare `/` would otherwise paper over the whole transcript. The window walks
+// with the selection, and a trailing count says how much is still below.
+function renderPalette(matches, selected = 0) {
+  if (!matches.length) return []
+  const nameWidth = Math.max(...matches.map((c) => c.name.length + 1))
+  const line = (c, highlighted) => {
+    const label = `/${c.name}`.padEnd(nameWidth)
+    const name = highlighted ? fg.magenta.render(label) : fg.cyan.render(label)
+    return `  ${name}  ${fg.dim.render(c.desc)}`
+  }
+  if (matches.length <= PALETTE_ROWS) return matches.map((c, i) => line(c, i === selected))
+  const room = PALETTE_ROWS - 1
+  const start = Math.min(Math.max(0, selected - (room >> 1)), matches.length - room)
+  const rows = matches.slice(start, start + room).map((c, i) => line(c, start + i === selected))
+  return [...rows, fg.dim.render(`  +${matches.length - room - start} more`)]
+}
+
+// Whitespace-delimited, like ctrl+w and readline's word motions.
+export function wordStart(value, cursor) {
+  let at = Math.min(cursor, value.length)
+  while (at > 0 && value[at - 1] === ' ') at--
+  while (at > 0 && value[at - 1] !== ' ') at--
+  return at
+}
+
+export function wordEnd(value, cursor) {
+  let at = Math.max(0, cursor)
+  while (at < value.length && value[at] === ' ') at++
+  while (at < value.length && value[at] !== ' ') at++
+  return at
+}
+
+const LABEL_WIDTH = 14
+function row(label, value) {
+  const key = fg.cyan.render(label.padEnd(LABEL_WIDTH))
+  return `  ${key}  ${fg.white.render(value)}`
+}
+
+function formatCpuLines(cpu) {
+  if (!cpu) return [fg.err.render('CPU  (unavailable — bare-cpu-info addon not loaded)')]
+  const arch = CPU_ARCH_NAMES[cpu.arch] ?? String(cpu.arch)
+  const lines = [
+    fg.magenta.render(`CPU  ${cpu.name ?? '?'}`),
+    row('vendor', `${cpu.vendor ?? '?'} · ${arch}`)
+  ]
+  const coreLayout =
+    (cpu.performanceCores ?? 0) + (cpu.efficiencyCores ?? 0) > 0
+      ? `${cpu.logicalCores} logical (${cpu.performanceCores}P / ${cpu.efficiencyCores}E)`
+      : `${cpu.logicalCores} logical · ${cpu.physicalCores} physical`
+  lines.push(row('cores', coreLayout))
+  const mem = bytesToGb(cpu.memory)
+  if (mem) lines.push(row('memory', mem))
+  const freq = hzToGhz(cpu.frequency)
+  if (freq) lines.push(row('frequency', freq))
+  if (typeof cpu.cacheLine === 'number' && cpu.cacheLine > 0) {
+    lines.push(row('cache line', `${cpu.cacheLine} B`))
+  }
+  const feats = enabledFeatures(cpu.features)
+  if (feats.length) {
+    const shown = feats.slice(0, 12).join(' ')
+    const rest = feats.length > 12 ? fg.dim.render(` (+${feats.length - 12} more)`) : ''
+    lines.push(row('features', shown + rest))
+  }
+  return lines
+}
+
+function formatGpuDevice(device, index) {
+  const type = GPU_TYPE_NAMES[device.type] ?? String(device.type)
+  const memory = bytesToGb(device.memory)
+  const badges = [device.vendor ?? '?', type]
+  if (device.unifiedMemory) badges.push('unified')
+  if (memory) badges.push(memory)
+  const lines = [
+    fg.magenta.render(`GPU ${index}  ${device.name ?? '?'}`),
+    row('badges', badges.join(' · '))
+  ]
+  const driverBits = []
+  if (device.driverName) driverBits.push(device.driverName)
+  if (device.driverVersion) driverBits.push(`v${device.driverVersion}`)
+  if (driverBits.length) lines.push(row('driver', driverBits.join(' · ')))
+  const ids = []
+  if (typeof device.vendorId === 'number') ids.push(`vendorId 0x${device.vendorId.toString(16)}`)
+  if (typeof device.deviceId === 'number') ids.push(`deviceId 0x${device.deviceId.toString(16)}`)
+  if (ids.length) lines.push(row('pci', ids.join(' · ')))
+  const perDeviceDrivers = enabledDrivers(device.drivers)
+  if (perDeviceDrivers.length) lines.push(row('backends', perDeviceDrivers.join(' ')))
+  return lines
+}
+
+function formatGpuLines(gpu) {
+  if (!gpu) return [fg.err.render('GPU  (unavailable — bare-gpu-info addon not loaded)')]
+  const systemDrivers = enabledDrivers(gpu.drivers)
+  const devices = gpu.devices ?? []
+  if (!devices.length) {
+    const lines = [fg.magenta.render('GPU  (no devices found)')]
+    if (systemDrivers.length) lines.push(row('system drivers', systemDrivers.join(' ')))
+    return lines
+  }
+  const lines = []
+  devices.forEach((device, index) => {
+    if (index > 0) lines.push('')
+    lines.push(...formatGpuDevice(device, index))
+  })
+  if (systemDrivers.length) {
+    lines.push('')
+    lines.push(row('system drivers', systemDrivers.join(' ')))
+  }
+  return lines
+}
+
+export function formatDiagnostics(stats) {
+  if (!stats) {
+    return [fg.dim.render('(no diagnostics snapshot yet — try again in a moment)')]
+  }
+  const header = fg.dim.render('My Device — CPU / GPU inventory — esc to return')
+  return [header, '', ...formatCpuLines(stats.cpu), '', ...formatGpuLines(stats.gpu)]
+}
+
+function runnable(action) {
+  if (action.command) return `: ${action.command}`
+  return action.prefill ? `: ${action.prefill}<value>` : ''
+}
+
+// A `ready` skill is just its name+state; a non-ready one appends the one thing
+// that makes it usable — the /connect or /cred to run, or the install steps —
+// so the fix is in the TUI rather than somewhere in the docs.
+export function renderSkill(s) {
+  const lines = [`${s.name}: ${s.status || 'unknown'} — ${s.description}`]
+  if (s.platform?.length) lines.push(`platforms: ${s.platform.join(', ')}`)
+  if (s.requires?.bins?.length) lines.push(`requires: ${s.requires.bins.join(', ')}`)
+  if (isReady(s)) {
+    for (const action of configureActions(s)) {
+      lines.push(`  change it: ${action.label}${runnable(action)}`)
+    }
+    return lines.join('\n')
+  }
+  if (s.setup?.summary) lines.push(`  ${s.setup.summary}`)
+  const { primary, others } = setupPlan(s)
+  if (primary) {
+    lines.push(`  ${primary.label}`)
+    if (primary.command) lines.push(`  run: ${primary.command}`)
+    if (primary.prefill) lines.push(`  run: ${primary.prefill}<value>`)
+    for (const step of primary.steps) lines.push(`    - ${step}`)
+    if (primary.helpUrl) lines.push(`    ${primary.helpUrl}`)
+  }
+  for (const other of others) {
+    lines.push(`  or ${other.label}${runnable(other)}${other.helpUrl ? ` (${other.helpUrl})` : ''}`)
+  }
+  return lines.join('\n')
+}
+
+// The mesh seeds its default agent at birth and a joiner waits for it to
+// replicate — resolves on the first agent the mesh yields (agentsWatch fires on
+// every change, no polling).
+async function firstAgent(engine) {
+  for await (const frame of engine.agentsWatch({})) {
+    if (frame.agents?.length) return frame.agents[0]
+  }
+  throw new Error('agent stream ended before an agent replicated')
+}
+
+// The birth op seeds a default chat too; a joiner waits for it to replicate —
+// watch-driven like firstAgent (chatsWatch), no polling. The provider mints one
+// as a fallback if none shows within the timeout.
+async function firstChat(engine, agent, isProvider) {
+  const watch = engine.chatsWatch({})[Symbol.asyncIterator]()
+  let timer
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(resolve, 10_000, { done: true })
+  })
+  try {
+    while (true) {
+      const { value, done } = await Promise.race([watch.next(), timeout])
+      if (done) break
+      const live = (value.chats ?? []).find((chat) => !chat.deletedAt)
+      if (live) return live
+    }
+  } finally {
+    clearTimeout(timer)
+    await watch.return?.()
+  }
+  if (isProvider) return engine.createChat({ agentId: agent.id, title: 'New Chat' })
+  throw new Error('no chat replicated before timeout')
+}
+
+// A joiner's own writes need writer admission first; the replicated mesh status
+// carries `writable`, so wait for the frame that flips it (a creator is writable
+// as soon as its genesis drains, so this returns on the first frame).
+async function firstWritable(engine) {
+  for await (const frame of engine.meshStatusWatch({})) {
+    if (frame.writable) return
+  }
+  throw new Error('mesh status stream ended before this device became writable')
+}
+
+export class ChatApp {
+  constructor({
+    engine = null,
+    connect = null,
+    agent = null,
+    chatId = null,
+    modelName = null,
+    originDeviceId = null,
+    invite,
+    requestRepaint,
+    copyToClipboard,
+    resolvePastedFile,
+    resolveFileAttachment,
+    saveDir,
+    skills
+  }) {
+    this.engine = engine
+    this._skills = skills || null
+    this.agent = agent
+    this.chatId = chatId
+    // The provider's model override (QVAC_MODEL) — applied to the agent once it
+    // resolves, only if this device is its provider. Null on a joiner.
+    this._modelName = modelName || null
+    // Host-provided engine bring-up (spawn sidecar / open in-process Core, then
+    // read deviceId + invite) — run as init()'s first command so the whole
+    // connection happens inside the TUI, not as a pre-render status line. Absent
+    // when a caller hands a ready engine in directly (e.g. headless tests).
+    this._connect = connect || null
+    this._connecting = !!connect && !engine
+    // Booting until the engine is bound AND the mesh yields the seed agent +
+    // chat (see _connect/_bootstrap); both agent+chat arrive already-set when a
+    // caller resolves them up front instead.
+    this._booting = this._connecting || !agent || !chatId
+    this.originDeviceId = originDeviceId
+    // The mesh invite string — no longer shown in the transcript; ctrl+y copies
+    // it to the clipboard (see _copyInvite) for pasting into a second duck.
+    this.invite = invite || null
+    // Host-provided clipboard write (ctrl+y copies the invite) — clipboard
+    // access is host plumbing, not app logic; null disables the shortcut.
+    this._copyToClipboard = copyToClipboard || null
+    // Host-provided paste resolver (ctrl+v attaches a file): returns
+    // { fileName, mimeType, data } when the clipboard holds a usable file
+    // reference, null otherwise. Same plumbing rule as above.
+    this._resolvePastedFile = resolvePastedFile || null
+    // `/attach <path>` resolver: named path -> attachment, or throws.
+    this._resolveFileAttachment = resolveFileAttachment || null
+    this._selection = null // { anchor, focus, edge } in content cells, while a drag selects text
+    this._dragToken = 0 // stale-guards the edge auto-scroll beats
+    this._saveDir = saveDir || path.join(os.homedir(), 'Downloads')
+    this._statusToken = 0 // stale-guards the transient status clears
+    // Called once a run settles — llama.cpp writes some of its own logs
+    // straight to the real terminal fd mid-generation, bypassing the
+    // renderer's diff cache, so the rows they land on need a forced full
+    // repaint to clear. No-op by default (e.g. headless tests).
+    this._requestRepaint = requestRepaint || (() => {})
+    this._converse = null
+
+    this.input = textinput
+      .create({
+        placeholder: 'say something… (/ commands · ctrl+p menu)',
+        prompt: '❯ '
+      })
+      .focus()
+    this.width = 80
+    this.height = 24
+    // The first frame renders before the initial windowSize message lands —
+    // use the same CHROME_ROWS math as the resize handler so it can't overflow.
+    this.vp = viewport.create({ width: 0, height: Math.max(1, this.height - CHROME_ROWS) })
+    this.spin = spinner.create({ fps: 10 })
+    this.busy = false
+    this.modelState = null // last 'model' event from the harness (loading/downloading/ready/unloading)
+    this.status = ''
+    this.notice = null // last /command output, rendered as a trailing transcript block
+    this.gen = 0 // shared stale-guard for the status/devices/diagnostics watches (never bumped today)
+    // chunk-watch-only generation: a chat switch tears down the chunk stream and re-arms it on the
+    // new chatId, so a stale frame from the old chat must be dropped. Separate from `gen` so it never
+    // stalls the status/devices/diagnostics loops, which share `gen` and re-arm on every frame.
+    this._chunkGen = 0
+    this._chunkIterator = null
+    this._files = []
+    this._filesIterator = null
+    this._statusIterator = null
+    this.meshStatus = null // last meshStatusWatch frame — rendered in the header
+    this._devicesIterator = null
+    this.deviceLabels = new Map() // hex device id → name, from devicesWatch
+    this.diagnostics = null
+    this._diagnosticsIterator = null
+    this.overlay = null
+    this._pinnedOverlay = null
+    // Interactive /models overlay: { rows (sorted), filter, cursor }, else null.
+    // Separate from `overlay` (the static diagnostics/error panel) because its
+    // rows respond to ↑/↓ and enter — see _overlayKey.
+    this._models = null
+    // Interactive /skills + /tools overlay: { kind, rows (names), enabled (Set),
+    // scope, cursor }, else null. Same ↑/↓ nav as _models, but space toggles.
+    this._selector = null
+    // The navigable menu overlay: { pages: [page, …] } as a drill-in stack, top
+    // of stack is the visible page. Lowest render precedence, so a selector or
+    // models list opened from a menu row draws on top and esc falls back here.
+    this._menu = null
+    // The chat sidebar: null when closed, else { selected (chat id), focus,
+    // moving }. Its rows are derived from the live chats watch on every render,
+    // so a replicated change never slides the cursor out from under you.
+    this._sidebar = null
+    // Tool calls and their results render as a short preview until this is on —
+    // ctrl+o, or a click on a preview's marker.
+    this._expandTools = false
+    this._chats = []
+    this._groups = []
+    this._chatsIterator = null
+    this._turns = [] // last rendered turns — re-combined with the busy line on every render
+    // Derived from _turns on every _setTranscript, not bridged in from the
+    // harness — approval state lives entirely in the chunk stream (see
+    // runAgent's createApprove); the UI only ever reads/writes chunks.
+    this.pendingApproval = null
+    this._runningRunId = null // the in-flight run's id, for _requestStop()
+    this._awaitingRun = false // bridged busy between our submit and its first frame
+    this._paste = null // chars accumulating between bracketed-paste markers, null = not pasting
+    this._pastes = new Map() // input placeholder -> full pasted text, expanded at submit
+    // Submitted lines, oldest first — ↑/↓ walk them (readline-style). `_historyAt`
+    // is null while typing a fresh line and an index into `_history` while recalling;
+    // `_historyDraft` preserves the in-progress line so ↓ past the newest restores it.
+    this._history = []
+    this._historyAt = null
+    this._historyDraft = ''
+    // Highlighted row in the `/` command palette — ↑/↓ move it, tab completes it,
+    // enter runs it. Reset to 0 whenever the palette's matches change.
+    this._paletteAt = 0
+    // Render immediately so the first frame isn't blank before any chunk-watch
+    // result arrives.
+    this._render()
+  }
+
+  init() {
+    // The spinner ticks from the very first frame (pure TUI feedback, driven
+    // locally). When a connect fn is set the engine isn't up yet, so the only
+    // other startup command is the connection itself — the engine-backed watches
+    // arm on the 'connected' message. With a ready engine handed in, they arm now.
+    if (this._connecting) return batch(this._connectCmd(), this.spin.init())
+    return batch(...this._engineWatches(), this.spin.init())
+  }
+
+  // The engine-backed watch loops. The chunk watch is deferred until a chatId
+  // exists (see _bootstrap); the mesh/devices/diagnostics watches run from the
+  // first frame so the header narrates live progress while the mesh converges.
+  _engineWatches() {
+    return [
+      this.chatId ? this._watchNext() : this._bootstrap(),
+      this.chatId ? this._watchNextFiles() : null,
+      this._watchNextStatus(),
+      this._watchNextDevices(),
+      this._watchNextDiagnostics(),
+      this._watchNextChats()
+    ].filter(Boolean)
+  }
+
+  // init()'s first command when connecting: bring the engine up inside the TUI
+  // and hand the results to the 'connected' message.
+  _connectCmd() {
+    return async () => {
+      try {
+        const conn = await this._connect()
+        return { type: 'connected', ...conn }
+      } catch (error) {
+        return { type: 'boot-error', error }
+      }
+    }
+  }
+
+  // Resolves the seed agent + chat over the mesh with the TUI already up — the
+  // waits that used to block before the first frame, now driven inside the app
+  // (the header's meshStatusWatch narrates joining/peers meanwhile).
+  _bootstrap() {
+    return async () => {
+      try {
+        await firstWritable(this.engine)
+        let agent = await firstAgent(this.engine)
+        const isProvider = agent.providerDeviceId?.equals(this.originDeviceId) ?? false
+        if (isProvider && this._modelName) {
+          // Only set the model — scopes stay as the shared seed left them
+          agent = await this.engine.updateAgent({ id: agent.id, modelName: this._modelName })
+        }
+        const chat = await firstChat(this.engine, agent, isProvider)
+        return { type: 'booted', agent, chat }
+      } catch (error) {
+        return { type: 'boot-error', error }
+      }
+    }
+  }
+
+  _watchNextDiagnostics() {
+    if (!this.engine.diagnosticsWatch) return null
+    const gen = this.gen
+    if (!this._diagnosticsIterator) {
+      this._diagnosticsIterator = this.engine.diagnosticsWatch({})[Symbol.asyncIterator]()
+    }
+    const it = this._diagnosticsIterator
+    return async () => {
+      const { value, done } = await it.next()
+      if (done) return { type: 'diagnostics.done', gen }
+      return { type: 'diagnostics', gen, stats: value.stats }
+    }
+  }
+
+  _iterator() {
+    if (!this._chunkIterator) {
+      this._chunkIterator = this.engine.chunksWatch({ chatId: this.chatId })[Symbol.asyncIterator]()
+    }
+    return this._chunkIterator
+  }
+
+  // File snapshots share the chunk generation so switching chats drops stale frames.
+  _watchNextFiles() {
+    if (!this.engine.fileStatusWatch || !this.chatId) return null
+    const gen = this._chunkGen
+    if (!this._filesIterator) {
+      this._filesIterator = this.engine
+        .fileStatusWatch({ chatId: this.chatId })
+        [Symbol.asyncIterator]()
+    }
+    const it = this._filesIterator
+    return async () => {
+      try {
+        const { value, done } = await it.next()
+        if (done) return { type: 'files.done', gen }
+        return { type: 'files', gen, files: value.files }
+      } catch (error) {
+        return { type: 'files.done', gen, error }
+      }
+    }
+  }
+
+  // Re-armed after every frame — the stale-result guard (per bare-tui's
+  // CLAUDE.md) is `gen`, captured here at issue time, checked in update().
+  _watchNext() {
+    const gen = this._chunkGen
+    const it = this._iterator()
+    return async () => {
+      const { value, done } = await it.next()
+      if (done) return { type: 'chunks.done', gen }
+      return { type: 'chunks', gen, frame: value }
+    }
+  }
+
+  // The sidebar's chats and groups — same re-arm/stale-guard shape as the
+  // other watches, so a chat created or moved on any device redraws the pane.
+  _watchNextChats() {
+    if (!this.engine.chatsWatch) return null
+    const gen = this.gen
+    if (!this._chatsIterator) {
+      this._chatsIterator = this.engine.chatsWatch({})[Symbol.asyncIterator]()
+    }
+    const it = this._chatsIterator
+    return async () => {
+      const { value, done } = await it.next()
+      if (done) return { type: 'chats.done', gen }
+      return { type: 'chats', gen, frame: value }
+    }
+  }
+
+  // Device names for the per-device user labels — same re-arm/stale-guard
+  // shape as the other watch loops. Null when the engine lacks the
+  // capability (e.g. a headless test fake).
+  _watchNextDevices() {
+    if (!this.engine.devicesWatch) return null
+    const gen = this.gen
+    if (!this._devicesIterator) {
+      this._devicesIterator = this.engine.devicesWatch({})[Symbol.asyncIterator]()
+    }
+    const it = this._devicesIterator
+    return async () => {
+      const { value, done } = await it.next()
+      if (done) return { type: 'devices.done', gen }
+      return { type: 'devices', gen, frame: value }
+    }
+  }
+
+  // The mesh-status counterpart to _watchNext — same re-arm/stale-guard
+  // shape, its own iterator (meshStatusWatch frames arrive independently of
+  // chunk frames).
+  _watchNextStatus() {
+    const gen = this.gen
+    if (!this._statusIterator) {
+      this._statusIterator = this.engine.meshStatusWatch({})[Symbol.asyncIterator]()
+    }
+    const it = this._statusIterator
+    return async () => {
+      const { value, done } = await it.next()
+      if (done) return { type: 'mesh-status.done', gen }
+      return { type: 'mesh-status', gen, frame: value }
+    }
+  }
+
+  _setTranscript(chunks) {
+    this._turns = turnsFromChunks(chunks)
+    this.pendingApproval = findPendingApproval(this._turns)
+    const lastTurn = this._turns[this._turns.length - 1]
+    const lastChunk = chunks[chunks.length - 1]
+    // Busy derives from the replicated stream, not a local submit flag — a
+    // non-terminal agent turn means a run is in flight SOMEWHERE, so every
+    // peer (requester, provider, bystander) shows the same live state.
+    // _awaitingRun only covers this device's own gap between submitting and
+    // its run-request landing in a watch frame.
+    const running = runInFlight(this._turns)
+    if (lastTurn?.from === 'agent') this._awaitingRun = false
+    const wasBusy = this.busy
+    this.busy = running || this._awaitingRun
+    // The most recent run's id, for _requestStop() below to stopRun() —
+    // undefined once nothing is running.
+    this._runningRunId = this.busy ? (lastChunk?.runId ?? this._runningRunId) : null
+    if (!this.busy) {
+      this.modelState = null
+      if (wasBusy) this._requestRepaint()
+    }
+    this._render()
+  }
+
+  // "Thinking" (or downloading/loading) is chat activity, not an input-box
+  // state — it belongs as a transient trailing line in the transcript,
+  // animated by the spinner, not swapping out the text field the user is
+  // typing into. A pending approval already renders inline as part of the
+  // transcript (see renderTurn's 'approval-request' branch) — nothing extra here.
+  // The device a model event belongs to, as a display name: local harness
+  // events are THIS device; replicated run-status progress names the device
+  // that stamped the chunk (the provider).
+  _deviceName(hexId) {
+    return (hexId && this.deviceLabels.get(hexId)) || hexId?.slice(0, 8) || null
+  }
+
+  _busyLine() {
+    if (this.pendingApproval) return null
+    if (!this.busy) return null
+    const runTurn = runningAgentTurn(this._turns)
+    const { text, on } = busyStatus(this.modelState, runTurn)
+    const where =
+      on === 'local'
+        ? this._deviceName(this.originDeviceId?.toString('hex'))
+        : on === 'host'
+          ? this._deviceName(runTurn?.statusDeviceId)
+          : null
+    return fg.dim.render(`${this.spin.view()} ${text}${where ? ` (on ${where})` : ''}`)
+  }
+
+  _bodyWidth() {
+    return Math.max(1, this.width - 4 - this._sidebarCols())
+  }
+
+  // The columns the pane takes from the frame — none when it is closed, and
+  // none on a terminal too narrow to keep a readable transcript beside it.
+  _sidebarCols() {
+    if (!this._sidebar) return 0
+    return this.width - SIDEBAR_COLS >= SIDEBAR_MIN_BODY ? SIDEBAR_COLS : 0
+  }
+
+  // one wrap per item, so the cursor still scrolls to the item's own first row
+  _setRows(rows, cursor) {
+    const width = this._bodyWidth()
+    const lines = []
+    let at = 0
+    for (let i = 0; i < rows.length; i++) {
+      if (i === cursor) at = lines.length
+      lines.push(...wrapLine(rows[i], width))
+    }
+    this.vp.setContent(lines.join('\n'))
+    this._scrollToLine(at)
+  }
+
+  _render() {
+    if (this._models) {
+      const rows = formatModels(this._models.rows, this._models.filter, {
+        cursor: this._models.cursor,
+        currentModel: this.agent?.modelName
+      })
+      this._setRows(rows, this._models.cursor + 2)
+      return
+    }
+    if (this._selector) {
+      this._setRows(formatSelector(this._selector), this._selector.cursor + 2)
+      return
+    }
+    if (this.overlay) {
+      this.vp.setContent(wrapBlock(this.overlay.join('\n'), this._bodyWidth()))
+      if (this._pinnedOverlay !== this.overlay) {
+        this.vp.gotoTop?.()
+        this._pinnedOverlay = this.overlay
+      }
+      return
+    }
+    if (this._menu) {
+      const page = this._menu.pages[this._menu.pages.length - 1]
+      this._setRows(formatMenu(page), page.cursor + 2)
+      return
+    }
+    this._pinnedOverlay = null
+    // atBottom must be read BEFORE setContent: setContent re-clamps yOffset
+    // against the new (taller) content, so checking it after would compare
+    // the old offset to the new max and read as "not at bottom" for every
+    // single append — defeating auto-scroll entirely.
+    const wasAtBottom = this.vp.atBottom
+    const lines = this._turns
+      .map((t) =>
+        renderTurn(t, this.agent.name, this.deviceLabels, {
+          expandTools: this._expandTools,
+          width: this._bodyWidth()
+        })
+      )
+      .filter(Boolean)
+    const busyLine = this._busyLine()
+    if (busyLine) lines.push(busyLine)
+    // A notice is chrome — a chat switch, a command's reply — not transcript, so
+    // a chat with nothing said in it still counts as empty and the notice rides
+    // under the art as its caption. That is what brings the ducks back on
+    // /new-chat, which switches chat and leaves a notice behind.
+    if (lines.length) {
+      if (this.notice) lines.push(fg.dim.render(this.notice))
+    } else {
+      const booting = this._connecting
+        ? 'starting up…'
+        : this._booting
+          ? 'connecting to the mesh…'
+          : null
+      // boot is the one wait with no busy line of its own — the spinner is the
+      // only sign the frame is live rather than wedged
+      const caption = this.notice || (booting ? `${this.spin.view()} ${booting}` : '(say hello)')
+      const width = this._bodyWidth()
+      // the join below spends a blank row and the caption's own row, which is
+      // the height splash() centers around
+      const art = splash(width, this.vp.height - 2)
+      if (art) lines.push(art)
+      // a multi-line notice is left to wrap on its own rather than centered
+      lines.push(
+        art && !caption.includes('\n')
+          ? center(fg.dim.render(caption), width, tui.style.width(caption))
+          : fg.dim.render(caption)
+      )
+    }
+    this.vp.setContent(wrapBlock(lines.join('\n\n'), this._bodyWidth()))
+    if (wasAtBottom) this.vp.gotoBottom()
+  }
+
+  // Sending while a run is in flight is fine: the message and its
+  // run-request just queue as chunks, and the provider executes them after
+  // the current run — with the new message in that run's prompt.
+  _command(text) {
+    const input = text.slice(1)
+    const [cmd, ...rest] = input.split(/\s+/)
+    const rawArgs = input.slice(cmd.length).trimStart()
+    const { engine, agent } = this
+    const HELP = [
+      'Chat',
+      '  /menu — open the navigable menu (Agent, Chat, Models, Voice, …); also ctrl+p, arrows + enter to browse',
+      '  ctrl+b — the chats sidebar: ↑/↓ walks it, enter opens a chat, m moves one to a group, esc closes',
+      '  esc — stop the run in flight, or clear the last command’s output',
+      '  ctrl+o — expand the tool call/result previews (a click on a preview’s marker does the same)',
+      '  /new-chat — create and switch to a new chat (shortcut for /chat new)',
+      '  /chats — pick from your chats to switch (interactive) · /chat — show current',
+      '  /chat new [title] · /chat use <title|id> · /chat rename <title> · /chat del <title|id> · /chat websearch on|off · /chat rag on|off',
+      '  /group — the sidebar as core orders it (groups, then ungrouped, each most-recently-active first)',
+      '  /group new <name> · /group rename <group> <name> · /group del <group> — quote any name containing spaces',
+      '  /group move <group> [chat] — move a chat into a group; the chat defaults to the active one, and - as the group ungroups it',
+      '  /knowledge [list] · /knowledge add <file> · /knowledge add-dir <directory> · /knowledge download <n|id> · /knowledge remove <n|id>',
+      '  /files — show upload progress, local readiness, and failures for this chat',
+      '  /attach <path> [<path> …] — attach local files to this chat (quote paths that contain spaces)',
+      '  /save [n] — download the latest (or n-th) attachment to ~/Downloads',
+      '  /export [n] — write the last run (or last n) to a markdown file: prompt, thinking, answer, tools',
+      '',
+      'Agent',
+      '  /agents — pick from your agents to switch (interactive) · /agent — show current · /agent list · /agent new <name> · /agent rename <name> · /agent use <name|id>',
+      "  /activity — list the active agent's recent tool calls, each with its decision (allowed/denied/auto/skip-all/blocked)",
+      '  /skills · /tools — browse installed; ↑/↓ move, space toggles each on/off (sets scope=selected), enter sets up or reconfigures the skill, esc returns',
+      '  /skill on|off <name> · /tool on|off <name> — toggle (sets scope=selected)',
+      '  /permissions — approval mode + the toolset switches; ↑/↓ move, space toggles',
+      '  /models [type] — browse every model in the SDK registry; type is an SDK addon (llm, tts, whisper, embeddings, diffusion, …) or an alias (transcription, embedding, image); ↑/↓ move, space selects',
+      '  /image [model <choice> | steps <n> | size <WxH> | reset] — the agent’s image-generation defaults',
+      '',
+      'Connections — a skill that needs an account or a token (Menu ▸ Agent ▸ Connections lists them with their state)',
+      '  /connect gmail|google-calendar|google-docs|google-drive|google-sheets — connect one Google skill (needs GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET)',
+      '  /connect spotify — OAuth-connect Spotify via PKCE (needs SPOTIFY_OAUTH_CLIENT_ID; no secret)',
+      '  /connect notion — OAuth-connect Notion MCP via PKCE + dynamic registration (no env, no secret)',
+      '  /connect asana — OAuth-connect Asana MCP via PKCE (needs ASANA_OAUTH_CLIENT_ID + ASANA_OAUTH_CLIENT_SECRET)',
+      '',
+      'Voice',
+      '  /speak <text> — synthesize speech (TTS) to a WAV file in the save dir',
+      '  /speak-stream <text> — synthesize speech per sentence over a duplex stream (TTS)',
+      '  /transcribe <path> — transcribe a 16kHz mono s16 WAV file to text (STT; no resampling)',
+      '  /converse [device] — hands-free voice conversation via the mic (Esc or /converse to stop)',
+      '  /record [seconds] [device] — record from the mic via ffmpeg (macOS avfoundation) and transcribe',
+      '',
+      'Advanced',
+      '  /cred <key> <value> — set a credential by hand for this agent (e.g. /cred github_access_token ghp_…); /skills, enter on the skill, fills this in for you',
+      '  /scope skills|tools all|selected — switch scope',
+      '  /join <qvac://mesh/…> — retire this device’s mesh and join that one (ctrl+y copies this mesh’s invite) · /join cancel — abort a join in progress',
+      '  /my-device — dump this device\u2019s CPU/GPU inventory (manufacturer, cores, drivers, …)'
+    ].join('\n')
+
+    const notice = (t) => [this, async () => ({ type: 'notice', text: t })]
+    const run = (fn) => [
+      this,
+      async () => {
+        try {
+          return { type: 'notice', text: await fn() }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+
+    // an overlay, not a notice: /help is a page you read and dismiss with esc,
+    // and it would otherwise sit under the transcript until the next message
+    if (cmd === 'help') {
+      this._models = null
+      this._selector = null
+      this._menu = null
+      this.overlay = [...HELP.split('\n'), '', fg.dim.render('esc to return')]
+      this._render()
+      return [this, null]
+    }
+
+    if (cmd === 'menu') return this._openMenu()
+
+    if (cmd === 'new-chat') return this._newChat('New Chat')
+
+    if (cmd === 'my-device') return this._showDiagnostics()
+
+    if (cmd === 'models') {
+      const raw = rest[0]?.toLowerCase()
+      if (!raw) return this._showModels(null)
+      const resolved = MODEL_TYPE_ALIASES[raw] ?? raw
+      if (!MODEL_TYPES.has(resolved)) {
+        const known = [...MODEL_TYPES].sort().join(', ')
+        const aliases = Object.keys(MODEL_TYPE_ALIASES).sort().join(', ')
+        return notice(`unknown model type: ${raw}\nknown types: ${known}\naliases: ${aliases}`)
+      }
+      return this._showModels(resolved)
+    }
+
+    if (cmd === 'image') {
+      const [field, value] = rest
+      const USAGE =
+        'usage: /image [model <sd2|sdxl|flux2-klein> | steps <1..100> | size <WxH> | reset]'
+      if (!field) {
+        return run(async () => {
+          const a = await engine.getAgent({ id: agent.id })
+          const size =
+            a.imageWidth || a.imageHeight
+              ? `${a.imageWidth || 512}x${a.imageHeight || 512}`
+              : '512x512 (default)'
+          return [
+            `image defaults for ${a.name}:`,
+            `  model ${a.imageModelChoice || '(device default)'}`,
+            `  steps ${a.imageSteps || '(model default)'}`,
+            `  size  ${size}`
+          ].join('\n')
+        })
+      }
+      if (field === 'model') {
+        if (!['sd2', 'sdxl', 'flux2-klein'].includes(value)) return notice(USAGE)
+        return run(async () => {
+          await engine.updateAgent({ id: agent.id, imageModelChoice: value })
+          return `image model set to ${value}`
+        })
+      }
+      if (field === 'steps') {
+        const steps = Number(value)
+        if (!Number.isInteger(steps) || steps < 1 || steps > 100) return notice(USAGE)
+        return run(async () => {
+          await engine.updateAgent({ id: agent.id, imageSteps: steps })
+          return `image steps set to ${steps}`
+        })
+      }
+      if (field === 'reset') {
+        return run(async () => {
+          await engine.updateAgent({ id: agent.id, clearImageSettings: true })
+          return 'image defaults reset (device default model, model-default steps, 512x512)'
+        })
+      }
+      if (field === 'size') {
+        const match = /^(\d+)x(\d+)$/.exec(value ?? '')
+        if (!match) return notice(USAGE)
+        // persist through the runtime's own clamp/snap so the stored size is the effective one
+        const width = settingsDimension(Number(match[1]))
+        const height = settingsDimension(Number(match[2]))
+        if (!width || !height) return notice(USAGE)
+        return run(async () => {
+          await engine.updateAgent({ id: agent.id, imageWidth: width, imageHeight: height })
+          return `image size set to ${width}x${height}`
+        })
+      }
+      return notice(USAGE)
+    }
+
+    if (cmd === 'agent') {
+      const [action, ...nameParts] = rest
+      const arg = nameParts.join(' ')
+      if (!action) {
+        return run(async () => {
+          const a = await engine.getAgent({ id: agent.id })
+          return `agent ${a.name} (${a.id.slice(0, 8)}) · skills=${a.skillsScope ?? 'all'} tools=${a.toolsScope ?? 'all'}`
+        })
+      }
+      if (action === 'list') {
+        return run(async () => {
+          const { agents } = await engine.listAgents({})
+          return agents
+            .map((a) => `${a.id === agent.id ? '*' : ' '}${a.name} (${a.id.slice(0, 8)})`)
+            .join('\n')
+        })
+      }
+      if (action === 'new') {
+        if (!arg) return notice('usage: /agent new <name>')
+        return run(async () => {
+          const created = await engine.createAgent({
+            name: arg,
+            bio: `${arg} — test agent`,
+            providerDeviceId: this.originDeviceId,
+            modelName: agent.modelName
+          })
+          this.agent = created
+          return `created + selected ${created.name} (${created.id.slice(0, 8)}) · no skills/tools enabled`
+        })
+      }
+      if (action === 'rename') {
+        if (!arg) return notice('usage: /agent rename <name>')
+        return run(async () => {
+          this.agent = await engine.updateAgent({ id: agent.id, name: arg })
+          return `renamed to ${this.agent.name} (${this.agent.id.slice(0, 8)})`
+        })
+      }
+      if (action === 'use') {
+        if (!arg) return notice('usage: /agent use <name|id>')
+        return run(async () => {
+          const { agents } = await engine.listAgents({})
+          const found = agents.find((a) => a.id === arg || a.id.startsWith(arg) || a.name === arg)
+          if (!found) return `no agent matching: ${arg}`
+          this.agent = found
+          return `selected ${found.name} (${found.id.slice(0, 8)})`
+        })
+      }
+      return notice('usage: /agent [list|new <name>|rename <name>|use <name|id>]')
+    }
+
+    if (cmd === 'activity') {
+      return run(async () => {
+        const { activities } = await engine.listToolActivity({ agentId: agent.id, limit: 30 })
+        if (!activities || activities.length === 0) {
+          return 'no tool activity yet for this agent'
+        }
+        return activities
+          .map((a) => {
+            const when = new Date(a.at).toISOString().slice(0, 19).replace('T', ' ')
+            const args = a.arguments ? JSON.stringify(a.arguments) : ''
+            const call = args.length > 60 ? `${args.slice(0, 57)}…` : args
+            return `${a.decision.padEnd(8)} ${a.toolName}(${call}) · ${when}`
+          })
+          .join('\n')
+      })
+    }
+
+    if (cmd === 'skills' || cmd === 'tools') return this._showSelector(cmd)
+
+    if (cmd === 'permissions') return this._showPermissions()
+
+    if (cmd === 'skill' || cmd === 'tool') {
+      const [action, name] = rest
+      if ((action !== 'on' && action !== 'off') || !name) {
+        return notice(`usage: /${cmd} on|off <name>`)
+      }
+      const field = cmd === 'skill' ? 'enabledSkills' : 'enabledTools'
+      const scopeField = cmd === 'skill' ? 'skillsScope' : 'toolsScope'
+      return run(async () => {
+        const fresh = await engine.getAgent({ id: agent.id })
+        const set = new Set(fresh[field] ?? [])
+        if (action === 'on') set.add(name)
+        else set.delete(name)
+        const updated = await engine.updateAgent({
+          id: agent.id,
+          [field]: [...set],
+          [scopeField]: 'selected'
+        })
+        this.agent = updated
+        const line = `${cmd} ${name} ${action} · ${field}=[${[...set].join(', ')}] scope=selected`
+        if (cmd !== 'skill' || action !== 'on') return line
+        const skill = (await this._skillDetail())?.get(name)
+        if (!skill || isReady(skill)) return line
+        return `${line}\n${renderSkill(skill)}`
+      })
+    }
+
+    if (cmd === 'scope') {
+      const [which, value] = rest
+      if ((which !== 'skills' && which !== 'tools') || (value !== 'all' && value !== 'selected')) {
+        return notice('usage: /scope skills|tools all|selected')
+      }
+      const scopeField = which === 'skills' ? 'skillsScope' : 'toolsScope'
+      return run(async () => {
+        const updated = await engine.updateAgent({ id: agent.id, [scopeField]: value })
+        this.agent = updated
+        return `${which} scope=${value}`
+      })
+    }
+
+    if (cmd === 'attach') {
+      if (!this._resolveFileAttachment) {
+        return notice('attach is unavailable (no file resolver wired)')
+      }
+      const paths = splitPaths(rawArgs)
+      if (!paths.length) {
+        return notice('usage: /attach <path> [<path> …] — quote paths that contain spaces')
+      }
+      // Each file uploads as its own chunk; a bad path fails only its line.
+      const app = this
+      return run(async () => {
+        const lines = []
+        for (const p of paths) {
+          try {
+            const file = app._resolveFileAttachment(p)
+            await app._uploadAttachment(file)
+            lines.push(`attached ${file.fileName} (${file.data.length}B) ✓`)
+          } catch (err) {
+            lines.push(`✗ ${p} — ${err.code === 'ENOENT' ? 'no such file' : err.message}`)
+          }
+        }
+        return lines.join('\n')
+      })
+    }
+
+    if (cmd === 'export') {
+      const runs = rest[0] ? Number(rest[0]) : 1
+      if (!Number.isInteger(runs) || runs < 1) {
+        return notice('usage: /export [n] — the last n runs (default 1)')
+      }
+      return run(async () => {
+        const chat = engine.getChat ? await engine.getChat({ id: this.chatId }) : null
+        const markdown = exportMarkdown(this._turns, runs, {
+          title: chat?.title ?? 'Chat',
+          chatId: this.chatId,
+          agentName: this.agent?.name,
+          modelName: this.agent?.modelName
+        })
+        if (!markdown) return 'nothing to export yet — no runs in this chat'
+        const name = `${chat?.title ?? 'chat'}-${this.chatId.slice(0, 8)}.md`
+        // the clipboard is where a report gets pasted; the file is the copy that keeps
+        const copied = await this._copyQuietly(markdown)
+        const file = await saveUniqueFile(this._saveDir, name, Buffer.from(markdown), '.md')
+        const what = runs === 1 ? 'the last run' : `the last ${runs} runs`
+        if (!file) {
+          const where = `100 files named ${name} already exist in ${this._saveDir}`
+          return copied
+            ? `copied ${what} to the clipboard · not saved: ${where}`
+            : `not saved: ${where}`
+        }
+        return `exported ${what} to ${file}${copied ? ' · copied to clipboard' : ''}`
+      })
+    }
+
+    if (cmd === 'save') {
+      // blobs are encrypted at rest — the only viewable copy is a fresh download
+      return run(async () => {
+        const { chunks } = await engine.listChunks({ chatId: this.chatId, type: 'attachment' })
+        const all = chunks ?? []
+        if (!all.length) return 'no attachments in this chat'
+        const picked = rest[0] ? all[Number(rest[0]) - 1] : all[all.length - 1]
+        if (!picked) return `no attachment #${rest[0]} (this chat has ${all.length})`
+        const att = picked.attachment
+        if (!att) return `attachment chunk ${picked.id} has no attachment payload`
+        if (att.deletedAt) return `${att.fileName} was deleted`
+        const pieces = []
+        for await (const frame of engine.downloadAttachment({ blobId: att.blobId })) {
+          if (frame.data) pieces.push(frame.data)
+        }
+        const bytes = Buffer.concat(pieces)
+        if (!bytes.length) return `empty download for ${att.fileName}`
+        const ext = { 'image/jpeg': '.jpg', 'image/png': '.png' }[att.mimeType]
+        const file = await saveUniqueFile(this._saveDir, att.fileName, bytes, ext ?? '')
+        if (file) return `saved ${att.fileName} (${bytes.length}B) to ${file}`
+        return `not saved: 100 files named ${att.fileName} already exist in ${this._saveDir}`
+      })
+    }
+
+    if (cmd === 'files') {
+      if (!engine.fileStatusWatch) return notice('file status unavailable on this engine')
+      return notice(this._files.map(fileStatusText).join('\n') || 'no files in this chat')
+    }
+
+    if (cmd === 'knowledge') {
+      return [
+        this,
+        () => knowledgeCommand(engine, { chatId: this.chatId, saveDir: this._saveDir }, rawArgs)
+      ]
+    }
+
+    if (cmd === 'speak') {
+      if (!engine.speak) return notice('voice not available in this build')
+      const text = rest.join(' ').trim()
+      if (!text) return notice('usage: /speak <text>')
+      return run(async () => {
+        const { audio, sampleRate } = await engine.speak({ text })
+        const file = path.join(this._saveDir, `speak-${Date.now()}.wav`)
+        await fs.promises.writeFile(file, floatPcmToWav(audio, sampleRate))
+        return `synthesized ${audio.length}B @ ${sampleRate}Hz → ${file}`
+      })
+    }
+
+    if (cmd === 'speak-stream') {
+      if (!engine.speakStream) return notice('voice not available in this build')
+      const text = rest.join(' ').trim()
+      if (!text) return notice('usage: /speak-stream <text>')
+      return run(async () => {
+        const duplex = engine.speakStream()
+        for (const fragment of text.split(/(?<=[.!?])\s+/)) duplex.write({ text: fragment })
+        duplex.end()
+        const parts = []
+        let sampleRate = 44100
+        let chunks = 0
+        for await (const frame of duplex) {
+          chunks++
+          sampleRate = frame.sampleRate
+          parts.push(frame.audio)
+        }
+        const audio = Buffer.concat(parts)
+        const file = path.join(this._saveDir, `speak-stream-${Date.now()}.wav`)
+        await fs.promises.writeFile(file, floatPcmToWav(audio, sampleRate))
+        return `streamed ${chunks} chunk(s), ${audio.length}B @ ${sampleRate}Hz → ${file}`
+      })
+    }
+
+    if (cmd === 'transcribe') {
+      if (!engine.transcribe) return notice('voice not available in this build')
+      const arg = rest.join(' ').trim()
+      if (!arg) return notice('usage: /transcribe <path-to-16kHz-mono-s16.wav>')
+      return run(async () => {
+        const audio = await fs.promises.readFile(arg.replace(/^~/, os.homedir()))
+        // Parakeet needs 16kHz mono s16 and the SDK does not resample — a wrong
+        // format transcribes to empty, so flag it here instead of silently failing.
+        if (audio.length > 44 && audio.toString('ascii', 0, 4) === 'RIFF') {
+          const fmt = audio.readUInt16LE(20)
+          const ch = audio.readUInt16LE(22)
+          const rate = audio.readUInt32LE(24)
+          const bits = audio.readUInt16LE(34)
+          if (fmt !== 1 || ch !== 1 || rate !== 16000 || bits !== 16) {
+            return `wrong WAV format: ${rate}Hz ${ch}ch ${bits}bit (fmt ${fmt}) — need 16000Hz mono 16-bit PCM\nconvert: ffmpeg -i "${arg}" -ar 16000 -ac 1 -c:a pcm_s16le out.wav`
+          }
+        }
+        const { text } = await engine.transcribe({ audio })
+        return `transcript: ${text || '(empty — silence or unsupported audio)'}`
+      })
+    }
+
+    if (cmd === 'record') {
+      if (!engine.transcribe) return notice('voice not available in this build')
+      const seconds = Number(rest[0]) || 5
+      const device = rest[1] || ':0'
+      const file = path.join(this._saveDir, `record-${Date.now()}.wav`)
+      return run(async () => {
+        await new Promise((resolve, reject) => {
+          const ff = spawn(
+            'ffmpeg',
+            // prettier-ignore
+            ['-y', '-f', 'avfoundation', '-i', device, '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le', '-t', String(seconds), file],
+            { stdio: 'ignore' }
+          )
+          ff.on('error', reject)
+          ff.on('exit', (code) =>
+            code === 0
+              ? resolve()
+              : reject(
+                  new Error(
+                    `ffmpeg exited ${code} (try a different device, e.g. /record ${seconds} :1)`
+                  )
+                )
+          )
+        })
+        const audio = await fs.promises.readFile(file)
+        const { text } = await engine.transcribe({ audio })
+        return `recorded ${seconds}s → transcript: ${text || '(empty — silence?)'}`
+      })
+    }
+
+    if (cmd === 'converse') {
+      if (!engine.transcribe || !engine.speakStream) {
+        return notice('voice not available in this build')
+      }
+      if (this._converse) {
+        this._stopConverse('off')
+        return notice('conversation mode off')
+      }
+      const device = rest[0] || ':0'
+      this._startConverse(device)
+      return notice(
+        `conversation mode on (${device}) — talk; /converse or Esc to stop. use headphones (speaker echo triggers false barge-in)`
+      )
+    }
+
+    if (cmd === 'connect') {
+      const [provider = ''] = rest
+      // Each Google skill has its own key, scopes and app: `connect gmail`, `connect google-docs`.
+      const googleSpec = oauthKeySpec(`${provider.replaceAll('-', '_')}_access_token`)
+      if (googleSpec?.provider === 'google') {
+        const clientId = process.env.GOOGLE_OAUTH_CLIENT_ID
+        const clientSecret = process.env.GOOGLE_OAUTH_CLIENT_SECRET
+        if (!clientId || !clientSecret) {
+          return notice('set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET, then retry')
+        }
+        return run(async () => {
+          const tokens = await connectGoogle({
+            clientId,
+            clientSecret,
+            credentialKey: googleSpec.credentialKey,
+            openUrl: (url) => {
+              this.status = fg.dim.render(`authorize in your browser: ${url}`)
+              this._render()
+              openInBrowser(url)
+            }
+          })
+          await engine.configSet({
+            key: credKey(agent.id, googleSpec.credentialKey),
+            value: tokens.accessToken
+          })
+          await engine.configSet({
+            key: credKey(agent.id, googleSpec.stateKey),
+            value: JSON.stringify({
+              refreshToken: tokens.refreshToken,
+              expiresAt: tokens.expiresAt,
+              clientId,
+              clientSecret
+            })
+          })
+          return `${provider} connected for agent ${agent.name} — token stored, auto-refreshes on use`
+        })
+      }
+      if (provider === 'spotify') {
+        const clientId = process.env.SPOTIFY_OAUTH_CLIENT_ID
+        if (!clientId) {
+          return notice('set SPOTIFY_OAUTH_CLIENT_ID, then retry')
+        }
+        return run(async () => {
+          const tokens = await connectSpotify({
+            clientId,
+            openUrl: (url) => {
+              this.status = fg.dim.render(`authorize in your browser: ${url}`)
+              this._render()
+              openInBrowser(url)
+            }
+          })
+          await engine.configSet({
+            key: credKey(agent.id, SPOTIFY_CREDENTIAL_KEY),
+            value: tokens.accessToken
+          })
+          await engine.configSet({
+            key: credKey(agent.id, SPOTIFY_OAUTH_STATE_KEY),
+            value: JSON.stringify({
+              refreshToken: tokens.refreshToken,
+              expiresAt: tokens.expiresAt,
+              clientId
+            })
+          })
+          return `spotify connected for agent ${agent.name} — token stored, auto-refreshes on use`
+        })
+      }
+      if (provider === 'notion') {
+        return run(async () => {
+          const tokens = await connectNotion({
+            openUrl: (url) => {
+              this.status = fg.dim.render(`authorize in your browser: ${url}`)
+              this._render()
+              openInBrowser(url)
+            }
+          })
+          await engine.configSet({
+            key: credKey(agent.id, NOTION_MCP_CREDENTIAL_KEY),
+            value: tokens.accessToken
+          })
+          await engine.configSet({
+            key: credKey(agent.id, NOTION_OAUTH_STATE_KEY),
+            value: JSON.stringify({
+              refreshToken: tokens.refreshToken,
+              expiresAt: tokens.expiresAt,
+              clientId: tokens.clientId
+            })
+          })
+          return `notion connected for agent ${agent.name} — token stored, auto-refreshes on use`
+        })
+      }
+      if (provider === 'asana') {
+        const clientId = process.env.ASANA_OAUTH_CLIENT_ID
+        const clientSecret = process.env.ASANA_OAUTH_CLIENT_SECRET
+        if (!clientId || !clientSecret) {
+          return notice('set ASANA_OAUTH_CLIENT_ID and ASANA_OAUTH_CLIENT_SECRET, then retry')
+        }
+        return run(async () => {
+          const tokens = await connectAsana({
+            clientId,
+            clientSecret,
+            openUrl: (url) => {
+              this.status = fg.dim.render(`authorize in your browser: ${url}`)
+              this._render()
+              openInBrowser(url)
+            }
+          })
+          await engine.configSet({
+            key: credKey(agent.id, ASANA_MCP_CREDENTIAL_KEY),
+            value: tokens.accessToken
+          })
+          await engine.configSet({
+            key: credKey(agent.id, ASANA_OAUTH_STATE_KEY),
+            value: JSON.stringify({
+              refreshToken: tokens.refreshToken,
+              expiresAt: tokens.expiresAt,
+              clientId,
+              clientSecret
+            })
+          })
+          return `asana connected for agent ${agent.name} — token stored, auto-refreshes on use`
+        })
+      }
+      return notice(
+        'usage: /connect gmail|google-calendar|google-docs|google-drive|google-sheets|spotify|notion|asana'
+      )
+    }
+
+    if (cmd === 'cred') {
+      const [key, ...valueParts] = rest
+      const value = valueParts.join(' ')
+      if (!key || !value) return notice('usage: /cred <key> <value>')
+      return run(async () => {
+        const storageKey = credKey(agent.id, key)
+        await engine.configSet({ key: storageKey, value })
+        return `set ${key} for agent ${agent.name} (${value.length} chars) — scoped, not shared`
+      })
+    }
+
+    // Moving mesh is a Core-side transition: it retires this device's mesh and
+    // admits it to the invited one, so every agent and chat the TUI is holding
+    // becomes stale. Block sending for its duration and re-resolve both from
+    // the joined mesh afterwards (see the 'mesh.joined' handler). A join parks
+    // until the inviting device admits it — /join cancel gives that a way out.
+    if (cmd === 'join') {
+      const arg = rawArgs.trim()
+      if (!arg) return notice('usage: /join <qvac://mesh/…> · /join cancel')
+      if (arg === 'cancel') {
+        return run(async () => {
+          await engine.cancelMeshJoin({})
+          return 'join canceled'
+        })
+      }
+      // an invite pasted from a wrapped terminal arrives with embedded newlines
+      const invite = arg.replace(/\s+/g, '')
+      this._booting = true
+      this.status = 'joining mesh…'
+      this.notice = null
+      return [
+        this,
+        async () => {
+          try {
+            await engine.joinMesh({ invite })
+            const next = await engine.meshInvite({}).catch(() => null)
+            return { type: 'mesh.joined', invite: next?.invite ?? null }
+          } catch (error) {
+            return { type: 'mesh.joined', error }
+          }
+        }
+      ]
+    }
+
+    // /chats + /agents open the same interactive pickers as the menu's Switch
+    // rows — a standalone menu.page (see the message handler) you arrow through
+    // and enter to switch, rather than a static list you'd then /…use by id.
+    if (cmd === 'chats') return this._chatListPage()
+
+    if (cmd === 'agents') return this._agentListPage()
+
+    if (cmd === 'chat') {
+      const [action, ...argParts] = rest
+      const arg = argParts.join(' ')
+      if (!action) {
+        return run(async () => {
+          const c = await engine.getChat({ id: this.chatId })
+          return `chat "${c.title}" (${c.id.slice(0, 8)}) · web=${c.webSearchEnabled ? 'on' : 'off'}`
+        })
+      }
+      if (action === 'new') return this._newChat(arg || 'New Chat')
+      if (action === 'use') {
+        if (!arg) return notice('usage: /chat use <id>')
+        return this._useChat(arg)
+      }
+      if (action === 'del') {
+        if (!arg) return notice('usage: /chat del <id>')
+        return this._deleteChat(arg)
+      }
+      if (action === 'rename') {
+        if (!arg) return notice('usage: /chat rename <title>')
+        return run(async () => {
+          const c = await engine.renameChat({ id: this.chatId, title: arg })
+          return `renamed to "${c.title}"`
+        })
+      }
+      if (action === 'websearch' || action === 'rag') {
+        const state = argParts[0]
+        if (state !== 'on' && state !== 'off') return notice(`usage: /chat ${action} on|off`)
+        const enabled = state === 'on'
+        return run(async () => {
+          if (action === 'rag') await engine.setChatRagEnabled({ id: this.chatId, enabled })
+          else await engine.setChatWebSearchEnabled({ id: this.chatId, enabled })
+          return `${action === 'rag' ? 'RAG' : 'web search'} ${state} for this chat`
+        })
+      }
+      return notice(
+        'usage: /chat [new <title>|use <id>|rename <title>|del <id>|websearch on|off|rag on|off]'
+      )
+    }
+
+    if (cmd === 'group') {
+      const [action, ...argParts] = rest
+      if (!action) return this._groupOverview()
+
+      // a needle matching nothing or several is a plain notice — a typo is not an engine error
+      const withGroup = (needle, fn) =>
+        run(async () => {
+          const { group, ambiguous } = await this._resolveGroup(needle)
+          if (ambiguous) return `"${needle}" matches ${ambiguous} groups — be specific`
+          if (!group) return `no group matching "${needle}"`
+          return fn(group)
+        })
+
+      if (action === 'new') {
+        const name = argParts.join(' ')
+        if (!name) return notice('usage: /group new <name>')
+        return run(async () => {
+          const group = await engine.createChatGroup({ name })
+          return `created group "${group.name}" (${group.id.slice(0, 8)})`
+        })
+      }
+      if (action === 'move') {
+        // group first, chat optional, so the one-argument form is a strict prefix of the two;
+        // tokenized rather than joined, which is why a name with a space has to be quoted
+        const [groupNeedle, chatNeedle, ...extra] = splitPaths(argParts.join(' '))
+        if (!groupNeedle || extra.length > 0) {
+          return notice(
+            'usage: /group move <group>|- [chat]   (defaults to this chat; quote a name with spaces)'
+          )
+        }
+        // a miss comes back as text, not a throw, so it renders as a notice like every other miss
+        const target = async () => {
+          if (!chatNeedle) return { id: this.chatId, what: 'this chat' }
+          const { chat, ambiguous } = await this._resolveChat(chatNeedle)
+          if (ambiguous) return { miss: `"${chatNeedle}" matches ${ambiguous} chats — be specific` }
+          if (!chat) return { miss: `no chat matching "${chatNeedle}"` }
+          return { id: chat.id, what: `"${chat.title}"` }
+        }
+        if (groupNeedle === '-') {
+          return run(async () => {
+            const { id, what, miss } = await target()
+            if (miss) return miss
+            await engine.setChatGroup({ id })
+            return `${what} is ungrouped`
+          })
+        }
+        return withGroup(groupNeedle, async (group) => {
+          const { id, what, miss } = await target()
+          if (miss) return miss
+          await engine.setChatGroup({ id, groupId: group.id })
+          return `moved ${what} to "${group.name}"`
+        })
+      }
+      if (action === 'rename') {
+        // quoted, or the first token is the needle and `Day job` -> `Personal` is inexpressible
+        const [needle, ...nameParts] = splitPaths(argParts.join(' '))
+        const name = nameParts.join(' ')
+        if (!needle || !name) {
+          return notice(
+            'usage: /group rename <group> <name>   (quote a group whose name has a space)'
+          )
+        }
+        return withGroup(needle, async (group) => {
+          const renamed = await engine.renameChatGroup({ id: group.id, name })
+          return `renamed "${group.name}" to "${renamed.name}"`
+        })
+      }
+      if (action === 'del') {
+        const needle = argParts.join(' ')
+        if (!needle) return notice('usage: /group del <group>')
+        return withGroup(needle, async (group) => {
+          await engine.deleteChatGroup({ id: group.id })
+          return `deleted "${group.name}" — its chats are now ungrouped`
+        })
+      }
+      return notice('usage: /group [new <name>|rename <group> <name>|del <group>|move <group>|-]')
+    }
+
+    return notice(`unknown command: /${cmd}\n${HELP}`)
+  }
+
+  // Exact id wins; otherwise a prefix must be UNIQUE — an ambiguous prefix is reported, never
+  // silently resolved to whichever chat sorts first. Returns { chat } | { ambiguous: n } | {}.
+  async _resolveChat(needle) {
+    const { chats } = await this.engine.listChats({})
+    const live = (chats ?? []).filter((c) => !c.deletedAt)
+    const lower = needle.toLowerCase()
+    // id first so a needle that is a real id can never be shadowed by a chat titled the same
+    const exact =
+      live.find((c) => c.id === needle) ?? live.find((c) => c.title.toLowerCase() === lower)
+    if (exact) return { chat: exact }
+    const matches = live.filter(
+      (c) => c.id.startsWith(needle) || c.title.toLowerCase().startsWith(lower)
+    )
+    if (matches.length > 1) return { ambiguous: matches.length }
+    return { chat: matches[0] ?? null }
+  }
+
+  // exact id, exact name, then a UNIQUE prefix of either — an ambiguous needle is reported,
+  // never resolved to whichever group happens to sort first
+  async _resolveGroup(needle) {
+    const { groups } = await this.engine.listChatGroups({})
+    const live = groups ?? []
+    const lower = needle.toLowerCase()
+    const exact =
+      live.find((g) => g.id === needle) ?? live.find((g) => g.name.toLowerCase() === lower)
+    if (exact) return { group: exact }
+    const matches = live.filter(
+      (g) => g.id.startsWith(needle) || g.name.toLowerCase().startsWith(lower)
+    )
+    if (matches.length > 1) return { ambiguous: matches.length }
+    return { group: matches[0] ?? null }
+  }
+
+  // core hands chats back oldest-activity first (app-runtime reverses to render); this does the
+  // same so the listing reads newest-first, and groups already arrive in presentation order
+  _groupOverview() {
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          const { chats, groups } = await engine.listChats({})
+          const live = [...(chats ?? [])].reverse()
+          const ago = (chat) =>
+            `${Math.round((Date.now() - (chat.lastActivityAt || chat.createdAt)) / 1000)}s ago`
+          const render = (chat) =>
+            `    ${chat.id === this.chatId ? '●' : ' '} ${chat.title} · ${chat.id.slice(0, 8)} · ${ago(chat)}`
+          const lines = []
+          for (const group of groups ?? []) {
+            const held = live.filter((chat) => chat.groupId === group.id)
+            lines.push(`  ▸ ${group.name} · ${group.id.slice(0, 8)}`)
+            lines.push(...(held.length ? held.map(render) : ['    (empty)']))
+          }
+          const loose = live.filter((chat) => !chat.groupId)
+          if (loose.length) {
+            lines.push('  ▸ (ungrouped)')
+            lines.push(...loose.map(render))
+          }
+          return {
+            type: 'notice',
+            text: lines.length
+              ? `chats by group — most recently active first\n${lines.join('\n')}`
+              : 'no chats yet'
+          }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Any surviving chat other than `excludeId` — the delete-active fallback. Deliberately not prefix
+  // resolution: an empty needle must not read as an ambiguous match.
+  async _anyLiveChat(excludeId) {
+    const { chats } = await this.engine.listChats({})
+    return (chats ?? []).find((c) => !c.deletedAt && c.id !== excludeId) ?? null
+  }
+
+  // The chat's agent is authoritative — a chat owned by a different agent must run under that agent,
+  // not whichever one happens to be active (else _submit() runs the wrong provider).
+  async _agentFor(chat) {
+    if (chat.agentId === this.agent.id) return this.agent
+    return (await this.engine.getAgent({ id: chat.agentId })) ?? this.agent
+  }
+
+  _newChat(title) {
+    return [
+      this,
+      async () => {
+        try {
+          const chat = await this.engine.createChat({ agentId: this.agent.id, title })
+          return { type: 'chat.switch', chat, agent: this.agent }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  _useChat(needle) {
+    return [
+      this,
+      async () => {
+        try {
+          const { chat, ambiguous } = await this._resolveChat(needle)
+          if (ambiguous) {
+            return {
+              type: 'notice',
+              text: `"${needle}" matches ${ambiguous} chats — be more specific`
+            }
+          }
+          if (!chat) return { type: 'notice', text: `no chat matching "${needle}"` }
+          return { type: 'chat.switch', chat, agent: await this._agentFor(chat) }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  _deleteChat(needle) {
+    return [
+      this,
+      async () => {
+        try {
+          const { chat, ambiguous } = await this._resolveChat(needle)
+          if (ambiguous) {
+            return {
+              type: 'notice',
+              text: `"${needle}" matches ${ambiguous} chats — be more specific`
+            }
+          }
+          if (!chat) return { type: 'notice', text: `no chat matching "${needle}"` }
+          await this.engine.deleteChat({ id: chat.id })
+          if (chat.id !== this.chatId) {
+            return { type: 'notice', text: `deleted "${chat.title}" (${chat.id.slice(0, 8)})` }
+          }
+          // deleted the active chat — switch to any survivor, else a fresh one
+          const next =
+            (await this._anyLiveChat(chat.id)) ??
+            (await this.engine.createChat({ agentId: this.agent.id, title: 'New Chat' }))
+          return { type: 'chat.switch', chat: next, agent: await this._agentFor(next) }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Tear down the chat-scoped watches so the next arm rebuilds them, bumping the
+  // chunk-only gen so a stale frame from the old chat is dropped. The cached
+  // iterators are bound to a chat that is no longer the one on screen — after a
+  // switch, or after a join replaced every chat in the mesh.
+  _resetChatWatches() {
+    this._chunkIterator?.return?.().catch(() => {})
+    this._chunkIterator = null
+    this._filesIterator?.return?.().catch(() => {})
+    this._filesIterator = null
+    this._files = []
+    this._chunkGen += 1
+  }
+
+  // Swap the active chat: drop the old chat's watches, adopt the chat's owning
+  // agent, clear the transcript + run state, and re-arm on the new chatId.
+  _switchTo(chat, agent) {
+    this._resetChatWatches()
+    this.chatId = chat.id
+    if (agent) this.agent = agent
+    this._turns = []
+    this.busy = false
+    this._awaitingRun = false
+    this._runningRunId = null
+    this.pendingApproval = null
+    this.notice = `switched to "${chat.title}" (${chat.id.slice(0, 8)})`
+    this._render()
+  }
+
+  _accumulatePaste(msg) {
+    if (msg.name === 'return' || msg.name === 'linefeed') {
+      this._paste += '\n'
+      return
+    }
+    if (msg.name === 'tab') {
+      this._paste += '\t'
+      return
+    }
+    const ch = msg.sequence
+    if (typeof ch === 'string' && !msg.ctrl && !msg.meta && ch >= ' ') this._paste += ch
+  }
+
+  // single-line pastes type straight in; multi-line becomes a one-line
+  // placeholder ("[pasted #1: 12 lines]") expanded back at submit
+  _insertPaste() {
+    const text = this._paste ?? ''
+    this._paste = null
+    if (!text) return
+    const lines = text.split('\n').length
+    if (lines === 1) return this._insertText(text)
+    const placeholder = `[pasted #${this._pastes.size + 1}: ${lines} lines]`
+    this._pastes.set(placeholder, text)
+    this._insertText(placeholder)
+  }
+
+  _insertText(text) {
+    const input = this.input
+    input.value = input.value.slice(0, input.cursor) + text + input.value.slice(input.cursor)
+    input.cursor += text.length
+  }
+
+  _expandPastes(text) {
+    for (const [placeholder, full] of this._pastes) text = text.split(placeholder).join(full)
+    this._pastes.clear()
+    return text
+  }
+
+  _setInput(text) {
+    this.input.value = text
+    this.input.cursor = text.length
+  }
+
+  // Claimed before textinput, whose is('left'/'backspace') matches the bare name
+  // and would swallow the chord as a single-character move.
+  _editKey(msg) {
+    const { value, cursor } = this.input
+    if (key.matches(msg, 'alt+enter', 'linefeed') || msg.sequence === SHIFT_ENTER) {
+      this._insertText('\n')
+      return true
+    }
+    if (key.matches(msg, 'alt+left', 'alt+b', 'ctrl+left')) {
+      this.input.cursor = wordStart(value, cursor)
+      return true
+    }
+    if (key.matches(msg, 'alt+right', 'alt+f', 'ctrl+right')) {
+      this.input.cursor = wordEnd(value, cursor)
+      return true
+    }
+    if (key.matches(msg, 'alt+backspace', 'ctrl+w')) {
+      const at = wordStart(value, cursor)
+      this.input.value = value.slice(0, at) + value.slice(cursor)
+      this.input.cursor = at
+      return true
+    }
+    return false
+  }
+
+  // Records a submitted line for ↑/↓ recall (dropping blanks and consecutive
+  // duplicates) and leaves recall mode.
+  _pushHistory(line) {
+    this._historyAt = null
+    this._historyDraft = ''
+    const value = line.trim()
+    if (!value || this._history[this._history.length - 1] === value) return
+    this._history.push(value)
+  }
+
+  // ↑ (delta -1) walks toward older entries, ↓ (delta +1) toward newer; the
+  // first ↑ stashes the in-progress line so ↓ past the newest restores it.
+  _recall(delta) {
+    if (!this._history.length) return
+    if (this._historyAt === null) {
+      if (delta > 0) return
+      this._historyDraft = this.input.value
+      this._historyAt = this._history.length
+    }
+    const next = this._historyAt + delta
+    if (next >= this._history.length) {
+      this._historyAt = null
+      this._setInput(this._historyDraft)
+      return
+    }
+    this._historyAt = Math.max(0, next)
+    this._setInput(this._history[this._historyAt])
+  }
+
+  _showDiagnostics() {
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          const { stats } = await engine.diagnostics({})
+          return { type: 'diagnostics.result', stats }
+        } catch (error) {
+          return { type: 'diagnostics.result', error }
+        }
+      }
+    ]
+  }
+
+  // /models [type]: fetch the full SDK registry via the Engine RPC (both
+  // topologies wire harness.list into Core.listModels) and overlay it. Always
+  // fullRegistry — the curated subset was a second command (/all-sdk-models);
+  // one browsable list plus the type filter replaces both.
+  _showModels(type) {
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          const { models } = await engine.listModels({
+            fullRegistry: true,
+            ...(type ? { type } : {})
+          })
+          return { type: 'models.result', filter: type, rows: models ?? [] }
+        } catch (error) {
+          return { type: 'models.result', filter: type, rows: null, error }
+        }
+      }
+    ]
+  }
+
+  // The provider device's advertised inventory — the installed skills/tools
+  // the active agent may enable (empty when the provider is offline).
+  async _providerCaps() {
+    const { devices } = await this.engine.listDevices({})
+    const hex = this.agent.providerDeviceId?.toString('hex')
+    const dev = devices.find((d) => d.id.toString('hex') === hex)
+    return { skills: dev?.installedSkillNames ?? [], tools: dev?.installedToolNames ?? [] }
+  }
+
+  // /skills + /tools: overlay the provider's installed list against the agent's
+  // enabled set. scope=all opens with everything on (see selector.result); a
+  // toggle then flips the agent to an explicit selected set.
+  _showSelector(kind) {
+    const { engine, agent } = this
+    return [
+      this,
+      async () => {
+        try {
+          const fresh = await engine.getAgent({ id: agent.id })
+          const caps = await this._providerCaps()
+          const scope = (kind === 'skills' ? fresh.skillsScope : fresh.toolsScope) ?? 'selected'
+          const enabled = (kind === 'skills' ? fresh.enabledSkills : fresh.enabledTools) ?? []
+          const detail = kind === 'skills' ? await this._skillDetail() : null
+          return { type: 'selector.result', kind, installed: caps[kind], scope, enabled, detail }
+        } catch (error) {
+          return { type: 'selector.result', kind, error }
+        }
+      }
+    ]
+  }
+
+  // Per-skill setup state, keyed by name. Null when the engine cannot report it
+  // (pre-upgrade provider) — the selector then renders as it always did.
+  async _skillDetail() {
+    if (!this._skills) return null
+    const skills = await this._skills(this.agent?.id, this.agent?.modelName).catch(() => null)
+    return skills ? new Map(skills.map((skill) => [skill.name, skill])) : null
+  }
+
+  // The PRD's Tools screen: the approval mode on top, then the toolset switches. Rows come
+  // from TOOLSETS, not the provider catalog — a toolset with nothing installed here still shows,
+  // so it can be switched off before the agent ever runs somewhere that has it.
+  _showPermissions() {
+    const { engine, agent } = this
+    return [
+      this,
+      async () => {
+        try {
+          const fresh = await engine.getAgent({ id: agent.id })
+          return {
+            type: 'permissions.result',
+            mode: fresh.approvalMode === 'skip-all' ? 'skip-all' : 'ask',
+            disabled: fresh.disabledToolsets ?? []
+          }
+        } catch (error) {
+          return { type: 'permissions.result', error }
+        }
+      }
+    ]
+  }
+
+  // ctrl+p / /menu: open the menu at its root, clearing any other overlay first.
+  _openMenu() {
+    this._models = null
+    this._selector = null
+    this.overlay = null
+    this._menu = { pages: [this._rootMenu()] }
+    this._render()
+    return [this, null]
+  }
+
+  // The command groups as one browsable tree. An entry carries exactly one of:
+  // submenu (push a page), overlay (open an interactive list, menu stays under
+  // it), command (dispatch a /command, close), prefill (stub the input, close).
+  _rootMenu() {
+    return {
+      title: 'Menu',
+      cursor: 0,
+      entries: [
+        { label: 'Agent', hint: 'skills, tools, permissions, model', submenu: true },
+        { label: 'Chat', hint: 'this chat, knowledge, attachments', submenu: true },
+        { label: 'Models', hint: "browse and pick the agent's model", overlay: 'models' },
+        { label: 'Voice', hint: 'speak, transcribe, converse', submenu: true },
+        { label: 'My device', hint: 'CPU / GPU inventory', overlay: 'diagnostics' },
+        { label: 'Mesh', hint: 'join another device’s mesh', submenu: true },
+        { label: 'Advanced', hint: 'credentials, scope, skill setup status', submenu: true },
+        { label: 'Help', hint: 'list every command', command: '/help' }
+      ]
+    }
+  }
+
+  _agentMenu() {
+    return {
+      title: `Agent · ${this.agent?.name ?? '?'}`,
+      cursor: 0,
+      entries: [
+        { label: 'Skills', hint: 'toggle skills on/off', overlay: 'skills' },
+        { label: 'Tools', hint: 'toggle tools on/off', overlay: 'tools' },
+        { label: 'Permissions', hint: 'approval mode & toolsets', overlay: 'permissions' },
+        { label: 'Model', hint: "pick the agent's model", overlay: 'models' },
+        { label: 'Image defaults', hint: 'model, steps, size', command: '/image' },
+        { label: 'Activity', hint: 'recent tool calls', command: '/activity' },
+        {
+          label: 'Connections',
+          hint: 'set up skills that need an account',
+          submenu: true,
+          connections: true
+        },
+        { label: 'Switch agent', hint: 'pick from your agents', submenu: true, agents: true },
+        { label: 'New agent…', hint: '/agent new <name>', prefill: '/agent new ' },
+        { label: 'Rename agent…', hint: '/agent rename <name>', prefill: '/agent rename ' }
+      ]
+    }
+  }
+
+  _connectMenu() {
+    return {
+      title: 'Connections',
+      cursor: 0,
+      entries: [
+        { label: 'Connect Gmail', hint: 'OAuth Gmail', command: '/connect gmail' },
+        {
+          label: 'Connect Google Calendar',
+          hint: 'OAuth Calendar',
+          command: '/connect google-calendar'
+        },
+        { label: 'Connect Google Docs', hint: 'OAuth Docs', command: '/connect google-docs' },
+        { label: 'Connect Google Drive', hint: 'OAuth Drive', command: '/connect google-drive' },
+        { label: 'Connect Google Sheets', hint: 'OAuth Sheets', command: '/connect google-sheets' },
+        { label: 'Connect Spotify', hint: 'OAuth Spotify (PKCE)', command: '/connect spotify' },
+        { label: 'Connect Notion', hint: 'OAuth Notion MCP', command: '/connect notion' },
+        { label: 'Connect Asana', hint: 'OAuth Asana MCP', command: '/connect asana' }
+      ]
+    }
+  }
+
+  // The live Connections page: every skill that needs an account or a token,
+  // with its current state and the one command that sets it up — so a pasted-token
+  // skill (github) sits beside the OAuth ones instead of being invisible here.
+  // Falls back to the static OAuth list when the engine cannot report skills.
+  _connectPage() {
+    return [
+      this,
+      async () => {
+        const detail = await this._skillDetail()
+        const rows = [...(detail?.values() ?? [])].flatMap((skill) =>
+          setupActions(skill)
+            .filter((action) => action.command || action.prefill)
+            .map((action) => ({ skill, action }))
+        )
+        if (!rows.length) return { type: 'menu.page', page: this._connectMenu() }
+        const entries = rows.map(({ skill, action }) => ({
+          label: `${isReady(skill) ? '●' : '○'} ${action.label}`,
+          hint: `${skill.name} · ${statusLabel(skill.status)}`,
+          command: action.command,
+          prefill: action.prefill
+        }))
+        return { type: 'menu.page', page: { title: 'Connections', cursor: 0, entries } }
+      }
+    ]
+  }
+
+  // The rarely-needed switches, kept off the main paths: a raw credential write,
+  // the scope flip, and the full setup dump for every skill.
+  _advancedMenu() {
+    return {
+      title: 'Advanced',
+      cursor: 0,
+      entries: [
+        { label: 'Set credential…', hint: '/cred <key> <value>', prefill: '/cred ' },
+        { label: 'Skills scope…', hint: '/scope skills all|selected', prefill: '/scope skills ' },
+        { label: 'Tools scope…', hint: '/scope tools all|selected', prefill: '/scope tools ' }
+      ]
+    }
+  }
+
+  _chatMenu() {
+    return {
+      title: 'Chat',
+      cursor: 0,
+      entries: [
+        { label: 'Chats sidebar', hint: 'ctrl+b — browse chats, m moves one', sidebar: true },
+        { label: 'Switch chat', hint: 'pick from your chats', submenu: true, chats: true },
+        { label: 'New chat', hint: 'create & switch to a new chat', command: '/chat new' },
+        { label: 'Rename chat…', hint: '/chat rename <title>', prefill: '/chat rename ' },
+        { label: 'Web search…', hint: '/chat websearch on|off', prefill: '/chat websearch ' },
+        { label: 'RAG…', hint: '/chat rag on|off', prefill: '/chat rag ' },
+        { label: 'Groups', hint: 'chats by group, in sidebar order', command: '/group' },
+        { label: 'Move to group…', hint: '/group move <group>|-', prefill: '/group move ' },
+        { label: 'New group…', hint: '/group new <name>', prefill: '/group new ' },
+        { label: 'Knowledge', hint: 'list chat knowledge', command: '/knowledge' },
+        { label: 'Files', hint: 'readiness, progress, and failures', command: '/files' },
+        { label: 'Attach file…', hint: '/attach <path>', prefill: '/attach ' },
+        { label: 'Save attachment', hint: 'latest → save dir', command: '/save' },
+        { label: 'Export last run', hint: 'markdown → save dir', command: '/export' }
+      ]
+    }
+  }
+
+  _meshMenu() {
+    return {
+      title: 'Mesh',
+      cursor: 0,
+      entries: [
+        { label: 'Join mesh…', hint: '/join <qvac://mesh/…>', prefill: '/join ' },
+        { label: 'Cancel join', hint: 'abort a join in progress', command: '/join cancel' }
+      ]
+    }
+  }
+
+  _voiceMenu() {
+    return {
+      title: 'Voice',
+      cursor: 0,
+      entries: [
+        { label: 'Speak…', hint: '/speak <text>', prefill: '/speak ' },
+        { label: 'Transcribe…', hint: '/transcribe <path>', prefill: '/transcribe ' },
+        { label: 'Record & transcribe', hint: '/record [seconds]', command: '/record' },
+        { label: 'Converse (hands-free)', hint: 'mic conversation', command: '/converse' }
+      ]
+    }
+  }
+
+  // The submenu a `submenu` row opens, keyed by label — kept next to the page
+  // builders so adding a branch is a one-line entry plus its page.
+  _submenuFor(label) {
+    if (label === 'Agent') return this._agentMenu()
+    if (label === 'Chat') return this._chatMenu()
+    if (label === 'Advanced') return this._advancedMenu()
+    if (label === 'Mesh') return this._meshMenu()
+    if (label === 'Voice') return this._voiceMenu()
+    return null
+  }
+
+  // The agents list as a menu page, fetched fresh — a `useAgent` row per agent,
+  // the active one marked and pre-cursored. Pushed via a menu.page message once
+  // the fetch resolves, so it opens like any other submenu.
+  _agentListPage() {
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          const { agents } = await engine.listAgents({})
+          const list = agents ?? []
+          const active = this.agent?.id
+          const entries = list.length
+            ? list.map((a) => ({
+                label: `${a.id === active ? '●' : ' '} ${a.name}`,
+                hint: a.id.slice(0, 8),
+                useAgent: a.id
+              }))
+            : [{ label: '(no agents)', hint: '' }]
+          const cursor = Math.max(
+            0,
+            list.findIndex((a) => a.id === active)
+          )
+          return { type: 'menu.page', page: { title: 'Switch agent', cursor, entries } }
+        } catch (error) {
+          return {
+            type: 'menu.page',
+            page: {
+              title: 'Switch agent',
+              cursor: 0,
+              entries: [{ label: "(couldn't load agents)", hint: error.message }]
+            }
+          }
+        }
+      }
+    ]
+  }
+
+  // The live chats as a menu page — a `useChat` row per chat (title + short id,
+  // with web/rag badges), the active one marked and pre-cursored. Same async
+  // push as _agentListPage.
+  _chatListPage() {
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          const { chats, groups } = await engine.listChats({})
+          const live = [...(chats ?? [])].reverse().filter((c) => !c.deletedAt)
+          const active = this.chatId
+          // reversed for the same reason as /group: core's list is oldest-activity first
+          const groupName = new Map((groups ?? []).map((g) => [g.id, g.name]))
+          const entries = live.length
+            ? live.map((c) => ({
+                label: `${c.id === active ? '●' : ' '} ${c.title}`,
+                hint:
+                  `${c.id.slice(0, 8)}` +
+                  `${c.groupId ? ` [${groupName.get(c.groupId)}]` : ''}` +
+                  `${c.webSearchEnabled ? ' [web]' : ''}${c.ragEnabled ? ' [rag]' : ''}`,
+                useChat: c.id
+              }))
+            : [{ label: '(no chats)', hint: '' }]
+          const cursor = Math.max(
+            0,
+            live.findIndex((c) => c.id === active)
+          )
+          return { type: 'menu.page', page: { title: 'Switch chat', cursor, entries } }
+        } catch (error) {
+          return {
+            type: 'menu.page',
+            page: {
+              title: 'Switch chat',
+              cursor: 0,
+              entries: [{ label: "(couldn't load chats)", hint: error.message }]
+            }
+          }
+        }
+      }
+    ]
+  }
+
+  // Enter/→ on the highlighted row. A submenu pushes a page (the agents/chats
+  // lists are fetched first); an overlay opens the matching interactive list
+  // (menu stays set, so esc falls back to it); useAgent/useChat switches the
+  // active agent/chat; a command dispatches and closes; a prefill hands the
+  // input a ready stub.
+  _menuActivate() {
+    const page = this._menu.pages[this._menu.pages.length - 1]
+    const entry = page.entries[page.cursor]
+    if (!entry) return [this, null]
+    if (entry.agents) return this._agentListPage()
+    if (entry.chats) return this._chatListPage()
+    if (entry.connections) return this._connectPage()
+    if (entry.sidebar) {
+      this._menu = null
+      return this._toggleSidebar()
+    }
+    if (entry.useAgent) {
+      this._menu = null
+      return this._command(`/agent use ${entry.useAgent}`)
+    }
+    if (entry.useChat) {
+      this._menu = null
+      return this._useChat(entry.useChat)
+    }
+    if (entry.submenu) {
+      const next = this._submenuFor(entry.label)
+      if (next) this._menu.pages.push(next)
+      this._render()
+      return [this, null]
+    }
+    if (entry.overlay) {
+      if (entry.overlay === 'models') return this._showModels(null)
+      if (entry.overlay === 'diagnostics') return this._showDiagnostics()
+      if (entry.overlay === 'permissions') return this._showPermissions()
+      return this._showSelector(entry.overlay)
+    }
+    if (entry.prefill) {
+      this._menu = null
+      this._setInput(entry.prefill)
+      this._render()
+      return [this, null]
+    }
+    if (entry.command) {
+      this._menu = null
+      return this._command(entry.command)
+    }
+    return [this, null]
+  }
+
+  // The menu's own keys: ↑/↓ move, enter/→ activate, esc/←/backspace step back a
+  // page (or close at the root). Returns null for anything else so update() can
+  // dismiss the menu into the input, like the other overlays.
+  _menuKey(msg) {
+    const page = this._menu.pages[this._menu.pages.length - 1]
+    if (key.matches(msg, 'escape', 'left', 'backspace')) {
+      if (this._menu.pages.length > 1) this._menu.pages.pop()
+      else this._menu = null
+      this._render()
+      return [this, null]
+    }
+    if (key.matches(msg, 'up')) {
+      page.cursor = Math.max(0, page.cursor - 1)
+      this._render()
+      return [this, null]
+    }
+    if (key.matches(msg, 'down')) {
+      page.cursor = Math.min(page.entries.length - 1, page.cursor + 1)
+      this._render()
+      return [this, null]
+    }
+    if (key.matches(msg, 'enter', 'right')) return this._menuActivate()
+    return null
+  }
+
+  // Keep the given row inside the visible window as the cursor walks past an edge.
+  _scrollToLine(line) {
+    const h = this.vp.height
+    if (line < this.vp.yOffset) this.vp.setYOffset(line)
+    else if (line >= this.vp.yOffset + h) this.vp.setYOffset(line - h + 1)
+  }
+
+  _moveCursor(delta) {
+    const m = this._models ?? this._selector
+    m.cursor = Math.max(0, Math.min(m.rows.length - 1, m.cursor + delta))
+    this._render()
+    return [this, null]
+  }
+
+  // An overlay's own controls (arrows move/scroll, esc closes, enter adopts a
+  // model). Returns null for any other key, which update() reads as "not mine".
+  _overlayKey(msg) {
+    if (this._models) {
+      if (key.matches(msg, 'escape')) {
+        this._models = null
+        this._render()
+        return [this, null]
+      }
+      if (key.matches(msg, 'up')) return this._moveCursor(-1)
+      if (key.matches(msg, 'down')) return this._moveCursor(1)
+      if (key.matches(msg, 'pageup')) return this._moveCursor(-this.vp.height)
+      if (key.matches(msg, 'pagedown')) return this._moveCursor(this.vp.height)
+      if (key.matches(msg, 'enter')) return this._useModel()
+      return null
+    }
+    if (this._selector) {
+      if (key.matches(msg, 'escape')) {
+        this._selector = null
+        this._render()
+        return [this, null]
+      }
+      if (key.matches(msg, 'up')) return this._moveCursor(-1)
+      if (key.matches(msg, 'down')) return this._moveCursor(1)
+      if (key.matches(msg, 'pageup')) return this._moveCursor(-this.vp.height)
+      if (key.matches(msg, 'pagedown')) return this._moveCursor(this.vp.height)
+      if (key.matches(msg, 'space')) return this._toggleSelector()
+      if (key.matches(msg, 'enter')) return this._setupSelected()
+      return null
+    }
+    if (this.overlay) {
+      if (key.matches(msg, 'escape')) {
+        this.overlay = null
+        this._render()
+        return [this, null]
+      }
+      if (key.matches(msg, 'up')) this.vp.scrollUp(1)
+      else if (key.matches(msg, 'down')) this.vp.scrollDown(1)
+      else if (key.matches(msg, 'pageup')) this.vp.scrollUp(this.vp.height)
+      else if (key.matches(msg, 'pagedown')) this.vp.scrollDown(this.vp.height)
+      else return null
+      return [this, null]
+    }
+    // Lowest precedence: a selector/models/static overlay opened from a menu row
+    // keeps _menu set underneath, and its own branch above wins until it closes.
+    if (this._menu) return this._menuKey(msg)
+    return null
+  }
+
+  // Matches bare-tui textinput's own printable test — the keys that would type
+  // into the field. Typing one is how you "click back into the text box".
+  _isTypingKey(msg) {
+    const ch = msg.sequence
+    return (
+      !msg.ctrl &&
+      !msg.meta &&
+      typeof ch === 'string' &&
+      ch.length === 1 &&
+      ch >= ' ' &&
+      ch !== '\x7f'
+    )
+  }
+
+  // Enter on a row makes it the agent's model. Nothing downloads here — the
+  // provider pulls the model when the agent next runs (the run path is the
+  // download trigger), so the notice says exactly that.
+  _useModel() {
+    const row = this._models.rows[this._models.cursor]
+    this._models = null
+    if (!row) {
+      this._render()
+      return [this, null]
+    }
+    const { engine, agent } = this
+    return [
+      this,
+      async () => {
+        try {
+          this.agent = await engine.updateAgent({ id: agent.id, modelName: row.name })
+          return {
+            type: 'notice',
+            text: `${agent.name} now uses ${row.name} — downloads on next run`
+          }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Space on a row flips its enabled membership and persists it — the same
+  // write as /skill|/tool on|off, so any toggle moves the agent to scope=selected.
+  // Optimistic: the row updates now, the engine call syncs this.agent after.
+  _toggleSelector() {
+    const s = this._selector
+    const name = s.rows[s.cursor]
+    if (!name) return [this, null]
+    if (s.kind === 'permissions') return this._togglePermission(s, name)
+    if (s.enabled.has(name)) s.enabled.delete(name)
+    else s.enabled.add(name)
+    s.scope = 'selected'
+    this._render()
+    const field = s.kind === 'skills' ? 'enabledSkills' : 'enabledTools'
+    const scopeField = s.kind === 'skills' ? 'skillsScope' : 'toolsScope'
+    const enabled = [...s.enabled]
+    const { engine, agent } = this
+    return [
+      this,
+      async () => {
+        try {
+          this.agent = await engine.updateAgent({
+            id: agent.id,
+            [field]: enabled,
+            [scopeField]: 'selected'
+          })
+          return { type: 'selector.saved' }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Enter on a skill row runs its setup: an OAuth skill connects there and then,
+  // a token skill hands the input a ready `/cred <key> ` stub, and anything else
+  // prints its steps. The overlay closes either way — the setup is the next step.
+  _setupSelected() {
+    const s = this._selector
+    if (s.kind !== 'skills' || !s.detail) return [this, null]
+    const skill = s.detail.get(s.rows[s.cursor])
+    if (!skill) return [this, null]
+    const action = configureActions(skill)[0]
+    this._selector = null
+    if (action?.command) return this._command(action.command)
+    if (action?.prefill) this._setInput(action.prefill)
+    this._render()
+    return [this, async () => ({ type: 'notice', text: renderSkill(skill) })]
+  }
+
+  // ctrl+b: open the chat sidebar focused, focus it again when typing has handed
+  // focus back, and close it from there. It draws from the chats watch, so it
+  // opens on what has already replicated — no fetch, no flicker.
+  _toggleSidebar() {
+    const s = this._sidebar
+    if (!s) this._sidebar = { selected: this.chatId, focus: true, moving: null }
+    else if (s.focus) this._sidebar = null
+    else s.focus = true
+    this._render()
+    return [this, null]
+  }
+
+  _toggleToolOutput() {
+    this._expandTools = !this._expandTools
+    this._render()
+    return [this, null]
+  }
+
+  // The pane's rows: the chat tree, or the group picker while a chat is moving.
+  _sidebarRows() {
+    const moving = this._sidebar?.moving
+    if (moving) return moveRows(this._groups, moving.groupId)
+    return sidebarRows(this._chats, this._groups, this.chatId)
+  }
+
+  // The move picker tracks its own index; the chat tree tracks the selected
+  // chat by id, so rows arriving from another device can't move the cursor.
+  _sidebarCursor(rows) {
+    const s = this._sidebar
+    if (s.moving) return Math.min(Math.max(s.moving.cursor, 0), rows.length - 1)
+    const at = rows.findIndex((row) => row.chatId === s.selected)
+    return at === -1 ? firstSelectable(rows) : at
+  }
+
+  _moveSidebar(delta) {
+    const s = this._sidebar
+    const rows = this._sidebarRows()
+    const at = nextSelectable(rows, this._sidebarCursor(rows), delta)
+    if (s.moving) s.moving.cursor = at
+    else s.selected = rows[at]?.chatId ?? s.selected
+    this._render()
+    return [this, null]
+  }
+
+  // m on a chat row: the pane becomes the group picker for that chat, enter
+  // lands it. The chat's own group is left out — moving there is a no-op.
+  _startMove() {
+    const rows = this._sidebarRows()
+    const row = rows[this._sidebarCursor(rows)]
+    if (row?.kind !== 'chat') return [this, null]
+    const groupId = this._chats.find((chat) => chat.id === row.chatId)?.groupId ?? null
+    this._sidebar.moving = {
+      chatId: row.chatId,
+      groupId,
+      cursor: firstSelectable(moveRows(this._groups, groupId))
+    }
+    this._render()
+    return [this, null]
+  }
+
+  _sidebarActivate() {
+    const s = this._sidebar
+    const rows = this._sidebarRows()
+    const row = rows[this._sidebarCursor(rows)]
+    if (!row) return [this, null]
+    if (row.kind === 'chat') return this._useChat(row.chatId)
+    const { chatId } = s.moving
+    s.moving = null
+    if (row.kind === 'new-group') {
+      this._setInput('/group new ')
+      s.focus = false
+      this._render()
+      return [this, null]
+    }
+    this._render()
+    const { engine } = this
+    const token = ++this._statusToken
+    return [
+      this,
+      async () => {
+        try {
+          await engine.setChatGroup({ id: chatId, groupId: row.groupId ?? undefined })
+          return { type: 'transient-status', token, text: `moved to ${row.label}` }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // The sidebar's own keys while it has focus. Returns null for anything else,
+  // which update() reads as "type into the input" — the pane stays open, it
+  // just hands focus back.
+  _sidebarKey(msg) {
+    const s = this._sidebar
+    if (key.matches(msg, 'up')) return this._moveSidebar(-1)
+    if (key.matches(msg, 'down')) return this._moveSidebar(1)
+    if (key.matches(msg, 'enter')) return this._sidebarActivate()
+    if (!s.moving && key.matches(msg, 'm')) return this._startMove()
+    if (key.matches(msg, 'escape')) {
+      if (s.moving) s.moving = null
+      else this._sidebar = null
+      this._render()
+      return [this, null]
+    }
+    return null
+  }
+
+  // Space on the mode row flips ask <-> skip-all; on any other row it flips that toolset. Same
+  // optimistic write as the skills/tools selector: the row moves now, the engine call follows.
+  _togglePermission(s, name) {
+    if (name === MODE_ROW) s.mode = s.mode === 'skip-all' ? 'ask' : 'skip-all'
+    else if (s.enabled.has(name)) s.enabled.delete(name)
+    else s.enabled.add(name)
+    this._render()
+    const patch =
+      name === MODE_ROW
+        ? { approvalMode: s.mode }
+        : {
+            disabledToolsets: [
+              ...TOOLSETS.filter((toolset) => !s.enabled.has(toolset)),
+              ...s.unknown
+            ]
+          }
+    const { engine, agent } = this
+    return [
+      this,
+      async () => {
+        try {
+          this.agent = await engine.updateAgent({ id: agent.id, ...patch })
+          return { type: 'selector.saved' }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Voice conversation loop, mirroring v1's design: an energy-VAD silence recorder
+  // captures ONE utterance from the mic, then unary transcribe (reliable, unlike
+  // live duplex STT) -> sendMessage -> speakStream -> ffplay, looping. During playback
+  // the VAD threshold rises to reject the assistant's own audio (echo); real speech
+  // over it is a barge-in that cuts playback. Runs in the background, painting
+  // status via _requestRepaint; Esc or a second /converse stops it. Needs
+  // headphones for clean barge-in; the RMS thresholds below are tunable.
+  _startConverse(device) {
+    const state = {
+      device,
+      mic: null,
+      player: null,
+      ttsDuplex: null,
+      chunkWatch: null,
+      runId: null,
+      speaking: false,
+      playing: false,
+      turnBusy: false,
+      stopped: false
+    }
+    this._converse = state
+    this._converseListen(state)
+  }
+
+  _stopConverse(reason) {
+    const state = this._converse
+    if (!state) return
+    state.stopped = true
+    try {
+      state.mic?.kill('SIGKILL')
+    } catch {}
+    try {
+      state.player?.kill('SIGKILL')
+    } catch {}
+    try {
+      state.ttsDuplex?.destroy?.()
+    } catch {}
+    this._converse = null
+    this.status = reason ? `conversation ${reason}` : ''
+    this._requestRepaint()
+  }
+
+  _converseListen(state) {
+    const LISTEN_RMS = 350 // speech vs a quiet room
+    const BARGE_RMS = 1600 // higher during playback to reject the TTS echo
+    const SILENCE_MS = 700 // trailing quiet that ends an utterance
+    const MIN_SPEECH_MS = 300 // ignore short noise blips
+    const mic = micProcess(state.device)
+    state.mic = mic
+    mic.on('error', () => this._stopConverse('mic error'))
+    mic.stdout.on('error', () => {}) // killed mic leaves a dead pipe; never let it abort
+    mic.on('close', () => {
+      if (!state.stopped) this._stopConverse('mic ended')
+    })
+    let recording = false
+    let parts = []
+    let speechMs = 0
+    let silenceMs = 0
+    this.status = '🎤 listening…'
+    this._requestRepaint()
+    mic.stdout.on('data', (chunk) => {
+      if (state.stopped) return
+      const chunkMs = (chunk.length / 2 / 16000) * 1000
+      // low bar while the assistant is silent (generating), high bar once audio
+      // is playing so the TTS echo doesn't self-interrupt.
+      const loud = rmsS16(chunk) > (state.playing ? BARGE_RMS : LISTEN_RMS)
+      // barge-in spans the whole assistant turn (generation AND playback): cut
+      // the run, the TTS, and the audio, and clear turnBusy so this same chunk
+      // falls through and starts capturing the interrupting utterance below.
+      if (state.speaking) {
+        if (!loud) return
+        state.speaking = false
+        state.turnBusy = false
+        if (state.runId) {
+          void this.engine.stopRun({ chatId: this.chatId, runId: state.runId }).catch(() => {})
+        }
+        try {
+          state.player?.kill('SIGKILL')
+        } catch {}
+        try {
+          state.ttsDuplex?.destroy?.()
+        } catch {}
+        this.status = '🎤 listening…'
+        this._requestRepaint()
+      }
+      if (state.turnBusy) return // transcribing — don't capture (unary, not interruptible)
+      if (loud) {
+        if (!recording) {
+          recording = true
+          parts = []
+          speechMs = 0
+        }
+        parts.push(chunk)
+        speechMs += chunkMs
+        silenceMs = 0
+      } else if (recording) {
+        parts.push(chunk)
+        silenceMs += chunkMs
+        if (silenceMs >= SILENCE_MS) {
+          recording = false
+          const pcm = Buffer.concat(parts)
+          parts = []
+          if (speechMs >= MIN_SPEECH_MS) void this._converseTurn(state, pcm)
+        }
+      }
+    })
+  }
+
+  async _converseTurn(state, pcm) {
+    state.turnBusy = true
+    try {
+      this.status = '📝 transcribing…'
+      this._requestRepaint()
+      const { text } = await this.engine.transcribe({ audio: pcm16ToWav(pcm, 16000) })
+      const clean = (text || '').trim()
+      if (state.stopped) return
+      if (!clean) return
+      this.status = `💬 ${clean}`
+      this._requestRepaint()
+      // sendMessage names the run it just enqueued, so the producer below can
+      // follow that exact turn instead of diffing against a pre-turn snapshot
+      const { runId } = await this.engine.sendMessage({
+        chatId: this.chatId,
+        agentId: this.agent.id,
+        text: clean
+      })
+      await this._converseRespond(state, runId)
+    } catch (err) {
+      if (!state.stopped) {
+        this.status = `turn error: ${err?.message ?? err}`
+        this._requestRepaint()
+      }
+    } finally {
+      state.turnBusy = false
+      if (!state.stopped) {
+        this.status = '🎤 listening…'
+        this._requestRepaint()
+      }
+    }
+  }
+
+  // Interleaves reply generation with TTS: a producer follows the new run's turn
+  // over chunksWatch and writes each newly-complete sentence into speakStream as
+  // the model emits it; the consumer plays the audio frames as they arrive, so the
+  // assistant starts talking at the first sentence instead of after the whole reply.
+  // Event-driven off the watch (no polling); `runId` is the run sendMessage just
+  // enqueued, so a prior reply — or a concurrent run from another device — is
+  // never mistaken for this turn.
+  async _converseRespond(state, runId) {
+    const duplex = this.engine.speakStream()
+    state.ttsDuplex = duplex
+    state.speaking = true
+    let player = null
+    const writePcm = (bytes) => {
+      // a killed ffplay leaves a dead pipe; an unhandled EPIPE here aborts the
+      // whole process (SIGABRT), so swallow every write/close error.
+      if (!player || !player.stdin.writable) return
+      try {
+        player.stdin.write(bytes)
+      } catch {}
+    }
+
+    const watch = this.engine.chunksWatch({ chatId: this.chatId })[Symbol.asyncIterator]()
+    state.chunkWatch = watch
+    state.runId = runId // for barge-in stopRun, armed before the turn materializes
+    const producer = (async () => {
+      let spoken = 0
+      let content = ''
+      while (!state.stopped && state.speaking) {
+        const { value, done } = await watch.next()
+        if (done) break
+        const turns = turnsFromChunks(value.chunks)
+        // this turn is the agent turn carrying the run sendMessage named — until
+        // it materializes, keep waiting rather than speaking a prior reply
+        const target = turns.find((turn) => turn.from === 'agent' && turn.runId === runId)
+        if (!target) continue
+        content = target.segments
+          .filter((segment) => segment.type === 'content')
+          .map((segment) => segment.text)
+          .join('')
+        this.status = `🔊 ${content}`
+        this._requestRepaint()
+        const ready = spoken + completePrefixLen(content.slice(spoken))
+        if (ready > spoken) {
+          try {
+            duplex.write({ text: content.slice(spoken, ready) })
+          } catch {}
+          spoken = ready
+        }
+        // break as soon as the new run is terminal — one that fails right after
+        // enqueue still ends the loop instead of waiting on a run that never streams.
+        if (!runInFlight(turns)) break
+      }
+      const tail = content.slice(spoken).trim()
+      if (tail && !state.stopped) {
+        try {
+          duplex.write({ text: tail })
+        } catch {}
+      }
+      try {
+        duplex.end()
+      } catch {}
+    })()
+
+    try {
+      for await (const frame of duplex) {
+        if (state.stopped || !state.speaking) break
+        if (!player) {
+          player = playerProcess(frame.sampleRate)
+          state.player = player
+          state.playing = true // audio is now audible → raise the barge-in bar
+          player.on('error', () => {})
+          player.stdin.on('error', () => {})
+        }
+        writePcm(frame.audio)
+      }
+      if (player && player.stdin.writable) {
+        try {
+          player.stdin.end()
+        } catch {}
+        await new Promise((resolve) => player.once('close', resolve))
+      }
+    } catch {
+      // duplex destroyed / errored (barge-in or stop)
+    } finally {
+      state.speaking = false
+      state.playing = false
+      // close the watch so a producer parked on watch.next() unblocks and exits
+      try {
+        await watch.return?.()
+      } catch {}
+      await producer.catch(() => {})
+      try {
+        duplex.destroy?.()
+      } catch {}
+      try {
+        player?.kill('SIGKILL')
+      } catch {}
+      state.ttsDuplex = null
+      state.chunkWatch = null
+      state.player = null
+      state.runId = null
+    }
+  }
+
+  _submit() {
+    // Still resolving the agent/chat — the input takes text but can't send yet.
+    if (this._booting) return [this, null]
+    const raw = this.input.value
+    const text = this._expandPastes(this.input.value).trim()
+    if (!text) return [this, null]
+    this._pushHistory(raw)
+    if (text.startsWith('/')) {
+      this.input.reset()
+      return this._command(text)
+    }
+    this.input.reset()
+    this.busy = true
+    this._awaitingRun = true
+    this.status = ''
+    this.notice = null
+    const { chatId, agent, engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          // One batched append: the user message and its run-request land in a
+          // single drain, so no peer can see the request before the message it
+          // answers. No device id either — the executing Core stamps every
+          // chunk with its own key; the host identity is never caller-supplied.
+          await engine.sendMessage({ chatId, agentId: agent.id, text })
+          return { type: 'run.done' }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Resolving is the dedicated resolve-approval op on the approval-request
+  // chunk — a decision, not a chunk edit, so ANY admitted device may answer
+  // (first decision wins). The provider's assistant is the one actually
+  // waiting (its chunk watch); there is no callback or resolver here at all.
+  // scope 'always' also mints a standing approval-rule from the request's
+  // tool + resource, so matching future calls never prompt again — on any
+  // device (the rule replicates like everything else).
+  _resolveApproval(status, scope = 'once') {
+    const { id } = this.pendingApproval
+    const { engine } = this
+    return [
+      this,
+      async () => {
+        try {
+          await engine.resolveApproval({ id, approved: status === 'approved', scope })
+          return { type: 'approval.done' }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  // Asks the engine to stop the currently running turn — the stop-native
+  // counterpart to _resolveApproval above; the executing assistant's own
+  // stop watcher is what actually aborts the harness.
+  _requestStop() {
+    if (!this.busy || !this._runningRunId) return [this, null]
+    const { chatId, engine } = this
+    const runId = this._runningRunId
+    const token = ++this._statusToken
+    this.status = fg.dim.render('stopping…')
+    this._render()
+    return [
+      this,
+      async () => {
+        try {
+          await engine.stopRun({ chatId, runId })
+          return { type: 'transient-status', token, text: 'run stopped' }
+        } catch (error) {
+          return { type: 'run.error', error }
+        }
+      }
+    ]
+  }
+
+  update(msg) {
+    if (this._converse && key.matches(msg, 'escape')) {
+      this._stopConverse('off')
+      return [this, null]
+    }
+    if (msg.type === 'resize') {
+      if (!msg.width || !msg.height) return [this, null] // a size-less pty reports 0×0
+      // Clamp geometry to something view() can actually render — below the
+      // minimums the styled blocks go non-positive and blow up padLine.
+      this.width = Math.max(MIN_WIDTH, msg.width)
+      this.height = Math.max(MIN_HEIGHT, msg.height)
+      // CHROME_ROWS = header (1) + transcript border (2) + skills line (1) +
+      // input (3) + footer (1); the frame must match the terminal height exactly
+      // or the alt-screen buffer scrolls and clips the header.
+      // A fresh viewport starts with no content — re-render immediately or
+      // the transcript goes blank until the next chunk/model event.
+      this.vp = viewport.create({ width: 0, height: Math.max(1, this.height - CHROME_ROWS) })
+      this._render()
+      return [this, null]
+    }
+
+    if (msg.type === 'chunks') {
+      if (msg.gen !== this._chunkGen) return [this, null] // stale: chat switched, old stream
+      this._setTranscript(msg.frame.chunks)
+      return [this, this._watchNext()]
+    }
+    if (msg.type === 'chunks.done') {
+      if (msg.gen !== this._chunkGen) return [this, null]
+      this.status = 'chunk stream ended'
+      return [this, null]
+    }
+
+    if (msg.type === 'files') {
+      if (msg.gen !== this._chunkGen) return [this, null] // stale: chat switched
+      const settled = this._settledFiles(msg.files)
+      this._files = msg.files
+      this._render()
+      return [this, batch(this._watchNextFiles(), this._fileStatus(settled))]
+    }
+    if (msg.type === 'files.done') {
+      if (msg.gen !== this._chunkGen) return [this, null]
+      this._files = []
+      this.status = `file status unavailable: ${msg.error?.message ?? 'stream ended'}`
+      this._render()
+      return [this, null]
+    }
+
+    if (msg.type === 'chat.switch') {
+      this._switchTo(msg.chat, msg.agent)
+      return [this, batch(this._watchNext(), this._watchNextFiles())]
+    }
+
+    // /join settled. The joined mesh brings its own agents and chats, so this
+    // drops everything chat-scoped and re-runs the same bootstrap the first
+    // boot uses — which waits for the new mesh to go writable before resolving.
+    if (msg.type === 'mesh.joined') {
+      if (msg.error) {
+        // the old mesh is still the active one — release the send block
+        this._booting = false
+        this.status = fg.err.render(`join failed: ${msg.error.message}`)
+        this._render()
+        return [this, null]
+      }
+      this._resetChatWatches()
+      this.chatId = null
+      this.agent = null
+      this._turns = []
+      this.busy = false
+      this._awaitingRun = false
+      this._runningRunId = null
+      this.pendingApproval = null
+      this.invite = msg.invite ?? this.invite
+      this.status = ''
+      this.notice = 'joined — resolving the mesh’s agent and chat…'
+      this._render()
+      return [this, this._bootstrap()]
+    }
+
+    // _connect resolved: bind the engine + its identity, then arm the watch
+    // loops init() couldn't start while the engine was still coming up. Still
+    // booting — _bootstrap (armed here) resolves the agent + chat next.
+    if (msg.type === 'connected') {
+      this.engine = msg.engine
+      if (msg.skills) this._skills = msg.skills
+      this.originDeviceId = msg.deviceId ?? this.originDeviceId
+      this.invite = msg.meshInvite ?? this.invite
+      this._modelName = msg.modelName ?? this._modelName
+      this._connecting = false
+      this._render()
+      return [this, batch(...this._engineWatches())]
+    }
+
+    // _bootstrap resolved: adopt the seed agent + chat and arm the chunk watch
+    // that init() deferred while there was no chatId.
+    if (msg.type === 'booted') {
+      this.agent = msg.agent
+      this.chatId = msg.chat.id
+      this._booting = false
+      this._render()
+      return [this, batch(this._watchNext(), this._watchNextFiles())]
+    }
+    if (msg.type === 'boot-error') {
+      this.status = fg.err.render(`startup failed: ${msg.error.message}`)
+      this._render()
+      return [this, null]
+    }
+
+    if (msg.type === 'mesh-status') {
+      if (msg.gen !== this.gen) return [this, null]
+      this.meshStatus = msg.frame
+      return [this, this._watchNextStatus()]
+    }
+    if (msg.type === 'mesh-status.done') {
+      if (msg.gen !== this.gen) return [this, null]
+      this.meshStatus = null
+      return [this, null]
+    }
+
+    if (msg.type === 'devices') {
+      if (msg.gen !== this.gen) return [this, null]
+      this.deviceLabels = new Map(
+        (msg.frame.devices ?? []).map((d) => [d.id.toString('hex'), d.name])
+      )
+      this._render()
+      return [this, this._watchNextDevices()]
+    }
+    if (msg.type === 'devices.done') return [this, null]
+
+    if (msg.type === 'diagnostics') {
+      if (msg.gen !== this.gen) return [this, null]
+      this.diagnostics = msg.stats
+      this._render()
+      return [this, this._watchNextDiagnostics()]
+    }
+    if (msg.type === 'diagnostics.done') return [this, null]
+
+    if (msg.type === 'diagnostics.result') {
+      this._models = null
+      this._selector = null
+      this.overlay = msg.error
+        ? [fg.err.render(`/my-device failed: ${msg.error.message}`)]
+        : formatDiagnostics(msg.stats)
+      this._render()
+      return [this, null]
+    }
+
+    // /models resolved: an interactive overlay (↑/↓ + enter to adopt a model)
+    // until esc; a rejection is a static err line instead of a silent dismiss.
+    if (msg.type === 'models.result') {
+      if (msg.error) {
+        this._models = null
+        this.overlay = [fg.err.render(`/models failed: ${msg.error.message}`)]
+      } else {
+        this.overlay = null
+        this._selector = null
+        this._models = { rows: sortModels(msg.rows), filter: msg.filter ?? null, cursor: 0 }
+      }
+      this._render()
+      return [this, null]
+    }
+
+    // /skills + /tools resolved: an interactive on/off overlay (space toggles a
+    // row, persisting immediately) until esc; scope=all opens with all enabled.
+    if (msg.type === 'selector.result') {
+      if (msg.error) {
+        this._selector = null
+        this.overlay = [fg.err.render(`/${msg.kind} failed: ${msg.error.message}`)]
+      } else {
+        this._models = null
+        this.overlay = null
+        const enabled = msg.scope === 'all' ? new Set(msg.installed) : new Set(msg.enabled)
+        this._selector = {
+          kind: msg.kind,
+          rows: msg.installed,
+          enabled,
+          scope: msg.scope,
+          detail: msg.detail ?? null,
+          cursor: 0
+        }
+      }
+      this._render()
+      return [this, null]
+    }
+    if (msg.type === 'permissions.result') {
+      if (msg.error) {
+        this._selector = null
+        this.overlay = [fg.err.render(`/permissions failed: ${msg.error.message}`)]
+      } else {
+        this._models = null
+        this.overlay = null
+        const off = new Set(msg.disabled)
+        this._selector = {
+          kind: 'permissions',
+          rows: [MODE_ROW, ...TOOLSETS],
+          enabled: new Set(TOOLSETS.filter((name) => !off.has(name))),
+          // ids this build cannot render still have to survive the write, or opening this screen
+          // on an older device switches a newer build's toolset back on
+          unknown: msg.disabled.filter((name) => !TOOLSETS.includes(name)),
+          mode: msg.mode,
+          cursor: 0
+        }
+      }
+      this._render()
+      return [this, null]
+    }
+    if (msg.type === 'selector.saved') return [this, null] // the toggle already re-rendered; sync only
+
+    // A fetched menu page resolved. From a menu row (menu open) it drills in as a
+    // pushed page; from a bare /chats or /agents (no menu open) it opens as the
+    // root of a fresh menu, so esc closes straight back to the chat.
+    if (msg.type === 'menu.page') {
+      if (this._menu) this._menu.pages.push(msg.page)
+      else this._menu = { pages: [msg.page] }
+      this._render()
+      return [this, null]
+    }
+
+    if (msg.type === 'run.error') {
+      this.busy = false
+      this.modelState = null
+      this.status = fg.err.render(`error: ${msg.error.message}`)
+      return [this, null]
+    }
+    if (msg.type === 'run.done') return [this, null] // completion arrives via the chunk stream itself
+
+    if (msg.type === 'notice') {
+      // transcript, not the footer — the footer is one truncated line and any
+      // status tick overwrites it, so /skills and /help output vanished there
+      this.notice = msg.text
+      this._render()
+      return [this, null]
+    }
+
+    // Bridged in from the harness's own EventEmitter (see index.mjs) —
+    // loading/downloading/ready/unloading. Ephemeral and local; never part of
+    // the chunk stream (see Harness's doc comment for why).
+    if (msg.type === 'model') {
+      this.modelState = msg.state
+      this._render()
+      return [this, null]
+    }
+
+    if (msg.type === 'spinner.tick') {
+      const [s, cmd] = this.spin.update(msg)
+      this.spin = s
+      if (this.busy || this._booting) this._render()
+      return [this, cmd]
+    }
+
+    if (msg.type === 'chats') {
+      this._chats = msg.frame.chats ?? []
+      this._groups = msg.frame.groups ?? []
+      if (this._sidebar) this._render()
+      return [this, this._watchNextChats()]
+    }
+    if (msg.type === 'chats.done') return [this, null]
+
+    if (msg.type === 'transient-status') {
+      if (msg.token !== this._statusToken) return [this, null] // superseded
+      this.status = msg.text
+      this._render()
+      if (!msg.text) return [this, null]
+      // Schedule the clear; a newer status bumps the token and orphans it.
+      const token = msg.token
+      return [
+        this,
+        async () => {
+          await new Promise((resolve) => setTimeout(resolve, 2000))
+          return { type: 'transient-status', token, text: '' }
+        }
+      ]
+    }
+
+    if (msg.type === 'mouse') {
+      if (msg.action === 'wheel') {
+        this._selection = null
+        if (msg.button === 'wheelup') this.vp.scrollUp(WHEEL_ROWS)
+        else if (msg.button === 'wheeldown') this.vp.scrollDown(WHEEL_ROWS)
+        return [this, null]
+      }
+      if (msg.button === 'left') return this._select(msg)
+      return [this, null]
+    }
+
+    if (msg.type === 'drag-scroll') return this._scrollSelection(msg.token)
+
+    if (msg.type === 'key') {
+      this._selection = null
+      // bracketed paste (index.mjs enables ?2004h): everything between the
+      // markers lands as ONE block — multi-line becomes an input placeholder
+      if (msg.name === 'paste-start') {
+        this._paste = ''
+        return [this, null]
+      }
+      if (msg.name === 'paste-end') {
+        this._insertPaste()
+        this._render()
+        return [this, null]
+      }
+      if (this._paste !== null) {
+        // a hung paste (no end marker) must not eat ctrl+c — drop it and fall through
+        if (msg.ctrl && msg.name === 'c') this._paste = null
+        else {
+          this._accumulatePaste(msg)
+          return [this, null]
+        }
+      }
+      if (key.matches(msg, 'ctrl+c')) return [this, quit]
+      // Work in every mode (modifier keys — never collide with typing or
+      // the y/n approval answers).
+      if (key.matches(msg, 'ctrl+y')) return this._copyInvite()
+      if (key.matches(msg, 'ctrl+v')) return this._pasteAttachment()
+      if (key.matches(msg, 'ctrl+p')) return this._openMenu()
+      if (key.matches(msg, 'ctrl+b')) return this._toggleSidebar()
+      if (key.matches(msg, 'ctrl+o')) return this._toggleToolOutput()
+
+      // An overlay owns its nav keys, but typing dismisses it into the input —
+      // the keyboard analog of clicking back into the text box. Non-typing keys
+      // (function keys, etc.) are swallowed so they can't leak through.
+      if (this._models || this._selector || this.overlay || this._menu) {
+        const handled = this._overlayKey(msg)
+        if (handled) return handled
+        if (!this._isTypingKey(msg)) return [this, null]
+        this._models = null
+        this._selector = null
+        this.overlay = null
+        this._menu = null
+        this._render()
+      }
+
+      // The sidebar is a pane, not a modal: it owns its nav keys while focused,
+      // and typing hands focus back to the input without closing it.
+      if (this._sidebar?.focus) {
+        const handled = this._sidebarKey(msg)
+        if (handled) return handled
+        if (!this._isTypingKey(msg)) return [this, null]
+        this._sidebar.focus = false
+        this._render()
+      }
+
+      // esc with nothing open stops the run in flight — the same stopRun the
+      // executing device's watcher acts on — and otherwise clears the last
+      // command's output, which is chrome the transcript would else keep.
+      if (key.matches(msg, 'escape')) {
+        if (this.busy) return this._requestStop()
+        if (this.notice) {
+          this.notice = null
+          this._render()
+          return [this, null]
+        }
+      }
+
+      if (this.pendingApproval) {
+        if (key.matches(msg, 'y')) return this._resolveApproval('approved')
+        if (key.matches(msg, 'a')) return this._resolveApproval('approved', 'always')
+        if (key.matches(msg, 'n')) return this._resolveApproval('denied')
+        return [this, null] // no other key does anything while a call awaits an answer
+      }
+
+      // The palette drives the arrows only when it's open AND we're not mid-recall
+      // — a recalled command line starts with '/' too, but browsing history must
+      // keep browsing history until the user edits or submits (shell behaviour).
+      const matches = this.input.value.startsWith('/') ? matchCommands(this.input.value) : []
+      const inPalette = matches.length > 0 && this._historyAt === null
+
+      if (inPalette && key.matches(msg, 'tab')) {
+        const pick = matches[Math.min(this._paletteAt, matches.length - 1)]
+        this._setInput(`/${pick.name} `)
+        return [this, null]
+      }
+
+      // Enter runs the highlighted palette row when the user is still choosing a
+      // command (no argument typed yet); once an argument follows — or the line
+      // came from history — the typed line is authoritative and submits verbatim.
+      if (key.matches(msg, 'enter')) {
+        if (inPalette && !/\s/.test(this.input.value.trim())) {
+          this._setInput(`/${matches[Math.min(this._paletteAt, matches.length - 1)].name}`)
+        }
+        return this._submit()
+      }
+
+      // ↑/↓ move the palette selection when it's open, otherwise walk input
+      // history. Transcript scrolling lives on PgUp/PgDn so the arrows are free
+      // for both. Typing stays live during a run — a message sent while busy
+      // queues as chunks and runs right after the current turn.
+      if (key.matches(msg, 'up') || key.matches(msg, 'down')) {
+        const delta = key.matches(msg, 'up') ? -1 : 1
+        if (inPalette) {
+          const max = matches.length - 1
+          this._paletteAt = Math.max(0, Math.min(max, Math.min(this._paletteAt, max) + delta))
+        } else {
+          this._recall(delta)
+        }
+        return [this, null]
+      }
+      if (key.matches(msg, 'pageup')) {
+        this.vp.scrollUp(this.vp.height)
+        return [this, null]
+      }
+      if (key.matches(msg, 'pagedown')) {
+        this.vp.scrollDown(this.vp.height)
+        return [this, null]
+      }
+      const before = this.input.value
+      let cmd = null
+      if (!this._editKey(msg)) {
+        const [f, c] = this.input.update(msg)
+        this.input = f
+        cmd = c
+      }
+      // A real edit (not a bare cursor move) re-opens the choice: reset the
+      // palette highlight and drop out of history recall.
+      if (this.input.value !== before) {
+        this._paletteAt = 0
+        this._historyAt = null
+      }
+      return [this, cmd]
+    }
+
+    return [this, null]
+  }
+
+  // Mouse reporting takes click+drag away from the terminal, so the transcript
+  // does its own selection: drag highlights cells, release copies them. Cells
+  // are content lines, not screen rows, so a scroll carries the selection.
+  _select(msg) {
+    if (msg.action === 'press') {
+      const region = this._regionAt(msg)
+      // a click on a preview's marker is the expand button, not a selection
+      if (region === 'transcript' && this._markerAt(msg.y)) return this._toggleToolOutput()
+      const at = this._cellAt(msg, region)
+      this._selection = region ? { region, anchor: at, focus: at, edge: 0 } : null
+      return [this, null]
+    }
+    if (!this._selection) return [this, null]
+    const { region } = this._selection
+    this._selection.focus = this._cellAt(msg, region)
+    if (msg.action !== 'motion') {
+      this._selection.edge = 0 // release: whatever beat is in flight stops here
+      return this._copySelection()
+    }
+    const armed = this._selection.edge
+    this._selection.edge = region === 'transcript' ? this._edgeAt(msg) : 0
+    return [this, this._selection.edge && !armed ? this._dragScroll() : null]
+  }
+
+  // Held past the top or bottom edge, the transcript keeps scrolling under the
+  // pointer — motion reports stop once the pointer does, so this beats on.
+  _dragScroll() {
+    const token = ++this._dragToken
+    return tick(DRAG_SCROLL_MS, () => ({ type: 'drag-scroll', token }))
+  }
+
+  _scrollSelection(token) {
+    const sel = this._selection
+    if (!sel?.edge || token !== this._dragToken) return [this, null]
+    if (sel.edge < 0) this.vp.scrollUp(1)
+    else this.vp.scrollDown(1)
+    const row = sel.edge < 0 ? 0 : this.vp.height - 1
+    sel.focus = { line: this.vp.yOffset + row, col: sel.focus.col }
+    return [this, tick(DRAG_SCROLL_MS, () => ({ type: 'drag-scroll', token }))]
+  }
+
+  // true when the clicked transcript row is a collapsed preview's marker
+  _markerAt(y) {
+    if (this._expandTools) return false
+    const row = y - TRANSCRIPT_TOP
+    return (this._viewLines()[row] ?? '').includes(EXPAND_MARK)
+  }
+
+  _edgeAt(msg) {
+    if (msg.y < TRANSCRIPT_TOP) return -1
+    return msg.y >= TRANSCRIPT_TOP + this.vp.height ? 1 : 0
+  }
+
+  // The transcript and the input box are both selectable; a press outside both
+  // selects nothing.
+  _regionAt(msg) {
+    if (msg.y >= TRANSCRIPT_TOP && msg.y < TRANSCRIPT_TOP + this.vp.height) return 'transcript'
+    const top = this._inputTop()
+    return msg.y >= top && msg.y < top + this._inputRows().length ? 'input' : null
+  }
+
+  // the input box's first content row: the transcript, its bottom border, the
+  // skills strip and the box's own top border sit above it
+  _inputTop() {
+    return TRANSCRIPT_TOP + this.vp.height + 3
+  }
+
+  _cellAt(msg, region) {
+    const col = Math.max(
+      0,
+      msg.x - TRANSCRIPT_LEFT - (region === 'input' ? 0 : this._sidebarCols())
+    )
+    if (region === 'input') {
+      const rows = this._inputRows().length
+      return { line: Math.min(Math.max(0, msg.y - this._inputTop()), rows - 1), col }
+    }
+    const row = Math.min(Math.max(0, msg.y - TRANSCRIPT_TOP), this.vp.height - 1)
+    return { line: this.vp.yOffset + row, col }
+  }
+
+  // The selection as screen cells, `offset` rows above the first content line.
+  _selectionCells(offset) {
+    const { anchor, focus } = this._selection
+    return [
+      { row: anchor.line - offset, col: anchor.col },
+      { row: focus.line - offset, col: focus.col }
+    ]
+  }
+
+  // Every content line, with the visible window replaced by what is actually
+  // drawn there — a selection copies exactly the rows the user dragged over.
+  _contentLines() {
+    const lines = this.vp.lines.slice()
+    const view = this._viewLines()
+    for (let i = 0; i < view.length; i++) lines[this.vp.yOffset + i] = view[i]
+    return lines
+  }
+
+  _copySelection() {
+    const { anchor, focus } = this._selection
+    if (anchor.line === focus.line && anchor.col === focus.col) {
+      this._selection = null // a click, not a drag
+      return [this, null]
+    }
+    const lines = this._selection.region === 'input' ? this._inputRows() : this._contentLines()
+    const text = selectionText(lines, ...this._selectionCells(0))
+    if (!text) this._selection = null
+    if (!text || !this._copyToClipboard) return [this, null]
+    const copy = this._copyToClipboard
+    const token = ++this._statusToken
+    return [
+      this,
+      async () => {
+        try {
+          await copy(text)
+          return {
+            type: 'transient-status',
+            token,
+            text: `copied ${text.length} chars to clipboard`
+          }
+        } catch (err) {
+          return { type: 'transient-status', token, text: `copy failed: ${err.message}` }
+        }
+      }
+    ]
+  }
+
+  // A clipboard that isn't there (or fails) must not fail the thing that wanted it.
+  async _copyQuietly(text) {
+    if (!this._copyToClipboard) return false
+    try {
+      await this._copyToClipboard(text)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ctrl+y: the invite string goes straight to the host clipboard — the only
+  // way to copy it now that the transcript no longer renders it.
+  _copyInvite() {
+    if (!this.invite || !this._copyToClipboard) return [this, null]
+    const invite = this.invite
+    const copy = this._copyToClipboard
+    const token = ++this._statusToken
+    return [
+      this,
+      async () => {
+        try {
+          await copy(invite)
+          return { type: 'transient-status', token, text: 'invite copied ✓' }
+        } catch (err) {
+          return { type: 'transient-status', token, text: `copy failed: ${err.message}` }
+        }
+      }
+    ]
+  }
+
+  // ctrl+v: whatever file the clipboard references becomes an attachment
+  // chunk — uploaded over the hrpc duplex, so the record (fileName, mime,
+  // size) replicates and every peer's transcript renders it.
+  _pasteAttachment() {
+    if (!this._resolvePastedFile) return [this, null]
+    const app = this
+    const token = ++this._statusToken
+    return [
+      this,
+      async () => {
+        try {
+          const file = await app._resolvePastedFile()
+          if (!file) return { type: 'transient-status', token, text: 'clipboard has no file' }
+          await app._uploadAttachment(file)
+          return { type: 'transient-status', token, text: `attached ${file.fileName} ✓` }
+        } catch (err) {
+          return { type: 'transient-status', token, text: `attach failed: ${err.message}` }
+        }
+      }
+    ]
+  }
+
+  async _uploadAttachment({ fileName, mimeType, data }) {
+    const duplex = this.engine.uploadAttachment()
+    await writeFrame(duplex, {
+      chatId: this.chatId,
+      originDeviceId: this.originDeviceId,
+      fileName,
+      mimeType,
+      totalBytes: data.length
+    })
+    for (let at = 0; at < data.length; at += UPLOAD_FRAME_BYTES) {
+      await writeFrame(duplex, { data: data.subarray(at, at + UPLOAD_FRAME_BYTES) })
+    }
+    duplex.end()
+    // Drain to completion — the final frame carries the attachment record,
+    // but the transcript picks it up from the chunk watch like everything else.
+    let final = null
+    for await (const frame of duplex) final = frame
+    return final
+  }
+
+  // Live network/membership state from meshStatusWatch, appended to the
+  // footer — joining/joined/leaving plus how many distinct peer devices are
+  // connected right now. Empty until the first frame arrives.
+  _meshLine() {
+    const parts = []
+    const s = this.meshStatus
+    if (s) {
+      const peers = s.peerCount === 1 ? '1 peer' : `${s.peerCount} peers`
+      parts.push(`mesh: ${s.state}`, peers)
+    }
+    const proc = this.diagnostics?.process
+    if (proc) {
+      const cpu = Math.round((proc.cpu ?? 0) * 100)
+      const mem = Math.round((proc.memory?.rss ?? 0) / (1024 * 1024))
+      parts.push(`proc ${cpu}%/${mem}MB`)
+    }
+    const cpuCompute = this.diagnostics?.cpu?.usage?.compute
+    if (typeof cpuCompute === 'number') parts.push(`cpu ${Math.round(cpuCompute * 100)}%`)
+    const gpuCompute = this.diagnostics?.gpu?.devices?.[0]?.usage?.compute
+    if (typeof gpuCompute === 'number') parts.push(`gpu ${Math.round(gpuCompute * 100)}%`)
+    return parts.length ? ` · ${parts.join(' · ')}` : ''
+  }
+
+  // The footer key legend, one line per active mode — an overlay owns its own
+  // keys, a pending approval its y/a/n, the palette its picker, else the default.
+  _hints(always, paletteOpen, copyHint, pasteHint) {
+    if (this._sidebar?.focus) {
+      return this._sidebar.moving
+        ? '↑/↓: group · enter: move here · esc: cancel · ctrl+c: quit'
+        : '↑/↓: chat · enter: open · m: move to group · esc: close · ctrl+c: quit'
+    }
+    if (this._models) return '↑/↓: move · enter: use · esc: back · ctrl+c: quit'
+    if (this._selector) {
+      const setup = this._selector.detail ? ' · enter: configure' : ''
+      return `↑/↓: move · space: toggle${setup} · esc: back · ctrl+c: quit`
+    }
+    if (this.overlay) return 'esc: back · ↑/↓: scroll · ctrl+c: quit'
+    if (this._menu) return '↑/↓: move · enter: select · esc: back · ctrl+c: quit'
+    if (this.pendingApproval) return `y: allow · a: ${always} · n: deny · ctrl+c: quit`
+    if (paletteOpen) return '↑/↓: pick · tab: complete · enter: run · ctrl+c: quit'
+    return (
+      this.status ||
+      `/: commands · ctrl+p: menu · ctrl+b: chats${copyHint}${pasteHint} · ctrl+c: quit`
+    )
+  }
+
+  // textinput draws one line: a cursor sitting on a newline would render as a
+  // reverse line break and vanish, so multi-line values are drawn here instead
+  _inputView() {
+    const { value, cursor, prompt } = this.input
+    if (!value.includes('\n')) return this.input.view()
+    const at = value[cursor]
+    const cell = at === undefined || at === '\n' ? ' ' : at
+    const tail = at === '\n' ? value.slice(cursor) : value.slice(cursor + 1)
+    return prompt + value.slice(0, cursor) + CURSOR_CELL + cell + CURSOR_OFF + tail
+  }
+
+  _inputRows() {
+    const width = this._bodyWidth()
+    const rows = this._inputView()
+      .split('\n')
+      .flatMap((line) => wrapLine(line, width))
+    const max = Math.max(1, Math.min(MAX_INPUT_ROWS, this.height - CHROME_ROWS))
+    if (rows.length <= max) return rows
+    const at = rows.findIndex((row) => row.includes(CURSOR_CELL))
+    const start = Math.min(Math.max(0, (at < 0 ? rows.length : at + 1) - max), rows.length - max)
+    return rows.slice(start, start + max)
+  }
+
+  // every extra input row costs the transcript one — the frame must stay exactly as tall as the terminal
+  _fitViewport(inputRows) {
+    const height = Math.max(1, this.height - CHROME_ROWS - (inputRows - 1))
+    if (this.vp.height === height) return
+    const wasAtBottom = this.vp.atBottom
+    this.vp.height = height
+    if (wasAtBottom) this.vp.gotoBottom()
+    else this.vp.setYOffset(this.vp.yOffset)
+  }
+
+  // The strip above the input: the active agent's enabled skills as pills. In
+  // scope=all every installed skill is on (a single "all skills" pill, since the
+  // names aren't held locally); scope=selected shows one pill per enabled skill,
+  // trimmed to the width with a dim "+N" when they don't all fit. Pills are
+  // measured by their PLAIN width and appended whole, so an escape is never cut.
+  _skillsLine() {
+    const active = this._files.filter(filePending)
+    if (active.length) return this._filesLine(active)
+    // Indent to the input box's content column (its border + padding), so the
+    // first pill lines up with the prompt instead of the frame's left edge.
+    const indent = '  '
+    const line = (body) => indent + body
+    const room = Math.max(0, this.width - indent.length - 1)
+    const pill = (text) => style().foreground('black').background('brightcyan').render(` ${text} `)
+    // a pill's visible width is the name plus its two padding spaces, plus a gap
+    // once it isn't the first — the frame breaks if the strip ever wraps.
+    const span = (name, first) => name.length + 2 + (first ? 0 : 1)
+    if (!this.agent) return ''
+    if ((this.agent.skillsScope ?? 'all') === 'all') return line(pill('all skills'))
+    const names = this.agent.enabledSkills ?? []
+    if (!names.length) return line(fg.dim.render('no skills enabled'))
+    const shown = []
+    let used = 0
+    for (const name of names) {
+      const width = span(name, !shown.length)
+      if (used + width > room) break
+      used += width
+      shown.push(name)
+    }
+    let hidden = names.length - shown.length
+    // make room for the "+N" itself, dropping trailing pills until it fits
+    while (hidden > 0 && shown.length && used + ` +${hidden}`.length > room) {
+      const wasFirst = shown.length === 1
+      used -= span(shown.pop(), wasFirst)
+      hidden = names.length - shown.length
+    }
+    const more = hidden > 0 ? fg.dim.render(` +${hidden}`) : ''
+    if (!shown.length) return line(fg.dim.render(`+${hidden} skills`.slice(0, room)))
+    return line(shown.map(pill).join(' ') + more)
+  }
+
+  _settledFiles(files) {
+    const before = new Set(this._files.filter(filePending).map((file) => file.fileId))
+    return files.filter((file) => !filePending(file) && before.has(file.fileId))
+  }
+
+  _fileStatus(settled) {
+    if (!settled.length) return null
+    const failed = settled.find((file) => file.state === 'failed' || file.state === 'cancelled')
+    const token = ++this._statusToken
+    const text = failed ? fg.err.render(fileStatusText(failed)) : fileStatusText(settled[0])
+    return async () => ({ type: 'transient-status', token, text })
+  }
+
+  _filesLine(files) {
+    const more = files.length > 1 ? ` (+${files.length - 1} files)` : ''
+    const body = `${this.spin.view()} ${fileStatusText(files[0])}${more}`
+    return '  ' + fg.dim.render(body.slice(0, Math.max(0, this.width - 3)))
+  }
+
+  // The pane beside the transcript, exactly as tall as it is so the two frames
+  // line up row for row.
+  _sidebarBox(cols, height) {
+    const s = this._sidebar
+    const rows = this._sidebarRows()
+    const inner = cols - 5 // border + padding, and a column of air before the transcript
+    const lines = formatSidebar(rows, this._sidebarCursor(rows), {
+      title: s.moving ? 'Move to…' : 'Chats',
+      focus: s.focus,
+      width: inner,
+      height
+    })
+    return style()
+      .border(style.borders.thick)
+      .borderForeground(s.focus ? 'brightcyan' : 'gray')
+      .width(inner)
+      .padding(0, 1)
+      .margin(0, 1, 0, 0)
+      .render(lines.join('\n'))
+  }
+
+  // The transcript rows as drawn: the viewport, with the command palette
+  // overlaid on its last rows. Selection reads the same lines the user sees.
+  _viewLines() {
+    const lines = this.vp.view().split('\n')
+    const matches = matchCommands(this.input.value)
+    const paletteLines = renderPalette(matches, Math.min(this._paletteAt, matches.length - 1))
+    const start = Math.max(0, lines.length - paletteLines.length)
+    for (let i = 0; i < paletteLines.length && start + i < lines.length; i++) {
+      lines[start + i] = paletteLines[i]
+    }
+    return lines
+  }
+
+  view() {
+    const title = `◤◢◤ ASSISTANT :: ${(this.agent?.name ?? 'connecting').toUpperCase()} ◣◥◣${this._meshLine()}`
+    const header = style()
+      .foreground('black')
+      .background('brightcyan')
+      .bold(true)
+      .width(this.width - 2)
+      .align(0.5)
+      .padding(0, 1)
+      .render(title.slice(0, Math.max(0, this.width - 4)))
+
+    const inputRows = this._inputRows()
+    this._fitViewport(inputRows.length)
+    const lines = this._viewLines()
+    const vpLines =
+      this._selection?.region === 'transcript'
+        ? paintSelection(lines, ...this._selectionCells(this.vp.yOffset))
+        : lines
+    const cols = this._sidebarCols()
+    const transcript = style()
+      .border(style.borders.thick)
+      .borderForeground('cyan')
+      .width(this.width - 4 - cols)
+      .padding(0, 1)
+      .render(vpLines.join('\n'))
+    const body = cols
+      ? style.joinHorizontal(0, this._sidebarBox(cols, vpLines.length), transcript)
+      : transcript
+
+    // Busy state shows in the transcript (_busyLine()), not here — the input
+    // box always shows the actual input field so it never appears to move.
+    const inputBox = style()
+      .border(style.borders.rounded)
+      .borderForeground(this.pendingApproval ? 'brightyellow' : this.busy ? 'gray' : 'brightcyan')
+      .width(this.width - 4)
+      .padding(0, 1)
+      .render(
+        (this._selection?.region === 'input'
+          ? paintSelection(inputRows, ...this._selectionCells(0))
+          : inputRows
+        ).join('\n')
+      )
+
+    const copyHint = this.invite && this._copyToClipboard ? ' · ctrl+y: copy invite' : ''
+    const pasteHint = this._resolvePastedFile ? ' · ctrl+v: attach' : ''
+    const always = this.pendingApproval?.detail.resource
+      ? `allow ${this.pendingApproval.detail.resource.label} for 1h`
+      : 'allow for 1h'
+    const paletteOpen = this.input.value.startsWith('/')
+    const hints = this._hints(always, paletteOpen, copyHint, pasteHint)
+    // a wrapped footer row shifts the whole frame and scrolls the header off — never let it wrap
+    const footer = fg.dim.render(hints.slice(0, Math.max(0, this.width - 1)))
+
+    return [header, body, this._skillsLine(), inputBox, footer].join('\n')
+  }
+}