@gotcos/glasses-server 6.82.0 → 6.83.0

package/server/lib/work-orchestrator/pickup.ts

@@ -0,0 +1,85 @@
+/**
+ * 6.83.0 (M2 planner input, canary C2): a bounded, deterministic "where it stopped, what is next" note from the tail of
+ * a session's log. No model call. The note goes only into the planner input; it is redacted (secrets and customer
+ * identifiers) before it leaves this module, and never longer than PICKUP_MAX_CHARS.
+ */
+import { readTail, turnsFrom, type LogProvider, type Turn } from './session-log.js'
+import { redactNote } from './redact.js'
+import { statusLines } from './tags.js'
+
+export const PICKUP_MAX_CHARS = 1500
+
+/** User turns the harness writes, not the person: task notifications, compaction summaries, interrupts. */
+const HARNESS = ['Perform any necessary follow-up actions', 'Briefly inform the user about the task result', '<task-notification>',
+  'This session is being continued from a previous conversation', '[Request interrupted', 'The following is the Codex agent history']
+
+export interface LiveOverlay { busy?: boolean; waitingOnUser?: boolean }
+
+const clip = (s: string, n: number) => {
+  const t = (s || '').replace(/\s+/g, ' ').trim()
+  return t.length <= n ? t : t.slice(0, n - 1).trimEnd() + '…'
+}
+
+export function pendingTodos(turns: Turn[]): string[] {
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const t = turns[i]!
+    if (t.role !== 'todo') continue
+    let items: unknown
+    try { items = JSON.parse(t.text) } catch { items = undefined }
+    if (typeof items === 'string') { try { items = JSON.parse(items) } catch { items = undefined } }
+    if (items && typeof items === 'object' && !Array.isArray(items)) items = (items as any).plan ?? (items as any).todos
+    if (!Array.isArray(items)) return []
+    return items.filter(it => it && typeof it === 'object' && !['completed', 'done'].includes(String((it as any).status ?? '').toLowerCase()))
+      .map(it => `${String((it as any).status || 'open')}: ${String((it as any).content ?? (it as any).step ?? (it as any).activeForm ?? '')}`)
+  }
+  return []
+}
+
+export function questionsIn(text: string): string[] {
+  const out: string[] = []
+  for (const piece of text.split(/(?<=[.?!])\s+|\n/)) {
+    const l = piece.trim().replace(/^[-*#> ]+/, '').replace(/[-*#> ]+$/, '')
+    if (l.endsWith('?') && l.length > 12 && l.length < 300 && !/^(https?:|what i |why )/i.test(l)) out.push(l)
+  }
+  return out.slice(-4)
+}
+
+export interface PickupNote { note: string; lastActivity: string | null; state: 'running' | 'mid_turn' | 'after_tools' | 'finished' | 'empty' }
+
+/** The note from turns already read. `mtimeMs` stands in for Cursor's missing timestamps. */
+export function pickupFromTurns(turns: Turn[], options: { live?: LiveOverlay; mtimeMs?: number; home?: string } = {}): PickupNote {
+  const r = (s: string) => redactNote(s, options.home)
+  const human = turns.filter(t => t.role === 'user' && t.text.trim() && !/^\s*[<{]/.test(t.text) && !HARNESS.some(h => t.text.trimStart().startsWith(h)))
+  const replies = turns.filter(t => t.role === 'assistant' && t.text.trim())
+  if (!human.length && !replies.length) return { note: 'No readable turns in the log tail.', lastActivity: null, state: 'empty' }
+  const lastUser = human[human.length - 1]
+  const lastReply = replies[replies.length - 1]
+  const iUser = turns.lastIndexOf(lastUser!), iReply = turns.lastIndexOf(lastReply!)
+  const toolsAfter = iReply >= 0 ? turns.slice(iReply + 1).filter(t => t.role === 'tool').length : 0
+  let state: PickupNote['state'] = iUser > iReply ? 'mid_turn' : toolsAfter ? 'after_tools' : 'finished'
+  let stateLine = state === 'mid_turn' ? 'Stopped mid-turn: the last ask has no reply yet.'
+    : state === 'after_tools' ? `Stopped after ${toolsAfter} tool call(s) with no closing reply.` : 'Stopped after a reply (turn finished).'
+  if (options.live?.busy) { state = 'running'; stateLine = 'Still running: a turn is in flight now, so this is a moving snapshot.' }
+  else if (options.live?.waitingOnUser) stateLine += ' The session list says it is waiting on the user.'
+  const stamp = lastReply?.at ?? lastUser?.at ?? null
+  const lastActivity = stamp ?? (options.mtimeMs ? new Date(options.mtimeMs).toISOString() : null)
+  const when = stamp ? `${stamp.slice(0, 16).replace('T', ' ')} UTC` : options.mtimeMs ? `${new Date(options.mtimeMs).toISOString().slice(0, 16).replace('T', ' ')} UTC (file time)` : 'unknown'
+  const parts = [`State: ${stateLine} Last activity ${when}.`]
+  parts.push('Last ask: ' + clip(r(lastUser?.text ?? ''), 300))
+  parts.push('Last result: ' + clip(r(lastReply?.text ?? ''), 520))
+  const status = lastReply ? statusLines(lastReply.text)[0] : undefined
+  if (status) parts.push('Status line: ' + clip(r(`${status.status}: ${status.evidence}`), 160))
+  const todos = pendingTodos(turns)
+  if (todos.length) parts.push('Open todos: ' + clip(r(todos.join('; ')), 220))
+  const qs = lastReply ? questionsIn(lastReply.text) : []
+  parts.push('Open questions: ' + (qs.length ? clip(r(qs.join(' | ')), 260) : 'none found in the last reply.'))
+  let note = parts.join('\n')
+  if (note.length > PICKUP_MAX_CHARS) note = note.slice(0, PICKUP_MAX_CHARS - 1) + '…'
+  return { note, lastActivity, state }
+}
+
+export async function pickupNote(path: string, provider: LogProvider, sessionID: string, live?: LiveOverlay, home?: string): Promise<PickupNote> {
+  const tail = await readTail(path)
+  const turns = turnsFrom(tail.text, provider, provider === 'claude' ? sessionID : undefined)
+  return pickupFromTurns(turns, { live, mtimeMs: tail.mtimeMs, home })
+}

package/server/lib/work-orchestrator/plan-log.ts

@@ -0,0 +1,38 @@
+/**
+ * 6.83.0: every Work chat plan, from any client, leaves one JSONL row and one server log line: the sessions sent with
+ * their availability, what was left out and why, the usage snapshot's age per provider, the assignments (mode and
+ * target, never prompt text), the planner, the outcome and the time taken. Bounded: past 2 MB the file keeps its newest
+ * half. Ids and enums only; no question, prompt, summary or pick-up text is written.
+ */
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { atomicWriteFileSync } from '../atomic-fs.js'
+
+export const PLAN_LOG_MAX_BYTES = 2 * 1024 * 1024
+
+export interface PlanLogRow {
+  at: string; workID: string; mode: string; planner: string; effort: string; orchestrator: boolean
+  sessions: Array<{ id: string; automatic: boolean; available?: boolean; reason?: string; discoveredBy?: string[] }>
+  leftOut: Array<{ id: string; reason: string }>
+  usageAgeSec: Record<string, number | null>
+  usageState: Record<string, string>
+  assignments: Array<{ mode: string; target: string }>
+  outcome: 'planned' | 'invalid_answer' | 'unavailable' | 'aborted'
+  ms: number
+}
+
+export function appendPlanLog(path: string, row: PlanLogRow): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    let size = 0
+    try { size = statSync(path).size } catch { /* new file */ }
+    if (size > PLAN_LOG_MAX_BYTES) {
+      const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean)
+      atomicWriteFileSync(path, lines.slice(Math.floor(lines.length / 2)).join('\n') + '\n')
+    }
+    appendFileSync(path, JSON.stringify(row) + '\n', { mode: 0o600 })
+  } catch (e) { console.warn(`[work-orchestrator] plan log not written: ${(e as Error).message}`) }
+  const sent = row.sessions.map(s => `${s.id.slice(0, 15)}${s.automatic ? '' : '(no-continue)'}${s.reason ? `[${s.reason}]` : ''}`).join(',') || 'none'
+  const usage = Object.entries(row.usageState).map(([p, s]) => `${p}=${s}/${row.usageAgeSec[p] ?? '-'}s`).join(' ') || 'none'
+  console.log(`[work-orchestrator] plan work=${row.workID} outcome=${row.outcome} planner=${row.planner}/${row.effort} orchestrator=${row.orchestrator} sessions=${sent} leftOut=${row.leftOut.length} usage=${usage} assignments=${row.assignments.map(a => `${a.mode}:${a.target.slice(0, 15)}`).join(',') || 'none'} ms=${row.ms}`)
+}

