@gotcos/glasses-server 6.80.0 → 6.82.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 6.82.0 - Routines: any COS skill on a schedule, each with its own cap, off switch and breaker
+
+Miles, 2026-10-20 (plan Decision Q4): "Any COS skill on a schedule. Pick a skill, a time and days; each routine has its own cap and off switch." Until now the server had one routine, the morning brief.
+
+- **Client matrix.** Server only in this release. Companion 6.10.650 lists, adds, edits, pauses and runs routines from the phone; older companions and COS Control keep using `/api/morning-brief`, which is unchanged. Nothing runs that a user did not create: a fresh server has the morning brief and no skill routines.
+- **The morning brief is routine #1, unchanged.** Its config file, scheduler, prompt, scheduled submission, `/api/morning-brief` envelope, a rejected PUT and Run now while it runs are pinned by `morning-brief-golden.test.ts`, recorded on the unmodified 6.81.0 base (6b2e70b) before any routine code existed and passing byte for byte after. The only change it sees: its run is counted in the token audit as `routine:morning-brief` instead of `full_query`.
+- **`/api/routines`.** `GET` lists the brief first, then skill routines, each with schedule, next run, gate (why it will not run), breaker state, today's runs against its cap, and its last run. `GET /routines/skills` lists this workspace's skills (`.agents/skills`, `.claude/skills`; labels only, never paths). `POST` creates; `PATCH` (or `PUT`) edits, and `resetBreaker: true` closes an open breaker; `POST /:id/pause` and `/:id/resume`; `DELETE` (the brief can only be turned off: 409 `cannot_delete_brief`); `POST /:id/run` is Run now (202; 409 running, off or skill missing; 423 breaker open, with `openUntil`; 429 capped); `GET /:id/runs` and `/routines/runs` are history. A brief edit through `/api/routines/morning-brief` takes only the brief's own fields and refuses any other (400 `not_a_brief_field`).
+- **A skill routine.** A workspace skill, an optional extra instruction, a time and days in a zone (default the Mac's, weekdays at 08:00), runs a day (default 2, at most 10), a model (default `sonnet`, never left to the user default, never a key lane), and its breaker (default 3 failures, 6 hours). Stored in `data/routines/routines.json`, runs in `data/routines/runs.json` (0600, atomic; a damaged file keeps its good routines and drops the rest). It runs as an ordinary durable job with `origin: { kind: 'routine', id }`, so it survives the phone sleeping and lands in the inbox with a message number. Its prompt says nobody is watching: read and summarise freely, write only the skill's own files, never send, publish, deploy, push, delete or spend; if a source is missing, say so in one line.
+- **How it stops.** Its own switch, and `COS_ROUTINES=0` turns every skill routine off (the brief keeps its own switch). Its daily cap counts scheduled and Run now runs together; a failed submit never ran and is not counted. Every skill routine together is capped at 40 runs a day. The breaker opens after N consecutive failed runs (a failed or interrupted job, or a failed submit) and nothing fires until the cooldown ends; then one trial run is allowed, a success closes it and a failure opens it again. A canceled run counts neither way, and each finished run is counted once however many ticks read it. One scheduled slot per selected day, three submit attempts two minutes apart, crash-resumed by a fixed client id. Inert while Background jobs are off or maintenance is closed, as the brief.
+- **Token audit by caller.** A routine's run is logged as `routine:<id>` (Claude, Codex, Cursor and direct bridges; the runtime passes `auditCaller` only for routine origins, so every other caller is byte for byte what it was).
+- **Checks.** Canary C7 (`server/scripts/routines-canary.ts`, not packaged): on a scratch data dir, a scratch HOME and workspace, an ephemeral port, and a stub `claude` on PATH, two routines fired at their slot on the production 30 s tick; the one whose skill fails exited 1, the breaker counted it, a second failure opened it, Run now answered 423 and the next tick skipped it, the other routine stayed ready, and the token audit row read `routine:<id>` on `sonnet`. Mutation gate `server/scripts/routines-mutation-gate.mjs` (not packaged): green baseline (55 tests in 6 files), 42 of 42 mutants killed, each by a named test. Full suite 8,503 passed, 0 failed, 3 skipped (562 files); `tsc --noEmit` clean. The key-lanes census classifies the three new model sites as Reject.
+
+## 6.81.0 - The Mac saves a stopped meeting on its own once it holds every chunk
+
+Miles, 2026-10-20: "if the application isn't in the foreground, it can fail to save the meetings". Both G2 meetings that day saved only once the phone came back on screen: the phone's Stop needs IndexedDB, and iOS suspends IndexedDB while the companion is hidden (11:19 qbbgyq: Stop 12:43, `stop_blocked`, "Load failed", saved 12:47 by a new WebView; 14:07 mip9qb: Stop 15:13:50, saved 15:14:37 only after the phone was visible). The full map is `docs/meeting-autonomous-save.md`.
+
+- **Client matrix.** Server only. Nothing changes until the companion sends the new Stop (a companion release, not in this one). Older companions never call the new route and save exactly as before.
+- **The phone's Stop, durable.** `POST /api/meeting/sessions/:id/stop` `{finalChunkIndex, serverInstanceId}`: one small fetch a hidden phone can still send. The server pin is required. It is written to `data/meeting-stop-intents.json` (0600, atomic) before the 202, so a restart keeps it. A repeat is idempotent; a higher index raises it, a lower one never lowers it. A Stop behind what the Mac already holds is refused 409 `final_index_behind_server`. It never closes the session and never refuses a chunk.
+- **The Mac saves only a complete capture.** Once every chunk 0..finalChunkIndex has arrived and finished ASR, and 45 s have passed since the Stop and since the last chunk (so a phone on screen saves first), the Mac runs the same save the phone's `POST /meeting/save` runs: one lock, one idempotent receipt. A gap means audio exists only on the phone, so the Mac waits and the late chunks land in the SAME live session. There is no timeout that saves with a gap: a gap that never fills is left to the existing 4 h stranded sweep, unchanged. A chunk past the Stop revokes it (the meeting is still recording). Checked every 15 s while a Stop waits, only while admissions are open and session recovery has run.
+- **The phone coming back.** Status answers `saved` with the receipt; `POST /meeting/save` replays it; and a chunk the phone re-sends because its answer was lost while hidden is answered from the saved sidecar instead of 410, so the phone no longer reads that state as a collision. This replay is only for meetings the Mac saved itself; every other closed session still answers 410.
+- **Telemetry.** `[meeting/auto-save]` lines and `data/meeting-autonomous-save.jsonl`: `stop_received`, `waiting` (once per change, with missing count and sample), `finalized` (chunks, canonical, gaps, waited ms), `phone_saved` (or `client_saved` for an unpinned save such as the stranded sweep's), `phone_confirmed` (how and how long after), `late_replay`, `late_chunk_refused`, `revoked`, `stood_down`, `finalize_failed`. The status route carries `stopIntent` additively. `recording_stop` carries `savedBy: "server"` for the Mac's own saves.
+- **Unchanged.** Transcription engines, the G2 matching thresholds, the restart and maintenance gate semantics, the stranded sweeper, and the save route's answers (its body moved into one shared `performSave`; the mutation gate anchor `cx-6533-save-nothing-to-save` follows it).
+- **Checks.** Full suite 8,462 passed, 0 failed, 3 skipped (557 files); `tsc --noEmit` clean. `server/scripts/autonomous-save-mutation-gate.mjs` (not packaged): green baseline (63 tests in 4 files), 42 of 42 mutants killed, each by a named test. The moved `cx-6533-save-nothing-to-save` anchor re-runs killed. Journeys: phone hidden after Stop (the Mac saves alone), phone back late with missing chunks (merged into one meeting), phone and Mac racing (one meeting), against the real chunk and save routes. Needs the companion release to send the Stop before it does anything on a real phone.
+
 ## 6.80.0 - Answer with your own key (opt in, off by default)
 
 You can now give COS your own provider key (OpenRouter, Anthropic, OpenAI, or a compatible endpoint) and pick a key profile for a thread, so that thread answers on the key instead of your Claude or ChatGPT plan. **This is opt in. Without a key, nothing changes:** with `COS_KEY_LANES` unset or `0`, or with lanes on but no key profile saved, the server answers, spawns and writes exactly as 6.79.1 did. Turning it on and saving keys happens in COS Control on this Mac.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.80.0",
+  "version": "6.82.0",
   "description": "COS Glasses: self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {
@@ -54,6 +54,9 @@
     "!server/scripts/work-search-mutation-gate.mjs",
     "!server/scripts/fact-check-mutation-gate.mjs",
     "!server/scripts/stale-session-mutation-gate.mjs",
+    "!server/scripts/autonomous-save-mutation-gate.mjs",
+    "!server/scripts/routines-mutation-gate.mjs",
+    "!server/scripts/routines-canary.ts",
     "!server/scripts/stt-mutation-gate.mjs",
     "!server/scripts/dictation-stt-mutation-gate.mjs",
     "!server/scripts/pairing-mutation-gate.mjs",

package/server/index.ts

@@ -74,7 +74,7 @@ import { nativeHead, realNativeHeadDeps, registerClaudeTranscriptHint } from './
 import { threadOccupancy, holderActivity } from './lib/thread-occupancy.js'
 import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter, getActiveTranscriptionSessionCount } from './routes/transcribe-stream.js'
-import { meetingRouter, resumeMeetingFinalizationJobs, scheduleTranscriptCleanupSweep, transcriptCleanupRouteDeps } from './routes/meeting.js'
+import { meetingRouter, resumeAutonomousMeetingSaves, resumeMeetingFinalizationJobs, scheduleTranscriptCleanupSweep, transcriptCleanupRouteDeps } from './routes/meeting.js'
 import { createTranscriptCleanupRouter } from './routes/transcript-cleanup.js'
 import { meetingsRouter } from './routes/meetings.js'
 import { openaiCompatRouter } from './routes/openai-compat.js'
@@ -170,6 +170,8 @@ import { listBoard } from './lib/task-store.js'
 import { createDefaultWorkReviewRuntime } from './lib/work-review-backend.js'
 import { createMorningBriefRouter } from './routes/morning-brief.js'
 import { getMorningBriefScheduler, startMorningBriefScheduler, stopMorningBriefScheduler } from './lib/morning-brief-runtime.js'
+import { createRoutinesRouter } from './routes/routines.js'
+import { getRoutineRegistry, routineSkillCatalog, startRoutineScheduler, stopRoutineScheduler } from './lib/routines-runtime.js'
 import {
   initQueryJobRuntime,
   preparePublicDurableQueryAdmission,
@@ -838,6 +840,8 @@ app.use('/api', queryRouter)
 // The scheduled start-of-day brief: settings, status, run-now. Same auth as
 // every other settings route; the brief itself is an ordinary durable job.
 app.use('/api', createMorningBriefRouter(getMorningBriefScheduler))
+// 6.82.0: every routine (the brief first, then skill routines), each with its own cap, switch and breaker.
+app.use('/api', createRoutinesRouter(getRoutineRegistry, routineSkillCatalog))
 app.use('/api', providerProofRouter)
 app.use('/api', transcribeRouter)
 // Ported from cos-glasses-app in 6.24.0. The companion's Sessions tab has been
@@ -1257,6 +1261,7 @@ async function gracefulShutdown(): Promise<void> {
   forceExit.unref?.()
   await meetingAskRuntime.shutdown()
   stopMorningBriefScheduler()
+  stopRoutineScheduler()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
   workHandoffRequestStore?.close()
@@ -1473,6 +1478,8 @@ listenRequiredServers(listeners).then(() => {
     // Resume already-saved meetings whose post-response HQ/operations work
     // was interrupted by a prior server update or process exit.
     resumeMeetingFinalizationJobs()
+    // 6.81.0: Stops the phone sent before the last exit; the server saves them once complete.
+    resumeAutonomousMeetingSaves()
     // 6.77.0: transcript cleanup data whose meeting is gone, and screen text past retention.
     scheduleTranscriptCleanupSweep()
 
@@ -1532,6 +1539,8 @@ listenRequiredServers(listeners).then(() => {
       // that store is ready. Its own tick checks the durable-jobs switch and the
       // maintenance gate, so starting it here is safe when either is off.
       startMorningBriefScheduler()
+      // 6.82.0: skill routines ride the same coordinator and the same gates.
+      startRoutineScheduler()
       void workReviewRuntime?.start().catch(error => console.error('[work-reviews] reconciliation unavailable:', error))
     }).catch(error => {
       // The store remains degraded and rejects admission. Legacy /api/query is

package/server/lib/claude-bridge.ts

@@ -436,6 +436,11 @@ export interface CallOptions {
   dispatch?: { restricted: true; tools: readonly string[] }
   /** 6.58.2: `claude --name` for a session this COS session starts fresh (QueryJobRequest.sessionName). */
   sessionName?: string
+  /**
+   * 6.82.0: the token-audit `caller` for this run, so a server-started job is counted by who started
+   * it (`routine:morning-brief`, `routine:routine-<id>`). Absent, every bridge writes the caller it always did.
+   */
+  auditCaller?: string
   /**
    * 6.78.0 Messages steer: the job's steer port. Present only when the coordinator decided the
    * run is steerable (lib/claude-steer.ts). Absent, every argument and every stdin byte is the
@@ -927,7 +932,7 @@ export async function callClaudeStreaming(
       inputChars: inputEstimate,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       ...keyAuditFields,
       ...keyUsdFields,
     })

package/server/lib/codex-bridge.ts

@@ -817,7 +817,7 @@ export async function callCodexStreaming(
       inputChars: systemPrompt.length + fullQuery.length + contextPrompt.length,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       ...keyAuditFields,
       ...keyUsdFields,
     })

package/server/lib/cursor-bridge.ts

@@ -528,7 +528,7 @@ export async function callCursorStreaming(
       inputChars: systemPrompt.length + fullQuery.length + contextPrompt.length,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       turnId: options?.turnId,
       runId: run.runId,
       sessionId: sid,

package/server/lib/direct-bridge.ts

@@ -564,7 +564,7 @@ export async function callDirectStreaming(
       inputChars: messages.reduce((n, m) => n + (typeof m.content === 'string' ? m.content.length : 0), 0),
       outputChars: text.length,
       durationMs: Date.now() - startTime,
-      caller: 'direct_query',
+      caller: options?.auditCaller ?? 'direct_query',
       ...(options?.turnId ? { turnId: options.turnId } : {}),
       runId: run.runId,
       sessionId: sid,

package/server/lib/meeting-autonomous-finalize.ts

@@ -0,0 +1,267 @@
+// The server finishes a stopped G2 meeting on its own (6.81.0).
+//
+// Miles, 2026-10-20: "if the application isn't in the foreground, it can fail to save the
+// meetings". Once the phone has told the server its meeting stopped (lib/meeting-stop-
+// intents.ts) and the server holds every chunk it captured, nothing is left that needs the
+// phone, so the server runs the same save the phone would have run. The phone, when it
+// comes back on screen, finds a saved meeting and adopts the receipt.
+//
+// THE ONE RULE: NEVER SAVE A CAPTURE THAT IS NOT COMPLETE. The server saves on its own only
+// when its ledger holds every index 0..N (N = the phone's last captured index) and every one
+// of them has finished ASR. A gap means audio exists only on the phone, so the server waits
+// and the session stays live: the phone's late upload lands in the SAME session (the merge)
+// and the next check saves. There is no shorter timeout that saves with the gap, because a
+// save closes the session, and a chunk that arrives after the close is refused (410) and the
+// phone reads "server closed, local audio pending" as a collision it cannot resolve: the
+// meeting splits or the tail is lost. A gap that never fills is handed to the existing
+// stranded sweeper at its existing 4 h horizon, exactly as before this release. Waiting
+// costs only time; saving early costs audio.
+//
+// Why a settle delay as well: a phone that is on screen saves within a few seconds of Stop.
+// The server stands back for AUTONOMOUS_FINALIZE_SETTLE_MS after the Stop and after the last
+// chunk arrived, so a healthy phone's own save is the normal path and the server's is the
+// fallback. Both racing is safe anyway (one save lock, an idempotent save route), but not
+// racing is quieter.
+
+import type { StopIntent } from './meeting-stop-intents.js'
+
+/** Quiet time after the Stop and after the last chunk before the server saves on its own. */
+export const AUTONOMOUS_FINALIZE_SETTLE_MS = 45_000
+/** How often a waiting Stop is checked again. Cheap: an in-memory ledger read. */
+export const AUTONOMOUS_FINALIZE_POLL_MS = 15_000
+/** Missing indices kept in a log line. */
+const MISSING_SAMPLE = 8
+
+export interface SessionLedger {
+  state: 'active' | 'closed' | 'missing'
+  received: readonly number[]
+  asrCompleted: readonly number[]
+  maxChunkIndex: number
+  /** ms since epoch of the last chunk arrival, or null. */
+  lastActivityAt: number | null
+}
+
+export type AutonomousWaitReason = 'settling' | 'missing_chunks' | 'asr_pending' | 'session_unknown' | 'saving' | 'not_ready'
+export type AutonomousStandDownReason = 'already_saved' | 'closed_unsaved' | 'nothing_captured' | 'server_instance_mismatch'
+
+export type AutonomousDecision =
+  | { action: 'finalize'; chunks: number }
+  | { action: 'wait'; reason: AutonomousWaitReason; missing: number[]; missingCount: number; retryInMs: number }
+  | { action: 'revoke'; reason: 'chunk_beyond_final'; maxChunkIndex: number }
+  | { action: 'stand_down'; reason: AutonomousStandDownReason }
+
+function missingFrom(finalIndex: number, have: readonly number[]): { sample: number[]; count: number } {
+  const present = new Set(have)
+  const sample: number[] = []
+  let count = 0
+  for (let index = 0; index <= finalIndex; index++) {
+    if (present.has(index)) continue
+    count++
+    if (sample.length < MISSING_SAMPLE) sample.push(index)
+  }
+  return { sample, count }
+}
+
+/**
+ * What to do with a waiting Stop right now. Pure: every input is passed in.
+ *
+ * Order matters and each step is pinned by a test: a saved meeting is never saved again, a
+ * chunk past the Stop means the meeting is still recording (revoke, never save), and only a
+ * complete, fully transcribed, quiet capture is saved.
+ */
+export function decideAutonomousFinalize(input: {
+  intent: Pick<StopIntent, 'finalChunkIndex' | 'receivedAt'>
+  ledger: SessionLedger
+  now: number
+  alreadySaved: boolean
+  saving: boolean
+}): AutonomousDecision {
+  const { intent, ledger, now } = input
+  if (input.alreadySaved) return { action: 'stand_down', reason: 'already_saved' }
+  if (input.saving) return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  // A session closed WITHOUT a save receipt (expired, quarantined) is the stranded and
+  // quarantine paths' to finish. Saving here would race them.
+  if (ledger.state === 'closed') return { action: 'stand_down', reason: 'closed_unsaved' }
+  if (intent.finalChunkIndex < 0) return { action: 'stand_down', reason: 'nothing_captured' }
+  // The server holds audio the phone says it never captured: the phone resumed after this
+  // Stop, or the Stop is stale. Either way the meeting may still be recording.
+  if (ledger.maxChunkIndex > intent.finalChunkIndex) {
+    return { action: 'revoke', reason: 'chunk_beyond_final', maxChunkIndex: ledger.maxChunkIndex }
+  }
+  // An offline capture: the Stop arrived before any chunk did. Wait for the upload.
+  if (ledger.state === 'missing') {
+    return { action: 'wait', reason: 'session_unknown', missing: [], missingCount: intent.finalChunkIndex + 1, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const absent = missingFrom(intent.finalChunkIndex, ledger.received)
+  if (absent.count > 0) {
+    return { action: 'wait', reason: 'missing_chunks', missing: absent.sample, missingCount: absent.count, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const pending = missingFrom(intent.finalChunkIndex, ledger.asrCompleted)
+  if (pending.count > 0) {
+    return { action: 'wait', reason: 'asr_pending', missing: pending.sample, missingCount: pending.count, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+  }
+  const quietSince = Math.max(intent.receivedAt, ledger.lastActivityAt ?? 0)
+  const settleLeft = quietSince + AUTONOMOUS_FINALIZE_SETTLE_MS - now
+  if (settleLeft > 0) {
+    return { action: 'wait', reason: 'settling', missing: [], missingCount: 0, retryInMs: Math.min(settleLeft, AUTONOMOUS_FINALIZE_POLL_MS) }
+  }
+  return { action: 'finalize', chunks: intent.finalChunkIndex + 1 }
+}
+
+/** Expand `[start, end]` ranges (the status route's shape) into indices. */
+export function indicesFromRanges(ranges: ReadonlyArray<readonly [number, number]>): number[] {
+  const out: number[] = []
+  for (const [start, end] of ranges) for (let index = start; index <= end; index++) out.push(index)
+  return out
+}
+
+export type AutonomousSaveOutcome =
+  | { ok: true; filename: string; sidecarPath: string; chunkCount: number; canonicalCount: number; missingIndices: number[] }
+  | { ok: false; status: number; reason: string }
+
+export interface AutonomousFinalizerDeps {
+  waiting(): StopIntent[]
+  get(sessionId: string): StopIntent | null
+  update(sessionId: string, patch: Partial<StopIntent>): void
+  ledger(sessionId: string): SessionLedger
+  alreadySaved(sessionId: string): boolean
+  saving(sessionId: string): boolean
+  save(intent: StopIntent): Promise<AutonomousSaveOutcome>
+  /** Maintenance admissions open AND durable session recovery has run. */
+  ready(): boolean
+  now(): number
+  /** Returns a cancel function. Production timers are unref'd so they never hold the process. */
+  schedule(fn: () => void, ms: number): () => void
+  log(event: string, fields: Record<string, unknown>): void
+}
+
+export interface AutonomousFinalizer {
+  /** Check one session now (a Stop arrived, a boot). Never throws. */
+  check(sessionId: string, trigger: string): Promise<AutonomousDecision | null>
+  /** Check every waiting Stop, then re-arm while any remain. */
+  tick(trigger?: string): Promise<void>
+  /** Make sure a tick is scheduled. */
+  arm(ms?: number): void
+}
+
+export function createAutonomousFinalizer(deps: AutonomousFinalizerDeps): AutonomousFinalizer {
+  const inFlight = new Set<string>()
+  let cancel: (() => void) | null = null
+  let armedFor = Infinity
+
+  const arm = (ms = AUTONOMOUS_FINALIZE_POLL_MS) => {
+    const due = deps.now() + Math.max(0, ms)
+    if (cancel && armedFor <= due) return
+    cancel?.()
+    armedFor = due
+    cancel = deps.schedule(() => {
+      cancel = null
+      armedFor = Infinity
+      void finalizer.tick('poll')
+    }, Math.max(0, ms))
+  }
+
+  const check = async (sessionId: string, trigger: string): Promise<AutonomousDecision | null> => {
+    if (inFlight.has(sessionId)) return null
+    const intent = deps.get(sessionId)
+    if (!intent || intent.state !== 'waiting') return null
+    // A boot behind a closed maintenance gate has not adopted the persisted sessions yet,
+    // so "the server holds no chunks" is not evidence of anything. Wait, never decide.
+    if (!deps.ready()) {
+      return { action: 'wait', reason: 'not_ready', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+    }
+    inFlight.add(sessionId)
+    try {
+      const now = deps.now()
+      const decision = decideAutonomousFinalize({
+        intent,
+        ledger: deps.ledger(sessionId),
+        now,
+        alreadySaved: deps.alreadySaved(sessionId),
+        saving: deps.saving(sessionId),
+      })
+      if (decision.action === 'stand_down') {
+        // A save the phone (or anyone) already made is the phone's save, not ours.
+        deps.update(sessionId, decision.reason === 'already_saved'
+          ? { state: 'saved', savedBy: intent.savedBy ?? 'phone', savedAt: intent.savedAt ?? now }
+          : { state: 'stood_down', reason: decision.reason })
+        deps.log('stood_down', { sessionId, reason: decision.reason, trigger, waitedMs: now - intent.receivedAt })
+        return decision
+      }
+      if (decision.action === 'revoke') {
+        deps.update(sessionId, { state: 'revoked', reason: decision.reason })
+        deps.log('revoked', { sessionId, reason: decision.reason, finalChunkIndex: intent.finalChunkIndex, maxChunkIndex: decision.maxChunkIndex, trigger })
+        return decision
+      }
+      if (decision.action === 'wait') {
+        const last = intent.lastWait
+        // One line per change of state, not one per poll.
+        if (!last || last.reason !== decision.reason || last.missingCount !== decision.missingCount) {
+          deps.update(sessionId, { lastWait: { reason: decision.reason, missingCount: decision.missingCount, missingSample: decision.missing, at: now } })
+          deps.log('waiting', { sessionId, reason: decision.reason, missingCount: decision.missingCount, missingSample: decision.missing, finalChunkIndex: intent.finalChunkIndex, trigger })
+        }
+        return decision
+      }
+      const outcome = await deps.save(intent)
+      const at = deps.now()
+      if (outcome.ok) {
+        deps.update(sessionId, {
+          state: 'saved', savedBy: 'server', savedAt: at,
+          filename: outcome.filename, sidecarPath: outcome.sidecarPath,
+          chunkCount: outcome.chunkCount, canonicalCount: outcome.canonicalCount, lastWait: null,
+        })
+        deps.log('finalized', {
+          sessionId, reason: 'stop_received_complete', trigger,
+          finalChunkIndex: intent.finalChunkIndex, chunks: outcome.chunkCount, canonical: outcome.canonicalCount,
+          gaps: outcome.missingIndices.length, filename: outcome.filename,
+          waitedMs: at - intent.receivedAt, phoneConfirmed: false,
+        })
+        return decision
+      }
+      // The phone saved between the decision and the lock: its save, not ours.
+      if (outcome.reason === 'already_saved') {
+        deps.update(sessionId, { state: 'saved', savedBy: 'phone', savedAt: at, lastWait: null })
+        deps.log('stood_down', { sessionId, reason: 'already_saved', trigger, waitedMs: at - intent.receivedAt })
+        return { action: 'stand_down', reason: 'already_saved' }
+      }
+      // The phone pinned another server instance: this Mac is not where it meant to save.
+      if (outcome.reason === 'server_instance_mismatch') {
+        deps.update(sessionId, { state: 'stood_down', reason: outcome.reason })
+        deps.log('stood_down', { sessionId, reason: outcome.reason, trigger })
+        return { action: 'stand_down', reason: 'server_instance_mismatch' }
+      }
+      // The phone's own save holds the lock: it wins, and the next check reads its receipt.
+      if (outcome.status === 409 && outcome.reason === 'save_in_progress') {
+        return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+      }
+      // Nothing to save (every chunk was silence): the phone's own Stop says so on the lens.
+      if (outcome.status === 404) {
+        deps.update(sessionId, { state: 'stood_down', reason: outcome.reason })
+        deps.log('stood_down', { sessionId, reason: outcome.reason, trigger })
+        return { action: 'stand_down', reason: 'nothing_captured' }
+      }
+      deps.log('finalize_failed', { sessionId, status: outcome.status, reason: outcome.reason, trigger })
+      return { action: 'wait', reason: 'saving', missing: [], missingCount: 0, retryInMs: AUTONOMOUS_FINALIZE_POLL_MS }
+    } catch (error) {
+      deps.log('finalize_failed', { sessionId, status: 500, reason: error instanceof Error ? error.message.slice(0, 200) : 'error', trigger })
+      return null
+    } finally {
+      inFlight.delete(sessionId)
+    }
+  }
+
+  const finalizer: AutonomousFinalizer = {
+    check,
+    async tick(trigger = 'poll') {
+      let soonest = Infinity
+      for (const intent of deps.waiting()) {
+        const decision = await check(intent.sessionId, trigger)
+        if (decision?.action === 'wait') soonest = Math.min(soonest, decision.retryInMs)
+        else if (decision === null && deps.get(intent.sessionId)?.state === 'waiting') soonest = Math.min(soonest, AUTONOMOUS_FINALIZE_POLL_MS)
+      }
+      if (Number.isFinite(soonest)) arm(soonest)
+    },
+    arm,
+  }
+  return finalizer
+}