@gotcos/glasses-server 6.5.0 → 6.6.0

package/.env.example

@@ -23,6 +23,11 @@ BIND_HOST=0.0.0.0
 # ~/.cos-glasses/data/media alongside the standalone conversation/archive data.
 # COS_MEDIA_ROOT=/path/on-a-local-volume/media
 
+# Optional logical server identity location. Most installs should keep the
+# default (~/.cos-glasses/server-instance-id) so reconnects can verify the same
+# server after Wi-Fi/Tailscale changes and process restarts.
+# COS_SERVER_INSTANCE_ID_PATH=/path/to/server-instance-id
+
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
 #   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 6.6.0
+
+Reconnect compatibility for COS Glasses build 188, without importing private
+COS day-context or Mac service-control behavior into the public package.
+
+- **Stable logical server identity.** The server creates one atomic UUID under
+  `~/.cos-glasses/server-instance-id`, preserves it across process and network
+  restarts, and returns it from authenticated `/api/models` probes. Files are
+  mode `0600`; identity is minted only after every required listener binds.
+- **Boot-scoped display cursors.** Display events receive one publish-owned ID
+  before fan-out, so multiple subscribers see the same cursor and cannot
+  duplicate replay records. Each process boot has a distinct UUID.
+- **Deterministic reconnect handshake.** `/api/display-stream` emits `ready`
+  before application events, accepts boot/event cursors, replays the last 200
+  publish-owned events, and reports typed `boot_changed`, `cursor_ahead`, or
+  `buffer_overflow` gaps so clients reconcile durable history instead of
+  guessing or silently dropping replies.
+- **Privacy boundary preserved.** Authenticated query activity remains off the
+  unauthenticated global display bus. The npm server does not include private
+  daily evidence exports, personal COS paths, launchd ownership, or remote
+  machine-restart controls.
+- **Backward compatible.** Older clients can continue opening the same SSE
+  endpoint and ignoring the additive `ready`, cursor metadata, and replay-gap
+  events.
+
 ## 6.5.0
 
 Durable phone photos and assistant-selected output images for COS Glasses

package/README.md

@@ -16,7 +16,10 @@ downloads the local voice model when needed, writes `~/.cos-glasses/.env`, and
 starts the server on `0.0.0.0:3141`. On boot it prints
 an **API token** — paste that into the COS Glasses app. Only one COS Glasses
 server may run on a Mac at a time; a second `npx` or source runner exits before
-opening ports or touching shared conversation/media state.
+opening ports or touching shared conversation/media state. Version 6.6.0 also
+gives that server a durable identity and boot-scoped display replay, allowing
+build 188+ to reconnect after a Tailscale, Wi-Fi, or process interruption
+without silently losing completed replies.
 
 ## Requirements
 
@@ -87,6 +90,7 @@ BIND_HOST=0.0.0.0 npm run start:server
 ## Troubleshooting
 
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
+- *Safari connects but the app does not* — confirm `npx @gotcos/glasses-server@latest` is 6.6.0+, then use the app's server reconnect/edit control to verify the current URL and token. Do not run a second source or `npx` server alongside it.
 - *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
 - *Voice getting billed?* — install `whisper-cpp` for free local transcription.
 - *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "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

@@ -38,6 +38,8 @@ import { initSpeakerEmbeddings } from './lib/speaker-embeddings.js'
 import { logActiveSessionsOnShutdown, startAutoSnapshot } from './lib/conversation.js'
 import { getMediaStore } from './lib/media-store.js'
 import { listenRequiredServers, type RequiredListener } from './lib/listener-startup.js'
+import { serverMetrics } from './lib/server-metrics.js'
+import { initializeServerInstanceId } from './lib/server-instance-id.js'
 
 const app = express()
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -69,12 +71,6 @@ if (API_TOKEN_AUTO) {
   } catch { /* read-only home — token stays per-session */ }
 }
 