package/server/lib/work-orchestrator/redact.ts

@@ -0,0 +1,41 @@
+/**
+ * 6.83.0: what a pick-up note may carry. Session logs hold secrets and customer identifiers; a note goes to the planner
+ * (and from there into a prompt), so both are removed here, before the note leaves the orchestrator.
+ *
+ * Secrets: the server's shared `redactSecrets` patterns, plus `name=value` secrets and credential file paths (canary C2).
+ * Customer identifiers (canary C2, N1 named a merchant's proposal slug with its fees): email addresses, phone numbers,
+ * the path and query of any URL (the host stays, so "bottlepos.com" still says where), money amounts, and long numeric
+ * ids (order, account, ticket and HubSpot ids). The replacements say what was there, never what it was.
+ */
+import { homedir } from 'node:os'
+import { redactSecrets } from '../lens-gist-engines.js'
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+function homeRes(home: string): Array<[RegExp, string]> {
+  const h = `(?:~|${escape(home)})`
+  return [
+    [new RegExp(`${h}/\\.(?:codex/auth\\.json|ssh/[\\w.\\-]+|aws/credentials|npmrc|netrc|config/gh/hosts\\.yml)`, 'g'), '[credential path]'],
+    [new RegExp(`${h}/\\.cos-glasses/[\\w.\\-/]*(?:token|key|secret)[\\w.\\-]*`, 'gi'), '[credential path]'],
+    // A path to an env file, or a bare `.env` token. `process.env` is code, not a file, and stays.
+    [new RegExp(`(?<![\\w])${h}?(?:/[\\w\\-.]+)*/\\.env(?:\\.[\\w-]+)?\\b|(?<![\\w.])\\.env(?:\\.[\\w-]+)?\\b`, 'g'), '[env file]'],
+  ]
+}
+
+const SECRET_ASSIGN = /\b(token|api[_-]?key|secret|password|passwd|x-cos-token|client[_-]?secret)\b(["']?\s*[:=]\s*["']?)[A-Za-z0-9_\-./+=]{12,}/gi
+const CUSTOMER: Array<[RegExp, string]> = [
+  [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, '[email]'],
+  // A URL keeps its scheme and host; its path, query and fragment can name a customer (slugs, ids, proposals).
+  [/\b(https?:\/\/[A-Za-z0-9.-]+(?::\d+)?)(?:[/?#][^\s)\]"'<>]*)/g, '$1/[path]'],
+  [/(?<![\w.])(?:\+?1[\s.-]?)?\(?\d{3}\)?[\s.-]\d{3}[\s.-]\d{4}(?!\d)/g, '[phone]'],
+  [/(?:[$£€]\s?\d[\d,]*(?:\.\d+)?(?:\s?(?:k|m|million|thousand))?|\b\d[\d,]*(?:\.\d+)?\s?(?:USD|dollars)\b)/gi, '[amount]'],
+  [/\b\d{6,}\b/g, '[id]'],
+]
+
+export function redactNote(text: string, home = homedir()): string {
+  let out = redactSecrets(text)
+  out = out.replace(SECRET_ASSIGN, '$1=[secret]')
+  for (const [re, to] of homeRes(home)) out = out.replace(re, to)
+  for (const [re, to] of CUSTOMER) out = out.replace(re, to)
+  return home.length > 1 ? out.split(home).join('~') : out
+}

package/server/lib/work-orchestrator/runtime.ts

@@ -0,0 +1,74 @@
+/**
+ * 6.83.0: the orchestrator's process-wide state, created on first use (importing this module starts nothing).
+ * Files live under `data/work-orchestrator/`.
+ */
+import { stat } from 'node:fs/promises'
+import { dataPath } from '../data-dir.js'
+import { agentSessionRoots, findAgentSessionFile, type AgentProvider } from '../agent-session-store.js'
+import { setUsageEventSink } from './usage-events.js'
+import { SnapshotStore, type ControlSnapshot } from './snapshot.js'
+import { TagIndex } from './tag-index.js'
+import { UsageMonitor, type UsageProvider } from './usage.js'
+import { buildOrchestratorInput, type OrchestratorInput } from './input.js'
+
+let snapshots: SnapshotStore | null = null
+let index: TagIndex | null = null
+let usage: UsageMonitor | null = null
+
+export function orchestratorSnapshots(): SnapshotStore { return snapshots ??= new SnapshotStore(dataPath('work-orchestrator', 'control-snapshot.json')) }
+export function orchestratorTagIndex(): TagIndex { return index ??= new TagIndex({ roots: agentSessionRoots(), path: dataPath('work-orchestrator', 'tag-index.json') }) }
+export function orchestratorUsage(): UsageMonitor {
+  if (!usage) {
+    // Inside a test the real probes are never reachable: any test that reads usage through this monitor gets an
+    // error reading, never a spawned claude or codex CLI (the boot guard below covers the poll; this covers on demand).
+    const inTest = !!(process.env.VITEST || process.env.NODE_ENV === 'test')
+    const noProbe = async (): Promise<never> => { throw new Error('not probed inside a test') }
+    const monitor = usage = new UsageMonitor({ path: dataPath('work-orchestrator', 'usage.json'), ...(inTest ? { probes: { claude: noProbe, codex: noProbe } } : {}) })
+    // Jobs report limits and rate-limit frames through the leaf module; this monitor is where they land.
+    setUsageEventSink({ limit: (p, message, source) => monitor.noteLimit(p as UsageProvider, message, source), claudeFrame: frame => monitor.noteClaudeRateLimitEvent(frame) })
+  }
+  return usage
+}
+export const PLAN_LOG_PATH = () => dataPath('work-orchestrator', 'plans.jsonl')
+
+/**
+ * Called once by the server at boot: registers the usage-event sink and schedules a first log scan. Usage is read on
+ * demand (a plan input or GET /usage); the 10-minute background poll starts only with `COS_WORK_USAGE_POLL=1`.
+ */
+export function startWorkOrchestrator(env: NodeJS.ProcessEnv = process.env): void {
+  // A test that boots the server must never spawn the real claude or codex CLI, nor scan this Mac's session logs.
+  orchestratorUsage() // registers the usage-event sink, so job limits and rate-limit frames are kept from boot
+  if (env.VITEST || env.NODE_ENV === 'test') return
+  orchestratorUsage().start(env) // opt-in only: a no-op unless COS_WORK_USAGE_POLL=1
+  setTimeout(() => { void orchestratorTagIndex().refresh().catch(() => {}) }, 45_000).unref?.()
+}
+
+/** How long a plan waits for the log scan before it answers with what the index already holds. */
+export const INPUT_SCAN_WAIT_MS = 20_000
+
+/** What one plan input reads. The server passes the process-wide stores; a test passes its own. */
+export interface OrchestratorParts { tags: TagIndex; usage: UsageMonitor; snapshot: () => ControlSnapshot | null }
+
+export async function orchestratorInputFor(workID: string, meetingWorkIDs: string[], parts?: OrchestratorParts): Promise<OrchestratorInput> {
+  const tags = parts?.tags ?? orchestratorTagIndex()
+  const monitor = parts?.usage ?? orchestratorUsage()
+  const scan = tags.refresh().catch(() => null)
+  const scanned = await Promise.race([scan, new Promise<null>(r => setTimeout(() => r(null), INPUT_SCAN_WAIT_MS).unref?.())])
+  // On demand: the plan this input feeds may fork or start a session, so a reading older than 2 minutes is re-read.
+  const usageViews = await monitor.forPlan()
+  const roots = agentSessionRoots()
+  return buildOrchestratorInput(workID, meetingWorkIDs, {
+    snapshot: parts ? parts.snapshot() : orchestratorSnapshots().get(),
+    hits: tags.hits(),
+    usage: usageViews,
+    skipped: tags.skippedSessions(),
+    logScanComplete: !!scanned?.complete,
+    pathOf: async sid => {
+      const known = tags.pathOf(sid)
+      if (known) return known
+      const [provider, id] = sid.split(':') as [AgentProvider, string]
+      return findAgentSessionFile(provider, id, roots)
+    },
+    mtimeOf: async path => (await stat(path)).mtimeMs,
+  })
+}

package/server/lib/work-orchestrator/session-log.ts

@@ -0,0 +1,114 @@
+/**
+ * 6.83.0: read the END of a session log without reading the whole file, and turn its rows into human-visible turns.
+ * Codex rollouts reach 1.4 GB (canary C2), so the reader seeks from the end: at most `TAIL_BYTES`, starting at the first
+ * whole line. Read-only; never writes beside the log.
+ *
+ * Row shapes (measured in canary C2 on 2026-10-20):
+ *   Claude  {type:'user'|'assistant', sessionId, timestamp, isSidechain, isMeta, message:{role, content}}
+ *   Cursor  {role, message:{content:[{type:'text', text:'<user_query>…</user_query>'}]}} (no timestamps: use mtime)
+ *   Codex   {timestamp, type:'response_item', payload:{type:'message', role, content:[{text}]}} and function calls
+ */
+import { open, stat } from 'node:fs/promises'
+
+export const TAIL_BYTES = 6_000_000
+export type LogProvider = 'claude' | 'codex' | 'cursor'
+export type TurnRole = 'user' | 'assistant' | 'tool' | 'todo' | 'ask'
+export interface Turn { role: TurnRole; text: string; at: string | null }
+
+/** Harness text that is not the person's ask nor the agent's answer. */
+const NOISE = ['<environment_context>', '<user_instructions>', '# AGENTS.md', '<permissions instructions>', '<system-reminder>',
+  '<command-name>', '<local-command', 'Caveat: The messages below', '<external_codex_apps_open_page>', '<turn_aborted>']
+const noisy = (text: string) => { const head = text.slice(0, 300); return NOISE.some(n => head.includes(n)) }
+
+export async function readTail(path: string, maxBytes = TAIL_BYTES): Promise<{ text: string; size: number; mtimeMs: number; truncated: boolean }> {
+  const info = await stat(path)
+  const start = Math.max(0, info.size - maxBytes)
+  const handle = await open(path, 'r')
+  try {
+    const length = info.size - start
+    const buffer = Buffer.alloc(length)
+    let read = 0
+    while (read < length) {
+      const { bytesRead } = await handle.read(buffer, read, length - read, start + read)
+      if (bytesRead === 0) break
+      read += bytesRead
+    }
+    let text = buffer.subarray(0, read).toString('utf8')
+    // Seeking lands mid-line: drop the partial first line so every row parses whole.
+    if (start > 0) { const nl = text.indexOf('\n'); text = nl < 0 ? '' : text.slice(nl + 1) }
+    return { text, size: info.size, mtimeMs: info.mtimeMs, truncated: start > 0 }
+  } finally { await handle.close() }
+}
+
+function record(line: string): Record<string, any> | null {
+  try { const v = JSON.parse(line); return v && typeof v === 'object' && !Array.isArray(v) ? v : null } catch { return null }
+}
+
+/**
+ * Turns from JSONL text. `onlySession`: a Claude file can replay rows of the session it was resumed from; only rows whose
+ * own `sessionId` is this one count (canary C3 precision fix 4). Rows without a sessionId are kept.
+ */
+export function turnsFrom(text: string, provider: LogProvider, onlySession?: string): Turn[] {
+  const out: Turn[] = []
+  const want = onlySession?.toLowerCase()
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    const o = record(line)
+    if (!o) continue
+    const at = typeof o.timestamp === 'string' ? o.timestamp : null
+    if (provider === 'claude' || provider === 'cursor') {
+      if (provider === 'claude') {
+        if (o.type !== 'user' && o.type !== 'assistant') continue
+        if (want && typeof o.sessionId === 'string' && o.sessionId.toLowerCase() !== want) continue
+      }
+      if (o.isSidechain || o.isMeta) continue
+      const m = o.message && typeof o.message === 'object' ? o.message : {}
+      const role = (m.role || o.role || o.type) as string
+      const content = m.content
+      if (typeof content === 'string') { if (!noisy(content)) out.push({ role: role === 'assistant' ? 'assistant' : 'user', text: content, at }); continue }
+      if (!Array.isArray(content)) continue
+      for (const b of content) {
+        if (!b || typeof b !== 'object') continue
+        if (b.type === 'text' && typeof b.text === 'string') {
+          let tx: string = b.text
+          if (provider === 'cursor') {
+            tx = tx.replace(/<timestamp>[\s\S]*?<\/timestamp>\s*/g, '')
+            const q = /<user_query>([\s\S]*?)<\/user_query>/.exec(tx)
+            if (q) tx = q[1]!
+          }
+          if (!noisy(tx)) out.push({ role: role === 'assistant' ? 'assistant' : 'user', text: tx, at })
+        } else if (b.type === 'tool_use') {
+          const input = b.input && typeof b.input === 'object' ? b.input : {}
+          if (b.name === 'TodoWrite' || Array.isArray(input.todos)) out.push({ role: 'todo', text: JSON.stringify(input.todos ?? []).slice(0, 3000), at })
+          else if (b.name === 'AskUserQuestion') out.push({ role: 'ask', text: JSON.stringify(input).slice(0, 1500), at })
+          else out.push({ role: 'tool', text: String(b.name || 'tool'), at })
+        }
+      }
+      continue
+    }
+    const p = o.payload && typeof o.payload === 'object' ? o.payload : {}
+    if (o.type === 'response_item' && p.type === 'message') {
+      const tx = (Array.isArray(p.content) ? p.content : []).map((b: any) => (b && typeof b.text === 'string' ? b.text : '')).join('\n')
+      if ((p.role === 'user' || p.role === 'assistant') && !noisy(tx)) out.push({ role: p.role, text: tx, at })
+    } else if (o.type === 'response_item' && (p.type === 'function_call' || p.type === 'custom_tool_call')) {
+      if (p.name === 'update_plan') out.push({ role: 'todo', text: String(p.arguments ?? '').slice(0, 3000), at })
+      else out.push({ role: 'tool', text: String(p.name || 'tool'), at })
+    }
+  }
+  return out
+}
+
+/** The first line of a Codex rollout says whether it is a child thread (canary C3 precision fix 3). */
+export interface CodexThreadKind { kind: 'thread' | 'guardian' | 'spawn' | 'other_child'; parent?: string }
+export function codexThreadKind(firstLine: string): CodexThreadKind {
+  const meta = record(firstLine)?.payload
+  const source = meta && typeof meta === 'object' ? meta.source : undefined
+  if (!source || typeof source !== 'object' || !('subagent' in source)) return { kind: 'thread' }
+  const sub = (source as any).subagent
+  if (sub && typeof sub === 'object' && sub.thread_spawn && typeof sub.thread_spawn.parent_thread_id === 'string') {
+    return { kind: 'spawn', parent: sub.thread_spawn.parent_thread_id.toLowerCase() }
+  }
+  if (sub && typeof sub === 'object' && sub.other === 'guardian') return { kind: 'guardian' }
+  if (sub === 'guardian') return { kind: 'guardian' }
+  return { kind: 'other_child' }
+}

package/server/lib/work-orchestrator/snapshot.ts

@@ -0,0 +1,87 @@
+/**
+ * 6.83.0 (Phase A, docs/work-orchestrator.md): the Work state COS Control pushes. Control owns the journal; the server
+ * keeps this bounded, versioned copy in `data/work-orchestrator/control-snapshot.json` (0600, atomic). Ids, modes,
+ * statuses and times only: never a prompt, a result or a file name. Out of bounds or malformed is refused whole.
+ */
+import { mkdirSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { atomicWriteFileSync } from '../atomic-fs.js'
+
+export const SNAPSHOT_VERSION = 1
+export const SNAPSHOT_MAX_LINKS = 4000
+export const SNAPSHOT_MAX_RECEIPTS = 4000
+export const SNAPSHOT_MAX_LIVE = 400
+const SID = /^(claude|codex|cursor):[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
+/** A task card (`task:<domain>:<12 hex>`), a meeting card (`meeting:<record id>`) or another kind COS Control adds later. */
+const WORK_ID = /^[a-z][a-z0-9_]{0,30}:[^\u0000-\u001f]{1,250}$/
+const MODES = ['continueSession', 'fork', 'newSession'] as const
+
+export interface SnapshotLink { sessionID: string; workID: string; at: number }
+export interface SnapshotReceipt {
+  id: string; workID: string; mode: typeof MODES[number]; provider: string
+  sessionID: string | null; sourceSessionID: string | null; forkChildID: string | null; status: string; createdAt: number
+}
+export interface SnapshotLiveRow { id: string; title: string; status: string; updatedAt: string | null; busy: boolean; waitingOnUser: boolean; appOwned: boolean; summary: string }
+export interface ControlSnapshot {
+  version: 1; controlVersion: string; sentAt: number; receivedAt: number
+  links: SnapshotLink[]; receipts: SnapshotReceipt[]; live: { checkedAt: number; rows: SnapshotLiveRow[] } | null
+}
+
+const obj = (v: unknown): v is Record<string, any> => !!v && typeof v === 'object' && !Array.isArray(v)
+const str = (v: unknown, n: number): v is string => typeof v === 'string' && v.length <= n && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(v)
+/** Seconds since 1970. A value from Swift's reference date (2001) is moved onto 1970. */
+export const epochSeconds = (v: unknown): number | null => typeof v === 'number' && Number.isFinite(v) && v > 0 ? (v < 1.5e9 ? v + 978_307_200 : v > 1e11 ? v / 1000 : v) : null
+const sidOrNull = (v: unknown): string | null => typeof v === 'string' && SID.test(v.toLowerCase()) ? v.toLowerCase() : null
+
+export function parseSnapshot(v: unknown, now = Date.now()): ControlSnapshot {
+  if (!obj(v) || v.version !== SNAPSHOT_VERSION || !str(v.controlVersion, 40) || !Array.isArray(v.links) || v.links.length > SNAPSHOT_MAX_LINKS
+    || !Array.isArray(v.receipts) || v.receipts.length > SNAPSHOT_MAX_RECEIPTS) throw new Error('invalid_snapshot')
+  const links: SnapshotLink[] = []
+  for (const l of v.links) {
+    const at = epochSeconds(l?.at), sid = sidOrNull(l?.sessionID)
+    if (!obj(l) || !sid || !str(l.workID, 256) || !WORK_ID.test(l.workID) || at === null) throw new Error('invalid_link')
+    links.push({ sessionID: sid, workID: l.workID, at })
+  }
+  const receipts: SnapshotReceipt[] = []
+  for (const r of v.receipts) {
+    const createdAt = epochSeconds(r?.createdAt)
+    if (!obj(r) || !str(r.id, 64) || !str(r.workID, 256) || !WORK_ID.test(r.workID) || !(MODES as readonly unknown[]).includes(r.mode)
+      || !str(r.provider, 20) || !str(r.status, 40) || createdAt === null) throw new Error('invalid_receipt')
+    receipts.push({ id: r.id, workID: r.workID, mode: r.mode, provider: r.provider, sessionID: sidOrNull(r.sessionID),
+      sourceSessionID: sidOrNull(r.sourceSessionID), forkChildID: sidOrNull(r.forkChildID), status: r.status, createdAt })
+  }
+  let live: ControlSnapshot['live'] = null
+  if (v.live != null) {
+    const checkedAt = epochSeconds(v.live?.checkedAt)
+    if (!obj(v.live) || checkedAt === null || !Array.isArray(v.live.rows) || v.live.rows.length > SNAPSHOT_MAX_LIVE) throw new Error('invalid_live')
+    const rows: SnapshotLiveRow[] = []
+    for (const r of v.live.rows) {
+      const id = sidOrNull(r?.id)
+      if (!obj(r) || !id || !str(r.title ?? '', 300) || !str(r.status ?? '', 100) || !str(r.summary ?? '', 2000)) throw new Error('invalid_live_row')
+      if (isGuardianRow(id, r.title ?? '', r.summary ?? '')) continue
+      rows.push({ id, title: r.title ?? '', status: r.status ?? '', updatedAt: str(r.updatedAt, 40) ? r.updatedAt : null,
+        busy: r.busy === true, waitingOnUser: r.waitingOnUser === true, appOwned: r.appOwned === true, summary: r.summary ?? '' })
+    }
+    live = { checkedAt, rows }
+  }
+  return { version: 1, controlVersion: v.controlVersion, sentAt: epochSeconds(v.sentAt) ?? now / 1000, receivedAt: now / 1000, links, receipts, live }
+}
+
+/** Codex guardian review threads (canary C3: 17 in the live list) are never offered as work sessions. */
+export function isGuardianRow(id: string, title: string, summary: string): boolean {
+  return id.startsWith('codex:') && (title.trim() === 'Guardian review' || summary.startsWith('The following is the Codex agent history'))
+}
+
+export class SnapshotStore {
+  private current: ControlSnapshot | null = null
+  constructor(private readonly path: string) {
+    try { const v = JSON.parse(readFileSync(path, 'utf8')); this.current = parseSnapshot(v, (v?.receivedAt ?? 0) * 1000) } catch { this.current = null }
+  }
+  get(): ControlSnapshot | null { return this.current }
+  put(snapshot: ControlSnapshot): void {
+    this.current = snapshot
+    try { mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 }); atomicWriteFileSync(this.path, JSON.stringify(snapshot)) } catch (e) {
+      console.warn(`[work-orchestrator] snapshot kept in memory only: ${(e as Error).message}`)
+    }
+  }
+}