@gotcos/glasses-server 6.82.0 → 6.84.0

package/server/routes/transcribe-stream.ts

@@ -1,7 +1,7 @@
 import { MacParakeetUnavailableError, transcribeMacParakeet } from '../lib/mac-recording-asr.js'
 import { getMeetingStore } from '../lib/meeting-store.js'
 import { appendAutonomousSaveLog, getStopIntentStore, savedChunkReplay, type StopIntent } from '../lib/meeting-stop-intents.js'
-import { MAC_AUDIO, MAC_CAPTURE_ID, persistMacChunkReceipt, macError, registerMacRecording, requireMacRecording, readMacRecording, validateMacWav } from '../lib/mac-recording.js'
+import { MAC_AUDIO, MAC_CAPTURE_ID, closeMacRecording, persistMacChunkReceipt, macError, registerMacRecording, requireMacRecording, readMacRecording, validateMacWav } from '../lib/mac-recording.js'
 import { AUTO_ENROLL_THRESHOLD } from '../lib/voiceprint-floor.js'
 import { readSpeakerPolicy, policyLabel, type SpeakerMode } from '../lib/meeting-speaker-policy.js'
 // POST /api/transcribe-stream — Streaming transcription for continuous meeting capture
@@ -15,7 +15,8 @@ import { chmodSync, readFileSync, writeFileSync, existsSync, lstatSync, mkdirSyn
 import { writeFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { getVocabulary, getOwnerName, getOwnerSpeakerLabel } from '../lib/profile.js'
+import { getVocabulary, getOwnerName, getOwnerSpeakerLabel, getWhisperCorrections } from '../lib/profile.js'
+import { decoderContextWindow } from '../lib/glossary-learn.js'
 import { getOpenAIKey } from '../lib/openai-key.js'
 import { getTranscriptionPolicySnapshot, isOpenAIWhisperFallbackReady } from '../lib/transcription-policy.js'
 import { STRANDED_STALE_MS } from '../lib/stranded-sessions.js'
@@ -81,12 +82,14 @@ import {
 } from '../lib/even-hub-speaker-role.js'
 import { archiveSessionAudio, runMeetingAudioRetention } from '../lib/meeting-audio-archive.js'
 import {
+  DISCARDED_RETENTION_MS,
   countChunkWavs,
   listUnsavedCaptures,
   purgeExpiredQuarantine,
   quarantineSessionAudio,
   readCaptureDisposition,
   sweepOrphanedSessionAudio,
+  type QuarantineReceipt,
 } from '../lib/unsaved-audio-quarantine.js'
 import {
   STALE_ACTIVE_SESSION_DIR_NAME,
@@ -1728,11 +1731,14 @@ export function getMeetingSessionStatus(sessionId: string, now = Date.now()): Me
   }
 }
 
+/** 6.83.2: a close that quarantines under its own reason, clock and terminal receipt (the Mac discard). */
+type CloseQuarantine = { reason: string; retentionMs?: number; receipt?: QuarantineReceipt }
+
 function closeTranscriptSession(
   sessionId: string,
   reason: ClosedTranscriptSession['reason'],
-  options: { preserveAudio?: boolean } = {},
-): void {
+  options: { preserveAudio?: boolean; quarantine?: CloseQuarantine } = {},
+): string | null {
   // Progressive HQ is disposable cache state. Every terminal session path —
   // save, expiry, quarantine, or abandonment — must release the single owner.
   void stopProgressiveHqSession(sessionId)
@@ -1751,7 +1757,7 @@ function closeTranscriptSession(
     maxChunkIndex,
     reason,
   })
-  finishClosingTranscriptSession(sessionId, { ...options, closeReason: reason })
+  return finishClosingTranscriptSession(sessionId, { ...options, closeReason: reason })
 }
 
 /** Delete session after save */
