@qvac/core 0.1.0 → 0.1.2

package/tui/index.mjs

@@ -0,0 +1,650 @@
+#!/usr/bin/env bare
+// The duck TUI host: CLI, storage resolution, and the two topologies it can
+// bring the stack up in — a stowed sidecar child (the desktop shape, default)
+// or everything in this process (QVAC_INPROCESS=1, the only way to inject a
+// live harness object). See README.md for flags, env, and layout.
+import fs from 'bare-fs'
+import os from 'bare-os'
+import process from 'bare-process'
+import tui from 'bare-tui'
+import { fileURLToPath } from 'bare-url'
+import { spawn } from 'child_process'
+import path from 'path'
+import { Harness, imageClampsFromEnv, imageModelFromEnv } from '@qvac/harness'
+import { createExecTool } from '@qvac/harness/lib/tools/exec.ts'
+import { createHttpRequestTool } from '@qvac/harness/lib/tools/http-request.ts'
+import { createMcpCallTool } from '@qvac/harness/lib/tools/mcp-call.ts'
+import { compileOperationTools } from '@qvac/harness/lib/tools/operations/compile.ts'
+import { createSkillTool } from '@qvac/harness/lib/tools/skill.ts'
+import { createWebFetchTool } from '@qvac/harness/lib/tools/web-fetch.ts'
+import { createWebSearchTool } from '@qvac/harness/lib/tools/web-search.ts'
+import {
+  credentialAllowListFor,
+  loadSkillCatalog,
+  mcpReadMethods
+} from '@qvac/harness/lib/tools/skills/index.ts'
+import {
+  harnessListModels,
+  harnessSpeak,
+  harnessTranscribe,
+  QvacAssistant
+} from '../dist-lib/lib/assistant.js'
+import { Client } from '../dist-lib/lib/client.js'
+import { Core } from '../dist-lib/lib/core.js'
+import { Logger, toLoggerOptions } from '../dist-lib/lib/log.js'
+import { extractOfficeText } from '../dist-lib/lib/core/files/rag/extract/office-collabora.js'
+import { DEFAULT_RAG_MODEL } from '../dist-lib/lib/core/files/rag/models.js'
+import { configureSdkStorage } from '@qvac/harness/sdk-storage'
+import { MODEL_CACHE_PATH_ENV, releaseChannel, resolveStorage } from '@qvac/harness/storage'
+import {
+  ASANA_MCP_CREDENTIAL_KEY,
+  ASANA_OAUTH_STATE_KEY,
+  oauthKeySpec,
+  NOTION_MCP_CREDENTIAL_KEY,
+  NOTION_OAUTH_STATE_KEY,
+  resolveAsanaCredential,
+  resolveGoogleCredential,
+  resolveNotionCredential,
+  resolveSpotifyCredential,
+  SPOTIFY_CREDENTIAL_KEY,
+  SPOTIFY_OAUTH_STATE_KEY
+} from '../dist-lib/lib/oauth.js'
+import sidecarRunner from 'bare-supervisor/runner/sidecar'
+import { duplexPair } from '@qvac/harness/transport'
+import { bootTimer, readBootTiming } from './lib/boot-timing.mjs'
+import { ensurePrebuilds } from './lib/prebuilds.mjs'
+import { ChatApp, credKey } from './app.mjs'
+import { parseProjectionEnv } from './lib/projection-env.mjs'
+
+const skillsDir = path.dirname(
+  path.dirname(new URL(import.meta.resolve('@qvac/skills/skills/weather/SKILL.md')).pathname)
+)
+// The harness the assistant sidecar spawns as its own child — the bundle
+// @qvac/harness publishes, resolved through its only dist export's sibling.
+const harnessEntry = path.join(
+  path.dirname(new URL(import.meta.resolve('@qvac/harness/dist/harness.cjs')).pathname),
+  'harness.bundle'
+)
+
+function createCredentialStore() {
+  let engine
+  return {
+    bind: (readyEngine) => {
+      engine = readyEngine
+    },
+    resolve: async (key, ctx) => {
+      if (!engine) return null
+      const googleSpec = oauthKeySpec(key)
+      if (googleSpec?.provider === 'google') {
+        return resolveOAuthRecord(
+          resolveGoogleCredential({
+            engine,
+            agentId: ctx?.agentId,
+            credentialKey: key,
+            stateKey: googleSpec.stateKey
+          }),
+          engine,
+          googleSpec.stateKey,
+          ctx?.agentId
+        )
+      }
+      if (key === SPOTIFY_CREDENTIAL_KEY) {
+        return resolveOAuthRecord(
+          resolveSpotifyCredential({ engine, agentId: ctx?.agentId }),
+          engine,
+          SPOTIFY_OAUTH_STATE_KEY,
+          ctx?.agentId
+        )
+      }
+      if (key === NOTION_MCP_CREDENTIAL_KEY) {
+        return resolveOAuthRecord(
+          resolveNotionCredential({ engine, agentId: ctx?.agentId }),
+          engine,
+          NOTION_OAUTH_STATE_KEY,
+          ctx?.agentId
+        )
+      }
+      if (key === ASANA_MCP_CREDENTIAL_KEY) {
+        return resolveOAuthRecord(
+          resolveAsanaCredential({ engine, agentId: ctx?.agentId }),
+          engine,
+          ASANA_OAUTH_STATE_KEY,
+          ctx?.agentId
+        )
+      }
+      const { value } = await engine.configGet({ key: credKey(ctx?.agentId, key) })
+      return typeof value === 'string' ? value : null
+    }
+  }
+}
+
+async function resolveOAuthRecord(tokenPromise, engine, stateKey, agentId) {
+  const token = await tokenPromise
+  if (!token) return null
+  const { value } = await engine.configGet({ key: credKey(agentId, stateKey) })
+  let expiresAt
+  try {
+    const state = typeof value === 'string' ? JSON.parse(value) : null
+    expiresAt = typeof state?.expiresAt === 'number' ? state.expiresAt : undefined
+  } catch {}
+  return { token, ...(expiresAt === undefined ? {} : { expiresAt }) }
+}
+
+const { Program } = tui
+
+// how long a lone esc waits to see whether it starts a sequence — the terminal
+// writes a real one in a single read, so this only has to beat human perception
+const ESCAPE_TIMEOUT_MS = 50
+
+// @qvac/sdk writes its own [sdk:client]/[sdk:server] logs straight to
+// console — bare-tui's Program owns the terminal via cursor-tracked ANSI
+// output, so any other writer to the same fd corrupts the redraw. Silence
+// console output for the TUI's lifetime; errors after it exits still print.
+// (llama.cpp's own native stdout logs are a separate path, not covered by
+// this — see assistant-harness/lib/sdk-loader.ts.)
+function withConsoleSuppressed(fn) {
+  const original = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug
+  }
+  const noop = () => {}
+  Object.assign(console, {
+    log: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    debug: noop
+  })
+  return fn().finally(() => Object.assign(console, original))
+}
+
+// llama.cpp writes some of its own init/inference logs straight to the real
+// stdout/stderr fd (see assistant-harness/lib/sdk-loader.ts) — that bypasses
+// both withConsoleSuppressed below AND bare-tui's Renderer, which only
+// repaints rows whose logical content changed and has no idea those rows got
+// clobbered by an external writer. Sending a synthetic resize forces the
+// same full repaint Program already does on a real terminal resize, wiping
+// any leaked lines. `getProgram` is a thunk because this is wired up before
+// Program exists.
+function requestRepaint(getProgram) {
+  const program = getProgram()
+  if (!program) return
+  // || not ??: a size-less pty reports 0 columns, and a 0-width resize turns
+  // the style width math into repeat(-2) — 0 means "unknown", not a size
+  program.send({
+    type: 'resize',
+    width: program.output.columns || 80,
+    height: program.output.rows || 24
+  })
+}
+
+// Where an in-process harness's model lifecycle lands: the log always, and the
+// running Program's message loop when there is one — bare-tui's documented
+// pattern for external code pushing messages in.
+function reportModel(state, logger, getProgram) {
+  const pct = typeof state.percentage === 'number' ? ` ${state.percentage}%` : ''
+  logger.info('model', `${state.model} ${state.status}${pct}`)
+  const program = getProgram()
+  if (!program) return
+  program.send({ type: 'model', state })
+  // 'loading'/'downloading' can't have leaked logs yet; force a repaint once
+  // the load itself (and its native init logs) has actually happened.
+  if (state.status === 'ready' || state.status === 'unloaded') requestRepaint(getProgram)
+}
+
+// ctrl+y clipboard write via the platform's own pipe-to-clipboard command —
+// spawned per copy, nothing printed to the tty (safe alongside bare-tui's
+// renderer). Candidates tried in order; the first that exits 0 wins (linux
+// terminals vary on wayland vs x11).
+function copyToClipboard(text) {
+  const commands =
+    process.platform === 'darwin'
+      ? [['pbcopy', []]]
+      : process.platform === 'win32'
+        ? [['clip', []]]
+        : [
+            ['wl-copy', []],
+            ['xclip', ['-selection', 'clipboard']]
+          ]
+  return new Promise((resolve, reject) => {
+    const attempt = (i) => {
+      if (i >= commands.length) {
+        reject(new Error('no clipboard command available'))
+        return
+      }
+      const [cmd, args] = commands[i]
+      let child
+      try {
+        child = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] })
+      } catch {
+        attempt(i + 1)
+        return
+      }
+      child.on('error', () => attempt(i + 1))
+      child.on('exit', (code) => (code === 0 ? resolve() : attempt(i + 1)))
+      child.stdin.write(Buffer.from(text))
+      child.stdin.end()
+    }
+    attempt(0)
+  })
+}
+
+function readClipboard() {
+  const commands =
+    process.platform === 'darwin'
+      ? [['pbpaste', []]]
+      : [
+          ['wl-paste', ['--no-newline']],
+          ['xclip', ['-o', '-selection', 'clipboard']]
+        ]
+  return new Promise((resolve, reject) => {
+    const attempt = (i) => {
+      if (i >= commands.length) {
+        reject(new Error('no clipboard command available'))
+        return
+      }
+      const [cmd, args] = commands[i]
+      let child
+      try {
+        child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] })
+      } catch {
+        attempt(i + 1)
+        return
+      }
+      const out = []
+      child.stdout.on('data', (data) => out.push(data))
+      child.on('error', () => attempt(i + 1))
+      child.on('exit', (code) =>
+        code === 0 ? resolve(Buffer.concat(out).toString()) : attempt(i + 1)
+      )
+    }
+    attempt(0)
+  })
+}
+
+const MIME_TYPES = new Map([
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+  ['.heic', 'image/heic'],
+  ['.heif', 'image/heif'],
+  ['.pdf', 'application/pdf'],
+  ['.txt', 'text/plain'],
+  ['.md', 'text/markdown'],
+  ['.json', 'application/json']
+])
+const MAX_ATTACHMENT_BYTES = 32 * 1024 * 1024
+
+// ctrl+v resolver: a clipboard holding a file path (or file:// URL — what
+// "copy" in a file manager and drag-to-terminal produce) becomes an
+// attachment; anything else is null and the shortcut just says so. Raw
+// image DATA on the clipboard has no portable tty-side accessor — copy the
+// file, not the pixels.
+async function resolvePastedFile() {
+  const text = (await readClipboard()).trim()
+  if (!text || text.includes('\n')) return null
+  const file = expandFilePath(text)
+  let stat
+  try {
+    stat = fs.statSync(file)
+  } catch {
+    return null
+  }
+  if (!stat.isFile()) return null
+  return fileToAttachment(file, stat)
+}
+
+// `/attach` resolver: a named path -> attachment; throws on a bad path.
+function resolveFileAttachment(pathString) {
+  return fileToAttachment(expandFilePath(pathString))
+}
+
+function expandFilePath(text) {
+  const file = text.startsWith('file://') ? decodeURI(text.slice('file://'.length)) : text
+  return file.startsWith('~/') ? path.join(os.homedir(), file.slice(2)) : file
+}
+
+function fileToAttachment(file, stat = fs.statSync(file)) {
+  if (!stat.isFile()) throw new Error('not a regular file')
+  if (stat.size > MAX_ATTACHMENT_BYTES) throw new Error('file too large (32MB cap)')
+  return {
+    fileName: path.basename(file),
+    mimeType: MIME_TYPES.get(path.extname(file).toLowerCase()) ?? 'application/octet-stream',
+    data: fs.readFileSync(file)
+  }
+}
+
+// The QVAC_INPROCESS=1 topology: Core + the harness + the QvacAssistant all
+// live in THIS process, so the harness — a live JS object, which cannot cross
+// the sidecar's process boundary as a spawn arg — can be injected directly.
+// llama.cpp's native logs then share the TUI's tty, the reason for
+// withConsoleSuppressed/requestRepaint above.
+async function startInProcess({ storagePath, deviceName, modelName, logger, onModel }) {
+  const timer = bootTimer(storagePath, 'in-process')
+  timer.stamp('entry')
+  const imageModel = imageModelFromEnv(
+    process.env,
+    () =>
+      console.error(
+        'QVAC_IMAGE_MODEL is a catalog choice — ignoring QVAC_IMAGE_LLM/QVAC_IMAGE_VAE/QVAC_IMAGE_PREDICTION'
+      ),
+    () =>
+      console.error(
+        'QVAC_IMAGE_PREDICTION needs QVAC_IMAGE_LLM and QVAC_IMAGE_VAE (a FLUX set) — ignoring it'
+      )
+  )
+  const credentials = createCredentialStore()
+  const skillCatalog = await loadSkillCatalog(skillsDir)
+  timer.stamp('skills-catalog')
+  const httpRequestTool = createHttpRequestTool({
+    credentialStore: credentials.resolve,
+    credentialAllowList: credentialAllowListFor(skillCatalog)
+  })
+  const mcpCallTool = createMcpCallTool({
+    credentialStore: credentials.resolve,
+    credentialAllowList: credentialAllowListFor(skillCatalog),
+    readMethods: mcpReadMethods(skillCatalog)
+  })
+  const harness = new Harness({
+    tools: [
+      httpRequestTool,
+      createExecTool({ skillsDir }),
+      mcpCallTool,
+      // typed tools compiled from each skill's operations.json, as the sidecar does —
+      // without them a skill that grants sheets_create or notion_create_page is unsupported here
+      ...compileOperationTools(skillCatalog, { httpRequestTool, mcpCallTool }),
+      createSkillTool({ skillsDir }),
+      createWebSearchTool(),
+      createWebFetchTool()
+    ],
+    skillsDir,
+    credentialStore: credentials.resolve,
+    projectionModel: parseProjectionEnv(process.env.QVAC_MMPROJ),
+    imageModel,
+    imageClamps: imageClampsFromEnv(process.env)
+  })
+  await harness.ready()
+  timer.stamp('harness-ready')
+  const [serverStream, clientStream] = duplexPair()
+  // `device` matters: the birth op registers this device's @qvac/devices row
+  // (keyed by the device's public key), which the chunk/approval writer
+  // guards resolve against — without it, every decision is silently dropped.
+  const core = new Core(() => serverStream, {
+    logger,
+    storagePath,
+    device: { name: deviceName, capabilityProfile: 'mid', recommendedModelName: modelName },
+    listModels: harnessListModels(harness),
+    transcribe: harnessTranscribe(harness),
+    speak: harnessSpeak(harness),
+    embedder: {
+      model: DEFAULT_RAG_MODEL,
+      embed: ({ texts, signal }) => harness.embed({ model: DEFAULT_RAG_MODEL, texts, signal })
+    },
+    extractors: { office: extractOfficeText }
+  })
+  await core.ready()
+  timer.stamp('core-ready')
+  const engine = new Client(() => clientStream)
+  await engine.ready()
+  credentials.bind(engine)
+  const assistant = new QvacAssistant(engine, harness)
+  await assistant.ready()
+  timer.stamp('sup-ready')
+  const offDiagnostics = core.registerDiagnostics(() => assistant.diagnosticsSlice())
+  // The harness's model lifecycle is a plain EventEmitter event (see Harness's
+  // own doc comment); the host decides where it lands — the TUI's message loop,
+  // or a log line.
+  harness.on('model', onModel)
+  return {
+    engine,
+    skills: (agentId, modelName) => assistant.skills(agentId, modelName),
+    close: async () => {
+      offDiagnostics()
+      await assistant.close()
+      await engine.close()
+      await core.close()
+      await harness.close()
+    }
+  }
+}
+
+// The prod/desktop topology (the default), and the whole integration story:
+// this spawns the SAME bundle the desktop app ships — dist/assistant.bundle,
+// stowed from worker/assistant-sidecar.mjs by scripts/build-bundle.mjs — and
+// speaks to it through a Client. The TUI used to stow a near-copy of that entry
+// of its own (tui/sidecar.mjs), which is how the two drifted: the copy built
+// its harness in-process while prod spawns one as a further child, and only
+// prod ran the credential pusher. One entry means a break here is a break
+// there. The child's stdout/stderr are pipes, so native model logs can never
+// corrupt this tty — the logger is where that output goes instead: the log file
+// always, and stdout too when headless.
+async function startSidecar({ config, logger }) {
+  const bundle = fileURLToPath(new URL('../dist/assistant.bundle', import.meta.url))
+  if (!fs.existsSync(bundle)) {
+    throw new Error('assistant bundle missing — run `npm run build:bundle`')
+  }
+  // Both bundles: the assistant spawns the harness, and a published install has
+  // neither forest on disk until now.
+  ensurePrebuilds(bundle)
+  ensurePrebuilds(config.harnessEntry)
+  const engine = new Client(async () => {
+    const { ipc, exit } = sidecarRunner(bundle, [JSON.stringify(config)], logger)
+    // the loser resolves rather than rejects: an armed rejection outlives the
+    // race, and the child's own clean exit at teardown would then go unhandled
+    const died = exit.then((code) => `sidecar exited (${code}) before ready`)
+    const failure = await Promise.race([ipc.ready.then(() => null), died])
+    if (failure) throw new Error(failure)
+    return ipc
+  })
+  await engine.ready()
+  return {
+    engine,
+    close: () => engine.close(),
+    skills: async (agentId, modelName) => (await engine.skills({ agentId, modelName })).skills ?? []
+  }
+}
+
+// CLI: `duck [--storage <dir>] [--temp] [--headless]`. Flags may appear in any
+// order. Precedence for the storage dir: --storage <dir> > QVAC_STORAGE env >
+// --temp/QVAC_TEMP=1 throwaway > the persistent global default (below).
+// Joining a mesh is /join inside the app, not a boot argument — the engine
+// takes an invite live (engine.joinMesh), so it never needed to be one.
+function parseArgs(argv) {
+  let storageDir = null
+  let temp = false
+  let headless = false
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--temp') temp = true
+    else if (arg === '--headless') headless = true
+    else if (arg === '--storage') storageDir = argv[++i] ?? null
+    else if (arg.startsWith('--storage=')) storageDir = arg.slice('--storage='.length)
+  }
+  return { storageDir, temp, headless }
+}
+
+// Boot-timing report (QVAC_BOOT_TIMING=1): per-stage stamps from the
+// sidecar/in-process bring-up (see lib/boot-timing.mjs), plus the host's own
+// connect wall time. The TUI calls this only once it has released the tty, so
+// it never fights bare-tui's live render.
+function printBootTiming(storagePath, connectMs) {
+  if (process.env.QVAC_BOOT_TIMING !== '1') return
+  const lines = [
+    connectMs === null ? null : `host: "starting up…" (connect) = ${connectMs}ms`,
+    readBootTiming(storagePath)
+  ].filter(Boolean)
+  if (lines.length) console.log(`\nboot timing:\n${lines.join('\n')}`)
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  // Only override the agent's model when QVAC_MODEL is EXPLICITLY set — otherwise
+  // resuming a shared mesh would silently rewrite the desktop's agent to this
+  // demo default. `recommendedModel` is just the device-row hint on first mint.
+  const modelOverride = process.env.QVAC_MODEL || null
+  const recommendedModel = modelOverride || 'Qwen3.5-9B-Q4_K_M'
+  // Default storage IS the desktop app's own release root, so the TUI resumes
+  // the same mesh + chats the desktop persists there. One at a time — quit the
+  // desktop first, the corestore is single-writer; only safe across matching
+  // Core/schema versions. configureSdkStorage points the SDK at this root's
+  // private sdk-home and the shared model cache, before the SDK's first load so
+  // spawned children inherit both.
+  const useTemp = args.temp || process.env.QVAC_TEMP === '1'
+  const explicitRoot =
+    args.storageDir ||
+    process.env.QVAC_STORAGE ||
+    (useTemp ? fs.mkdtempSync(path.join(os.tmpdir(), 'duck-')) : null)
+  const environment = process.env.QVAC_ENV || 'local'
+  const storage = resolveStorage(releaseChannel(environment), {
+    root: explicitRoot,
+    models: process.env[MODEL_CACHE_PATH_ENV] ?? null
+  })
+  const storagePath = storage.assistant
+  fs.mkdirSync(storagePath, { recursive: true })
+  configureSdkStorage(storage.sdk)
+  let program
+  // reassigned to the engine's close() once connect resolves; noop until then
+  let teardown = () => {}
+  const deviceName = `duck-${process.pid}`
+  // Every run logs; only the destination differs. Both modes write
+  // <storage.root>/assistant.log — the same file the desktop app writes, and
+  // the only way to read a TUI session's engine and sidecar output, since
+  // anything printed outside bare-tui's renderer corrupts the frame. Headless
+  // owns nothing on the tty, so it streams to stdout as well.
+  const logFile = process.env.QVAC_LOG_FILE || path.join(storage.root, 'assistant.log')
+  const logger = new Logger(
+    toLoggerOptions({ logFile, logLevel: process.env.QVAC_LOG_LEVEL, logVerbose: args.headless })
+  )
+
+  // The whole engine bring-up runs INSIDE the TUI (ChatApp calls this from
+  // init()), so the terminal shows the app's own "starting up…" frame instead
+  // of a pre-render status line — console is suppressed for run()'s lifetime
+  // below, so the SDK's boot logs can't corrupt the render. Sidecar is the
+  // default (desktop topology); QVAC_INPROCESS=1 keeps everything in this
+  // process. The app never mints an agent: a fresh mesh seeds its default at
+  // birth (contract/seed-defaults.ts) and a joiner waits for it to replicate;
+  // the provider applies the QVAC_MODEL override only when one is set (below).
+  // Wall time of the whole "starting up…" frame (connect start → resolve), for
+  // the boot-timing report printed after the TUI exits (QVAC_BOOT_TIMING=1).
+  let connectMs = null
+  const connect = async () => {
+    const connectStart = Date.now()
+    const { engine, close, skills } =
+      process.env.QVAC_INPROCESS === '1'
+        ? await startInProcess({
+            storagePath,
+            deviceName,
+            modelName: recommendedModel,
+            logger,
+            onModel: (state) => reportModel(state, logger, () => program)
+          })
+        : await startSidecar({
+            // worker/assistant-sidecar.mjs's own contract, verbatim: it resolves
+            // its storage, logger and image set from this, and spawns the
+            // harness child from harnessEntry. Everything it leaves out keeps
+            // that entry's default (llm kv-cache, hostsModelSource, eager).
+            config: {
+              environment,
+              // ALREADY resolved, not the overrides this host resolved from.
+              // worker/assistant-sidecar.mjs calls resolveStorage again, and by
+              // then configureSdkStorage (below) has exported SDK_HOME_ENV,
+              // which resolveStorage reads as the base a relative root hangs
+              // off: a null root would re-resolve to <root>/sdk-home/qvac/<ch>
+              // — a second, empty mesh beside the real one, with an empty model
+              // cache to match. Passing both values makes that call a
+              // pass-through.
+              storage: { root: storage.root, models: storage.sdk.models },
+              logFlags: {
+                logFile,
+                logLevel: process.env.QVAC_LOG_LEVEL,
+                logVerbose: args.headless
+              },
+              skillsDir,
+              harnessEntry,
+              // only the image keys cross: the arg is argv on a spawned process,
+              // readable by anything that can list processes
+              imageEnv: Object.fromEntries(
+                Object.entries(process.env).filter(([key]) => key.startsWith('QVAC_IMAGE_'))
+              ),
+              device: {
+                name: deviceName,
+                capabilityProfile: 'mid',
+                recommendedModelName: recommendedModel
+              }
+            },
+            logger
+          })
+    teardown = close
+    // The device id IS the device's public key — the raw 32-byte buffer end to
+    // end (schema fixed32), never a hex string.
+    const deviceId = (await engine.deviceInfo({})).id
+    const meshInvite = (await engine.meshInvite({})).invite ?? null
+    connectMs = Date.now() - connectStart
+    return { engine, skills, deviceId, meshInvite, modelName: modelOverride }
+  }
+
+  // Headless: the same stack with no TUI at all. Bring the engine up, print the
+  // invite another instance joins with, then park — the engine's own handles
+  // hold the loop open and its logs stream to stdout until a signal arrives.
+  if (args.headless) {
+    // armed before connect, not after: a ctrl+C partway through a first-run
+    // model download still unwinds cleanly (teardown is a noop until then)
+    const shutdown = async () => {
+      await teardown()
+      Bare.exit(0)
+    }
+    process.on('SIGINT', () => void shutdown())
+    process.on('SIGTERM', () => void shutdown())
+    const { deviceId, meshInvite } = await connect()
+    console.log(`storage ${storagePath}`)
+    console.log(`log     ${logFile}`)
+    console.log(`device  ${deviceName} ${deviceId.toString('hex')}`)
+    console.log(`invite  ${meshInvite ?? '(none — mesh not writable)'}`)
+    printBootTiming(storagePath, connectMs)
+    return
+  }
+
+  const app = new ChatApp({
+    connect,
+    requestRepaint: () => requestRepaint(() => program),
+    copyToClipboard,
+    resolvePastedFile,
+    resolveFileAttachment
+  })
+  // wheel + drag reports (1002+1006) instead of the terminal turning the wheel
+  // into ↑/↓ keys: the transcript scrolls, and it selects its own text (the
+  // terminal can't while tracking is on) — see ChatApp._select
+  program = new Program(app, { mouse: 'drag' })
+  // bracketed paste: a paste arrives as one paste-start/…/paste-end block
+  // instead of per-line key events submitting each pasted line
+  program.output.write('\x1b[?2004h')
+  try {
+    await withConsoleSuppressed(() => {
+      const running = program.run()
+      // run() builds the key decoder synchronously, and bare-tui gives no way to
+      // configure it: a lone esc waits out its 500ms sequence timeout, which is
+      // the visible beat before an overlay closes.
+      if (program._decoder) program._decoder._escapeDelay = ESCAPE_TIMEOUT_MS
+      return running
+    })
+  } finally {
+    program.output.write('\x1b[?2004l')
+  }
+
+  await teardown()
+  printBootTiming(storagePath, connectMs)
+  // Quitting is the goal — don't idle the terminal waiting for the child to
+  // unwind a blocking native call (e.g. a model still loading) before its loop
+  // drains; close() has already torn the sidecar down.
+  Bare.exit(0)
+}
+
+main().catch((err) => {
+  console.error(err)
+  Bare.exit(1)
+})

