@gotcos/glasses-server 6.1.0

package/server/index.ts

@@ -0,0 +1,211 @@
+// Load .env FIRST — ESM evaluates this module before subsequent imports,
+// ensuring process.env is populated before python-bridge.ts reads COS_SCRIPTS_DIR.
+import './env.js'
+
+import express from 'express'
+import cors from 'cors'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createServer as createHttpsServer } from 'node:https'
+import { readFileSync, existsSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { healthRouter } from './routes/health.js'
+import { diagRouter } from './routes/diag.js'
+import { queryRouter } from './routes/query.js'
+import { transcribeRouter } from './routes/transcribe.js'
+import { displayRouter } from './routes/display.js'
+import { transcribeStreamRouter } from './routes/transcribe-stream.js'
+import { openaiCompatRouter } from './routes/openai-compat.js'
+import { openaiKeyRouter } from './routes/openai-key.js'
+import { prewarmContext } from './lib/context-builder.js'
+import { preWarmCLI } from './lib/claude-bridge.js'
+import { startWhisperServer, stopWhisperServer } from './lib/whisper-local.js'
+import { initSileroVAD } from './lib/vad-silero.js'
+import { initSessionCache } from './lib/session-cache-writer.js'
+import { initSpeakerEmbeddings } from './lib/speaker-embeddings.js'
+import { logActiveSessionsOnShutdown, startAutoSnapshot } from './lib/conversation.js'
+
+const app = express()
+const PORT = parseInt(process.env.PORT ?? '3141', 10)
+
+// Mode detection — COS mode when a full pipeline directory is configured.
+// Standalone (default): glasses + your local Claude Code CLI only.
+export const COS_MODE = !!process.env.COS_SCRIPTS_DIR
+
+// Bind host: the glasses' phone app must reach this server over your network or
+// mesh (e.g. Tailscale), so the default is 0.0.0.0 (all interfaces). The IP
+// allowlist below still blocks untrusted public traffic. Set BIND_HOST=127.0.0.1
+// to restrict to localhost only.
+const BIND_HOST = process.env.BIND_HOST ?? '0.0.0.0'
+
+// API token — auto-generate if not set so every session is authenticated.
+const API_TOKEN_AUTO = !process.env.COS_API_TOKEN
+const API_TOKEN = process.env.COS_API_TOKEN ?? `_${randomBytes(32).toString('base64url')}`
+process.env.COS_API_TOKEN = API_TOKEN  // make available to routes that check it
+
+// Server metrics — shared with /api/health for monitoring
+export const serverMetrics = {
+  startedAt: Date.now(),
+  requestCount: 0,
+}
+
+// IP allowlist — only accept connections from localhost, meshnet, and private networks.
+// Blocks untrusted public access (coffee-shop WiFi, the open internet) while keeping all
+// local + meshnet (Tailscale/CGNAT) + LAN consumers working.
+app.use((req, res, next) => {
+  const ip = req.ip || req.socket.remoteAddress || ''
+  // Normalize IPv6-mapped IPv4 (::ffff:127.0.0.1 → 127.0.0.1)
+  const cleanIp = ip.replace(/^::ffff:/, '')
+  const allowed =
+    cleanIp === '127.0.0.1' || cleanIp === '::1' ||               // localhost
+    /^100\./.test(cleanIp) ||                                       // meshnet (CGNAT)
+    /^10\./.test(cleanIp) ||                                        // private 10.x
+    /^172\.(1[6-9]|2\d|3[01])\./.test(cleanIp) ||                  // private 172.16-31.x
+    /^192\.168\./.test(cleanIp)                                     // private 192.168.x
+  if (!allowed) {
+    res.status(403).json({ error: 'forbidden — not on allowed network' })
+    return
+  }
+  next()
+})
+
+// Allow localhost + LAN IPs (glasses WebView accesses server over LAN)
+app.use(cors({
+  origin: (origin, cb) => {
+    // Allow requests with no origin (same-origin, curl, SSE) or "null" origin (file:// WebViews like Even Hub)
+    if (!origin || origin === 'null') return cb(null, true)
+    // Allow localhost variants
+    if (/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) return cb(null, true)
+    // Allow private network IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 100.x.x.x for Meshnet/CGNAT)
+    if (/^https?:\/\/(10|172\.(1[6-9]|2\d|3[01])|192\.168|100)(\.\d+){2,3}(:\d+)?$/.test(origin)) return cb(null, true)
+    cb(new Error('CORS blocked'))
+  },
+}))
+app.use(express.json({ limit: '10mb' }))
+
+// Auth middleware — always active (token is auto-generated if not set)
+app.use('/api', (req, res, next) => {
+  // Allow health checks, display stream, and client diagnostics without auth.
+  // Diagnostics are whitelisted because the client needs to report crashes
+  // that may happen before the wizard has supplied an API token, and
+  // enforcing auth on a debug telemetry endpoint adds risk during the exact
+  // boot window we're trying to observe.
+  if (
+    req.path === '/health' ||
+    req.path === '/display-stream' ||
+    req.path === '/diag/client' ||
+    req.path === '/diag/health'
+  ) return next()
+  if (req.headers['x-cos-token'] !== API_TOKEN) {
+    return res.status(401).json({ error: 'unauthorized' })
+  }
+  next()
+})
+
+// Request counter — must be before route registrations
+app.use((_req, _res, next) => {
+  serverMetrics.requestCount++
+  next()
+})
+
+// API routes
+app.use('/api', healthRouter)
+app.use('/api', diagRouter)
+app.use('/api', queryRouter)
+app.use('/api', transcribeRouter)
+app.use('/api', displayRouter)
+app.use('/api', transcribeStreamRouter)
+app.use('/api', openaiKeyRouter)
+
+// OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
+// Mounted at root — routes are /v1/chat/completions and /v1/models
+app.use(openaiCompatRouter)
+
+// Friendly root — this is an API server. The glasses client ships as the Even Hub
+// app (the .ehpk), not from here. A browser hitting the host sees a status page.
+app.get('/', (_req, res) => {
+  res.type('html').send(
+    '<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' +
+    '<title>COS Glasses Server</title>' +
+    '<body style="font-family:system-ui,sans-serif;max-width:40rem;margin:4rem auto;padding:0 1.25rem;line-height:1.6;color:#111">' +
+    '<h1 style="font-size:1.4rem">COS Glasses Server</h1>' +
+    '<p>Running. This is the local API for the <strong>COS Glasses</strong> app on Even G2 smart glasses.</p>' +
+    '<ul><li>Health: <a href="/api/health">/api/health</a></li>' +
+    '<li>Setup guide: <a href="https://www.gotcos.com">gotcos.com</a></li></ul>' +
+    '<p style="color:#666;font-size:.9rem">Install the client from the Even Hub, then point it at this server\'s address + token.</p></body>'
+  )
+})
+
+// Graceful shutdown — stop whisper-server child process
+process.on('SIGTERM', () => { stopWhisperServer(); process.exit(0) })
+process.on('SIGINT', () => { logActiveSessionsOnShutdown(); stopWhisperServer(); process.exit(0) })
+
+// Crash protection — log and survive instead of dying mid-meeting
+process.on('uncaughtException', (err) => {
+  console.error('[CRASH GUARD] Uncaught exception (server stays alive):', err.message)
+  console.error(err.stack)
+})
+process.on('unhandledRejection', (reason: any) => {
+  console.error('[CRASH GUARD] Unhandled rejection (server stays alive):', reason?.message ?? reason)
+  if (reason?.stack) console.error(reason.stack)
+})
+
+// Start HTTPS alongside HTTP — Even Hub WebView prefers HTTPS (iOS ATS).
+// Optional: drop cert.pem + key.pem in server/certs/ (e.g. via mkcert) to enable.
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const HTTPS_PORT = parseInt(process.env.HTTPS_PORT ?? '3143', 10)
+const certDir = path.join(__dirname, 'certs')
+if (existsSync(path.join(certDir, 'cert.pem'))) {
+  const httpsServer = createHttpsServer({
+    cert: readFileSync(path.join(certDir, 'cert.pem')),
+    key: readFileSync(path.join(certDir, 'key.pem')),
+  }, app)
+  httpsServer.listen(HTTPS_PORT, BIND_HOST, () => {
+    console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
+  })
+} else {
+  console.log('[COS API] No certs found — HTTPS disabled (drop cert.pem/key.pem in server/certs to enable)')
+}
+
+app.listen(PORT, BIND_HOST, () => {
+  console.log(`[COS API] HTTP server running on http://${BIND_HOST}:${PORT}`)
+  console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
+
+  // Print the full API token when auto-generated — the user pastes it into the app.
+  if (API_TOKEN_AUTO) {
+    console.log('')
+    console.log(`[COS API] API Token: ${API_TOKEN}`)
+    console.log('[COS API]   ^ paste this into the COS Glasses app (set COS_API_TOKEN in .env for a fixed token)')
+    console.log('')
+  }
+
+  // Check Claude CLI availability — the chat backend
+  try {
+    execSync('claude --version', { timeout: 5000, stdio: 'pipe' })
+    console.log('[COS API] Claude Code CLI detected')
+  } catch {
+    console.warn('[COS API] Claude Code CLI not found — install from https://claude.ai/download')
+    console.warn('[COS API]   AI queries will not work without the Claude Code CLI')
+  }
+
+  if (COS_MODE) {
+    initSessionCache()
+    // Pre-warm context cache so first query doesn't wait for the pipeline
+    prewarmContext()
+  }
+  // Start local whisper-server (model stays in RAM for ~50ms transcription)
+  startWhisperServer().catch(err => console.error('[startup] Whisper server error:', err))
+  // Initialize speaker embeddings (voiceprint-based diarization) — fails soft if model absent
+  const embeddingOk = initSpeakerEmbeddings()
+  console.log(`[startup] Speaker embeddings: ${embeddingOk ? 'active' : 'disabled (model not found)'}`)
+  // Initialize Silero VAD (silence trimming before Whisper) — fails soft if model absent
+  const vadOk = initSileroVAD()
+  console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
+
+  // Pre-warm the Claude CLI so the first query doesn't eat a 2-15s cold start
+  preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+
+  // Auto-snapshot active sessions every 5 min (survives restarts)
+  startAutoSnapshot(5 * 60_000)
+})

package/server/lib/archive-budget.ts

@@ -0,0 +1,65 @@
+// Daily LLM call budget for archive summary generation.
+// `claude -p` calls count against the user's Claude plan allocation. A boot
+// after a long offline period could trigger N × (chats + 1) Sonnet calls via
+// `runDailyArchiveMirror` — easily hundreds in one burst. This cap (checked
+// before EVERY claude -p call from archive.ts) forces the system to degrade
+// to string-fallback summaries once the daily budget is spent.
+//
+// You can raise the cap or clear the counter manually if needed.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { localDay } from './local-day.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+import { dataPath } from './data-dir.js'
+const BUDGET_FILE = dataPath('archive-budget.json')
+
+/** Max claude -p calls per local day across all archive summary generation. */
+export const MAX_DAILY_ARCHIVE_LLM_CALLS = 30
+
+interface BudgetState {
+  date: string  // local YYYY-MM-DD
+  calls: number
+}
+
+function readBudget(): BudgetState {
+  const today = localDay()
+  if (!existsSync(BUDGET_FILE)) return { date: today, calls: 0 }
+  try {
+    const raw = readFileSync(BUDGET_FILE, 'utf-8')
+    const data = JSON.parse(raw) as BudgetState
+    if (data.date !== today) return { date: today, calls: 0 } // new day, reset
+    return data
+  } catch {
+    return { date: today, calls: 0 }
+  }
+}
+
+function writeBudget(state: BudgetState): void {
+  try {
+    writeFileSync(BUDGET_FILE, JSON.stringify(state))
+  } catch {
+    /* non-fatal — worst case we might double-count next read */
+  }
+}
+
+/**
+ * Attempt to consume one LLM call from today's budget.
+ * Returns true if the call is allowed and budget was decremented.
+ * Returns false if budget is exhausted — caller must use a non-LLM fallback.
+ */
+export function consumeArchiveLLMBudget(): boolean {
+  const state = readBudget()
+  if (state.calls >= MAX_DAILY_ARCHIVE_LLM_CALLS) return false
+  state.calls++
+  writeBudget(state)
+  return true
+}
+
+/** For diagnostics / dashboards. */
+export function getArchiveLLMBudgetState(): BudgetState & { max: number; remaining: number } {
+  const state = readBudget()
+  return { ...state, max: MAX_DAILY_ARCHIVE_LLM_CALLS, remaining: Math.max(0, MAX_DAILY_ARCHIVE_LLM_CALLS - state.calls) }
+}

package/server/lib/archive.ts

@@ -0,0 +1,414 @@
+// Daily archive system — persists conversation history beyond session TTL
+// Archives are stored as JSON files per day in server/data/archive/
+// Each day's archive contains one or more "chats" (split by context breaks)
+// Summaries are generated via `claude -p --model sonnet`, budget-capped per day.
+
+import { mkdirSync, readdirSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { exec } from 'node:child_process'
+import { promisify } from 'node:util'
+import { logTokenAudit } from './token-audit.js'
+import { atomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+import { consumeArchiveLLMBudget } from './archive-budget.js'
+
+const execAsync = promisify(exec)
+import type { Exchange } from './conversation.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+import { dataPath } from './data-dir.js'
+const ARCHIVE_DIR = dataPath('archive')
+
+// ── Interfaces ──────────────────────────────────────────────
+
+export interface ArchivedChat {
+  id: number
+  sessionId: string            // Original 8-char UUID from conversation.ts (added v3.9.0)
+  exchanges: Exchange[]
+  startedAt: number
+  endedAt: number
+  exchangeCount: number
+  summary: string
+}
+
+export interface DailyArchive {
+  date: string             // YYYY-MM-DD
+  summary: string          // <60 char day summary
+  chats: ArchivedChat[]
+  archivedAt: string       // ISO timestamp
+}
+
+export interface ArchiveDateSummary {
+  date: string
+  summary: string
+  chatCount: number
+  exchangeCount: number
+}
+
+export interface ArchiveChatSummary {
+  index: number
+  summary: string
+  exchangeCount: number
+  startedAt: number
+}
+
+// ── Internal: session structure for archiving ────────────────
+
+export interface SessionToArchive {
+  id: string
+  exchanges: Exchange[]
+  contextBreaks: number[]
+  createdAt: number
+  lastActivity: number
+}
+
+// ── Directory management ────────────────────────────────────
+
+function ensureArchiveDir(): string {
+  mkdirSync(ARCHIVE_DIR, { recursive: true })
+  return ARCHIVE_DIR
+}
+
+function archivePath(date: string): string {
+  return resolve(ensureArchiveDir(), `${date}.json`)
+}
+
+// ── Read/Write ──────────────────────────────────────────────
+
+export function loadArchive(date: string): DailyArchive | null {
+  const result = loadJsonOrQuarantine<DailyArchive>(archivePath(date))
+  if (result.status === 'corrupt') {
+    // Loud — a silent return masked archive corruption as "day unavailable"
+    console.error(
+      `[archive] Corrupt archive for ${date} quarantined to ${result.quarantinedAs}. ` +
+      `Raw bytes are recoverable by hand from that file.`,
+      result.error,
+    )
+    return null
+  }
+  if (result.status === 'missing') return null
+  return result.data
+}
+
+function saveArchive(archive: DailyArchive): void {
+  ensureArchiveDir()
+  atomicWriteFileSync(archivePath(archive.date), JSON.stringify(archive, null, 2))
+}
+
+// Per-date write lock — prevents `runDailyArchiveMirror` from racing parallel
+// appends on the same day file. Each appendToArchive chains behind the current
+// in-flight write for that date. Lock map is cleaned up when the chain resolves.
+const archiveWriteLocks = new Map<string, Promise<void>>()
+
+function withArchiveLock<T>(date: string, op: () => Promise<T>): Promise<T> {
+  const prev = archiveWriteLocks.get(date) ?? Promise.resolve()
+  const next = prev.then(op, op) // run op regardless of prior success/failure
+  // Store a void-typed tail in the lock map so a rejection here doesn't cause
+  // unhandled-rejection noise — op's result is returned to the caller via `next`.
+  const tail: Promise<void> = next.then(() => undefined, () => undefined)
+  archiveWriteLocks.set(date, tail)
+  tail.finally(() => {
+    if (archiveWriteLocks.get(date) === tail) archiveWriteLocks.delete(date)
+  })
+  return next
+}
+
+// ── Chat splitting ──────────────────────────────────────────
+
+/** Split a session's exchanges into chats using contextBreaks[] timestamps */
+export function splitSessionIntoChats(session: SessionToArchive): ArchivedChat[] {
+  const { exchanges, contextBreaks } = session
+  if (exchanges.length === 0) return []
+
+  // Build break points (sorted)
+  const breaks = [...contextBreaks].sort((a, b) => a - b)
+  const chats: ArchivedChat[] = []
+  let chatId = 0
+
+  // Find chat boundaries
+  const boundaries: number[] = [0] // start index of each chat
+  for (const breakTs of breaks) {
+    // Find first exchange after this break
+    const idx = exchanges.findIndex(e => e.timestamp > breakTs)
+    if (idx > 0 && !boundaries.includes(idx)) {
+      boundaries.push(idx)
+    }
+  }
+
+  // Build chats from boundaries
+  for (let b = 0; b < boundaries.length; b++) {
+    const startIdx = boundaries[b]
+    const endIdx = b + 1 < boundaries.length ? boundaries[b + 1] : exchanges.length
+    const chatExchanges = exchanges.slice(startIdx, endIdx)
+    if (chatExchanges.length === 0) continue
+
+    chats.push({
+      id: chatId++,
+      sessionId: session.id,
+      exchanges: chatExchanges,
+      startedAt: chatExchanges[0].timestamp,
+      endedAt: chatExchanges[chatExchanges.length - 1].timestamp,
+      exchangeCount: chatExchanges.length,
+      summary: '', // filled by generateChatSummary
+    })
+  }
+
+  return chats
+}
+
+// ── Summary generation ──────────────────────────────────────
+
+/** Deterministic fallback used when LLM is budget-skipped or errors out. */
+function fallbackChatSummary(exchanges: Exchange[]): string {
+  const firstQuery = exchanges.find(e => e.role === 'user')?.content ?? ''
+  if (!firstQuery.trim()) return 'Empty chat'
+  return firstQuery.length > 57 ? firstQuery.slice(0, 57) + '...' : firstQuery
+}
+
+function fallbackDaySummary(chats: ArchivedChat[]): string {
+  const summaries = chats.map(c => {
+    const first = c.exchanges.find(e => e.role === 'user')?.content ?? ''
+    return first.length > 30 ? first.slice(0, 27) + '...' : first
+  }).filter(Boolean)
+  return summaries.slice(0, 2).join(', ').slice(0, 60) || 'Day activity'
+}
+
+/** Generate a <60 char summary for a single chat via claude -p.
+ *  Budget-capped: if MAX_DAILY_ARCHIVE_LLM_CALLS is exhausted or `skipLLM` is
+ *  passed, returns a deterministic string fallback. */
+export async function generateChatSummary(exchanges: Exchange[], skipLLM = false): Promise<string> {
+  if (skipLLM || !consumeArchiveLLMBudget()) {
+    return fallbackChatSummary(exchanges)
+  }
+
+  const userQueries = exchanges
+    .filter(e => e.role === 'user')
+    .map(e => e.content)
+    .slice(0, 10) // cap to avoid token overflow
+    .join('\n')
+
+  if (!userQueries.trim()) return 'Empty chat'
+
+  const startMs = Date.now()
+  try {
+    const { stdout } = await execAsync(
+      `echo ${JSON.stringify(userQueries)} | claude -p --model sonnet "Summarize these COS Glasses queries into a single title under 60 characters. Just the title, no quotes, no explanation."`,
+      { timeout: 15_000 }
+    )
+    const result = stdout.trim()
+
+    logTokenAudit({
+      source: 'g2-archive',
+      model: 'sonnet',
+      inputChars: userQueries.length + 100,
+      outputChars: result.length,
+      durationMs: Date.now() - startMs,
+      caller: 'chat_summary',
+    })
+
+    // Validate: must be reasonable length
+    if (result.length > 0 && result.length <= 80) {
+      return result.slice(0, 60)
+    }
+  } catch {
+    // Fall through to fallback
+  }
+
+  return fallbackChatSummary(exchanges)
+}
+
+/** Generate a <60 char summary for a full day's chats. Same budget semantics. */
+export async function generateDaySummary(chats: ArchivedChat[], skipLLM = false): Promise<string> {
+  if (skipLLM || !consumeArchiveLLMBudget()) {
+    return fallbackDaySummary(chats)
+  }
+
+  const allQueries = chats
+    .flatMap(c => c.exchanges.filter(e => e.role === 'user').map(e => e.content))
+    .slice(0, 15)
+    .join('\n')
+
+  if (!allQueries.trim()) return 'No activity'
+
+  const startMs = Date.now()
+  try {
+    const { stdout } = await execAsync(
+      `echo ${JSON.stringify(allQueries)} | claude -p --model sonnet "Summarize these COS Glasses queries from one day into a daily title under 60 characters. Just the title, no quotes."`,
+      { timeout: 15_000 }
+    )
+    const result = stdout.trim()
+
+    logTokenAudit({
+      source: 'g2-archive',
+      model: 'sonnet',
+      inputChars: allQueries.length + 100,
+      outputChars: result.length,
+      durationMs: Date.now() - startMs,
+      caller: 'day_summary',
+    })
+
+    if (result.length > 0 && result.length <= 80) {
+      return result.slice(0, 60)
+    }
+  } catch {
+    // Fall through to fallback
+  }
+
+  return fallbackDaySummary(chats)
+}
+
+// ── Archive operations ──────────────────────────────────────
+
+export interface AppendToArchiveOpts {
+  /** When true, skip all `claude -p` summary calls — use deterministic string
+   *  fallbacks instead. Used by the daily archive-mirror path to prevent a
+   *  cost spike on boot after long idle periods. */
+  skipLLM?: boolean
+}
+
+/** Append an archived session (split into chats) to a daily archive file.
+ *  Serialized per date via `withArchiveLock` so concurrent callers cannot
+ *  race on load→mutate→save and clobber each other's writes. */
+export async function appendToArchive(
+  date: string,
+  session: SessionToArchive,
+  opts: AppendToArchiveOpts = {},
+): Promise<void> {
+  return withArchiveLock(date, async () => {
+    const existing = loadArchive(date)
+    const newChats = splitSessionIntoChats(session)
+
+    // Generate summaries for new chats
+    for (const chat of newChats) {
+      chat.summary = await generateChatSummary(chat.exchanges, opts.skipLLM)
+    }
+
+    if (existing) {
+      // Merge: re-number chat IDs
+      const nextId = existing.chats.length
+      for (let i = 0; i < newChats.length; i++) {
+        newChats[i].id = nextId + i
+      }
+      existing.chats.push(...newChats)
+      existing.summary = await generateDaySummary(existing.chats, opts.skipLLM)
+      existing.archivedAt = new Date().toISOString()
+      saveArchive(existing)
+    } else {
+      const archive: DailyArchive = {
+        date,
+        summary: await generateDaySummary(newChats, opts.skipLLM),
+        chats: newChats,
+        archivedAt: new Date().toISOString(),
+      }
+      saveArchive(archive)
+    }
+  })
+}
+
+// ── Query functions ─────────────────────────────────────────
+
+/** List all archive dates with summaries */
+export function listArchiveDates(): ArchiveDateSummary[] {
+  try {
+    ensureArchiveDir()
+    const files = readdirSync(ARCHIVE_DIR)
+      .filter(f => f.endsWith('.json'))
+      .sort()
+      .reverse() // newest first
+
+    return files.map(f => {
+      const date = f.replace('.json', '')
+      const archive = loadArchive(date)
+      if (!archive) return null
+      return {
+        date: archive.date,
+        summary: archive.summary,
+        chatCount: archive.chats.length,
+        exchangeCount: archive.chats.reduce((sum, c) => sum + c.exchangeCount, 0),
+      }
+    }).filter(Boolean) as ArchiveDateSummary[]
+  } catch {
+    return []
+  }
+}
+
+/** Get chat summaries for a specific day */
+export function getArchiveChats(date: string): ArchiveChatSummary[] {
+  const archive = loadArchive(date)
+  if (!archive) return []
+  return archive.chats.map(c => ({
+    index: c.id,
+    summary: c.summary,
+    exchangeCount: c.exchangeCount,
+    startedAt: c.startedAt,
+  }))
+}
+
+/** Get paired Q&A messages for a specific chat within a day */
+export function getArchiveChatMessages(date: string, chatIndex: number): Array<{ query: string; text: string; timestamp: number }> {
+  const archive = loadArchive(date)
+  if (!archive) return []
+  const chat = archive.chats.find(c => c.id === chatIndex)
+  if (!chat) return []
+
+  const messages: Array<{ query: string; text: string; timestamp: number }> = []
+  for (let i = 0; i < chat.exchanges.length; i++) {
+    const ex = chat.exchanges[i]
+    if (ex.role === 'user') {
+      const next = chat.exchanges[i + 1]
+      if (next && next.role === 'assistant') {
+        messages.push({ query: ex.content, text: next.content, timestamp: next.timestamp })
+        i++ // skip assistant
+      }
+    }
+  }
+  return messages
+}
+
+/** Get all messages for a day (flat, across all chats) — for phone browser.
+ *  `sessionId` is included so the today/all-messages endpoint can dedup on
+ *  (sessionId, timestamp) instead of bare timestamp (collision-prone). */
+export function getArchiveDayMessages(
+  date: string,
+): Array<{ query: string; text: string; timestamp: number; chatIndex: number; sessionId: string }> {
+  const archive = loadArchive(date)
+  if (!archive) return []
+
+  const messages: Array<{ query: string; text: string; timestamp: number; chatIndex: number; sessionId: string }> = []
+  for (const chat of archive.chats) {
+    for (let i = 0; i < chat.exchanges.length; i++) {
+      const ex = chat.exchanges[i]
+      if (ex.role === 'user') {
+        const next = chat.exchanges[i + 1]
+        if (next && next.role === 'assistant') {
+          messages.push({
+            query: ex.content,
+            text: next.content,
+            timestamp: next.timestamp,
+            chatIndex: chat.id,
+            sessionId: chat.sessionId,
+          })
+          i++
+        }
+      }
+    }
+  }
+  return messages
+}
+
+// ── Startup check ───────────────────────────────────────────
+
+/** Check if yesterday needs archiving (handles overnight server restarts) */
+export function checkYesterdayArchive(): void {
+  const yesterday = new Date(Date.now() - 86_400_000).toISOString().slice(0, 10)
+  const existing = loadArchive(yesterday)
+  if (!existing) {
+    // No yesterday archive exists — but we can't archive sessions that are already expired
+    // This is a no-op unless we add persistent session storage beyond TTL
+    // The main trigger is the session expiry hook in conversation.ts
+    console.log(`[archive] No archive for ${yesterday} — sessions may have already expired`)
+  }
+}
+
+// Run on module load
+checkYesterdayArchive()