-// 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.
@@ -218,10 +214,12 @@ const httpServer = createHttpServer(app)
 listeners.push({ server: httpServer, port: PORT, host: BIND_HOST, label: 'HTTP' })
 
 listenRequiredServers(listeners).then(() => {
+  const serverInstanceId = initializeServerInstanceId()
   if (listeners.some(listener => listener.label === 'HTTPS')) {
     console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
   }
   console.log(`[COS API] HTTP server running on http://${BIND_HOST}:${PORT}`)
+  console.log(`[COS API] Server instance: ${serverInstanceId}`)
   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

package/server/lib/display-bus.ts

@@ -2,6 +2,7 @@
 // to all connected glasses clients (SSE display-stream subscribers)
 
 import { EventEmitter } from 'node:events'
+import { serverMetrics } from './server-metrics.js'
 
 const bus = new EventEmitter()
 bus.setMaxListeners(20) // Multiple glasses clients
@@ -11,11 +12,68 @@ export interface DisplayEvent {
   data: Record<string, unknown>
 }
 
-export function emitDisplay(event: DisplayEvent): void {
-  bus.emit('display', event)
+export interface PublishedDisplayEvent extends DisplayEvent {
+  bootId: string
+  eventId: number
+  publishedAt: string
 }
 
-export function onDisplay(listener: (event: DisplayEvent) => void): () => void {
+export interface DisplayReplayResult {
+  events: PublishedDisplayEvent[]
+  gap: boolean
+  reason?: 'boot_changed' | 'cursor_ahead' | 'buffer_overflow'
+  oldestEventId: number
+  latestEventId: number
+}
+
+const REPLAY_BUFFER_SIZE = 200
+let eventId = 0
+const replayBuffer: PublishedDisplayEvent[] = []
+
+export function emitDisplay(event: DisplayEvent): PublishedDisplayEvent {
+  const published: PublishedDisplayEvent = {
+    ...event,
+    bootId: serverMetrics.bootId,
+    eventId: ++eventId,
+    publishedAt: new Date().toISOString(),
+  }
+  replayBuffer.push(published)
+  if (replayBuffer.length > REPLAY_BUFFER_SIZE) replayBuffer.shift()
+  bus.emit('display', published)
+  return published
+}
+
+export function onDisplay(listener: (event: PublishedDisplayEvent) => void): () => void {
   bus.on('display', listener)
   return () => { bus.off('display', listener) }
 }
+
+export function getDisplayWatermark(): { bootId: string; eventId: number } {
+  return { bootId: serverMetrics.bootId, eventId }
+}
+
+export function replayDisplayEvents(bootId: string | null, afterEventId: number): DisplayReplayResult {
+  const oldestEventId = replayBuffer[0]?.eventId ?? eventId + 1
+  const latestEventId = eventId
+  if (bootId && bootId !== serverMetrics.bootId) {
+    return { events: [], gap: true, reason: 'boot_changed', oldestEventId, latestEventId }
+  }
+  if (afterEventId > latestEventId) {
+    return { events: [], gap: true, reason: 'cursor_ahead', oldestEventId, latestEventId }
+  }
+  if (afterEventId > 0 && afterEventId < oldestEventId - 1) {
+    return { events: [], gap: true, reason: 'buffer_overflow', oldestEventId, latestEventId }
+  }
+  return {
+    events: replayBuffer.filter(item => item.eventId > afterEventId),
+    gap: false,
+    oldestEventId,
+    latestEventId,
+  }
+}
+
+export function __resetDisplayBusForTests(): void {
+  eventId = 0
+  replayBuffer.splice(0)
+  bus.removeAllListeners('display')
+}

package/server/lib/server-instance-id.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto'
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+let initializedId: string | null = null
+
+export function defaultServerInstanceIdPath(): string {
+  return process.env.COS_SERVER_INSTANCE_ID_PATH
+    ?? join(homedir(), '.cos-glasses', 'server-instance-id')
+}
+
+/**
+ * Initialize only after every required listener binds. A failed or half-bound
+ * process must not mint an identity that a client later trusts as healthy.
+ */
+export function initializeServerInstanceId(path = defaultServerInstanceIdPath()): string {
+  if (initializedId) return initializedId
+
+  try {
+    const existing = readFileSync(path, 'utf8').trim()
+    if (UUID_RE.test(existing)) {
+      chmodSync(path, 0o600)
+      initializedId = existing
+      return existing
+    }
+  } catch {
+    // Missing or invalid state is replaced atomically below.
+  }
+
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const id = randomUUID()
+  const tmp = `${path}.tmp-${process.pid}-${randomUUID()}`
+  writeFileSync(tmp, `${id}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' })
+  renameSync(tmp, path)
+  chmodSync(path, 0o600)
+  initializedId = id
+  return id
+}
+
+export function getServerInstanceId(): string | null {
+  return initializedId
+}
+
+export function __resetServerInstanceIdForTests(): void {
+  initializedId = null
+}

package/server/lib/server-metrics.ts

@@ -0,0 +1,7 @@
+import { randomUUID } from 'node:crypto'
+
+export const serverMetrics = {
+  bootId: randomUUID(),
+  startedAt: Date.now(),
+  requestCount: 0,
+}

package/server/routes/display.ts

@@ -2,15 +2,28 @@
 // Any connected glasses client receives real-time query responses
 // regardless of which interface submitted the query
 
-import { Router } from 'express'
-import { onDisplay, emitDisplay } from '../lib/display-bus.js'
+import { Router, type Response } from 'express'
+import {
+  emitDisplay,
+  getDisplayWatermark,
+  onDisplay,
+  replayDisplayEvents,
+  type PublishedDisplayEvent,
+} from '../lib/display-bus.js'
 
 export const displayRouter = Router()
 
-// Replay buffer — last N events so reconnecting clients don't miss in-flight data
-const REPLAY_BUFFER_SIZE = 20
-let eventId = 0
-const replayBuffer: Array<{ id: number; type: string; data: string }> = []
+function writeEvent(res: Response, event: PublishedDisplayEvent): void {
+  const data = JSON.stringify({
+    ...event.data,
+    _cosDisplayCursor: {
+      bootId: event.bootId,
+      eventId: event.eventId,
+      publishedAt: event.publishedAt,
+    },
+  })
+  res.write(`id: ${event.bootId}:${event.eventId}\nevent: ${event.type}\ndata: ${data}\n\n`)
+}
 
 displayRouter.get('/display-stream', (req, res) => {
   res.writeHead(200, {
@@ -25,15 +38,29 @@ displayRouter.get('/display-stream', (req, res) => {
   // Tell EventSource to retry quickly on disconnect (3s instead of browser default ~5-10s)
   res.write('retry: 3000\n\n')
 
-  // Replay missed events if client sends Last-Event-ID (browser does this automatically)
-  const lastId = parseInt(req.headers['last-event-id'] as string, 10)
-  if (!isNaN(lastId) && lastId > 0) {
-    const missed = replayBuffer.filter(e => e.id > lastId)
-    for (const e of missed) {
-      res.write(`id: ${e.id}\nevent: ${e.type}\ndata: ${e.data}\n\n`)
-    }
-    if (missed.length > 0) {
-      console.log(`[display-bus] Replayed ${missed.length} events for reconnecting client (from id ${lastId})`)
+  const headerCursor = String(req.headers['last-event-id'] ?? '')
+  const [headerBootId, headerEventId] = headerCursor.includes(':')
+    ? headerCursor.split(':', 2)
+    : ['', headerCursor]
+  const cursorBootId = String(req.query.bootId ?? headerBootId ?? '') || null
+  const cursorEventId = Number(req.query.eventId ?? headerEventId ?? 0)
+  const replay = replayDisplayEvents(cursorBootId, Number.isFinite(cursorEventId) ? cursorEventId : 0)
+
+  // Ready is a transport handshake, not proof that replay was consumed. It
+  // must precede application events so build 188 can finish admission first.
+  const watermark = getDisplayWatermark()
+  res.write(`event: ready\ndata: ${JSON.stringify(watermark)}\n\n`)
+  if (replay.gap) {
+    res.write(`event: replay_gap\ndata: ${JSON.stringify({
+      reason: replay.reason,
+      requested: { bootId: cursorBootId, eventId: cursorEventId },
+      watermark,
+      oldestEventId: replay.oldestEventId,
+    })}\n\n`)
+  } else {
+    for (const event of replay.events) writeEvent(res, event)
+    if (replay.events.length > 0) {
+      console.log(`[display-bus] Replayed ${replay.events.length} publish-owned events after ${cursorEventId}`)
     }
   }
 
@@ -43,13 +70,7 @@ displayRouter.get('/display-stream', (req, res) => {
   }, 15_000)
 
   const unsub = onDisplay((event) => {
-    eventId++
-    const data = JSON.stringify(event.data)
-    // Buffer for replay
-    replayBuffer.push({ id: eventId, type: event.type, data })
-    if (replayBuffer.length > REPLAY_BUFFER_SIZE) replayBuffer.shift()
-    // Send with id for Last-Event-ID tracking
-    try { res.write(`id: ${eventId}\nevent: ${event.type}\ndata: ${data}\n\n`) } catch { /* client gone */ }
+    try { writeEvent(res, event) } catch { /* client gone */ }
   })
 
   req.on('close', () => {

package/server/routes/health.ts

@@ -3,7 +3,8 @@ import { execFile } from 'node:child_process'
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { COS_SCRIPTS_DIR, COS_MODE, PYTHON_BIN } from '../lib/python-bridge.js'
-import { serverMetrics } from '../index.js'
+import { serverMetrics } from '../lib/server-metrics.js'
+import { getServerInstanceId } from '../lib/server-instance-id.js'
 import { isSileroAvailable } from '../lib/vad-silero.js'
 import { getAvailableCliSessionId } from '../lib/claude-bridge.js'
 import { isWhisperLocalAvailable, getWhisperHealth } from '../lib/whisper-local.js'
@@ -133,7 +134,7 @@ healthRouter.get('/health', async (_req, res) => {
 // authenticated by the global /api middleware; ?refresh=1 forces discovery.
 healthRouter.get('/models', async (req, res) => {
   const catalog = await getCodexModelCatalog(req.query.refresh === '1')
-  res.json(catalog)
+  res.json({ ...catalog, serverInstanceId: getServerInstanceId() })
 })
 
 // GET /api/cli-session — returns current CLI session ID for cross-device resume