@gotcos/glasses-server 6.23.1 → 6.24.0

package/CHANGELOG.md

@@ -1,3 +1,88 @@
+## 6.24.0
+
+The Sessions tab stops 404ing, and a read-only presence view of Claude Code
+sessions on this Mac arrives behind a flag.
+
+- **`/api/session-index` was never ported into the published package.** The route
+  lives in the private app repo and is mounted there; the companion has been calling
+  it and getting an Express HTML 404 since the managed-runtime cutover. Same class as
+  the stranded voice profiles, the npmignore-excluded speaker model and the stranded
+  `.cos-profile.json`.
+- **Ported rather than retired, against the original recommendation.**
+  `/api/sessions/recent` looked like a duplicate and is not: it reads an IN-MEMORY map
+  on a 24-hour window, carries no `domain` and no `device_id`, gives `lastQuery` where
+  the companion wants `first_prompt`, dies on restart, and has no counterpart at all
+  for the detail view's `tools_used`, `files_touched`, `git_branch` and token counts.
+  `lib/session-cache-writer.ts` already writes the disk cache, so only the reader was
+  missing.
+- **Four defects fixed in the port, all measured on the real 37,700-entry cache.**
+  An unset `COS_SCRIPTS_DIR` returned `[]` — a 200 that reads as "you have no
+  sessions" on every standalone install — now 503 with `reason: pythonBridgeState()`.
+  `err.message` leaked filesystem paths; now a generic reason, detail to the log.
+  31.7 MB was parsed synchronously per request, the detail endpoint included, on a
+  process that also streams live audio; now async and cached against file identity
+  (161ms cold, 15ms warm). And the filename filter matched iCloud sync-conflict
+  duplicates: `.session_index_cache_Ukaoma-Mac-Studio 3.json` shared 543 of its 602
+  rows with the canonical file, so the merged list served 543 duplicates. Verified on
+  real data: 37,700 naive becomes 37,157 served, exactly 543 removed. Filtering ` N`
+  filenames would have been wrong in the other direction, since ` 2.json` holds 245
+  rows appearing nowhere else, so dedupe is by session_id with newest winning.
+- **New `GET /api/claude-sessions`, off unless `COS_CLAUDE_SESSIONS_ENABLED=1`.**
+  It projects another product's 0700 state directory over a socket bound to 0.0.0.0
+  behind a private-network allowlist, so in a published package that has to be opt-in.
+  Named `claude-sessions` rather than `peers` because COS already overloads "session"
+  three ways and the glasses, phone and server are all arguably peers.
+- **Redaction is decided by `nameSource`, and only `derived` passes.** `auto` means an
+  LLM wrote the label FROM THE WORK, and `/rename` clears the field entirely, so a
+  missing `nameSource` is a renamed session rather than a derived one. Anything but an
+  exact `derived` is replaced with the recomputed folder name and flagged
+  `nameRedacted`. Echoing `name` while redacting `cwd` would not have been redaction.
+- **Reachability is a conjunction: alive AND a declared socket path AND that file
+  present.** Each alone is a false positive. Verified live: the 2.1.222 row reports
+  `reachable: false` for having no socket path, and `/tmp/cc-socks` holds an orphaned
+  `.sock` whose pid is dead and whose registry file is already gone, because sockets
+  are not reaped. Liveness is a signal 0, never inferred from mtime, and EPERM
+  resolves to false rather than true.
+- Fields are named explicitly, never spread. The writer can also emit `logPath` (a
+  full path), `agent`, `jobId`, `bridgeSessionId` and `parkedJobId`. Verified against
+  the live registry: no `/Users/`, no `cc-socks`, no `logPath`, no `cwd` on the wire.
+- Registry reads honor `CLAUDE_CONFIG_DIR`, match `<pid>.json` strictly rather than
+  `*.json`, `lstat` to refuse symlinks, and treat an ENOENT mid-read as normal because
+  the reaper is actively unlinking.
+
+- **Session labels you can actually read, and machine sessions you can hide.** The
+  list is only useful if the rows have names. Measured 2026-08-10: `first_prompt` took
+  the first user message unconditionally, so a slash-command session was labelled
+  `<command-message>cos-glasses</command-message>`, a proxy session was labelled "You
+  are the COS Slack Bridge proxy", and everything else fell back to a random slug
+  (`crispy-coalescing-salamander`) or the bare UUID. Fixed in the Python indexer with a
+  filter, not an LLM: wrappers are stripped, a slash command keeps its name, injected
+  persona prompts are rejected. `custom_title` now carries Claude Code's own sidebar
+  title where the user set one — `3dc7e253` correctly reads "COS-glasses Server work
+  (meetings)". New `display_label` resolves title, then derived label, then short id,
+  and falls back for the 37,157 rows written before these fields existed.
+- **`?human=1` hides harness-opened sessions.** 1,045 of 1,210 local sessions are proxy
+  calls, readiness probes and hook spawns; roughly 165 were opened by a person, which is
+  the order of magnitude Claude Code's own sidebar shows. `machine_spawned` is strict
+  `=== true`, so a bad value fails OPEN — losing a session the user had is worse than
+  showing a machine one.
+- **`COS_CLAUDE_SESSIONS_SHOW_NAMES=1` opts into real session names.** Redaction stays
+  the default so the published package is safe for anyone, but on an owner's own machine
+  it deleted the whole value of the view, since the names are how you tell one session
+  from another. Deliberately a SEPARATE switch from the enable flag: turning the feature
+  on must not silently turn redaction off. Opting in still never exposes a path or an
+  unlisted field.
+
+**Sending messages from the glasses stays closed, not parked.** COS launches Claude
+with `--dangerously-skip-permissions` in BOTH branches of `claude-permissions.ts:44`,
+so there is no configuration in which an inbound message reaches a receiver that
+would prompt. Combined with the 0.0.0.0 bind, that is a LAN-token-to-RCE path.
+
+Coverage: 75 tests across the two routes, 20 mutations all caught. One was an invalid
+experiment first time round — the 500 responder is identical in both handlers, so
+mutating them together looked covered; mutated one at a time the list site was caught
+and the DETAIL site SURVIVED, which found a genuinely untested leak path.
+
 ## 6.23.1
 
 Closes the hole 6.23.0 left open, plus a lockfile version that 6.23.0 shipped out of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.23.1",
