@gotcos/glasses-server 6.2.0 → 6.3.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 6.3.1
+
+Security + robustness hardening on the 6.3.0 archive routes, from a 3-agent QA pass. (6.3.0 was never published; 6.3.1 is the first release of the expanded route set.)
+
+- **SECURITY — path traversal blocked.** The new `:date` archive routes fed the param straight into `<dir>/${date}.json`, so an encoded traversal (`/api/archive/..%2F..%2Fetc%2Fhosts`) could read arbitrary `*.json` on the host (and rename-corrupt one via the quarantine path). Auth+IP gated, but a real exposure on a shared LAN/meshnet. Fixed: `archiveRouter.param('date', …)` enforces `^\d{4}-\d{2}-\d{2}$` on every `:date` route before any fs access; defense-in-depth guard in `readArchiveChatNumbered`. Verified: traversal/bad-format → 400, valid dates → 200.
+- **Reference date label (US evenings).** Live-session `reference message N` stamped the date with UTC, labeling an evening reference with tomorrow's date. Now `localDay()`.
+- **Malformed day file no longer wipes History.** A valid-JSON wrong-shape day file (no `chats[]`) 500'd the readers and dropped `listArchiveDates` into its catch, hiding all history. `loadArchive` coerces `chats` to `[]`; the bad day lists as 0 chats.
+- **Thrift/cosmetic:** `/api/archive/now` passes `skipLLM:true` (no surprise LLM spend on a public manual snapshot); stale path comment + unused `__dirname` removed from `lib/archive.ts`.
+
+## 6.3.0
+
+Message History, cross-day references, and history recovery for public installs.
+These features previously required a full COS server; now `npx @gotcos/glasses-server`
+exposes them too, so the G2 app's Message History and "reference message N" work
+on a vanilla install.
+
+- **Message History** — the archive routes (`/api/archive`, `/api/archive/:date/chats`,
+  `/api/archive/:date/chats/:i/messages`, `/api/archive/:date/messages`, `/api/archive/now`)
+  are now served. The daily archive-mirror (already in this package) writes prior-day
+  sessions to disk; these routes browse them. Each day row shows chat count + topic.
+- **Cross-day "reference message N"** — new `/api/message/:num` resolves a permanent
+  message number across live sessions then day archives (newest-first), and
+  `/api/message-counter` publishes the numbering ceiling so a fresh/cleared client
+  never reuses a number. Message numbers were already stored (`globalMsgNum`); this
+  makes them resolvable.
+- **History recovery** — session routes (`/api/sessions/today/all-messages`,
+  `/api/sessions/:id/messages`, recent-sessions index, context-break, end-session)
+  let the app restore recent history and open archived chats.
+
+No change to the public-safe model curation (Sonnet default, no pinned/unreleased
+model ids) or the core query/voice/display paths. Typecheck clean; new routes
+smoke-tested (message-counter, archive list, message lookup).
+
+## 6.2.1
+
+Foolproofing release — driven by an adversarial onboarding QA pass.
+
+- **The server now prints URLs the phone can actually use.** Boot output lists
+  your real addresses (`http://100.x.x.x:3141` labeled Tailscale, LAN IPs labeled
+  same-Wi-Fi) instead of only the un-pasteable bind address `0.0.0.0`.
+- **Auto-generated API tokens survive restarts.** First boot saves the token to
+  `~/.cos-glasses/.env`, so re-running the server no longer silently rotates the
+  credential your app already saved (the "worked yesterday, 401 today" trap).
+- **Starter-Kit COS inheritance is real now.** Run `npx @gotcos/glasses-server`
+  from your COS folder and glasses chat loads its brain: the launcher records
+  your launch directory, and when it contains `.cos/manifest.json`, `AGENTS.md`,
+  or `CLAUDE.md`, Claude/Codex spawn there (explicit `COS_SCRIPTS_DIR` still wins).
+- **Transfer-integrity report actually surfaces.** 6.2.0 recorded lost chunks but
+  never returned them; the offline-session `finalize` response now includes
+  `transferIntegrity` (received/expected/missing/completeness) and a gap-aware
+  `transcript` with inline `[… audio gap …]` markers.
+- **One default model everywhere: Sonnet.** The query router, the OpenAI-compat
+  surface, and CLI pre-warm all default to Sonnet (was a mix of Opus and Haiku).
+  Set `COS_G2_DEFAULT_MODEL` to override; per-query picks unchanged.
+
 ## 6.2.0
 
 Reliability release — ports the hardening the full COS Glasses app shipped in June.

package/README.md

@@ -44,6 +44,8 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 ## What it does
 
 - Ask anything, get a streamed answer on the lens (`/api/query`, `/v1/chat/completions`)
+- Message History + cross-day "reference message N" — your chats are archived by day
+  and every message keeps a permanent number you can recall (`/api/archive`, `/api/message/:num`)
 - Live voice capture + transcription during meetings
 - Local whisper.cpp transcription (free) with OpenAI fallback (optional)
 - Tasks / calendar / people context **if** you run the

package/bin/cli.cjs