@@ -1759,10 +1765,11 @@ export function deleteSession(sessionId: string, options: { preserveAudio?: bool
   closeTranscriptSession(sessionId, 'saved', options)
 }
 
+/** Where a close put the session's chunk audio (the quarantine dir), or null when it moved none. */
 function finishClosingTranscriptSession(
   sessionId: string,
-  options: { preserveAudio?: boolean; closeReason?: ClosedTranscriptSession['reason'] },
-): void {
+  options: { preserveAudio?: boolean; closeReason?: ClosedTranscriptSession['reason']; quarantine?: CloseQuarantine },
+): string | null {
   sessions.delete(sessionId)
   sessionAudioBytes.delete(sessionId)
   sessionAudioWrites.delete(sessionId)
@@ -1794,6 +1801,7 @@ function finishClosingTranscriptSession(
     if (countChunkWavs(audioDir) > 0) {
       const target = quarantineSessionAudio(audioDir, 'close_saved_residual_chunks')
       if (target) console.warn(`[transcribe-stream] Saved-close left chunk audio behind; quarantined: ${sessionId} → ${target}`)
+      return target
     } else {
       try { rmSync(audioDir, { recursive: true, force: true }) } catch {}
     }
@@ -1801,13 +1809,114 @@ function finishClosingTranscriptSession(
     // Any non-saved close (expired, error, …) with chunk audio still on disk
     // is an unsaved capture. Quarantine it — never delete evidence (6.19.0).
     if (countChunkWavs(audioDir) > 0) {
-      const target = quarantineSessionAudio(audioDir, `close_${options.closeReason ?? 'unknown'}`)
+      const quarantine = options.quarantine
+      const target = quarantineSessionAudio(audioDir, quarantine?.reason ?? `close_${options.closeReason ?? 'unknown'}`, undefined,
+        quarantine ? { retentionMs: quarantine.retentionMs, receipt: quarantine.receipt } : {})
       if (target) console.warn(`[transcribe-stream] Quarantined unsaved session-audio on close: ${sessionId} → ${target}`)
       else console.error(`[transcribe-stream] Quarantine move failed on close, source retained: ${sessionId}`)
+      return target
     } else {
       try { rmSync(audioDir, { recursive: true, force: true }) } catch {}
     }
   }
+  return null
+}
+
+// ── 6.83.2: discard a stranded Mac capture that holds no sound ─────────────────────
+// Miles, 2026-10-21: Record on Mac captured a 21-minute Zoom call as 211 chunks of exact zeros (macOS returns
+// zeros, not an error, when system audio recording is not allowed). The save refused it (no_speech), and the
+// capture then sat in the stranded list with a Save that can never work. COS Control asks the server to let it go.
+//
+// What it may touch: a Mac capture (Control is its only uploader, so nothing else will send it a chunk) that is in
+// memory, holds NO canonical chunk (no transcribed text, so no speech), has finished ASR on every chunk it received
+// (an in-flight chunk could still become speech), is idle past EMPTY_SESSION_STALE_MS, and has no chunk upload in
+// progress. Anything else is refused and left exactly as it was. The audio is never deleted here: it moves into the
+// existing quarantine with a terminal no_speech receipt and a 24-hour clock (DISCARDED_RETENTION_MS).
+export type MacDiscardRefusal =
+  | 'session_not_found' | 'not_mac_capture' | 'has_speech' | 'asr_in_progress' | 'not_idle' | 'chunk_in_progress'
+
+export interface MacDiscardResult {
+  ok: boolean
+  reason?: MacDiscardRefusal
+  sessionId: string
+  /** The quarantine dir the audio moved into, or null when the capture held no chunk audio. */
+  quarantined: string | null
+  chunkFiles: number
+  receivedCount: number
+  retainedUntil: string | null
+}
+
+export const MAC_DISCARD_IDLE_MS = EMPTY_SESSION_STALE_MS
+
+/** Why a session may not be discarded, or null when it may. Pure over the session's ledger. */
+export function macDiscardRefusal(input: {
+  sessionId: string
+  present: boolean
+  canonicalCount: number
+  receivedIndices: number[]
+  asrCompletedIndices: number[]
+  silentForMs: number
+  chunkInProgress: boolean
+}): MacDiscardRefusal | null {
+  if (!MAC_CAPTURE_ID.test(input.sessionId)) return 'not_mac_capture'
+  if (!input.present) return 'session_not_found'
+  if (input.canonicalCount > 0) return 'has_speech'
+  const completed = new Set(input.asrCompletedIndices)
+  if (input.receivedIndices.some(index => !completed.has(index))) return 'asr_in_progress'
+  if (input.chunkInProgress) return 'chunk_in_progress'
+  if (input.silentForMs < MAC_DISCARD_IDLE_MS) return 'not_idle'
+  return null
+}
+
+export async function discardSilentMacCapture(sessionId: string, options: { now?: number; dryRun?: boolean } = {}): Promise<MacDiscardResult> {
+  const now = options.now ?? Date.now()
+  const refusalFor = () => {
+    const session = sessions.get(sessionId)
+    return {
+      session,
+      refusal: macDiscardRefusal({
+        sessionId,
+        present: !!session,
+        canonicalCount: session ? canonicalIndices(session).length : 0,
+        receivedIndices: session?.receivedIndices ?? [],
+        asrCompletedIndices: session?.asrCompletedIndices ?? [],
+        silentForMs: session ? now - session.lastActivityAt : 0,
+        chunkInProgress: macChunkLocks.has(sessionId),
+      }),
+    }
+  }
+  const empty = (reason: MacDiscardRefusal, receivedCount = 0): MacDiscardResult =>
+    ({ ok: false, reason, sessionId, quarantined: null, chunkFiles: 0, receivedCount, retainedUntil: null })
+  const first = refusalFor()
+  if (first.refusal) return empty(first.refusal, first.session?.receivedIndices?.length ?? 0)
+  if (options.dryRun) {
+    const audioDir = getSessionAudioDirectory(sessionId)
+    return { ok: true, sessionId, quarantined: null, chunkFiles: audioDir ? countChunkWavs(audioDir) : 0,
+      receivedCount: first.session?.receivedIndices?.length ?? 0, retainedUntil: null }
+  }
+  // Every chunk write this session started reaches disk before its directory moves.
+  await drainSessionAudioWrites(sessionId)
+  // Ask again after the await: a chunk may have arrived meanwhile.
+  const second = refusalFor()
+  if (second.refusal) return empty(second.refusal, second.session?.receivedIndices?.length ?? 0)
+  const receivedCount = second.session?.receivedIndices?.length ?? 0
+  const quarantined = closeTranscriptSession(sessionId, 'closed', {
+    quarantine: {
+      reason: 'discarded_no_sound',
+      retentionMs: DISCARDED_RETENTION_MS,
+      receipt: { outcome: 'no_speech', discarded: true, note: 'Discarded from COS Control: no sound was captured. Audio retained until its 24-hour clock clears it.' },
+    },
+  })
+  // A late chunk or a replayed start for this capture answers 410 from here on.
+  closeMacRecording(sessionId)
+  return {
+    ok: true,
+    sessionId,
+    quarantined,
+    chunkFiles: quarantined ? countChunkWavs(quarantined) : 0,
+    receivedCount,
+    retainedUntil: quarantined ? new Date(Date.now() + DISCARDED_RETENTION_MS).toISOString() : null,
+  }
 }
 
 function isIosAsrCandidateEnabled(): boolean {
@@ -1946,7 +2055,13 @@ function recentWhisperContext(sessionId: string, session: TranscriptSession): st
     .map(c => c.text)
     .join(' ')
   const cleanedContext = stripInlineHallucinations(recentText, sessionId)
-  return cleanedContext.length > 250 ? cleanedContext.slice(-250) : cleanedContext
+  // 6.83.1: correction-only forms ("/pricing") go back to speech BEFORE the 250-character cut.
+  return decoderContextWindow(cleanedContext, decoderCorrections()) ?? ''
+}
+
+/** The corrections map for the decoder window; a test double without it reads as none. */
+function decoderCorrections(): Record<string, string> {
+  try { return getWhisperCorrections() } catch { return {} }
 }
 
 function isCrossChunkRepeat(session: TranscriptSession, text: string): boolean {
@@ -2610,7 +2725,9 @@ export function assertMacCaptureComplete(sessionId: string, expectedChunkCount:
 
 // Manual Mac pilot: independent from iPhone candidate and cue rollout gates.
 transcribeStreamRouter.get('/mac-recording/capabilities', (_req, res) => {
-  res.set('Cache-Control', 'private, no-store').json({ available: true, ...MAC_AUDIO, serverInstanceId: getServerInstanceId() })
+  // 6.83.2: `discard` advertises POST /api/meeting/sessions/:id/discard for a stranded no-sound capture. Older
+  // servers omit it, and COS Control then discards only its own local copy and says so.
+  res.set('Cache-Control', 'private, no-store').json({ available: true, ...MAC_AUDIO, serverInstanceId: getServerInstanceId(), discard: true })
 })
 function requireMacPin(req: { get(name: string): string | undefined }): string {
   const pin = req.get('X-COS-Server-Instance')?.trim()

package/server/routes/work-chat.ts

@@ -1,33 +1,76 @@
 import { Router } from 'express'
-import { parseWorkChatInput, parseWorkChatAnswer, WORK_CHAT_SYSTEM, WORK_CHAT_PLANNERS, WORK_CHAT_EFFORTS, WORK_CHAT_DEFAULT_EFFORT,
-  WORK_CHAT_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS, WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS, WORK_CHAT_MAX_ITEMS, WORK_CHAT_MAX_REFERENCES } from '../lib/work-chat.js'
+import { parseWorkChatInput, parseWorkChatAnswer, WORK_CHAT_SYSTEM, WORK_CHAT_ORCHESTRATOR_RULES, WORK_CHAT_PLANNERS, WORK_CHAT_EFFORTS, WORK_CHAT_DEFAULT_EFFORT,
+  WORK_CHAT_OUTPUT_TOKENS, WORK_CHAT_ORCHESTRATOR_OUTPUT_TOKENS, WORK_CHAT_THINKING_TOKENS, WORK_CHAT_DEADLINE_MS, WORK_CHAT_MAX_ASSIGNMENTS, WORK_CHAT_MAX_ITEMS, WORK_CHAT_MAX_REFERENCES,
+  WORK_CHAT_BODY_BYTES, WORK_CHAT_ORCHESTRATOR_BODY_BYTES, type WorkChatInput, type WorkChatAnswer } from '../lib/work-chat.js'
 import { runMeetingAskModel } from '../lib/meeting-ask-runner.js'
 import { acquireMaintenanceWork, maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
-export function createWorkChatRouter(deps = {run:runMeetingAskModel, admissions:maintenanceAdmissionsOpen, lease:()=>acquireMaintenanceWork('work_chat')}) {
+import { appendPlanLog, type PlanLogRow } from '../lib/work-orchestrator/plan-log.js'
+import { PLAN_LOG_PATH } from '../lib/work-orchestrator/runtime.js'
+import { defaultLensRoundStore } from '../lib/work-lens-rounds.js'
+
+/** 6.83.0: one plan's log row. Ids and enums only (plan-log.ts). */
+export function planLogRow(input: WorkChatInput, outcome: PlanLogRow['outcome'], answer: WorkChatAnswer | null, ms: number, now = new Date()): PlanLogRow {
+  return {
+    at: now.toISOString(), workID: input.workID, mode: input.mode, planner: input.planner ?? 'sonnet', effort: input.effort ?? WORK_CHAT_DEFAULT_EFFORT,
+    orchestrator: input.orchestrator === true,
+    sessions: input.sessions.map(s => ({ id: s.id, automatic: s.automatic, ...(s.available !== undefined ? { available: s.available } : {}),
+      ...(s.reason ? { reason: s.reason } : {}), ...(s.discoveredBy ? { discoveredBy: s.discoveredBy } : {}) })),
+    leftOut: (input.leftOut ?? []).map(l => ({ id: l.id, reason: l.reason })),
+    usageAgeSec: Object.fromEntries((input.usage ?? []).map(u => [u.provider, u.ageSec])),
+    usageState: Object.fromEntries((input.usage ?? []).map(u => [u.provider, u.state])),
+    assignments: (answer?.assignments ?? []).map(a => ({ mode: a.mode ?? 'continue', target: a.mode === 'newSession' ? `new:${a.provider}` : a.sessionID ?? '' })),
+    outcome, ms,
+  }
+}
+
+const WORK_CHAT_DEPS = {run:runMeetingAskModel, admissions:maintenanceAdmissionsOpen, lease:()=>acquireMaintenanceWork('work_chat'),
+  planLog:(row: PlanLogRow)=>appendPlanLog(PLAN_LOG_PATH(), row), now:()=>Date.now(),
+  lensPlansControl:()=>defaultLensRoundStore().controlStatus()}
+export function createWorkChatRouter(given: Partial<typeof WORK_CHAT_DEPS> = {}) {
+  // 6.83.0: a caller that passes only some deps (the tests pass run, admissions and lease) gets the rest by default.
+  const deps={...WORK_CHAT_DEPS,...given}
   const router=Router(); let running=false
   router.use('/work/chat', (_req,res,next)=>{res.set('Cache-Control','private, no-store');next()})
   // 6.73.15: queueRounds means sessions may carry openWork, and the planner routes around sessions with earlier work open.
   // references means the input may carry read-only reference sessions (never targets).
-  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',planners:WORK_CHAT_PLANNERS,effort:WORK_CHAT_DEFAULT_EFFORT,efforts:WORK_CHAT_EFFORTS,automaticProviders:['claude','codex'],maxAssignments:WORK_CHAT_MAX_ASSIGNMENTS,contextItems:true,maxContextItems:WORK_CHAT_MAX_ITEMS,queueRounds:true,references:true,maxReferences:WORK_CHAT_MAX_REFERENCES}))
+  // 6.83.0: orchestrator 1 means a client may send the orchestrator input (POST /api/work/orchestrator/input) and get
+  // fork and new-session assignments back (docs/work-orchestrator.md).
+  // 6.83.0: lensPlans 1 means the lens may record a plan into the card's Work chat history and ask COS Control to send
+  // it (routes/work-lens-rounds.ts); lensPlansControl says whether a COS Control polled the lens inbox in the last 60 s.
+  router.get('/work/chat',(_req,res)=>res.json({protocolVersion:1,planner:'sonnet',planners:WORK_CHAT_PLANNERS,effort:WORK_CHAT_DEFAULT_EFFORT,efforts:WORK_CHAT_EFFORTS,automaticProviders:['claude','codex'],maxAssignments:WORK_CHAT_MAX_ASSIGNMENTS,contextItems:true,maxContextItems:WORK_CHAT_MAX_ITEMS,queueRounds:true,references:true,maxReferences:WORK_CHAT_MAX_REFERENCES,orchestrator:1,
+    lensPlans:1,lensPlansControl:deps.lensPlansControl()}))
   router.post('/work/chat',async(req,res)=>{
-    let input
-    try { if (Buffer.byteLength(JSON.stringify(req.body))>100000) throw new Error(); input=parseWorkChatInput(req.body) }
+    let input: WorkChatInput
+    try {
+      const limit=req.body?.orchestrator===true ? WORK_CHAT_ORCHESTRATOR_BODY_BYTES : WORK_CHAT_BODY_BYTES
+      if (Buffer.byteLength(JSON.stringify(req.body))>limit) throw new Error(); input=parseWorkChatInput(req.body)
+    }
     catch {return res.status(400).json({error:'invalid_work_chat'})}
     if (running || !deps.admissions()) return res.status(409).json({error:'work_chat_busy'})
     running=true
+    const started=deps.now()
     let lease: ReturnType<typeof acquireMaintenanceWork> | undefined
+    let outcome: PlanLogRow['outcome']='unavailable', answer: WorkChatAnswer | null=null
     const controller=new AbortController(); const abort=()=>controller.abort()
     res.on('close',abort)
     try {
       lease=deps.lease()
       // Planner and effort select how the model runs; they are not evidence, so they never reach the prompt.
       const {planner='sonnet',effort=WORK_CHAT_DEFAULT_EFFORT,...prompt}=input
-      const out=await deps.run({engine:'claude',model:planner},JSON.stringify(prompt),WORK_CHAT_SYSTEM,controller.signal,undefined,{caller:'work_chat_'+input.mode},
-        {effort,maxOutputTokens:WORK_CHAT_OUTPUT_TOKENS,maxThinkingTokens:WORK_CHAT_THINKING_TOKENS[effort],deadlineMs:WORK_CHAT_DEADLINE_MS})
-      const answer=parseWorkChatAnswer(out.text,input)
+      const orchestrator=input.orchestrator===true
+      const system=orchestrator ? WORK_CHAT_SYSTEM+'\n\n'+WORK_CHAT_ORCHESTRATOR_RULES : WORK_CHAT_SYSTEM
+      const out=await deps.run({engine:'claude',model:planner},JSON.stringify(prompt),system,controller.signal,undefined,{caller:'work_chat_'+input.mode},
+        {effort,maxOutputTokens:orchestrator ? WORK_CHAT_ORCHESTRATOR_OUTPUT_TOKENS : WORK_CHAT_OUTPUT_TOKENS,maxThinkingTokens:WORK_CHAT_THINKING_TOKENS[effort],deadlineMs:WORK_CHAT_DEADLINE_MS})
+      try { answer=parseWorkChatAnswer(out.text,input) } catch (e) { outcome='invalid_answer'; throw e }
+      outcome='planned'
       if (!res.destroyed) return res.json({protocolVersion:1,...answer,model:out.model??`claude:${planner} (requested)`,effort})
-    } catch {if(!res.destroyed) return res.status(503).json({error:'work_chat_unavailable',message:'No assignment was dispatched. Your saved request can be retried.'})}
-    finally {res.off('close',abort);lease?.release();running=false}
+      outcome='aborted'
+    } catch {if (controller.signal.aborted && outcome==='unavailable') outcome='aborted'; if(!res.destroyed) return res.status(503).json({error:'work_chat_unavailable',message:'No assignment was dispatched. Your saved request can be retried.'})}
+    finally {
+      res.off('close',abort);lease?.release();running=false
+      // 6.83.0: every plan is logged, whatever its outcome (plan-log.ts); a log failure never changes the answer.
+      try { deps.planLog(planLogRow(input,outcome,answer,deps.now()-started)) } catch { /* observation only */ }
+    }
   })
   return router
 }

package/server/routes/work-lens-rounds.ts

@@ -0,0 +1,179 @@
+/**
+ * 6.83.0: lens plans in Work chat history, and "Send this plan" (docs/work-orchestrator.md, "Lens plans").
+ *
+ * Lens (over the network, token auth from the parent /api mount):
+ *   POST /api/work/chat/lens-rounds                       record a plan the lens made (idempotent on clientRoundId)
+ *   GET  /api/work/chat/lens-rounds/:roundId              the round's live state, never its prompts
+ *   POST /api/work/chat/lens-rounds/:roundId/send         ask COS Control to send it (two-step confirm, or card Auto-send)
+ *   POST /api/work/chat/lens-rounds/:roundId/stop         ask COS Control to Stop assignments
+ * COS Control (this Mac only):
+ *   GET  /api/work/chat/lens-inbox?since=<cursor>[&autoSend=1]   rounds not yet in history, send and stop requests
+ *   POST /api/work/chat/lens-rounds/:roundId/history      { state: "in_history", autoSendCard? }
+ *   POST /api/work/chat/lens-send/:sendRequestId/result   { assignments: [{ id, state, receiptId?, detail?, sessionID? }] }
+ *   POST /api/work/chat/lens-rounds/:roundId/mac-send     the same shape, for COS Control's own Send of this round on the Mac
+ *
+ * Nothing here sends to a session: COS Control performs every send through its own Send path and reports back.
+ * Every route answers 503 `maintenance` while admissions are closed; writes hold the api_mutation lease themselves
+ * (index.ts leaves these paths to this router so the error code is the contract's).
+ */
+import { Router, type Request, type Response } from 'express'
+import { LensRoundError, LensRoundStore, LENS_ROUND_BODY_BYTES, ROUND_ID, SEND_ID, cardSessionsOf, parseLensRound, parseResultBody,
+  parseSendBody, parseStopBody, roundView, defaultLensRoundStore } from '../lib/work-lens-rounds.js'
+import type { ControlSnapshot } from '../lib/work-orchestrator/snapshot.js'
+import { orchestratorSnapshots } from '../lib/work-orchestrator/runtime.js'
+import { acquireMaintenanceWork, maintenanceAdmissionsOpen } from '../lib/maintenance-lifecycle.js'
+import { isLoopbackRequest } from './work-handoff-requests.js'
+import { listBoard, type TaskBoardRow } from '../lib/task-store.js'
+import { createWorkBoardReader, type WorkBoardReader } from '../lib/work-board-reader.js'
+
+export interface WorkLensRoundsDeps {
+  store: LensRoundStore
+  /** COS Control's Work snapshot (links and receipts), for the card's sessions. */
+  snapshot: () => ControlSnapshot | null
+  /** Whether the workID is a card the server knows: in COS Control's snapshot or on the Work board. Throws when unknowable. */
+  knownWork: (workID: string) => Promise<boolean>
+  admissions: () => boolean
+  lease: () => { release(): void }
+  isLocal: (req: Request) => boolean
+}
+
+/** A card is known when COS Control's snapshot names it, or the Work board (a bounded read, 2 s old at most) lists it. */
+export function knownWorkFrom(snapshot: () => ControlSnapshot | null, board: WorkBoardReader<TaskBoardRow>) {
+  return async (workID: string): Promise<boolean> => {
+    const s = snapshot()
+    if (s && (s.links.some(l => l.workID === workID) || s.receipts.some(r => r.workID === workID))) return true
+    const rows = await board.read(2_000)
+    return rows.some(r => `task:${r.domain}:${r.workIdentity || r.id}` === workID)
+  }
+}
+
+let defaultBoard: WorkBoardReader<TaskBoardRow> | null = null
+const DEFAULTS = (): WorkLensRoundsDeps => ({
+  store: defaultLensRoundStore(),
+  snapshot: () => orchestratorSnapshots().get(),
+  knownWork: knownWorkFrom(() => orchestratorSnapshots().get(), defaultBoard ??= createWorkBoardReader(() => listBoard())),
+  admissions: maintenanceAdmissionsOpen,
+  lease: () => acquireMaintenanceWork('api_mutation'),
+  isLocal: isLoopbackRequest,
+})
+
+const MAINTENANCE = { error: 'maintenance', message: 'The server is updating. The plan is kept on the lens; try again shortly.' }
+
+export function createWorkLensRoundsRouter(given: Partial<WorkLensRoundsDeps> = {}) {
+  const deps: WorkLensRoundsDeps = { ...DEFAULTS(), ...given }
+  const router = Router()
+  router.use(['/work/chat/lens-rounds', '/work/chat/lens-inbox', '/work/chat/lens-send'], (_req, res, next) => {
+    res.set('Cache-Control', 'private, no-store')
+    if (!deps.admissions()) return res.status(503).json(MAINTENANCE)
+    next()
+  })
+  const fail = (res: Response, e: unknown, where: string) => {
+    if (e instanceof LensRoundError) {
+      if (e.status >= 500 || where !== 'record') console.warn(`[work-lens-rounds] ${where}: ${e.status} ${e.code}`)
+      return res.status(e.status).json({ error: e.code, message: e.message, ...e.extra })
+    }
+    console.error(`[work-lens-rounds] ${where} failed: ${e instanceof Error ? e.message : String(e)}`)
+    return res.status(503).json({ error: 'lens_rounds_unavailable', message: 'Lens plans are unavailable. Try again shortly.' })
+  }
+  /** A write holds the api_mutation lease for its own (sub-millisecond) body; a closed gate is `maintenance`. */
+  const write = <T>(res: Response, where: string, fn: () => Promise<T> | T) => {
+    let lease: { release(): void }
+    try { lease = deps.lease() } catch { return res.status(503).json(MAINTENANCE) }
+    return Promise.resolve().then(fn).catch(e => fail(res, e, where)).finally(() => lease.release())
+  }
+  const local = (req: Request) => { if (!deps.isLocal(req)) throw new LensRoundError('local_only', 403, 'Only COS Control on this Mac can do this.') }
+  const roundIdOf = (req: Request) => {
+    const id = String(req.params.roundId ?? '')
+    if (!ROUND_ID.test(id)) throw new LensRoundError('unknown_round', 404, 'This plan is not on the server any more.')
+    return id
+  }
+  const connected = () => deps.store.controlStatus().connected
+
+  router.post('/work/chat/lens-rounds', (req, res) => write(res, 'record', async () => {
+    if (Buffer.byteLength(JSON.stringify(req.body ?? null)) > LENS_ROUND_BODY_BYTES) {
+      return res.status(413).json({ error: 'lens_round_too_large', message: 'This plan is too large to save.' })
+    }
+    const input = parseLensRound(req.body)
+    // A repeat is answered from the store, even when the board has since changed or is unreachable.
+    const replay = deps.store.replay(input.clientRoundId)
+    if (!replay) {
+      let known: boolean
+      try { known = await deps.knownWork(input.workID) }
+      catch { throw new LensRoundError('work_board_unavailable', 503, 'The Work board is unavailable. The plan is kept on the lens; try again shortly.') }
+      if (!known) throw new LensRoundError('unknown_work', 404, 'This card is not on the Work board any more.')
+    }
+    const { round, created } = deps.store.record(input, cardSessionsOf(deps.snapshot(), input.workID))
+    if (created) console.log(`[work-lens-rounds] recorded ${round.roundId} work=${round.workID} assignments=${round.assignments.length}`)
+    return res.status(created ? 201 : 200).json({ roundId: round.roundId, workID: round.workID, state: roundView(round).state, control: { connected: connected() } })
+  }))
+
+  router.get('/work/chat/lens-rounds/:roundId', (req, res) => {
+    try {
+      const round = deps.store.find(roundIdOf(req))
+      if (!round) throw new LensRoundError('unknown_round', 404, 'This plan is not on the server any more.')
+      return res.json(roundView(round))
+    } catch (e) { return fail(res, e, 'status') }
+  })
+
+  router.post('/work/chat/lens-rounds/:roundId/send', (req, res) => write(res, 'send', () => {
+    const roundId = roundIdOf(req)
+    const body = parseSendBody(req.body)
+    const round = deps.store.find(roundId)
+    if (!round) throw new LensRoundError('unknown_round', 404, 'This plan is not on the server any more.')
+    const send = deps.store.requestSend(roundId, body, { cardSessions: cardSessionsOf(deps.snapshot(), round.workID), controlConnected: connected() })
+    console.log(`[work-lens-rounds] send requested ${send.id} round=${roundId} assignments=${send.assignmentIds.join(',')} confirm=${send.confirm ?? 'auto-send'}`)
+    return res.status(202).json({ sendRequestId: send.id, state: 'send_requested' })
+  }))
+
+  router.post('/work/chat/lens-rounds/:roundId/stop', (req, res) => write(res, 'stop', () => {
+    const roundId = roundIdOf(req)
+    const stop = deps.store.requestStop(roundId, parseStopBody(req.body), connected())
+    console.log(`[work-lens-rounds] stop requested ${stop.id} round=${roundId} assignments=${stop.assignmentIds.join(',')}`)
+    return res.status(202).json({ stopRequestId: stop.id, state: 'stop_requested' })
+  }))
+
+  // COS Control: polling this is what the capability reports as connected. Listing a send or a stop picks it up.
+  router.get('/work/chat/lens-inbox', (req, res) => {
+    try {
+      local(req)
+      const { since, autoSend } = req.query
+      if (Object.keys(req.query).some(k => k !== 'since' && k !== 'autoSend')
+        || (since !== undefined && !(typeof since === 'string' && /^\d{1,12}$/.test(since)))
+        || (autoSend !== undefined && autoSend !== '0' && autoSend !== '1')) {
+        throw new LensRoundError('invalid_lens_inbox', 400, 'since is a cursor and autoSend is 0 or 1.')
+      }
+      return res.json(deps.store.inbox(since === undefined ? 0 : Number(since), autoSend === '1'))
+    } catch (e) { return fail(res, e, 'inbox') }
+  })
+
+  router.post('/work/chat/lens-rounds/:roundId/history', (req, res) => write(res, 'history', () => {
+    local(req)
+    const roundId = roundIdOf(req)
+    const b = req.body
+    if (!b || typeof b !== 'object' || Array.isArray(b) || b.state !== 'in_history' || (b.autoSendCard !== undefined && typeof b.autoSendCard !== 'boolean')) {
+      throw new LensRoundError('invalid_lens_round', 400, 'History takes { state: "in_history" }.', { field: 'state' })
+    }
+    const round = deps.store.markInHistory(roundId, b.autoSendCard)
+    return res.json(roundView(round))
+  }))
+
+  // COS Control: it sent assignments of this round with its own Send on the Mac. Same assignments[] shape as a result.
+  router.post('/work/chat/lens-rounds/:roundId/mac-send', (req, res) => write(res, 'mac-send', () => {
+    local(req)
+    const round = deps.store.reportMac(roundIdOf(req), parseResultBody(req.body))
+    const view = roundView(round)
+    console.log(`[work-lens-rounds] mac send round=${round.roundId} state=${view.state} ${view.assignments.map(a => `${a.id}:${a.state}`).join(' ')}`)
+    return res.json(view)
+  }))
+
+  router.post('/work/chat/lens-send/:sendRequestId/result', (req, res) => write(res, 'result', () => {
+    local(req)
+    const id = String(req.params.sendRequestId ?? '')
+    if (!SEND_ID.test(id)) throw new LensRoundError('unknown_send', 404, 'No such send request.')
+    const round = deps.store.report(id, parseResultBody(req.body))
+    const view = roundView(round)
+    console.log(`[work-lens-rounds] result ${id} round=${round.roundId} state=${view.state} ${view.assignments.map(a => `${a.id}:${a.state}`).join(' ')}`)
+    return res.json(view)
+  }))
+  return router
+}

package/server/routes/work-orchestrator.ts

@@ -0,0 +1,71 @@
+/**
+ * 6.83.0 Work orchestrator routes (docs/work-orchestrator.md). Read and plan inputs only: nothing here sends to a
+ * session, changes a link or a receipt, or calls a model.
+ *
+ *   POST /api/work/orchestrator/input  {workID, meetingWorkIDs?, snapshot?}
+ *        Stores Control's snapshot when one is sent (Phase A: Control pushes, the server keeps the copy), then answers
+ *        the card's planner rows, what was left out and why, and the usage snapshot.
+ *   GET  /api/work/orchestrator/usage[?refresh=1]
+ *        The usage snapshot per provider, read on demand: Claude and Codex are re-read when their reading is older than
+ *        10 minutes (`refresh=1`: 2 minutes). No timer reads usage unless COS_WORK_USAGE_POLL=1.
+ */
+import { Router } from 'express'
+import { parseSnapshot, type ControlSnapshot } from '../lib/work-orchestrator/snapshot.js'
+import type { OrchestratorInput } from '../lib/work-orchestrator/input.js'
+import type { UsageMonitor, UsageView } from '../lib/work-orchestrator/usage.js'
+import { orchestratorInputFor, orchestratorSnapshots, orchestratorUsage } from '../lib/work-orchestrator/runtime.js'
+
+const WORK_ID = /^task:[a-z_]+:[a-f0-9]{12}$/
+const MEETING_ID = /^meeting:[^\u0000-\u001f]{1,250}$/
+export const ORCHESTRATOR_BODY_BYTES = 4_000_000
+
+export interface WorkOrchestratorDeps {
+  putSnapshot: (s: ControlSnapshot) => void
+  input: (workID: string, meetingWorkIDs: string[]) => Promise<OrchestratorInput>
+  usage: (refresh: boolean) => Promise<UsageView[]>
+  now: () => number
+}
+
+/** GET /usage reads on demand: a reading older than 10 minutes is re-read (`refresh=1`: 2 minutes). */
+export const readUsage = (refresh: boolean, monitor: UsageMonitor = orchestratorUsage()): Promise<UsageView[]> => monitor.onDemand(refresh)
+
+const DEFAULTS: WorkOrchestratorDeps = {
+  putSnapshot: s => orchestratorSnapshots().put(s),
+  input: orchestratorInputFor,
+  usage: refresh => readUsage(refresh),
+  now: () => Date.now(),
+}
+
+export function createWorkOrchestratorRouter(given: Partial<WorkOrchestratorDeps> = {}) {
+  const deps = { ...DEFAULTS, ...given }
+  const router = Router()
+  router.use('/work/orchestrator', (_req, res, next) => { res.set('Cache-Control', 'private, no-store'); next() })
+  router.post('/work/orchestrator/input', async (req, res) => {
+    const body = req.body
+    const meetings: unknown = body?.meetingWorkIDs ?? []
+    if (!body || typeof body !== 'object' || Object.keys(body).some(k => !['workID', 'meetingWorkIDs', 'snapshot'].includes(k))
+      || typeof body.workID !== 'string' || !WORK_ID.test(body.workID)
+      || !Array.isArray(meetings) || meetings.length > 20 || !meetings.every(m => typeof m === 'string' && MEETING_ID.test(m))) {
+      return res.status(400).json({ error: 'invalid_orchestrator_input' })
+    }
+    if ('snapshot' in body) {
+      if (Buffer.byteLength(JSON.stringify(body.snapshot)) > ORCHESTRATOR_BODY_BYTES) return res.status(413).json({ error: 'snapshot_too_large' })
+      let snapshot: ControlSnapshot
+      try { snapshot = parseSnapshot(body.snapshot, deps.now()) } catch (e) { return res.status(400).json({ error: 'invalid_snapshot', reason: (e as Error).message }) }
+      deps.putSnapshot(snapshot)
+    }
+    try {
+      const input = await deps.input(body.workID, meetings as string[])
+      console.log(`[work-orchestrator] input work=${body.workID} rows=${input.rows.length} discovered=${input.discovered} leftOut=${input.leftOut.length} snapshotAge=${input.snapshotAgeSec ?? '-'}s liveAge=${input.liveListAgeSec ?? '-'}s scan=${input.logScanComplete ? 'complete' : 'partial'}`)
+      return res.json(input)
+    } catch (e) {
+      console.warn(`[work-orchestrator] input failed for ${body.workID}: ${(e as Error).message}`)
+      return res.status(503).json({ error: 'orchestrator_input_unavailable' })
+    }
+  })
+  router.get('/work/orchestrator/usage', async (req, res) => {
+    try { return res.json({ protocolVersion: 1, now: new Date(deps.now()).toISOString(), usage: await deps.usage(req.query.refresh === '1') }) }
+    catch { return res.status(503).json({ error: 'usage_unavailable' }) }
+  })
+  return router
+}