+  "version": "6.24.0",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -17,6 +17,8 @@ import { diagRouter } from './routes/diag.js'
 import { queryRouter } from './routes/query.js'
 import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
+import { sessionIndexRouter } from './routes/session-index.js'
+import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter } from './routes/transcribe-stream.js'
 import { meetingRouter, resumeMeetingFinalizationJobs } from './routes/meeting.js'
@@ -231,6 +233,12 @@ app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
 app.use('/api', queryRouter)
 app.use('/api', providerProofRouter)
 app.use('/api', transcribeRouter)
+// Ported from cos-glasses-app in 6.24.0. The companion's Sessions tab has been
+// calling this and getting a 404 since the managed-runtime cutover.
+app.use('/api', sessionIndexRouter)
+// Presence view of Claude Code sessions on this Mac. Dark unless
+// COS_CLAUDE_SESSIONS_ENABLED=1 — it projects another product's 0700 state dir.
+app.use('/api', claudeSessionsRouter)
 app.use('/api', displayRouter)
 app.use('/api', transcribeStreamRouter)
 app.use('/api', meetingRouter)

package/server/lib/claude-session-registry.ts

@@ -0,0 +1,185 @@
+// Who else is alive on this Mac right now.
+//
+// Claude Code 2.1.224+ writes one JSON file per session into
+// `<CLAUDE_CONFIG_DIR|~/.claude>/sessions/<pid>.json` and binds a Unix socket at
+// `/tmp/cc-socks/<pid>.sock`. This reads that directory to answer one question the
+// COS session index cannot: which processes are running, and which can be reached.
+//
+// PRESENCE, NOT MEMORY. The COS session index is durable by design and knows what
+// was discussed and which business domain it belongs to. This registry is ephemeral
+// by design — actively reaped on exit and again at next startup — and knows only
+// where a process runs and whether it is busy. They are different layers and
+// merging them into one list would lose both meanings.
+//
+// FOUR THINGS THAT LOOK TRUE AND ARE NOT, all probed on this machine 2026-08-10:
+//
+//  1. Recency is not liveness. Compute it with a signal 0, never infer it from
+//     mtime.
+//  2. A socket file is not liveness. `/tmp/cc-socks` had an orphaned `.sock` whose
+//     PID was dead and whose registry file no longer existed. Sockets are not
+//     reaped. Reachability needs alive AND a declared socket path AND that file
+//     present.
+//  3. A registry file outliving its process is the EXCEPTION. An earlier draft of
+//     this work claimed the two newest files were dead and built a rule on it; on
+//     re-probe fifteen minutes later all files mapped to live PIDs and the two
+//     called dead no longer existed. Reaping is aggressive, so an "ended sessions"
+//     section will be empty almost always. Design for that empty state.
+//  4. `name` is not safe to echo. `nameSource: 'auto'` means an LLM wrote the label
+//     FROM THE WORK, so it can carry conversation content, and `/rename` clears
+//     nameSource entirely. Only `derived` is a function of the folder name.
+
+/** Fields this module will read. Everything else in the file is ignored. */
+export interface RawClaudeSession {
+  pid?: unknown
+  sessionId?: unknown
+  cwd?: unknown
+  startedAt?: unknown
+  version?: unknown
+  kind?: unknown
+  entrypoint?: unknown
+  messagingSocketPath?: unknown
+  name?: unknown
+  nameSource?: unknown
+  status?: unknown
+  updatedAt?: unknown
+  waitingFor?: unknown
+}
+
+export interface ClaudePeer {
+  /** Short form of sessionId. The full UUID is not needed to render a list. */
+  id: string
+  name: string
+  /** True when `name` was replaced because the original could carry work content. */
+  nameRedacted: boolean
+  workspace: string
+  entrypoint: string
+  kind: string
+  version: string
+  alive: boolean
+  reachable: boolean
+  status: string | null
+  waitingFor: string | null
+  lastActiveAt: number | null
+  startedAt: number | null
+}
+
+export interface PeerProbes {
+  /** signal-0 liveness. EPERM (another user) must resolve to false, not true. */
+  isAlive: (pid: number) => boolean
+  /** Does the declared socket file exist right now? */
+  socketExists: (path: string) => boolean
+}
+
+/** A registry filename is exactly `<pid>.json`. Not `*.json`. */
+export const REGISTRY_FILENAME = /^\d+\.json$/
+
+function str(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+function millis(value: unknown): number | null {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}
+
+/** Last path segment of a cwd, with no separators and no full path. */
+export function workspaceFromCwd(cwd: string | null): string {
+  if (!cwd) return 'unknown'
+  const parts = cwd.split('/').filter(Boolean)
+  return parts.length > 0 ? parts[parts.length - 1]! : 'unknown'
+}
+
+/**
+ * The label Claude derives itself: `<folder>-<suffix>`.
+ *
+ * Recomputing the derived form is what lets a `user` or `auto` name be replaced with
+ * something that carries no conversation content while still being recognizable.
+ */
+export function derivedName(cwd: string | null): string {
+  return workspaceFromCwd(cwd)
+}
+
+/**
+ * Is this name safe to return?
+ *
+ * ONLY `derived`. `auto` is LLM-written from the work; `user` is arbitrary text; and
+ * `/rename` deletes nameSource, so a missing value means a renamed session, not a
+ * derived one. Anything but an exact `derived` gets the recomputed folder name.
+ */
+export function nameIsSafe(nameSource: unknown): boolean {
+  return nameSource === 'derived'
+}
+
+/**
+ * Project one registry entry to the wire shape, or null if it is not usable.
+ *
+ * NEVER spreads the parsed object. The writer can also emit `logPath` (a full
+ * filesystem path), `agent`, `jobId`, `bridgeSessionId` and `parkedJobId`, none of
+ * which belong on a lens. Every field below is named explicitly.
+ */
+export function toPeer(
+  raw: RawClaudeSession,
+  probes: PeerProbes,
+  fallbackMtimeMs: number | null = null,
+  /** Owner opt-in. Default false keeps the published package safe by default. */
+  showNames = false,
+): ClaudePeer | null {
+  const pid = Number(raw.pid)
+  if (!Number.isInteger(pid) || pid <= 0) return null
+  const sessionId = str(raw.sessionId)
+  if (!sessionId) return null
+
+  const cwd = str(raw.cwd)
+  const alive = probes.isAlive(pid)
+  const socketPath = str(raw.messagingSocketPath)
+  // Reachability is a conjunction. Any one of these alone is a false positive:
+  // an alive process on an old build has no socket, and a socket file outlives
+  // its process because nothing reaps /tmp/cc-socks.
+  const reachable = alive && socketPath !== null && probes.socketExists(socketPath)
+
+  // An explicit owner opt-in makes ANY name showable; otherwise only `derived`.
+  const safe = showNames || nameIsSafe(raw.nameSource)
+  const rawName = str(raw.name)
+  return {
+    id: sessionId.slice(0, 8),
+    name: safe && rawName ? rawName : derivedName(cwd),
+    nameRedacted: !(safe && rawName),
+    workspace: workspaceFromCwd(cwd),
+    entrypoint: str(raw.entrypoint) ?? 'unknown',
+    kind: str(raw.kind) ?? 'unknown',
+    version: str(raw.version) ?? 'unknown',
+    alive,
+    reachable,
+    status: str(raw.status),
+    waitingFor: str(raw.waitingFor),
+    lastActiveAt: millis(raw.updatedAt) ?? fallbackMtimeMs ?? millis(raw.startedAt),
+    startedAt: millis(raw.startedAt),
+  }
+}
+
+/**
+ * Alive first, then most recently active.
+ *
+ * Alive-first matters because the list is a presence view: a dead row is history and
+ * must never outrank something running.
+ */
+export function sortPeers(peers: ClaudePeer[]): ClaudePeer[] {
+  return [...peers].sort((a, b) => {
+    if (a.alive !== b.alive) return a.alive ? -1 : 1
+    return (b.lastActiveAt ?? 0) - (a.lastActiveAt ?? 0)
+  })
+}
+
+export interface PeerCounts {
+  alive: number
+  reachable: number
+  stale: number
+}
+
+export function countPeers(peers: readonly ClaudePeer[]): PeerCounts {
+  return {
+    alive: peers.filter(p => p.alive).length,
+    reachable: peers.filter(p => p.reachable).length,
+    stale: peers.filter(p => !p.alive).length,
+  }
+}

package/server/routes/claude-sessions.ts

@@ -0,0 +1,162 @@
+// GET /api/claude-sessions — read-only presence view of Claude Code sessions.
+//
+// Named `claude-sessions` rather than `peers` deliberately. COS already overloads
+// "session" three ways — meeting recording sessions, COS conversation sessions, and
+// now Claude OS processes — and in a system where the glasses, the phone and the
+// server are all arguably peers, `/api/peers` would be ambiguous in exactly the
+// place clarity matters.
+//
+// OFF BY DEFAULT. This reads another product's private state directory (mode 0700)
+// and serves a projection of it over a socket that binds 0.0.0.0 behind a
+// private-network allowlist. In a published npm package that has to be opt-in, so it
+// stays dark until COS_CLAUDE_SESSIONS_ENABLED is set.
+//
+// The redaction rules and the reachability conjunction live in
+// lib/claude-session-registry.ts, with the evidence for each. This file is the fs
+// and process plumbing only.
+
+import { Router } from 'express'
+import { existsSync } from 'node:fs'
+import { lstat, readdir, readFile, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import {
+  REGISTRY_FILENAME,
+  countPeers,
+  sortPeers,
+  toPeer,
+  type ClaudePeer,
+  type PeerProbes,
+  type RawClaudeSession,
+} from '../lib/claude-session-registry.js'
+
+export const claudeSessionsRouter = Router()
+
+/** Guard against a directory someone has filled with junk. */
+const MAX_REGISTRY_FILES = 500
+
+export function claudeSessionsEnabled(): boolean {
+  return process.env.COS_CLAUDE_SESSIONS_ENABLED === '1'
+}
+
+/**
+ * Show real session names instead of the recomputed folder name?
+ *
+ * Default OFF, so the published package is safe for anyone: a `user` or `auto` name
+ * describes the WORK ("Kevin/Miles grievance analysis"), and this socket binds
+ * 0.0.0.0 behind a private-network allowlist, so anyone on the LAN holding the token
+ * would read it off the wire.
+ *
+ * On an owner's own machine that redaction deletes the entire value of the view —
+ * the names are how you tell one session from another — so it is a deliberate opt-in
+ * rather than a hardcoded policy. Separate from the ENABLED flag: turning the feature
+ * on should not silently also turn off redaction.
+ */
+export function claudeSessionNamesVisible(): boolean {
+  return process.env.COS_CLAUDE_SESSIONS_SHOW_NAMES === '1'
+}
+
+/**
+ * Where the registry lives.
+ *
+ * `COS_CLAUDE_SESSIONS_DIR` first because it is both the override for a non-standard
+ * install AND the test seam — `homedir()` is not mockable, so without an env hook the
+ * only testable path would be the real one. Then CLAUDE_CONFIG_DIR, which real
+ * installs do set; hardcoding ~/.claude breaks those.
+ */
+export function claudeSessionsDir(): string {
+  const explicit = process.env.COS_CLAUDE_SESSIONS_DIR
+  if (explicit) return resolve(explicit)
+  const configDir = process.env.CLAUDE_CONFIG_DIR
+  return join(configDir ? resolve(configDir) : join(homedir(), '.claude'), 'sessions')
+}
+
+const realProbes: PeerProbes = {
+  isAlive: pid => {
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch (error: any) {
+      // ESRCH: gone. EPERM: alive but owned by another user, which is NOT reachable
+      // from here and must not be reported as ours.
+      return false
+    }
+  },
+  socketExists: path => {
+    try { return existsSync(path) } catch { return false }
+  },
+}
+
+export async function readClaudePeers(
+  dir: string,
+  probes: PeerProbes = realProbes,
+  showNames = claudeSessionNamesVisible(),
+): Promise<ClaudePeer[]> {
+  let names: string[]
+  try {
+    names = await readdir(dir)
+  } catch {
+    // No directory means Claude Code has never run here, or the path is wrong.
+    // An empty presence list is the honest answer; the route reports `enabled`
+    // separately so this cannot be mistaken for "the feature is off".
+    return []
+  }
+  const peers: ClaudePeer[] = []
+  for (const name of names.filter(n => REGISTRY_FILENAME.test(n)).slice(0, MAX_REGISTRY_FILES)) {
+    const full = join(dir, name)
+    try {
+      // lstat, not stat: a symlink here would let anything on the filesystem be read
+      // and projected onto the lens.
+      const link = await lstat(full)
+      if (!link.isFile()) continue
+      const raw = JSON.parse(await readFile(full, 'utf-8')) as RawClaudeSession
+      // mtime is the fallback for lastActiveAt only, never for liveness.
+      let mtimeMs: number | null = null
+      try { mtimeMs = (await stat(full)).mtimeMs } catch { /* raced the reaper */ }
+      const peer = toPeer(raw, probes, mtimeMs, showNames)
+      if (peer) peers.push(peer)
+    } catch {
+      // ENOENT between readdir and read is NORMAL here — the reaper is actively
+      // unlinking these — and a torn read is expected because writes are
+      // read-modify-write. Neither is worth surfacing.
+      continue
+    }
+  }
+  return sortPeers(peers)
+}
+
+function boundedInteger(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+claudeSessionsRouter.get('/claude-sessions', async (req, res) => {
+  res.set('Cache-Control', 'private, no-store')
+  if (!claudeSessionsEnabled()) {
+    // 200, not 503. The feature being switched off is a normal configuration, not a
+    // fault, and the companion needs to tell those apart to decide whether to render
+    // the section at all.
+    res.json({
+      peers: [],
+      counts: { alive: 0, reachable: 0, stale: 0 },
+      enabled: false,
+      reason: 'disabled',
+      generatedAt: Date.now(),
+    })
+    return
+  }
+  try {
+    const limit = boundedInteger(req.query.limit, 30, 1, 100)
+    const peers = await readClaudePeers(claudeSessionsDir())
+    res.json({
+      peers: peers.slice(0, limit),
+      counts: countPeers(peers),
+      enabled: true,
+      generatedAt: Date.now(),
+    })
+  } catch (error) {
+    console.error(`[claude-sessions] read failed: ${error instanceof Error ? error.message : error}`)
+    res.status(500).json({ error: 'Failed to read Claude session registry', reason: 'registry_read_failed' })
+  }
+})

package/server/routes/session-index.ts

@@ -0,0 +1,282 @@
+// GET /api/session-index        — COS conversation sessions, compact list
+// GET /api/session-index/:id    — one session, full detail
+//
+// PORTED, NOT COPIED. This route lived only in the private cos-glasses-app repo
+// and was never carried into the published package, so the companion's Sessions
+// tab has been calling a 404 since the managed-runtime cutover — the same class of
+// gap as the stranded voice profiles, the npmignore-excluded speaker model, and the
+// stranded .cos-profile.json.
+//
+// WHY PORT RATHER THAN RETIRE. `/api/sessions/recent` looks like a duplicate and is
+// not. It returns {id, exchangeCount, lastActivity, createdAt, modelPreference,
+// lastQuery} from an IN-MEMORY map on a 24-hour window, so it carries no `domain`,
+// no `device_id`, gives `lastQuery` where the companion wants `first_prompt`, dies
+// on restart, and has no counterpart at all for the detail view's `tools_used`,
+// `files_touched`, `git_branch` and token counts. The cache this route reads is
+// disk-backed and already WRITTEN by the published package
+// (lib/session-cache-writer.ts), so only the reader was missing.
+//
+// FOUR DEFECTS IN THE ORIGINAL, all fixed here and all measured on real data
+// (37,700 servable entries across 5 cache files on this machine):
+//
+//  1. An unset COS_SCRIPTS_DIR returned `[]`, so a standalone npm install answered
+//     200 with an empty list — indistinguishable from "you have no sessions". It is
+//     now 503 with `reason: pythonBridgeState()`, matching routes/memory.ts.
+//  2. `res.status(500).json({ error: err.message })` leaked filesystem paths. No
+//     other router in this repo does that.
+//  3. Synchronous `readdirSync`/`readFileSync` of 31.7 MB on EVERY request, the
+//     detail endpoint included, which parsed all of it to find one row. This
+//     process also streams live audio, so that blocked the event loop. Now async
+//     and cached against file identity.
+//  4. The filename filter matched iCloud sync-conflict duplicates. On this machine
+//     `.session_index_cache_Ukaoma-Mac-Studio 3.json` shares 543 of its 602 rows
+//     with the canonical file, so the merged list served 543 duplicates. Filtering
+//     ` N` filenames out would be wrong in the other direction: ` 2.json` holds 245
+//     rows that appear nowhere else. Dedupe therefore happens by session_id, newest
+//     wins, and every file is still read.
+
+import { Router } from 'express'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { COS_SCRIPTS_DIR, pythonBridgeState } from '../lib/python-bridge.js'
+
+export const sessionIndexRouter = Router()
+
+const CACHE_PREFIX = '.session_index_cache_'
+/** Guard against a pathological cache file. 37,700 entries measured; 250k is slack. */
+const MAX_ENTRIES = 250_000
+
+export interface SessionEntry {
+  session_id: string
+  /** Claude Code's own sidebar title when the user set one, else ''. */
+  custom_title: string
+  /** custom_title, else the first real user message, else the short id. */
+  display_label: string
+  /** True when the harness opened this session rather than a person. */
+  machine_spawned: boolean
+  glasses_session_id: string
+  slug: string
+  created: string
+  modified: string
+  duration_minutes: number
+  message_count: number
+  first_prompt: string
+  domain: string
+  device_id: string
+}
+
+interface RawEntry extends Record<string, unknown> {
+  session_id: string
+  slug: string
+}
+
+/**
+ * Parse-cache keyed on the identity of the files themselves.
+ *
+ * 31.7 MB of JSON is too much to re-parse per request, and this data changes only
+ * when the Python side rewrites a cache file. The key is every file's name, size and
+ * mtime, so any write invalidates it without a timer and without serving staleness.
+ */
+let parseCache: { key: string; entries: RawEntry[] } | null = null
+
+async function cacheFileIdentity(dir: string): Promise<{ key: string; files: string[] }> {
+  const names = (await readdir(dir))
+    .filter(f => f.startsWith(CACHE_PREFIX) && f.endsWith('.json') && !f.endsWith('.lock'))
+    .sort()
+  const parts: string[] = []
+  const files: string[] = []
+  for (const name of names) {
+    try {
+      const st = await stat(join(dir, name))
+      if (!st.isFile()) continue
+      parts.push(`${name}:${st.size}:${st.mtimeMs}`)
+      files.push(name)
+    } catch { /* vanished between readdir and stat: normal, skip it */ }
+  }
+  return { key: parts.join('|'), files }
+}
+
+/**
+ * Every entry across every cache file, deduplicated by session_id.
+ *
+ * Newest wins, measured by `modified` and then `_file_mtime`. Without this the
+ * iCloud duplicate described in the header serves the same session twice.
+ */
+async function readAllSessionCaches(dir: string): Promise<RawEntry[]> {
+  const { key, files } = await cacheFileIdentity(dir)
+  if (parseCache && parseCache.key === key) return parseCache.entries
+
+  const byId = new Map<string, RawEntry>()
+  for (const name of files) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(await readFile(join(dir, name), 'utf-8'))
+    } catch {
+      // Unreadable or torn mid-write. One bad file must not empty the whole list.
+      continue
+    }
+    const sessions = (parsed as { sessions?: unknown })?.sessions
+    if (!sessions || typeof sessions !== 'object') continue
+    for (const value of Object.values(sessions as Record<string, unknown>)) {
+      if (!value || typeof value !== 'object') continue
+      const entry = value as RawEntry
+      if (typeof entry.session_id !== 'string' || !entry.session_id) continue
+      if (typeof entry.slug !== 'string' || !entry.slug) continue
+      const existing = byId.get(entry.session_id)
+      if (!existing || freshness(entry) > freshness(existing)) byId.set(entry.session_id, entry)
+      if (byId.size >= MAX_ENTRIES) break
+    }
+  }
+  const entries = [...byId.values()]
+  parseCache = { key, entries }
+  return entries
+}
+
+/** Sort key for "which copy of this session is the real one". */
+function freshness(entry: RawEntry): number {
+  const modified = typeof entry.modified === 'string' ? Date.parse(entry.modified) : Number.NaN
+  if (Number.isFinite(modified)) return modified
+  const fileMtime = Number(entry._file_mtime)
+  return Number.isFinite(fileMtime) ? fileMtime : 0
+}
+
+function boundedInteger(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+function str(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback
+}
+
+function num(value: unknown): number {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/** Unset COS_SCRIPTS_DIR means standalone: say so, never answer with an empty list. */
+function unavailable(res: import('express').Response): void {
+  res.status(503).json({
+    available: false,
+    reason: pythonBridgeState(),
+    sessions: [],
+    total: 0,
+    devices: [],
+  })
+}
+
+sessionIndexRouter.get('/session-index', async (req, res) => {
+  if (!COS_SCRIPTS_DIR) { unavailable(res); return }
+  try {
+    const limit = boundedInteger(req.query.limit, 30, 1, 50)
+    const domainFilter = str(req.query.domain, 'all') || 'all'
+    const deviceFilter = str(req.query.device, 'all') || 'all'
+    const sidFilter = str(req.query.sid)
+    // 1,045 of 1,210 local sessions are proxy calls, readiness probes and hook
+    // spawns. A list of all of them is unbrowsable, which is why Claude Code's own
+    // sidebar shows roughly the 165 that a person actually opened.
+    const humanOnly = str(req.query.human) === '1'
+
+    const all = await readAllSessionCaches(COS_SCRIPTS_DIR)
+    const sessions: SessionEntry[] = []
+    const devices = new Set<string>()
+
+    for (const entry of all) {
+      const domain = str(entry.domain, 'unknown') || 'unknown'
+      const deviceId = str(entry.device_id, 'unknown') || 'unknown'
+      const glassesId = str(entry.glasses_session_id)
+      if (domainFilter !== 'all' && domain !== domainFilter) continue
+      if (deviceFilter !== 'all' && deviceId !== deviceFilter) continue
+      if (sidFilter && !glassesId.startsWith(sidFilter)) continue
+      if (humanOnly && entry.machine_spawned === true) continue
+
+      // Collected from the FILTERED set on purpose, so the device picker offers only
+      // devices that can actually produce rows under the current filters.
+      if (deviceId !== 'unknown') devices.add(deviceId)
+
+      sessions.push({
+        session_id: entry.session_id,
+        glasses_session_id: glassesId,
+        slug: entry.slug,
+        created: str(entry.created),
+        modified: str(entry.modified),
+        duration_minutes: num(entry.duration_minutes),
+        message_count: num(entry.message_count),
+        first_prompt: str(entry.first_prompt),
+        custom_title: str(entry.custom_title),
+        // Older cache rows predate these fields, so fall back rather than emitting
+        // an empty label for every session written before this release.
+        display_label: str(entry.display_label) || str(entry.custom_title)
+          || str(entry.first_prompt) || str(entry.slug) || entry.session_id.slice(0, 8),
+        machine_spawned: entry.machine_spawned === true,
+        domain,
+        device_id: deviceId,
+      })
+    }
+
+    sessions.sort((a, b) => (b.modified || '').localeCompare(a.modified || ''))
+    res.set('Cache-Control', 'private, no-store')
+    res.json({ sessions: sessions.slice(0, limit), total: sessions.length, devices: [...devices] })
+  } catch (error) {
+    // Detail to the operator's log, never to the client: err.message here is a
+    // filesystem path.
+    console.error(`[session-index] list failed: ${error instanceof Error ? error.message : error}`)
+    res.status(500).json({ error: 'Failed to read session index', reason: 'session_index_read_failed' })
+  }
+})
+
+sessionIndexRouter.get('/session-index/:session_id', async (req, res) => {
+  if (!COS_SCRIPTS_DIR) { unavailable(res); return }
+  try {
+    const wanted = String(req.params.session_id ?? '')
+    if (!wanted) {
+      res.status(400).json({ error: 'session_id required', reason: 'missing_session_id' })
+      return
+    }
+    const all = await readAllSessionCaches(COS_SCRIPTS_DIR)
+    // Exact id, then the original glasses UUID, then a UUID prefix — the companion
+    // links by whichever it happens to hold.
+    const entry = all.find(e => e.session_id === wanted)
+      ?? all.find(e => str(e.glasses_session_id) === wanted)
+      ?? all.find(e => wanted.length >= 6 && str(e.glasses_session_id).startsWith(wanted))
+    if (!entry) {
+      res.status(404).json({ error: 'Session not found', reason: 'session_not_found' })
+      return
+    }
+    res.set('Cache-Control', 'private, no-store')
+    res.json({
+      session_id: entry.session_id,
+      glasses_session_id: str(entry.glasses_session_id),
+      slug: str(entry.slug),
+      created: str(entry.created),
+      modified: str(entry.modified),
+      duration_minutes: num(entry.duration_minutes),
+      user_message_count: num(entry.user_message_count),
+      assistant_message_count: num(entry.assistant_message_count),
+      message_count: num(entry.message_count),
+      first_prompt: str(entry.first_prompt),
+      custom_title: str(entry.custom_title),
+      display_label: str(entry.display_label) || str(entry.custom_title)
+        || str(entry.first_prompt) || str(entry.slug) || entry.session_id.slice(0, 8),
+      machine_spawned: entry.machine_spawned === true,
+      tools_used: (entry.tools_used && typeof entry.tools_used === 'object') ? entry.tools_used : {},
+      files_touched: Array.isArray(entry.files_touched) ? entry.files_touched : [],
+      domain: str(entry.domain, 'unknown') || 'unknown',
+      git_branch: str(entry.git_branch, 'unknown') || 'unknown',
+      has_subagents: entry.has_subagents === true,
+      total_input_tokens: num(entry.total_input_tokens),
+      total_output_tokens: num(entry.total_output_tokens),
+      file_size_bytes: num(entry.file_size_bytes),
+      device_id: str(entry.device_id, 'unknown') || 'unknown',
+    })
+  } catch (error) {
+    console.error(`[session-index] detail failed: ${error instanceof Error ? error.message : error}`)
+    res.status(500).json({ error: 'Failed to read session index', reason: 'session_index_read_failed' })
+  }
+})
+
+/** Test seam: drop the parse cache between cases. */
+export function __resetSessionIndexCache(): void {
+  parseCache = null
+}