@@ -13,6 +13,12 @@ const { homedir } = require('os')
 const PKG_ROOT = resolve(__dirname, '..')
 const CONFIG_DIR = join(homedir(), '.cos-glasses')
 
+// Record where the user ran `npx @gotcos/glasses-server` from. The server spawns
+// with cwd = PKG_ROOT (the npx cache), so without this the user's Starter-Kit COS
+// (AGENTS.md / CLAUDE.md / .cos/) in their launch folder would never be seen.
+// Chat spawns of claude/codex use this dir when it contains a COS brain.
+if (!process.env.COS_LAUNCH_DIR) process.env.COS_LAUNCH_DIR = process.cwd()
+
 const green = (s) => `\x1b[32m${s}\x1b[0m`
 const red = (s) => `\x1b[31m${s}\x1b[0m`
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`
@@ -185,6 +191,12 @@ if (!process.env.BIND_HOST) {
 }
 
 // Step 7: start the bundled server
+try {
+  const ld = process.env.COS_LAUNCH_DIR
+  if (ld && (existsSync(join(ld, '.cos', 'manifest.json')) || existsSync(join(ld, 'AGENTS.md')) || existsSync(join(ld, 'CLAUDE.md')))) {
+    console.log(green('  ✓') + ` COS detected in ${dim(ld)} — glasses chat will load its brain`)
+  }
+} catch { /* detection is best-effort */ }
 console.log('')
 console.log(dim('  Starting server...'))
 console.log('')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.2.0",
+  "version": "6.3.1",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -7,7 +7,9 @@ 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 { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
+import { networkInterfaces, homedir } from 'node:os'
+import { join } from 'node:path'
 import { execSync } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { healthRouter } from './routes/health.js'
@@ -18,6 +20,9 @@ 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 { messageRefRouter } from './routes/message-ref.js'
+import { archiveRouter } from './routes/archive.js'
+import { sessionsRouter } from './routes/sessions.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { startWhisperServer, stopWhisperServer } from './lib/whisper-local.js'
@@ -43,6 +48,18 @@ const BIND_HOST = process.env.BIND_HOST ?? '0.0.0.0'
 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
+// Persist an auto-generated token to ~/.cos-glasses/.env so it SURVIVES restarts.
+// Without this, every re-run mints a new token and the app's saved token starts
+// returning 401 — the symptom looks like a broken app, not a rotated credential.
+let API_TOKEN_PERSISTED = false
+if (API_TOKEN_AUTO) {
+  try {
+    const envDir = join(homedir(), '.cos-glasses')
+    mkdirSync(envDir, { recursive: true })
+    appendFileSync(join(envDir, '.env'), `\n# auto-generated by the server so the app token survives restarts\nCOS_API_TOKEN=${API_TOKEN}\n`)
+    API_TOKEN_PERSISTED = true
+  } catch { /* read-only home — token stays per-session */ }
+}
 
 // Server metrics — shared with /api/health for monitoring
 export const serverMetrics = {
@@ -117,6 +134,11 @@ app.use('/api', transcribeRouter)
 app.use('/api', displayRouter)
 app.use('/api', transcribeStreamRouter)
 app.use('/api', openaiKeyRouter)
+// v6.3.0 — Message History, cross-day 'reference message N', and history
+// recovery for public npx users (previously full-COS-server only).
+app.use('/api', messageRefRouter)
+app.use('/api', archiveRouter)
+app.use('/api', sessionsRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -178,11 +200,31 @@ 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 ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
+  // not paste-able — enumerate real interfaces and label the Tailscale one.
+  try {
+    const nets = networkInterfaces()
+    const addrs: Array<{ ip: string; label: string }> = []
+    for (const [name, infos] of Object.entries(nets)) {
+      for (const info of infos ?? []) {
+        if (info.family !== 'IPv4' || info.internal) continue
+        const isTailscale = info.address.startsWith('100.') || name.startsWith('utun') || name.startsWith('tailscale')
+        addrs.push({ ip: info.address, label: isTailscale ? 'Tailscale — works from anywhere' : `${name} — same Wi-Fi only` })
+      }
+    }
+    if (addrs.length > 0) {
+      addrs.sort((a, b) => Number(b.label.startsWith('Tailscale')) - Number(a.label.startsWith('Tailscale')))
+      console.log('')
+      console.log('[COS API] Server URL for the COS Glasses app:')
+      for (const a of addrs) console.log(`[COS API]   http://${a.ip}:${PORT}   (${a.label})`)
+    }
+  } catch { /* interface enumeration is best-effort */ }
+
   // 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('[COS API]   ^ paste this into the COS Glasses app' + (API_TOKEN_PERSISTED ? ' — saved to ~/.cos-glasses/.env so it stays the same across restarts' : ' (set COS_API_TOKEN in .env for a fixed token)'))
     console.log('')
   }
 

package/server/lib/archive.ts

@@ -1,5 +1,5 @@
 // Daily archive system — persists conversation history beyond session TTL
-// Archives are stored as JSON files per day in server/data/archive/
+// Archives are stored as JSON files per day in ~/.cos-glasses/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.
 
@@ -15,7 +15,6 @@ 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')
 
@@ -87,7 +86,12 @@ export function loadArchive(date: string): DailyArchive | null {
     return null
   }
   if (result.status === 'missing') return null
-  return result.data
+  // Defense: a valid-JSON but wrong-shape day file (no chats[]) would make the
+  // readers throw 500 AND drop listArchiveDates into its catch → the whole
+  // Message History list vanishes on one bad file. Coerce to an empty day.
+  const data = result.data
+  if (data && !Array.isArray(data.chats)) data.chats = []
+  return data
 }
 
 function saveArchive(archive: DailyArchive): void {

package/server/lib/claude-bridge.ts

@@ -12,11 +12,12 @@ import { join } from 'node:path'
 import { appendFileSync } from 'node:fs'
 import crypto from 'node:crypto'
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
+import { cosBrainDir } from './launch-dir.js'
 import { logTokenAudit } from './token-audit.js'
 import { buildSystemPrompt, buildLightweightSystemPrompt, buildPrewarmSystemPrompt, getCachedContextInstant } from './context-builder.js'
 import { getHistory, addExchange, formatHistoryForPrompt, getOrCreateSession, isNewSession, markSessionNotified, getSessionModel, getSessionRaw, replaceLastExchangeWithSummary, type ModelPreference, type PromptReference } from './conversation.js'
 import { notifySessionStart, notifyExchange } from './telegram-notify.js'
-import { isClaudeModel, type ClaudeModelPreference } from '../../shared/model-preference.js'
+import { isClaudeModel, DEFAULT_MODEL, type ClaudeModelPreference } from '../../shared/model-preference.js'
 import {
   finishClaudeRun,
   getClaudeEffortLevel,
@@ -182,7 +183,7 @@ export async function preWarmCLI(): Promise<void> {
 
     const proc = spawn('claude', [
       '-p',
-      '--model', 'opus',  // Must match default query model — --resume inherits session model
+      '--model', DEFAULT_MODEL,  // Must match default query model — --resume inherits session model
       '--effort', getClaudeEffortLevel(),
       '--output-format', 'stream-json',
       '--verbose',
@@ -191,7 +192,7 @@ export async function preWarmCLI(): Promise<void> {
     ], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
-      cwd: COS_SCRIPTS_DIR ?? process.cwd(),
+      cwd: COS_SCRIPTS_DIR ?? cosBrainDir() ?? process.cwd(),
     })
 
     let buffer = ''
@@ -419,7 +420,7 @@ export async function callClaudeStreaming(
   // Strip CLAUDECODE env var so claude -p doesn't think it's nested
   const env = { ...process.env }
   delete env.CLAUDECODE
-  const cliCwd = COS_SCRIPTS_DIR ?? process.cwd()
+  const cliCwd = COS_SCRIPTS_DIR ?? cosBrainDir() ?? process.cwd()
   const inactivityMs = INACTIVITY_BY_MODEL[resolvedModel]
   const defaultWallMax = WALL_MAX_BY_MODEL[resolvedModel]
   const wallMax = isExtendedQuery(query) ? WALL_MAX_EXTENDED_MS : defaultWallMax

package/server/lib/codex-run-ledger.ts

@@ -2,6 +2,7 @@ import crypto from 'node:crypto'
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { COS_SCRIPTS_DIR } from './python-bridge.js'
+import { cosBrainDir } from './launch-dir.js'
 import { CODEX_ENGINE_SESSION_TTL_MS, type CodexTrustMode } from './codex-engine-sessions.js'
 import {
   CODEX_HIGH_REASONING_EFFORT,
@@ -80,6 +81,10 @@ export function getCodexExecutionCwd(): string {
   const configured = process.env.CODEX_GLASSES_WORKDIR?.trim()
   if (configured) return resolve(configured)
   if (COS_SCRIPTS_DIR) return resolve(COS_SCRIPTS_DIR, '..', '..')
+  // A Starter-Kit COS in the directory the user launched npx from — Codex
+  // loads its AGENTS.md brain natively when run there.
+  const brain = cosBrainDir()
+  if (brain) return brain
   // Last resort when neither CODEX_GLASSES_WORKDIR nor COS_SCRIPTS_DIR is set:
   // the server's own working dir (codex glasses is an optional, env-configured feature).
   return process.cwd()

package/server/lib/launch-dir.ts

@@ -0,0 +1,29 @@
+// COS brain auto-detection for the "glasses inherit your COS" promise.
+//
+// The npx launcher (bin/cli.cjs) records the directory the user ran `npx
+// @gotcos/glasses-server` from as COS_LAUNCH_DIR before re-spawning the server
+// with cwd = the package root. If that launch directory contains a COS brain
+// (a Starter-Kit scaffold: .cos/manifest.json, AGENTS.md, or CLAUDE.md), chat
+// spawns of claude/codex use IT as their working directory — so the CLIs load
+// the user's brain exactly as they would in a terminal session in that folder.
+//
+// Precedence stays: COS_SCRIPTS_DIR (full COS pipeline) > detected brain dir >
+// process.cwd(). Explicit config always wins.
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+let cached: string | null | undefined
+
+/** The user's launch directory IF it contains a COS brain; otherwise null. */
+export function cosBrainDir(): string | null {
+  if (cached !== undefined) return cached
+  const raw = process.env.COS_LAUNCH_DIR?.trim()
+  if (!raw) { cached = null; return cached }
+  const dir = resolve(raw)
+  const hasBrain =
+    existsSync(join(dir, '.cos', 'manifest.json')) ||
+    existsSync(join(dir, 'AGENTS.md')) ||
+    existsSync(join(dir, 'CLAUDE.md'))
+  cached = hasBrain ? dir : null
+  return cached
+}

package/server/routes/archive.ts

@@ -0,0 +1,79 @@
+// Archive endpoints — daily conversation archive for glasses history browser
+import { Router } from 'express'
+import { listArchiveDates, loadArchive, getArchiveChats, getArchiveDayMessages, appendToArchive } from '../lib/archive.js'
+import { getArchiveChatMessagesNumbered } from './message-ref.js'
+import { getActiveSessions } from '../lib/conversation.js'
+
+export const archiveRouter = Router()
+
+// v5.15.6 / pkg v6.3.1 — SECURITY: :date is used to build filesystem paths
+// (loadArchive/getArchiveChats/getArchiveDayMessages/getArchiveChatMessagesNumbered
+// all resolve `<dir>/${date}.json`). Without validation, an encoded traversal
+// (e.g. /api/archive/..%2F..%2Fetc%2Fhosts) reads/renames arbitrary *.json on
+// the host. Validate the segment as a strict YYYY-MM-DD once for every :date
+// route before any fs access.
+archiveRouter.param('date', (req, res, next, date) => {
+  if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+    res.status(400).json({ error: 'Invalid date' })
+    return
+  }
+  next()
+})
+
+// GET /api/archive — list all archive dates with summaries
+archiveRouter.get('/archive', (_req, res) => {
+  const archives = listArchiveDates()
+  res.json({ archives })
+})
+
+// POST /api/archive/now — snapshot active sessions into today's archive (non-destructive)
+archiveRouter.post('/archive/now', async (_req, res) => {
+  const activeSessions = getActiveSessions()
+  if (activeSessions.length === 0) {
+    res.json({ archived: 0, date: new Date().toISOString().slice(0, 10) })
+    return
+  }
+
+  const todayDate = new Date().toISOString().slice(0, 10)
+  let archived = 0
+  for (const session of activeSessions) {
+    await appendToArchive(todayDate, session, { skipLLM: true }) // public thrift: no surprise LLM spend on a manual snapshot
+    archived++
+  }
+
+  res.json({ archived, date: todayDate })
+})
+
+// GET /api/archive/:date — full daily archive
+archiveRouter.get('/archive/:date', (req, res) => {
+  const archive = loadArchive(req.params.date)
+  if (!archive) {
+    res.status(404).json({ error: 'Archive not found for date' })
+    return
+  }
+  res.json(archive)
+})
+
+// GET /api/archive/:date/chats — chat summaries for a day
+archiveRouter.get('/archive/:date/chats', (req, res) => {
+  const chats = getArchiveChats(req.params.date)
+  res.json({ chats })
+})
+
+// GET /api/archive/:date/chats/:index/messages — paired Q&A for a specific chat
+archiveRouter.get('/archive/:date/chats/:index/messages', (req, res) => {
+  const index = parseInt(req.params.index, 10)
+  if (isNaN(index)) {
+    res.status(400).json({ error: 'Invalid chat index' })
+    return
+  }
+  // v5.15.1 — numbered form so the browser can show the durable Msg #N
+  const messages = getArchiveChatMessagesNumbered(req.params.date, index)
+  res.json({ messages })
+})
+
+// GET /api/archive/:date/messages — all messages for a day (flat)
+archiveRouter.get('/archive/:date/messages', (req, res) => {
+  const messages = getArchiveDayMessages(req.params.date)
+  res.json({ messages })
+})

package/server/routes/message-ref.ts

@@ -0,0 +1,190 @@
+// Global message reference resolution (v5.15.0) — the server half of
+// "reference message N" across days. Numbers are stamped at exchange time
+// (client-sent, stored via conversation.addExchange) and persist durably in
+// the day archives; this router resolves a number the client no longer holds
+// in its local list, and publishes the numbering ceiling so a cleared or
+// fresh client continues the sequence instead of reusing numbers.
+//
+//   GET /api/message/:num     → { globalMsgNum, date, query, response }  (404 when unknown)
+//   GET /api/message-counter  → { max }
+//
+// Resolution order (per the prompt-queue/archive plan): live in-memory
+// sessions first (covers the mirror's 15-minute lag), then day archives
+// newest-first. Day files are read as plain data — their write path belongs
+// to the archive workstream and is not touched here.
+import { Router } from 'express'
+import { readdirSync, readFileSync } from 'fs'
+import { resolve } from 'path'
+import { getActiveSessions } from '../lib/conversation.js'
+import { dataPath } from '../lib/data-dir.js'
+import { localDay } from '../lib/local-day.js'
+
+// v6.3.0 — read archives from the SAME persistent location the archive-mirror
+// writes to (~/.cos-glasses/data/archive via dataPath), not a package-relative
+// dir. The app repo uses server/data/archive; the public package uses dataPath,
+// so this file must match the package's lib/archive.ts, or npx users' cross-day
+// references + archive-chat detail read an empty/nonexistent directory.
+const ARCHIVE_DIR = dataPath('archive')
+
+export interface ResolvedGlobalMessage {
+  globalMsgNum: number
+  date: string
+  query: string
+  response: string
+}
+
+interface ExchangeLike {
+  role?: string
+  content?: string
+  timestamp?: number
+  globalMsgNum?: number
+}
+
+/** Pair the stamped exchange with its other half: a user turn pairs forward
+ *  to the next assistant turn; an assistant turn pairs backward. */
+function pairExchange(exchanges: ExchangeLike[], i: number): { query: string; response: string } {
+  const hit = exchanges[i]
+  const user = hit.role === 'user'
+    ? hit
+    : [...exchanges.slice(0, i)].reverse().find((e) => e?.role === 'user')
+  const assistant = hit.role === 'assistant'
+    ? hit
+    : exchanges.slice(i + 1).find((e) => e?.role === 'assistant')
+  return { query: user?.content ?? '', response: assistant?.content ?? '' }
+}
+
+function scanExchanges(exchanges: ExchangeLike[], num: number, date: string): ResolvedGlobalMessage | null {
+  for (let i = 0; i < exchanges.length; i++) {
+    if (exchanges[i]?.globalMsgNum !== num) continue
+    const { query, response } = pairExchange(exchanges, i)
+    return { globalMsgNum: num, date, query, response }
+  }
+  return null
+}
+
+/** Resolve a global message number from the day archives, newest-first.
+ *  Exported with an explicit dir for tests. */
+export function resolveFromArchiveDir(dir: string, num: number): ResolvedGlobalMessage | null {
+  let files: string[] = []
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f)).sort().reverse()
+  } catch {
+    return null
+  }
+  for (const f of files) {
+    try {
+      const day = JSON.parse(readFileSync(resolve(dir, f), 'utf8'))
+      const chats = Array.isArray(day?.chats) ? day.chats : []
+      for (const chat of chats) {
+        const exchanges = Array.isArray(chat?.exchanges) ? chat.exchanges : []
+        const hit = scanExchanges(exchanges, num, typeof day?.date === 'string' ? day.date : f.slice(0, 10))
+        if (hit) return hit
+      }
+    } catch {
+      // Unreadable/corrupt day file — skip; the archive workstream owns repair.
+    }
+  }
+  return null
+}
+
+/** Read a specific archived chat's paired Q&A messages WITH their durable
+ *  global numbers (the archive-lib read path strips globalMsgNum; the browser
+ *  needs it so "reference message N" is self-evident from the screen). Same
+ *  user->next-assistant pairing as the lib; the pair's number is the user
+ *  turn's stamp (falling back to the assistant's). Dir-param form for tests. */
+export function readArchiveChatNumbered(
+  dir: string,
+  date: string,
+  chatIndex: number,
+): Array<{ query: string; text: string; timestamp: number; no?: number }> {
+  // Defense-in-depth against path traversal — `date` builds a `${date}.json`
+  // path. The archive route also validates, but this is exported/reused.
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return []
+  let day: { chats?: Array<{ id?: number; exchanges?: ExchangeLike[] }> }
+  try {
+    day = JSON.parse(readFileSync(resolve(dir, `${date}.json`), 'utf8'))
+  } catch {
+    return []
+  }
+  const chat = (Array.isArray(day?.chats) ? day.chats : []).find((c) => c?.id === chatIndex)
+  if (!chat) return []
+  const exchanges: ExchangeLike[] = Array.isArray(chat.exchanges) ? chat.exchanges : []
+  const out: Array<{ query: string; text: string; timestamp: number; no?: number }> = []
+  for (let i = 0; i < exchanges.length; i++) {
+    const ex = exchanges[i]
+    if (ex?.role !== 'user') continue
+    const next = exchanges[i + 1]
+    if (next?.role !== 'assistant') continue
+    out.push({
+      query: ex.content ?? '',
+      text: next.content ?? '',
+      timestamp: next.timestamp ?? ex.timestamp ?? 0,
+      no: ex.globalMsgNum ?? next.globalMsgNum,
+    })
+    i++
+  }
+  return out
+}
+
+/** ARCHIVE_DIR-bound form for the route. */
+export function getArchiveChatMessagesNumbered(date: string, chatIndex: number) {
+  return readArchiveChatNumbered(ARCHIVE_DIR, date, chatIndex)
+}
+
+/** Highest stamped number across the day archives (0 when none). */
+export function maxGlobalMsgNumInDir(dir: string): number {
+  let max = 0
+  let files: string[] = []
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f))
+  } catch {
+    return 0
+  }
+  for (const f of files) {
+    try {
+      const day = JSON.parse(readFileSync(resolve(dir, f), 'utf8'))
+      for (const chat of Array.isArray(day?.chats) ? day.chats : []) {
+        for (const ex of Array.isArray(chat?.exchanges) ? chat.exchanges : []) {
+          if (typeof ex?.globalMsgNum === 'number' && ex.globalMsgNum > max) max = ex.globalMsgNum
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return max
+}
+
+function resolveFromLiveSessions(num: number): ResolvedGlobalMessage | null {
+  const today = localDay() // local calendar day, not UTC — a live ref in the user's evening must not label tomorrow
+  for (const session of getActiveSessions()) {
+    const exchanges = (session as { exchanges?: ExchangeLike[] }).exchanges ?? []
+    const hit = scanExchanges(exchanges, num, today)
+    if (hit) return hit
+  }
+  return null
+}
+
+export const messageRefRouter = Router()
+
+messageRefRouter.get('/message/:num', (req, res) => {
+  const num = Number.parseInt(req.params.num, 10)
+  if (!Number.isFinite(num) || num < 1) {
+    res.status(400).json({ error: 'invalid message number' })
+    return
+  }
+  const hit = resolveFromLiveSessions(num) ?? resolveFromArchiveDir(ARCHIVE_DIR, num)
+  if (!hit) {
+    res.status(404).json({ error: `message ${num} not found` })
+    return
+  }
+  res.json(hit)
+})
+
+messageRefRouter.get('/message-counter', (_req, res) => {
+  let liveMax = 0
+  for (const session of getActiveSessions()) {
+    for (const ex of ((session as { exchanges?: ExchangeLike[] }).exchanges ?? [])) {
+      if (typeof ex?.globalMsgNum === 'number' && ex.globalMsgNum > liveMax) liveMax = ex.globalMsgNum
+    }
+  }
+  res.json({ max: Math.max(liveMax, maxGlobalMsgNumInDir(ARCHIVE_DIR)) })
+})

package/server/routes/openai-compat.ts

@@ -6,7 +6,7 @@
 import { Router } from 'express'
 import { preWarmCLI, logLatency } from '../lib/claude-bridge.js'
 import { callModelStreaming } from '../lib/model-router.js'
-import { normalizeModelPreference, type ModelPreference } from '../../shared/model-preference.js'
+import { normalizeModelPreference, DEFAULT_MODEL, type ModelPreference } from '../../shared/model-preference.js'
 import { tryInstantResponse } from '../lib/response-cache.js'
 import crypto from 'node:crypto'
 
@@ -79,7 +79,7 @@ function resolveModel(model?: string, _query?: string): ModelPreference {
   if (model === 'cos-sonnet') return 'sonnet'
   if (model === 'cos-haiku') return 'haiku'
   if (model === 'cos-codex-high' || model === 'cos-codex') return 'codex-high'
-  return normalizeModelPreference(process.env.COS_G2_DEFAULT_MODEL) ?? 'haiku'
+  return normalizeModelPreference(process.env.COS_G2_DEFAULT_MODEL) ?? DEFAULT_MODEL
 }
 
 const MODEL_NAMES: Record<ModelPreference, string> = {

package/server/routes/sessions.ts

@@ -0,0 +1,270 @@
+// Session endpoints — recent list, full history, existence check, client-format messages, context breaks, end
+import { Router } from 'express'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { getRecentSessions, getHistory, sessionExists, addContextBreak, endSession, getSessionRaw, getActiveSessions } from '../lib/conversation.js'
+import { buildSessionLogEntry, writeSessionLog } from '../lib/session-log.js'
+import { getArchiveDayMessages } from '../lib/archive.js'
+import { localDay } from '../lib/local-day.js'
+import { clearCodexEngineSession } from '../lib/codex-engine-sessions.js'
+
+export const sessionsRouter = Router()
+
+sessionsRouter.get('/sessions/recent', (_req, res) => {
+  const sessions = getRecentSessions(24 * 60 * 60_000)
+  res.json({ sessions })
+})
+
+// HEAD /api/sessions/:id — lightweight existence check for restore validation
+sessionsRouter.head('/sessions/:id', (req, res) => {
+  res.status(sessionExists(req.params.id) ? 200 : 404).end()
+})
+
+// GET /api/sessions/:id/history — full exchange list for session resume
+sessionsRouter.get('/sessions/:id/history', (req, res) => {
+  const exchanges = getHistory(req.params.id)
+  if (exchanges.length === 0) {
+    res.status(404).json({ error: 'Session not found or empty' })
+    return
+  }
+  res.json({ exchanges })
+})
+
+// POST /api/sessions/:id/context-break — insert a context break (prompt history gate)
+sessionsRouter.post('/sessions/:id/context-break', (req, res) => {
+  const ok = addContextBreak(req.params.id)
+  if (!ok) {
+    res.status(404).json({ error: 'Session not found' })
+    return
+  }
+  res.json({ ok: true })
+})
+
+// GET /api/sessions/:id/messages — client-compatible format (paired Q&A)
+sessionsRouter.get('/sessions/:id/messages', (req, res) => {
+  const exchanges = getHistory(req.params.id)
+  if (exchanges.length === 0) {
+    res.status(404).json({ error: 'Session not found or empty' })
+    return
+  }
+
+  // Pair user+assistant exchanges into client message format
+  const messages: Array<{ query: string; text: string; timestamp: number }> = []
+  for (let i = 0; i < exchanges.length; i++) {
+    const ex = exchanges[i]
+    if (ex.role === 'user') {
+      const next = exchanges[i + 1]
+      if (next && next.role === 'assistant') {
+        messages.push({ query: ex.content, text: next.content, timestamp: next.timestamp })
+        i++ // skip the assistant exchange
+      }
+    }
+  }
+
+  res.json({ messages })
+})
+
+// POST /api/sessions/:id/end — Explicitly end a session (archive + log + notify)
+// Called by client on "new session", "clear session", or app backgrounding.
+// Prevents data loss — session gets logged to .glasses_sessions.jsonl immediately
+// instead of waiting for the 2hr TTL expiry.
+// POST /api/sessions/lookup — batch resolve timestamps to session IDs
+// Used to retroactively stamp messages that predate the sessionId feature
+sessionsRouter.post('/sessions/lookup', (req, res) => {
+  const { timestamps } = req.body as { timestamps: number[] }
+  if (!timestamps || !Array.isArray(timestamps)) {
+    res.status(400).json({ error: 'timestamps[] required' })
+    return
+  }
+
+  // Build time ranges from BOTH JSONL history AND live server sessions
+  const logPath = join(process.env.COS_SCRIPTS_DIR || '', '.glasses_sessions.jsonl')
+  const sessionRanges: Array<{ sid: string; start: number; end: number }> = []
+
+  // 1. Live server sessions (always current — no snapshot lag)
+  const recentSessions = getRecentSessions(24 * 60 * 60_000)
+  for (const rs of recentSessions) {
+    const raw = getSessionRaw(rs.id)
+    if (raw) {
+      sessionRanges.push({ sid: raw.id, start: raw.createdAt, end: Date.now() }) // extends to NOW
+    }
+  }
+
+  // 2. JSONL history (ended sessions + snapshots)
+  try {
+    const lines = readFileSync(logPath, 'utf-8').trim().split('\n')
+    for (const line of lines) {
+      const d = JSON.parse(line)
+      if (d.session_id && d.created_at) {
+        const start = new Date(d.created_at).getTime()
+        const end = d.ended_at ? new Date(d.ended_at).getTime() : start + 7200_000
+        // Live sessions take priority. For JSONL, keep the widest (latest) time range per session.
+        const existing = sessionRanges.find(s => s.sid === d.session_id)
+        if (!existing) {
+          sessionRanges.push({ sid: d.session_id, start, end })
+        } else if (end > existing.end && !getSessionRaw(d.session_id)) {
+          // Widen the JSONL range (but don't overwrite live sessions which extend to NOW)
+          existing.end = end
+        }
+      }
+    }
+  } catch { /* no log file */ }
+
+  // Match each timestamp to a session (live sessions checked first, then JSONL)
+  const results: Record<number, string | null> = {}
+  for (const ts of timestamps) {
+    let match: string | null = null
+    for (const s of sessionRanges) {
+      if (ts >= s.start && ts <= s.end) {
+        match = s.sid
+        break
+      }
+    }
+    results[ts] = match
+  }
+
+  res.json({ results, sessionsScanned: sessionRanges.length })
+})
+
+sessionsRouter.post('/sessions/:id/end', async (req, res) => {
+  try {
+    const result = await endSession(req.params.id)
+    if (!result) {
+      res.status(404).json({ error: 'Session not found' })
+      return
+    }
+    // When logged === false the archive write failed — we keep the session
+    // in the Map for the next mirror to retry, but signal 503 so the client
+    // knows NOT to wipe local messages (they're still the user's only copy).
+    if (!result.logged && result.exchangeCount > 0) {
+      res.status(503).json({
+        ok: false,
+        error: 'Archive write failed — session retained for retry',
+        exchange_count: result.exchangeCount,
+        duration_minutes: result.durationMin,
+      })
+      return
+    }
+    clearCodexEngineSession(req.params.id)
+    res.json({
+      ok: true,
+      logged: result.logged,
+      exchange_count: result.exchangeCount,
+      duration_minutes: result.durationMin,
+    })
+  } catch (err) {
+    console.error('[sessions] /end unexpected error:', err)
+    res.status(500).json({ error: String(err) })
+  }
+})
+
+// POST /api/sessions/:id/snapshot — write live session to .glasses_sessions.jsonl WITHOUT ending it
+// Enables M3 Ultra TUI to read current glasses conversation while session is still active
+sessionsRouter.post('/sessions/:id/snapshot', (req, res) => {
+  const session = getSessionRaw(req.params.id)
+  if (!session) {
+    res.status(404).json({ error: 'Session not found' })
+    return
+  }
+
+  const entry = buildSessionLogEntry({
+    id: session.id,
+    exchanges: session.exchanges,
+    createdAt: session.createdAt,
+    lastActivity: session.lastActivity,
+    modelPreference: session.modelPreference,
+    endReason: 'explicit_end', // marker — will be overwritten when session actually ends
+    slug: `[LIVE] ${(session.exchanges.find(e => e.role === 'user')?.content ?? '').slice(0, 50)}`,
+  })
+
+  const logged = writeSessionLog(entry)
+  res.json({
+    ok: true,
+    logged,
+    session_id: session.id,
+    message_count: entry.total_message_count,
+    messages_logged: entry.messages.length,
+  })
+})
+
+// GET /api/sessions/today/live-chats — live session chat summaries for today (not yet archived).
+// Date compare is LOCAL time so users chatting in CDT/PST late evening still see their
+// session under "today" instead of "tomorrow UTC".
+// Each summary includes `sessionId` so the client can drill down via
+// `/api/sessions/:id/messages` — index=-1 is a sentinel and is NOT a valid archive chat index.
+sessionsRouter.get('/sessions/today/live-chats', (_req, res) => {
+  const todayDate = localDay()
+  const liveSessions = getActiveSessions()
+  const chats: Array<{ index: number; summary: string; exchangeCount: number; startedAt: number; isLive: boolean; sessionId: string }> = []
+
+  for (const session of liveSessions) {
+    const sessionDay = localDay(session.lastActivity)
+    if (sessionDay !== todayDate) continue
+    if (session.exchanges.length === 0) continue
+
+    const firstQuery = session.exchanges.find(e => e.role === 'user')?.content ?? ''
+    const summary = firstQuery.length > 57 ? firstQuery.slice(0, 54) + '...' : firstQuery || 'Live session'
+
+    chats.push({
+      index: -1,
+      summary: `[LIVE] ${summary}`,
+      exchangeCount: session.exchanges.length,
+      startedAt: session.createdAt,
+      isLive: true,
+      sessionId: session.id,
+    })
+  }
+
+  res.json({ chats })
+})
+
+// GET /api/sessions/today/all-messages — merged view of today's archived + live session messages.
+// Dedup key is `sessionId|timestamp` (was bare timestamp, which collided on NTP skew or
+// same-ms adds). `sessionId` is always known for live exchanges; archive messages fall
+// back to the archived chat's sessionId via getArchiveDayMessages.
+sessionsRouter.get('/sessions/today/all-messages', (_req, res) => {
+  const todayDate = localDay()
+
+  const archivedMessages = getArchiveDayMessages(todayDate).map(m => ({
+    ...m,
+    source: 'archive' as const,
+  }))
+
+  const liveMessages: Array<{ query: string; text: string; timestamp: number; chatIndex: number; sessionId: string; source: 'live' }> = []
+  const liveSessions = getActiveSessions()
+  for (const session of liveSessions) {
+    const sessionDay = localDay(session.lastActivity)
+    if (sessionDay !== todayDate) continue
+    for (let i = 0; i < session.exchanges.length; i++) {
+      const ex = session.exchanges[i]
+      if (ex.role === 'user') {
+        const next = session.exchanges[i + 1]
+        if (next && next.role === 'assistant') {
+          liveMessages.push({
+            query: ex.content,
+            text: next.content,
+            timestamp: next.timestamp,
+            chatIndex: -1,
+            sessionId: session.id,
+            source: 'live',
+          })
+          i++
+        }
+      }
+    }
+  }
+
+  // Merge, dedup by (sessionId, timestamp), sort chronologically.
+  const seen = new Set<string>()
+  const keyOf = (m: { sessionId?: string; timestamp: number }) => `${m.sessionId ?? ''}|${m.timestamp}`
+  const merged = [...archivedMessages, ...liveMessages]
+    .filter(m => {
+      const k = keyOf(m as any)
+      if (seen.has(k)) return false
+      seen.add(k)
+      return true
+    })
+    .sort((a, b) => a.timestamp - b.timestamp)
+
+  res.json({ messages: merged, date: todayDate })
+})

package/server/routes/transcribe-stream.ts

@@ -1170,11 +1170,16 @@ transcribeStreamRouter.post('/transcribe-stream/offline-sessions/:sessionId/fina
     const chunks = getSessionChunks(sessionId)
     if (!chunks || chunks.length === 0) throw makeHttpError(404, 'offline session has no chunks', 'session_not_found')
     await drainSessionAudioWrites(sessionId)
-    const transcript = getSessionTranscript(sessionId) ?? ''
+    // Gap-aware assembly: chunks lost in transit surface as inline
+    // "[… audio gap …]" markers instead of being silently stitched over.
+    const transcript = getSessionTranscript(sessionId, { withGaps: true }) ?? ''
+    const transferIntegrity = analyzeTranscriptGaps(sessionId)
     res.json({
       sessionId,
       chunks: chunks.length,
       transcriptChars: transcript.length,
+      transcript,
+      transferIntegrity,
       readyToSave: true,
     })
   } catch (err: unknown) {

package/shared/model-preference.ts

@@ -2,7 +2,7 @@ export type ClaudeModelPreference = 'opus' | 'sonnet' | 'haiku'
 export type CodexModelPreference = 'codex-high'
 export type ModelPreference = ClaudeModelPreference | CodexModelPreference
 
-export const DEFAULT_MODEL = 'opus' as const
+export const DEFAULT_MODEL = 'sonnet' as const
 export const CODEX_HIGH_MODEL: CodexModelPreference = 'codex-high'
 
 // Optional codex model passed to `codex exec --model`. Empty (the default) means