@gotcos/glasses-server 6.81.0 → 6.83.0

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
+}

package/server/scripts/work-lens-rounds-mutation-gate.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Lens plans mutation gate (6.83.0: lens rounds in Work chat history, Send this plan). Mutations run only in a disposable copy of server/ and shared/; the live
+// checkout is never rewritten. Same proof as the autonomous-save gate:
+//   0. The target suites are GREEN unmutated (a gate over a red suite proves nothing).
+//   1. Each target string appears EXACTLY ONCE in its file.  2. The mutated file differs.
+//   3. A NAMED test fails ("FAIL  server/x.test.ts > name"); a build error or harness failure is not a kill.
+//   4. The file is restored byte for byte before the next mutant.
+// Usage: node server/scripts/work-lens-rounds-mutation-gate.mjs [--list | --check] [name…]
+import { mkdtempSync, cpSync, readFileSync, writeFileSync, symlinkSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { resolve, join, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+const tests = [
+  'server/routes/work-lens-rounds.test.ts',
+  'server/routes/work-chat.test.ts',
+]
+const LR = 'server/lib/work-lens-rounds.ts', RR = 'server/routes/work-lens-rounds.ts', WR = 'server/routes/work-chat.ts'
+const EXPECTED_SURVIVORS = new Set([])
+const mutations = [
+  // The record body.
+  ['lr-v-gate', LR, "  if (v.v !== 1) throw invalid('v')\n", ''],
+  ['lr-workid', LR, "  if (!str(v.workID, 256) || !WORK_ID.test(v.workID)) throw invalid('workID')\n", ''],
+  ['lr-question-bound', LR, "  if (!str(v.question, LENS_QUESTION_CHARS) || !v.question.trim()) throw invalid('question')\n", ''],
+  ['lr-answer-bound', LR, "if (!str(v.answer, LENS_ANSWER_CHARS)) throw invalid('answer')", "if (typeof v.answer !== 'string') throw invalid('answer')"],
+  ['lr-source-lens', LR, "  if (v.source !== 'lens') throw invalid('source')\n", ''],
+  ['lr-ids-in-order', LR, "a.id !== `a${i + 1}`", "typeof a.id !== 'string'"],
+  ['lr-continue-needs-session', LR, "  if (mode !== 'newSession' && !(str(a.sessionID, 64) && SID.test(a.sessionID))) throw invalid('assignments.sessionID')\n", ''],
+  ['lr-new-session-provider', LR, "mode === 'newSession' ? !['claude', 'codex'].includes(a.provider)", "mode === 'newSession' ? false"],
+  ['lr-prompt-bound', LR, "!str(a.prompt, LENS_PROMPT_CHARS)", "typeof a.prompt !== 'string'"],
+  ['lr-assignment-cap', LR, "!Array.isArray(v.assignments) || v.assignments.length > WORK_CHAT_MAX_ASSIGNMENTS) throw invalid('assignments')", "!Array.isArray(v.assignments)) throw invalid('assignments')"],
+  // Plan stale.
+  ['lr-stale-size', LR, "return after.length !== before.size || after.some(s => !before.has(s))", "return after.some(s => !before.has(s))"],
+  ['lr-stale-members', LR, "return after.length !== before.size || after.some(s => !before.has(s))", "return after.length !== before.size"],
+  ['lr-stale-own-excluded', LR, "  const after = now.filter(s => !own.has(s))\n", "  const after = now\n"],
+  ['lr-stale-unknown', LR, "  if (!round.cardSessions || !now) return false\n", ''],
+  ['lr-card-fork-source', LR, "if (r.sessionID && !(r.mode === 'fork' && r.sessionID === r.sourceSessionID)) out.add(r.sessionID)", "if (r.sessionID) out.add(r.sessionID)"],
+  ['lr-card-fork-child', LR, "    if (r.forkChildID) out.add(r.forkChildID)\n", ''],
+  // Outcomes, expiry and bounds.
+  ['lr-outcome-partly', LR, "  if (sent > 0) return 'partly_sent'\n", ''],
+  ['lr-outcome-stopped', LR, "  if (states.every(s => s === 'stopped')) return 'stopped'\n", ''],
+  ['lr-outcome-failed', LR, "return states.every(s => s === 'refused' || s === 'stopped') ? 'refused' : 'failed'", "return 'refused'"],
+  // COS Control's own Send on the Mac (QA 6.10.651 blocker: a later lens send must never deliver twice).
+  ['lr-already-held', LR, "const ALREADY: readonly AssignmentState[] = ['sent', 'delivered', 'held']", "const ALREADY: readonly AssignmentState[] = ['sent', 'delivered']"],
+  ['lr-already-lists-ids', LR, "{ assignmentIds: r.assignments.map(a => a.id).filter(sentAlready) }", "{}"],
+  ['lr-mac-records', LR, "    r.mac = { at: now, ids: [...new Set([...(r.mac?.ids ?? []), ...results.map(x => x.id)])] }\n", ''],
+  ['lr-mac-view', LR, "  if (r.mac && (!send || r.mac.at >= send.requestedAt)) {", "  if (false) {"],
+  ['lr-mac-partial', LR, "    if (state === 'sent' && r.mac.ids.length < r.assignments.length) state = 'partly_sent'\n", ''],
+  ['rr-local-mac', RR, "    local(req)\n    const round = deps.store.reportMac", "    const round = deps.store.reportMac"],
+  ['lr-settle-terminal', LR, "if (states.every(s => TERMINAL.includes(s)))", "if (true)"],
+  ['lr-pickup-expiry', LR, "now - send.requestedAt > LENS_SEND_PICKUP_MS", "false"],
+  ['lr-report-timeout', LR, "now - send.pickedUpAt > LENS_SEND_REPORT_MS", "false"],
+  ['lr-ttl', LR, "const kept = this.file.rounds.filter(r => now - r.recordedAt <= LENS_ROUND_TTL_MS)", "const kept = this.file.rounds"],
+  ['lr-cap-200', LR, "    while (this.file.rounds.length > LENS_ROUNDS_MAX) {", "    while (false) {"],
+  ['lr-cap-keeps-active', LR, "this.file.rounds.splice(idle >= 0 ? idle : 0, 1)", "this.file.rounds.splice(0, 1)"],
+  ['lr-idempotent', LR, "    if (existing) return { round: existing, created: false }\n", ''],
+  ['lr-unreadable-aside', LR, "      try { renameSync(path, aside) } catch { /* nothing to move */ }\n", ''],
+  ['lr-test-store-in-memory', LR, "process.env.VITEST || process.env.NODE_ENV === 'test' ? null : ", ''],
+  // Send rules.
+  ['lr-in-progress', LR, "    if (this.active(r)) throw new LensRoundError('send_in_progress', 409, 'This plan is already being sent.')\n", ''],
+  ['lr-already-sent', LR, "if (!ids.length || ids.some(sentAlready))", "if (!ids.length)"],
+  ['lr-whole-plan-skips-sent', LR, ".map(a => a.id).filter(id => !sentAlready(id))", ".map(a => a.id)"],
+  ['lr-confirm-required', LR, "if (body.confirm !== 'two-step' && !r.autoSendCard)", "if (false)"],
+  ['lr-auto-send-card', LR, "if (body.confirm !== 'two-step' && !r.autoSendCard)", "if (body.confirm !== 'two-step')"],
+  ['lr-control-required', LR, "    if (!checks.controlConnected) throw new LensRoundError('control_not_connected', 423,", "    if (false) throw new LensRoundError('control_not_connected', 423,"],
+  ['lr-stop-control-required', LR, "    if (!controlConnected) throw new LensRoundError('control_not_connected', 423, 'COS Control is not connected. Stop it from the Mac.')\n", ''],
+  ['lr-fresh-60s', LR, "connected: age <= LENS_CONTROL_FRESH_MS", "connected: true"],
+  // The inbox.
+  ['lr-pickup-once', LR, "s.state === 'send_requested') { s.state = 'sending';", "(s.state === 'send_requested' || s.state === 'sending')) { s.state = 'sending';"],
+  ['lr-stop-once', LR, "if (room > 0 && s.pickedUpAt === null)", "if (room > 0)"],
+  ['lr-inbox-cap', LR, "let room = LENS_INBOX_MAX, changed = false", "let room = Infinity, changed = false"],
+  ['lr-inbox-since', LR, "!r.inHistory && r.seq > since", "!r.inHistory"],
+  ['lr-inbox-history', LR, "!r.inHistory && r.seq > since", "r.seq > since"],
+  ['lr-report-picked-up', LR, "    if (send.state === 'send_requested' || send.state === 'expired') throw new LensRoundError('send_not_picked_up'", "    if (false) throw new LensRoundError('send_not_picked_up'"],
+  ['lr-view-hides-prompts', LR, "assignments: r.assignments.map(a => ({ id: a.id, state: a.state,", "assignments: r.assignments.map(a => ({ id: a.id, prompt: a.prompt, state: a.state,"],
+  // Routes.
+  ['rr-known-work', RR, "      if (!known) throw new LensRoundError('unknown_work', 404,", "      if (false) throw new LensRoundError('unknown_work', 404,"],
+  ['rr-known-snapshot-first', RR, "    if (s && (s.links.some(l => l.workID === workID) || s.receipts.some(r => r.workID === workID))) return true\n", ''],
+  ['rr-body-cap', RR, "> LENS_ROUND_BODY_BYTES) {", "> Infinity) {"],
+  ['rr-201-vs-200', RR, "res.status(created ? 201 : 200)", "res.status(201)"],
+  ['rr-admissions', RR, "    if (!deps.admissions()) return res.status(503).json(MAINTENANCE)\n", ''],
+  ['rr-lease-maintenance', RR, "    try { lease = deps.lease() } catch { return res.status(503).json(MAINTENANCE) }", "    lease = deps.lease()"],
+  ['rr-lease-released', RR, ".finally(() => lease.release())", ""],
+  ['rr-local-inbox', RR, "      local(req)\n      const { since, autoSend } = req.query", "      const { since, autoSend } = req.query"],
+  ['rr-local-history', RR, "    local(req)\n    const roundId = roundIdOf(req)\n    const b = req.body", "    const roundId = roundIdOf(req)\n    const b = req.body"],
+  ['rr-local-result', RR, "    local(req)\n    const id = String(req.params.sendRequestId", "    const id = String(req.params.sendRequestId"],
+  ['rr-card-sessions-at-send', RR, "cardSessions: cardSessionsOf(deps.snapshot(), round.workID), controlConnected", "cardSessions: null, controlConnected"],
+  ['rr-card-sessions-at-record', RR, "deps.store.record(input, cardSessionsOf(deps.snapshot(), input.workID))", "deps.store.record(input, null)"],
+  ['rr-history-autosend', RR, "    const round = deps.store.markInHistory(roundId, b.autoSendCard)", "    const round = deps.store.markInHistory(roundId, undefined)"],
+  ['rr-inbox-autosend', RR, "deps.store.inbox(since === undefined ? 0 : Number(since), autoSend === '1')", "deps.store.inbox(since === undefined ? 0 : Number(since), false)"],
+  // The capability.
+  ['wr-lens-plans-capability', WR, ",\n    lensPlans:1,lensPlansControl:deps.lensPlansControl()}))", "}))"],
+]
+
+const args = process.argv.slice(2)
+if (args.includes('--list')) { for (const [name] of mutations) console.log(name); process.exit(0) }
+const names = args.filter(a => !a.startsWith('--'))
+const selected = names.length ? mutations.filter(([name]) => names.includes(name)) : mutations
+if (names.length && selected.length !== names.length) throw new Error('Unknown mutation name in: ' + args.join(' '))
+if (args.includes('--check')) {
+  let bad = 0
+  for (const [name, file, find, replacement] of mutations) {
+    const text = readFileSync(join(root, file), 'utf8'), count = text.split(find).length - 1
+    if (count !== 1 || find === replacement) { bad++; console.log(`${name}: ${count} matches in ${file}${find === replacement ? ' (no change)' : ''}`) }
+  }
+  console.log(`${mutations.length - bad} of ${mutations.length} targets unique`); process.exit(bad ? 1 : 0)
+}
+const scratch = mkdtempSync(join(tmpdir(), 'work-lens-rounds-mutations-'))
+try {
+  const skip = new Set(['data', 'models', 'certs', 'node_modules'])
+  cpSync(join(root, 'server'), join(scratch, 'server'), { recursive: true, filter: src => !(skip.has(basename(src)) && dirname(src) === join(root, 'server')) })
+  cpSync(join(root, 'shared'), join(scratch, 'shared'), { recursive: true })
+  cpSync(join(root, 'bin'), join(scratch, 'bin'), { recursive: true })
+  cpSync(join(root, 'vitest.config.ts'), join(scratch, 'vitest.config.ts'))
+  cpSync(join(root, 'package.json'), join(scratch, 'package.json'))
+  symlinkSync(join(root, 'node_modules'), join(scratch, 'node_modules'), 'dir')
+  const run = () => spawnSync(process.execPath, [join(root, 'node_modules/vitest/vitest.mjs'), 'run', '--maxWorkers=1', ...tests], {
+    cwd: scratch,
+    env: { PATH: process.env.PATH, HOME: scratch, COS_DATA_DIR: join(scratch, 'data'), COS_PROFILE_PATH: join(scratch, 'data', 'profile.json'),
+      COS_MAINTENANCE_GATE_PATH: join(scratch, 'gate', 'maintenance-gate.json') },
+    encoding: 'utf8', timeout: 300000,
+  })
+  const baseline = run()
+  if (baseline.status !== 0) throw new Error('Baseline failed; a gate over a red suite proves nothing:\n' + baseline.stdout + '\n' + baseline.stderr)
+  const totals = /Tests\s+(\d+) passed/.exec(baseline.stdout)
+  console.log(`baseline PASS (${totals ? totals[1] : '?'} tests in ${tests.length} files)`)
+  const survived = []
+  for (const [name, file, find, replacement] of selected) {
+    const target = join(scratch, file), original = readFileSync(target, 'utf8')
+    if (original.split(find).length !== 2) throw new Error(`Mutation ${name} does not match exactly once in ${file}`)
+    // A function replacement: `$&` and `$1` in a mutant are literal text, never replace() patterns.
+    const mutated = original.replace(find, () => replacement)
+    if (mutated === original) throw new Error(`Mutation ${name} did not change ${file}`)
+    writeFileSync(target, mutated)
+    const result = run(), output = result.stdout + '\n' + result.stderr
+    writeFileSync(target, original)
+    if (readFileSync(target, 'utf8') !== original) throw new Error(`Restore failed for ${file} after ${name}`)
+    const killers = [...new Set([...output.matchAll(/FAIL\s+(server\/\S+\.test\.ts > [^\n]+)/g)].map(m => m[1].trim()))]
+    if (result.status === 0 || result.error || !killers.length) {
+      const expected = EXPECTED_SURVIVORS.has(name) && result.status === 0
+      if (!expected) survived.push(name)
+      console.log(`${name} ${expected ? 'SURVIVED (expected, documented)' : 'SURVIVED'}${result.error ? ' (harness: ' + result.error.message + ')' : ''}`); continue
+    }
+    console.log(`${name} KILLED by ${killers.slice(0, 2).join(' | ')}${killers.length > 2 ? ` (+${killers.length - 2} more)` : ''}`)
+  }
+  const expectedCount = selected.filter(([n]) => EXPECTED_SURVIVORS.has(n)).length
+  console.log(`${selected.length - survived.length - expectedCount} of ${selected.length} lens-plans mutations killed by a named test; ${expectedCount} expected survivors`)
+  if (survived.length) { console.log('SURVIVED: ' + survived.join(', ')); process.exitCode = 1 }
+} finally { rmSync(scratch, { recursive: true, force: true }) }