package/tui/lib/boot-timing.mjs

@@ -0,0 +1,41 @@
+// Opt-in boot-stage timing for the chat demo. Set QVAC_BOOT_TIMING=1 and the
+// bring-up (sidecar child or in-process) stamps each startup milestone to
+// <storagePath>/boot-timing.log; index.mjs reads + prints it after the TUI exits
+// (writing to a file, not the tty, so it can't corrupt bare-tui's live render).
+// A no-op when the env flag is unset, so it never costs anything by default.
+import fs from 'bare-fs'
+import path from 'path'
+import process from 'process'
+
+const NOOP = { enabled: false, stamp() {} }
+
+export function bootTimer(storagePath, tag) {
+  if (process.env.QVAC_BOOT_TIMING !== '1') return NOOP
+  const file = path.join(storagePath, 'boot-timing.log')
+  const t0 = Date.now()
+  try {
+    fs.writeFileSync(file, `# ${tag} boot @ ${new Date().toISOString()}\n`)
+  } catch {}
+  return {
+    enabled: true,
+    stamp(label) {
+      try {
+        fs.appendFileSync(file, `+${Date.now() - t0}ms\t${label}\n`)
+      } catch {}
+    }
+  }
+}
+
+// Read + consume the log the timer wrote (deleted after reading so each launch
+// starts clean). Null when timing is off or nothing was stamped.
+export function readBootTiming(storagePath) {
+  const file = path.join(storagePath, 'boot-timing.log')
+  try {
+    if (!fs.existsSync(file)) return null
+    const text = fs.readFileSync(file, 'utf8').trim()
+    fs.unlinkSync(file)
+    return text || null
+  } catch {
+    return null
+  }
+}