@gotcos/glasses-server 6.99.20 → 6.99.29

package/server/routes/agent-session-bindings.ts

@@ -98,7 +98,7 @@
 import type { FenceRecord } from '../lib/thread-fence-store.js'
 import { defaultPidStartProbe, fenceLiveness, type FenceLiveness, type FenceLivenessDeps } from '../lib/fence-liveness.js'
 import { Router, type Request, type Response } from 'express'
-import { createHash, randomUUID } from 'node:crypto'
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
 import {
   threadOccupancy,
   type Occupancy,
@@ -131,7 +131,9 @@ import { isValidNativeThreadId } from '../lib/native-thread-id.js'
 import { FORK_PROVIDER_FAILURES, type ForkProviderFailure } from '../lib/fork-thread.js'
 import { CLIENT_FORK_ID_RE, ForkJobLedger, type ForkJobRow } from '../lib/fork-job-ledger.js'
 import { PEER_VERIFY_TIMEOUT_MS } from '../lib/session-peer-inbox.js'
+import { attachmentsDigest, FOOTER_LINE_REFUSED_COPY, hasFooterShapedLine, QUEUED_TURN_TAMPERED_COPY, sealMatches, TURN_CARRY_HEADER, TURN_ID_IN_USE_COPY, unvouched, type G2TurnProvenance, type OriginVerdict, type QueueSeal } from '../lib/g2-turn-provenance.js'
 import { KEYED_SESSION_REFUSAL } from '../lib/keyed-sessions.js'
+import { associateTurnAttachments, composeTurnPrompt, parseTurnAttachmentIds, TURN_ATTACHMENT_COPY, turnAttachmentManifest, type TurnAttachmentStore } from '../lib/session-turn-attachments.js'
 import {
   CANCEL_QUEUE_HOLD_MS,
   CLIENT_CANCEL_ID_RE,
@@ -318,6 +320,13 @@ export type AttachedTurnResult =
   | { ok: boolean; delivery: 'not_attempted' | 'aborted' | 'ambiguous' | 'delivered' | 'cancelled' }
 
 export interface AgentSessionBindingsDeps {
+  /**
+   * G2 authority Tier 1, with web origin (6.99.29): where each turn came from. With it, every turn
+   * and fork this router hands to a session is ledgered, and a VERIFIED glasses or phone turn
+   * carries the one verify footer line (a Control Web turn is recorded, never vouched or footed).
+   * Footer-shaped words and reused turn ids are refused. Absent: the 6.99.28 behaviour, byte for byte.
+   */
+  provenance?: G2TurnProvenance
   /** Shared fence state. Omit and the router owns a private one, which is correct
    *  for tests and wrong for the server -- see the wiring note at its use site. */
   guard?: TargetGuard
@@ -437,6 +446,11 @@ export interface AgentSessionBindingsDeps {
    * and before the claim; a hit is replayed, never sent again. Absent: 6.77 behaviour.
    */
   turnReceipt?: (provider: string, nativeThreadId: string, clientTurnId: string, prompt: string) => TurnReceipt | null
+  /**
+   * 11/07 (Control Web attach): the media store a turn's `attachmentIds` resolve against. Absent: the real store
+   * (lib/session-turn-attachments.ts). Tests pass a fake. Never read for a turn without files.
+   */
+  turnAttachmentStore?: TurnAttachmentStore
 
   /**
    * 6.78.0 (COS_SESSION_STEER): could a turn go INTO this thread's running turn? Added to an
@@ -2601,10 +2615,13 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (typeof cosSessionId !== 'string' || !COS_SESSION_ID_RE.test(cosSessionId)) {
         return refuseFork('invalid_request')
       }
-      const prompt = body.prompt
-      if (typeof prompt !== 'string' || prompt.trim().length === 0 || prompt.length > maxPromptChars) {
+      const words = body.prompt
+      if (typeof words !== 'string' || words.trim().length === 0 || words.length > maxPromptChars) {
         return refuseFork('invalid_request')
       }
+      // 6.99.27: a fork's first turn takes files as a turn does (the message written with them, sent to the copy).
+      const forkFiles = parseTurnAttachmentIds(body.attachmentIds)
+      if (!forkFiles.ok) return refuseFork('invalid_request')
       // 6.63.0: optional. With it, the fork answers 202 once every gate has passed and runs
       // in the background; without it, the route behaves exactly as before.
       const clientForkId = body.clientForkId
@@ -2628,6 +2645,28 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         if (known) return known.source === forkSource ? replayForkJob(known) : refuseFork('invalid_request')
       }
 
+      // After the replay (a known fork sends nothing), before the workspace, the claim and the spawn: where each file is
+      // on this Mac goes under the words. Without files the prompt is the words, untouched. Nothing is kept yet: the
+      // files are associated only once this fork holds its claim (below, QA 6.99.27).
+      const forkComposed = await composeTurnPrompt(words, forkFiles.ids, {
+        maxChars: maxPromptChars,
+        ...(deps.turnAttachmentStore ? { store: deps.turnAttachmentStore } : {}),
+      })
+      if (!forkComposed.ok) {
+        return refuseFork('invalid_request', { reasonCopy: TURN_ATTACHMENT_COPY[forkComposed.code], attachmentError: forkComposed.code })
+      }
+      const prompt = forkComposed.prompt
+      // G2 authority Tier 1 (QA 6.99.29): only the server writes a verify footer. Words (or a file
+      // name) carrying anything footer-shaped are refused before anything is spawned.
+      if (deps.provenance && hasFooterShapedLine(prompt)) {
+        return refuseFork('invalid_request', { retryable: false, error: 'footer_line_refused', reasonCopy: FOOTER_LINE_REFUSED_COPY })
+      }
+      // A client fork id this server already holds a turn record for is never reused (a new id
+      // would overwrite that record). A repeat of this same fork was replayed above.
+      if (deps.provenance && typeof clientForkId === 'string' && deps.provenance.holds(clientForkId)) {
+        return refuseFork('invalid_request', { retryable: false, error: 'turn_id_in_use', reasonCopy: TURN_ID_IN_USE_COPY })
+      }
+
       const now = readNow()
       if (now === null) return refuseFork('fork_failed')
 
@@ -2636,7 +2675,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       let cwd: string | null = null
       try {
         // 6.62.0: may answer later (a Cursor IDE composer's folder is read from Cursor's own
-        // store). Still before the claim below, which stays the last synchronous step.
+        // store). Before the claim below, whose check and set stay one synchronous call.
         cwd = await resolveWorkspace(providerParam, threadIdParam)
       } catch (error) {
         console.error(`[agent-session-bindings] fork workspace resolve threw: ${error instanceof Error ? error.message : error}`)
@@ -2649,9 +2688,10 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         return refuseFork('fork_workspace_unresolvable')
       }
 
-      // LAST SYNCHRONOUS STATEMENT BEFORE THE FIRST AWAIT. One fork per source
-      // thread at a time: this route spawns a provider CLI, and without a claim a
-      // client retry loop spawns one child per request with nothing bounding it.
+      // Check and set in ONE synchronous call (awaits above, the workspace read and the
+      // files, come before it; nothing may sit between the check and the set). One fork
+      // per source thread at a time: this route spawns a provider CLI, and without a claim
+      // a client retry loop spawns one child per request with nothing bounding it.
       // A DISTINCT key namespace from the turn claim, so a fork can never block a
       // continuation or be blocked by one — `targetKey` is length-prefixed and
       // therefore unambiguous, and this prefix cannot collide with one.
@@ -2665,6 +2705,13 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       }
       claimedForkKey = forkKey
 
+      // QA 6.99.27 (Skeptic W2): the files are kept with this fork only now that it holds the claim and every gate
+      // has passed, before the job is recorded or anything is spawned. A file that went in the meantime refuses here.
+      if (forkFiles.ids.length > 0) {
+        const kept = await associateTurnAttachments(forkFiles.ids, `session-fork:${typeof clientForkId === 'string' ? clientForkId : mintId()}`, deps.turnAttachmentStore)
+        if (!kept.ok) return refuseFork('invalid_request', { reasonCopy: TURN_ATTACHMENT_COPY[kept.code], attachmentError: kept.code })
+      }
+
       if (typeof clientForkId === 'string') {
         // Recorded BEFORE the spawn and before the 202: a job the ledger cannot hold would
         // have an outcome nobody can read, so it does not start.
@@ -2686,12 +2733,26 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         console.log(`[agent-session-bindings] fork accepted provider=${providerParam} background=true`)
       }
 
+      // G2 authority Tier 1: a fork is a turn too, ledgered. Its id is the client's fork id, or one
+      // minted here; the target is the SOURCE thread (the copy's id is not known until it ran). The
+      // hash covers the prompt as composed (words plus any files block). Never vouched (below).
+      let forkPrompt = prompt
+      if (deps.provenance) {
+        // 6.99.29 (Codex audit of e4758a6): the record names the SOURCE session, never the fork child
+        // that actually receives the words, and the child has no binding yet. Until a destination
+        // binding exists, a forked turn is recorded UNVERIFIED for the child: no footer, ever.
+        const forkVerdict = unvouched(deps.provenance.originOf(req), 'fork_destination_unbound')
+        const forkTurnId = typeof clientForkId === 'string' ? clientForkId : `fork-${randomBytes(12).toString('hex')}`
+        forkPrompt = deps.provenance.footed(prompt, forkTurnId, forkVerdict, providerParam)
+        deps.provenance.record({ turnId: forkTurnId, prompt, verdict: forkVerdict, provider: providerParam, sessionId: threadIdParam, via: 'fork', fork: true })
+      }
+
       let raw: unknown
       try {
         raw = await fork({
           provider: providerParam,
           nativeThreadId: threadIdParam,
-          prompt,
+          prompt: forkPrompt,
           cwd,
           // Text-only, same as the attached path. A fork runs a real model turn
           // against a workspace the user did not hand us explicitly.
@@ -2973,10 +3034,13 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // an empty one, and must not fall through as a turn with no claims to check.
       if (body === null) return refuseTurn('invalid_request')
 
-      const prompt = body.prompt
-      if (typeof prompt !== 'string' || prompt.trim().length === 0 || prompt.length > maxPromptChars) {
+      const words = body.prompt
+      if (typeof words !== 'string' || words.trim().length === 0 || words.length > maxPromptChars) {
         return refuseTurn('invalid_request')
       }
+      // 11/07: files with the turn, as media-store ids. Absent is the old turn; a bad list refuses it whole.
+      const attachIds = parseTurnAttachmentIds(body.attachmentIds)
+      if (!attachIds.ok) return refuseTurn('invalid_request')
       const epoch = body.epoch
       if (!Number.isInteger(epoch) || (epoch as number) < 1) return refuseTurn('invalid_request')
       const claimedTargetKey = body.targetKey
@@ -3014,6 +3078,59 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         return
       }
 
+      // 11/07: the files' paths on this Mac go under the words HERE, after the ledger replay (a replayed turn sends
+      // nothing) and before the receipt (which matches the transcript against what was actually sent). Without files
+      // the prompt is the words, untouched. A file that cannot be read refuses the turn before anything is sent. The
+      // files are kept with the turn only after the claim and the gates (before the pin, below; QA 6.99.27).
+      const composed = await composeTurnPrompt(words, attachIds.ids, {
+        maxChars: maxPromptChars,
+        ...(deps.turnAttachmentStore ? { store: deps.turnAttachmentStore } : {}),
+      })
+      if (!composed.ok) {
+        return refuseTurn('invalid_request', { reasonCopy: TURN_ATTACHMENT_COPY[composed.code], attachmentError: composed.code })
+      }
+      const prompt = composed.prompt
+      // G2 authority Tier 1 (QA 6.99.29): only the server writes a verify footer. Words (or a file
+      // name) carrying anything footer-shaped are refused here, before any gate, claim or hop.
+      if (deps.provenance && hasFooterShapedLine(prompt)) {
+        return refuseTurn('invalid_request', { retryable: false, error: 'footer_line_refused', reasonCopy: FOOTER_LINE_REFUSED_COPY })
+      }
+
+      // G2 authority Tier 1 (6.99.29 port, with web origin): who said this, and the exact text the
+      // session will see. A turn the queue drains re-enters over loopback with a single-use carry
+      // token naming the origin captured when it was parked (bound to the WORDS it parked, before
+      // any files block); anything else is judged by its own socket, its token and its cookie.
+      // `prompt` stays the unfooted text: the receipts, the turn ledger and the queue evidence
+      // compare against it, and the transcript readers take the footer off before they compare.
+      const provenance = deps.provenance
+      let turnVerdict: OriginVerdict | null = null
+      let turnCarried = false
+      /** The seal a vouched queued turn carries; checked against the files here and the binding below. */
+      let turnSeal: QueueSeal | null = null
+      if (provenance) {
+        // A carry marks the queue's own drain of a parked turn: it carries the parked origin while
+        // one is held (else none, and the hop is judged as the local call it is) and is the one
+        // caller allowed to add to that turn's record.
+        const carried = provenance.takeCarry(req.headers[TURN_CARRY_HEADER], clientTurnId, words)
+        turnCarried = carried !== null
+        turnVerdict = carried?.verdict ?? provenance.originOf(req)
+        turnSeal = carried?.seal ?? null
+      }
+      // 6.99.29 (Codex audit of e4758a6): the queue file holds MUTABLE attachment ids, and the drain
+      // composes them into the text this turn vouches for. A carried seal names the manifest (each id
+      // with its content hash) the origin was given for; files that differ now refuse the turn.
+      if (turnSeal !== null) {
+        const files = attachIds.ids.length === 0 ? { ok: true as const, manifest: [] } : await turnAttachmentManifest(attachIds.ids, deps.turnAttachmentStore)
+        if (!files.ok || attachmentsDigest(files.manifest) !== turnSeal.attachments) {
+          console.warn(`[agent-session-bindings] queued turn seal mismatch (files) turnId=${turnId} clientTurnId=${clientTurnId}`)
+          return refuseTurn('invalid_request', { retryable: false, error: 'queued_turn_tampered', reasonCopy: QUEUED_TURN_TAMPERED_COPY })
+        }
+      }
+      /** Ledgered once the text did, or may have, reached a session. Hash of the text WITHOUT the footer. */
+      const ledgerTurn = (via: string, provider: string, sessionId: string): void => {
+        if (provenance && turnVerdict && clientTurnId !== null) provenance.record({ turnId: clientTurnId, prompt, verdict: turnVerdict, provider, sessionId, via: turnCarried ? `drain-${via}` : via, continues: turnCarried })
+      }
+
       // 6.78.0: RECEIPTS, before any gate, claim, pin or hop. The ledger above is dropped
       // with its binding and records nothing for a pre-202 `live_unverified`; a crash after
       // the pin leaves no record at all. The receipt covers those (target-scoped attempt
@@ -3074,6 +3191,22 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (!isBindableProvider(binding.provider) || !isValidNativeThreadId(binding.nativeThreadId)) {
         return refuseTurn('binding_unusable')
       }
+      // G2 authority Tier 1 (QA 6.99.29): a turn id this server already holds a record for is never
+      // reused for a different turn (it would overwrite that record: a denial of service on a
+      // vouched turn). An identical retry is not reuse, and the queue's own drain (a carry) continues
+      // its turn while that turn is still parked; never over a delivered record.
+      // ...and the seal names the provider and thread it was parked for: a drain into any other
+      // binding is refused, never delivered under the parked origin.
+      if (turnSeal !== null && !sealMatches(turnSeal, { provider: binding.provider, threadId: binding.nativeThreadId, attachments: turnSeal.attachments })) {
+        console.warn(`[agent-session-bindings] queued turn seal mismatch (target) turnId=${turnId} clientTurnId=${clientTurnId}`)
+        return refuseTurn('invalid_request', { retryable: false, error: 'queued_turn_tampered', reasonCopy: QUEUED_TURN_TAMPERED_COPY })
+      }
+      if (provenance && turnVerdict && provenance.reusesTurnId(clientTurnId, { prompt, verdict: turnVerdict, provider: binding.provider, sessionId: binding.nativeThreadId }, { continues: turnCarried })) {
+        return refuseTurn('invalid_request', { retryable: false, error: 'turn_id_in_use', reasonCopy: TURN_ID_IN_USE_COPY })
+      }
+      // Footed HERE, once the binding names the harness the text goes into: the footer's verify
+      // command carries that provider (Codex re-audit of 910eb90). Every delivery below uses this text.
+      const deliveredPrompt = provenance && turnVerdict ? provenance.footed(prompt, clientTurnId, turnVerdict, binding.provider) : prompt
 
       const key = binding.targetKey
       const fenced = guard.fencedReason(key)
@@ -3082,9 +3215,10 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         return refuseTurn(fenced, { retryable: false, deliveryState: 'unknown' })
       }
 
-      // LAST SYNCHRONOUS STATEMENT BEFORE THE FIRST AWAIT. Check-and-set in one
-      // call: with an await between them, two turns admitted in the same tick both
-      // see a free target and both deliver.
+      // Check-and-set in ONE synchronous call. Awaits come before it (the files above,
+      // QA 6.99.27) and after it, never between the check and the set: with an await
+      // between them, two turns admitted in the same tick both see a free target and
+      // both deliver.
       if (!guard.tryClaim(key, turnId)) return refuseTurn('native_turn_in_progress')
       claimedKey = key
       // 6.53.0: cancellable from here, with the claim. Same key, same lifetime.
@@ -3137,6 +3271,14 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         guard.acknowledgeHead(bindingId, head.digest)
       }
 
+      // QA 6.99.27 (Skeptic W2): the files are kept with this turn only now, with the claim held and every gate
+      // passed, and before the pin and any hop. A turn refused above keeps nothing past the 4 hour staged TTL.
+      if (attachIds.ids.length > 0) {
+        const kept = await associateTurnAttachments(attachIds.ids, `session-turn:${clientTurnId}`, deps.turnAttachmentStore)
+        stage('files')
+        if (!kept.ok) return refuseTurn('invalid_request', { reasonCopy: TURN_ATTACHMENT_COPY[kept.code], attachmentError: kept.code })
+      }
+
       // A failed pin is FATAL, per the registry's own caller contract: an unpinned
       // binding can expire or be detached mid-turn, which defeats the lease.
       // 6.78.0: the pin names its client turn (COS_PIN_BOOT_REAP) and opens the attempt
@@ -3184,7 +3326,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           live = await deps.deliverLiveTurn({
             provider: binding.provider,
             sessionId: binding.nativeThreadId,
-            prompt,
+            prompt: deliveredPrompt,
             verifyTimeoutMs: LIVE_VERIFY_BUDGET_MS,
             clientTurnId,
           })
@@ -3204,6 +3346,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           const latched = latchedHere()
           if (latched) settleLatchedCancel(latched, binding.provider, binding.nativeThreadId, 'reached', { prompt, sentAt: handOffAt })
           console.log(`[agent-session-bindings] turn delivered live provider=${binding.provider} turnId=${turnId} bindingId=${bindingId} verifiedBy=${live.verifiedBy ?? 'unknown'} pid=${live.pid ?? 'null'}`)
+          ledgerTurn('live', binding.provider, binding.nativeThreadId)
           respond(200, {
             turnId,
             outcome: 'completed',
@@ -3222,6 +3365,8 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           // 6.53.3: something MAY be in the session and the person asked for it to stop: arm
           // the marker as for a landed turn, and settle this turn as cancelled, never as a
           // retryable hold that the queue would send again after the cancel's two minutes.
+          // The text MAY be in the session, footer and all: a record, so a verify finds it.
+          ledgerTurn('live-unverified', binding.provider, binding.nativeThreadId)
           const latched = latchedHere()
           if (latched) {
             settleLatchedCancel(latched, binding.provider, binding.nativeThreadId, 'maybe', { prompt, sentAt: handOffAt })
@@ -3263,7 +3408,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           live = await deps.deliverCodexLiveTurn({
             provider: binding.provider,
             sessionId: binding.nativeThreadId,
-            prompt,
+            prompt: deliveredPrompt,
             foreignHolder: true,
           })
         } catch (error) {
@@ -3278,6 +3423,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           // 6.53.3: queued in the Codex app, which only the app can stop ("Stop it there").
           const latched = latchedHere()
           if (latched) settleLatchedCancel(latched, binding.provider, binding.nativeThreadId, 'reached', { prompt, sentAt: handOffAt, busy: busyCodexHop })
+          ledgerTurn('codex-live', binding.provider, binding.nativeThreadId)
           console.log(`[agent-session-bindings] turn delivered live provider=codex turnId=${turnId} bindingId=${bindingId} verifiedBy=${live.verifiedBy ?? 'unknown'} queuedId=${live.queuedId ?? 'null'}`)
           respond(200, {
             turnId,
@@ -3320,6 +3466,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           // delivery is: ambiguous, ledgered (a replay answers the same), and fenced until
           // a person looks at the Codex app's queue and releases it.
           if (live === null || live.reason === 'unverified') {
+            ledgerTurn('codex-live-unverified', binding.provider, binding.nativeThreadId)
             guard.fence(key, 'native_target_fenced', {
               provider: binding.provider,
               headBefore: head.digest,
@@ -3373,6 +3520,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       let delivery: Delivery
       deliveryAttempted = true
       spawnMay = true
+      ledgerTurn('spawn', binding.provider, binding.nativeThreadId)
       try {
         const result = await deliver({
           turnId,
@@ -3383,7 +3531,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           workspaceFingerprint: binding.workspaceFingerprint,
           sourceFingerprint: binding.sourceFingerprint,
           expectedNativeHead: head.raw,
-          prompt,
+          prompt: deliveredPrompt,
           abortSignal: cancelController.signal,
           // 6.62.0 /qa (Q3): only a client that shows `continue_note` gets Cursor Run Everything.
           continueNoteAck: continueNoteAcknowledged(req.headers[CONTINUE_NOTE_HEADER]),

package/server/routes/agent-sessions.ts

@@ -83,6 +83,8 @@ import { cosSpawnedPids } from '../lib/agent-session-ownership-store.js'
 import { sessionActFactsFor, sessionActFields } from '../lib/session-act-fields.js'
 import { CONTINUE_NOTE_HEADER, continueNoteAcknowledged } from '../lib/continue-plan.js'
 
+import { agentSessionOutputImages } from '../lib/agent-session-output-images.js'
+
 export const agentSessionsRouter = Router()
 
 function boundedInteger(value: unknown, fallback: number, min: number, max: number): number {
@@ -236,7 +238,7 @@ export function withRunning<T extends { session_id: string }>(entry: T, scan: Oc
     // clears on its own when the work stops. Still a display hint, never a gate.
     // 6.62.0: or the engine's own hooks (or a Codex rollout) say a turn is open and the
     // last event is inside HOOK_ACTIVE_CAP_MS (plan 1.1-1.3).
-    running_active: decides ? hint!.active : occ?.activeRecently === true || hint?.active === true,
+    running_active: decides || hint?.activeDecides === true ? hint!.active : occ?.activeRecently === true || hint?.active === true,
   }
 }
 
@@ -254,14 +256,22 @@ export function withRunning<T extends { session_id: string }>(entry: T, scan: Oc
  *                                             and an Esc with no Stop looks the same, QA W8);
  *                                             Claude and Codex: no hint (occupancy answers)
  *   hook waiting                               running, not active
+ *   hook or registry idle (Claude, Codex)      not active even if the file was just written
+ *                                             (a flush after Stop), unless the transcript's
+ *                                             newest record is more than
+ *                                             TRANSCRIPT_AFTER_IDLE_GRACE_MS past the idle
+ *                                             signal: then no hint (occupancy freshness
+ *                                             answers, a hookless restarted turn)
+ *   hook or registry waiting, ended, failed    not active, ownership kept (Cursor: decided)
  *   Codex rollout turn open inside the cap     running, active (no Codex hooks yet)
  *   Cursor, any other hook state               not running, not active (`decides`)
  *
  * A hook-derived `running` only exists inside the deriver's 30-minute open-turn ceiling, so an
  * open-quiet Cursor row ends there, or at its Stop or SessionEnd.
  *
- * For Claude and Codex the hint only ADDS to occupancy (a held, freshly written thread still
- * reads as it did). For Cursor, whose list has no occupancy at all, a hook signal decides, and
+ * For Claude and Codex, authoritative idle/waiting states suppress recent-write activity
+ * for display while leaving ownership intact. Other hints add to occupancy. For Cursor,
+ * whose list has no occupancy at all, a hook signal decides, and
  * a running Cursor turn is the user's own (an IDE composer or their terminal; COS's own child
  * is kept out of the phase), so it is foreign.
  */
@@ -271,15 +281,42 @@ export interface RunningHint {
   foreign: boolean
   /** Cursor with hook evidence: this hint IS the answer, occupancy and file time are not read. */
   decides: boolean
+  /** Authoritative non-working state suppresses file-write activity without changing occupancy. */
+  activeDecides?: boolean
 }
 
-export function runningHintFor(provider: AgentProvider, derived: DerivedSessionState | undefined, lastEventAt: number | null, now: number): RunningHint | null {
+/**
+ * A transcript write this long after the idle signal is new work, not the flush that
+ * trails a Stop. Claude writes its last records around the Stop hook; a turn that wakes
+ * later (a background-task notification restarts a text-only turn, with no prompt and no
+ * tool call, so no hook fires until its Stop) writes well past this.
+ */
+export const TRANSCRIPT_AFTER_IDLE_GRACE_MS = 5_000
+
+export function runningHintFor(provider: AgentProvider, derived: DerivedSessionState | undefined, lastEventAt: number | null, now: number, transcriptAt: number | null = null): RunningHint | null {
   const cursor = provider === 'cursor'
   const quiet: RunningHint | null = cursor ? { running: false, active: false, foreign: false, decides: true } : null
   if (!derived) return null
+  // The state deriver already arbitrates fresh work, waits and completed turns.
+  // A transcript flush after Stop must not turn an idle/waiting badge back to
+  // working. Keep ownership/open-window evidence intact: this is display only.
+  if ((derived.state_source === 'hook' || derived.state_source === 'registry') && derived.agent_state !== 'running') {
+    // An idle signal OLDER than the transcript's newest real record is not the latest
+    // word: a turn restarted with no hook (see TRANSCRIPT_AFTER_IDLE_GRACE_MS) is writing.
+    // Fall back to occupancy freshness. Idle only: waiting keeps `running: true` and its
+    // question; ended and failed stay settled. Cursor's transcript has no clock.
+    if (!cursor && derived.agent_state === 'idle' && transcriptAt !== null) {
+      const since = Date.parse(derived.state_since)
+      const signalAt = Math.max(Number.isFinite(since) ? since : 0, derived.state_source === 'hook' ? lastEventAt ?? 0 : 0)
+      if (transcriptAt > signalAt + TRANSCRIPT_AFTER_IDLE_GRACE_MS) return null
+    }
+    if (cursor) return derived.agent_state === 'waiting'
+      ? { running: true, active: false, foreign: true, decides: true }
+      : quiet
+    return { running: derived.agent_state === 'waiting', active: false, foreign: false, decides: false, activeDecides: true }
+  }
   const inCap = lastEventAt !== null && now - lastEventAt <= HOOK_ACTIVE_CAP_MS && lastEventAt <= now + 5_000
   if (derived.state_source === 'hook') {
-    if (derived.agent_state === 'waiting') return { running: true, active: false, foreign: cursor, decides: cursor }
     if (derived.agent_state === 'running' && inCap) return { running: true, active: true, foreign: cursor, decides: cursor }
     if (derived.agent_state === 'running' && cursor) return { running: true, active: false, foreign: true, decides: true }
     return quiet
@@ -535,7 +572,7 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
         const derived = derivedById.get(row.session_id)
         const signal = signalFor(row.session_id)
         const facts = rolloutById.get(row.session_id) ?? null
-        const hint = runningHintFor(row.provider, derived, hintClock(signal, derived, facts), now)
+        const hint = runningHintFor(row.provider, derived, hintClock(signal, derived, facts), now, clocks.get(row.session_id) ?? null)
         return {
           ...withRunning(toEntry(row, activity[index], derived, queuedOf(row.provider, row.session_id)), running, hint),
           ...cursorActivityFields(row.provider, signal),
@@ -604,6 +641,37 @@ agentSessionsRouter.get('/agent-sessions/search', async (req, res) => {
   }
 })
 
+// Authenticated by index.ts's shared /api gate. Neither the request nor the response
+// carries a filesystem path; the resolver reauthorizes exact transcript membership.
+agentSessionsRouter.get('/agent-sessions/:provider/:sessionId/output-images/:imageId/content', async (req, res) => {
+  res.set('Cache-Control', 'private, no-store')
+  res.set('X-Content-Type-Options', 'nosniff')
+  const provider = asProvider(String(req.params.provider ?? '').toLowerCase())
+  if (!provider || (req.query.variant !== undefined && req.query.variant !== 'thumb' && req.query.variant !== 'phone')) {
+    res.status(404).json({ error: 'image_not_found' }); return
+  }
+  try {
+    const content = await agentSessionOutputImages.content(provider, String(req.params.sessionId), String(req.params.imageId), req.query.variant === 'thumb' ? 'thumb' : 'phone')
+    if (content.status !== 'ok') {
+      res.status(content.status === 'not_found' ? 404 : 503).json({ error: content.status === 'not_found' ? 'image_not_found' : 'image_unavailable' }); return
+    }
+    res.type('image/jpeg')
+    // `send` defaults to `dotfiles: 'ignore'` and applies it to the WHOLE absolute path
+    // when no `root` is given, so a media root under `~/.cos-glasses/data` 404'd on
+    // every default install (see the header of lib/send-audio.ts). 'allow' is safe: the
+    // dot component is our data home, and the resolver above returned an exact,
+    // containment-checked path with no caller-supplied segments.
+    res.sendFile(content.path, { dotfiles: 'allow' }, err => {
+      if (!err) return
+      if (!res.headersSent) res.status(503).json({ error: 'image_unavailable' })
+      else res.destroy()
+    })
+  } catch {
+    console.warn('[agent-sessions] output image unavailable')
+    res.status(503).json({ error: 'image_unavailable' })
+  }
+})
+
 agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res) => {
   res.set('Cache-Control', 'private, no-store')
   const provider = asProvider(String(req.params.provider ?? '').toLowerCase())
@@ -647,7 +715,8 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
     let recentTurns: RecentTurnsRead | null = null
     if (turnsWanted !== null) {
       try {
-        recentTurns = await readRecentSessionTurns(provider, found, turnsWanted)
+        const images = await agentSessionOutputImages.context(provider, sessionId, found)
+        recentTurns = await readRecentSessionTurns(provider, found, turnsWanted, undefined, images.project)
       } catch (error) {
         console.warn(`[agent-sessions] recent turns failed provider=${provider}: ${error instanceof Error ? error.message : error}`)
       }
@@ -684,7 +753,7 @@ agentSessionsRouter.get('/agent-sessions/:provider/:sessionId', async (req, res)
       derived = deriveCodexRow(parsed.session_id, running.occupied.has(parsed.session_id), rollout, now, false)
     }
     const signal = signalFor(parsed.session_id)
-    const hint = runningHintFor(provider, derived, hintClock(signal, derived, rollout), now)
+    const hint = runningHintFor(provider, derived, hintClock(signal, derived, rollout), now, activityClockMs(st.mtimeMs, activity))
     res.json({
       ...withRunning({ session_id: parsed.session_id }, running, hint),
       ...derivedRowFields(derived),

package/server/routes/client-instance.ts

@@ -32,6 +32,17 @@ export const CLIENT_INSTANCE_MAX_SEEN = 64
 
 export interface ClientInstanceRouterDeps {
   now?: () => number
+  /**
+   * G2 authority Tier 1 (6.99.29): the owner-per-device map, shared so the turn provenance
+   * can ask which app copy holds the ring for a request's address. Absent: private, as before.
+   */
+  owners?: Map<string, ClientInstanceOwner>
+}
+
+/** The ring owner's id for this device address, when it claimed within `freshMs`; else null. */
+export function pairedInstanceFrom(owners: ReadonlyMap<string, ClientInstanceOwner>, device: string, now: number, freshMs: number): string | null {
+  const owner = owners.get(deviceKey(device))
+  return owner && now - owner.seenAt <= freshMs ? owner.id : null
 }
 
 /** A POST that carries a meeting chunk: a live one, or an iPhone offline chunk replayed. The preview is not one. */
@@ -49,7 +60,7 @@ export function createClientInstanceRouter(deps: ClientInstanceRouterDeps | (()
   const opts: ClientInstanceRouterDeps = typeof deps === 'function' ? { now: deps } : deps
   const now = opts.now ?? Date.now
   const router = Router()
-  const owners = new Map<string, ClientInstanceOwner>()
+  const owners = opts.owners ?? new Map<string, ClientInstanceOwner>()
   const chunks = new ClientChunkLedger()
   // 6.52.3: when each copy last claimed, so an older boot proves it was awake before it
   // may take a quiet ring back. Bounded like the chunk ledger.

package/server/routes/cursor-stop-followup.ts

@@ -14,12 +14,15 @@ import express, { Router, type NextFunction, type Request, type Response } from
 import { timingSafeTokenEqual } from '../lib/token-auth.js'
 import { claimNextCursorTurn, cursorStopAcceptsFollowup, cursorStopIsFresh, parseCursorStopEnvelope } from '../lib/cursor-stop-followup.js'
 import { MAX_QUEUED_PER_THREAD, type QueuedThreadTurn } from '../lib/thread-turn-queue.js'
+import { hasFooterShapedLine, type G2TurnProvenance } from '../lib/g2-turn-provenance.js'
 
 export interface CursorStopFollowupDeps {
   /** The per-install hook token, or null when none has been minted (then nothing is answered). */
   hookToken: () => string | null
   readQueue: (provider: string, threadId: string, now: number) => QueuedThreadTurn[]
   writeQueue: (provider: string, threadId: string, queue: QueuedThreadTurn[]) => void
+  /** G2 authority Tier 1 (6.99.29), optional: ledger the hand-off and foot a glasses or phone turn. */
+  provenance?: G2TurnProvenance
   now: () => number
 }
 
@@ -60,6 +63,20 @@ export function createCursorStopFollowupRouter(deps: CursorStopFollowupDeps): Ro
       }
       claimed = claimNextCursorTurn(deps.readQueue('cursor', facts.conversationId, now), now)
       if (!claimed) return res.json({})
+      // G2 authority Tier 1 (Codex re-audit of 910eb90): the queue file is mutable, and this is the
+      // last hand-off before the words reach the composer. Words carrying a footer-shaped line are
+      // refused here exactly as at every other route that hands words to a session: the row is
+      // settled refused (never handed over, never retried) and its parked origin forgotten.
+      if (deps.provenance && hasFooterShapedLine(claimed.turn.prompt)) {
+        const refusedTurn = claimed.turn
+        const settled = claimed.queue.map(t => t.clientTurnId === refusedTurn.clientTurnId
+          ? { ...t, status: 'refused' as const, reason: 'footer_line_refused', settledAt: now }
+          : t)
+        deps.writeQueue('cursor', facts.conversationId, settled)
+        deps.provenance.forgetQueued('cursor', facts.conversationId, refusedTurn.clientTurnId)
+        console.warn(`[cursor-stop-followup] refused a queued turn with a footer-shaped line clientTurnId=${refusedTurn.clientTurnId}`)
+        return res.json({})
+      }
       // Written BEFORE the text leaves: the row must never read `waiting` after the
       // composer has been handed it, or a later Stop would hand it over again.
       deps.writeQueue('cursor', facts.conversationId, claimed.queue)
@@ -68,7 +85,19 @@ export function createCursorStopFollowupRouter(deps: CursorStopFollowupDeps): Ro
       return res.json({})
     }
     console.log(`[cursor-stop-followup] handed a queued turn to Cursor clientTurnId=${claimed.turn.clientTurnId} chars=${claimed.turn.prompt.length} loop=${facts.loopCount ?? 'null'} cursor=${facts.cursorVersion}`)
-    return res.json({ followup_message: claimed.turn.prompt })
+    let followup = claimed.turn.prompt
+    if (deps.provenance) {
+      // The hook's own socket is local; the origin is the one captured when the turn was
+      // parked, and only while the queued text is still the text it vouched for.
+      const turn = claimed.turn
+      const verdict = deps.provenance.queuedVerdict('cursor', facts.conversationId, turn.clientTurnId, turn.prompt) ?? deps.provenance.originOf(req)
+      followup = deps.provenance.footed(turn.prompt, turn.clientTurnId, verdict, 'cursor')
+      // The queue's own hand-off of its parked turn: it continues the record parked under this id.
+      deps.provenance.record({ turnId: turn.clientTurnId, prompt: turn.prompt, verdict, provider: 'cursor', sessionId: facts.conversationId, via: 'cursor-stop-followup', continues: true })
+      // Settled (handed over): the parked origin is forgotten (QA 6.99.29).
+      deps.provenance.forgetQueued('cursor', facts.conversationId, turn.clientTurnId)
+    }
+    return res.json({ followup_message: followup })
   })
   return router
 }

package/server/routes/g2-turns.ts

@@ -0,0 +1,46 @@
+// GET /api/g2-turns/:turnId (and its 6.99.29 alias GET /api/turn-provenance/:turnId): read-only provenance for one turn this server delivered or queued
+// into an agent session (G2 authority Tier 1, see lib/g2-turn-provenance.ts). Behind the global
+// X-Cos-Token gate like every /api route. 400 on a malformed id, 404 `{ found: false }` when no
+// record names it. Answers what was recorded, and vouches (`verifiedOrigin: true`) only for a
+// glasses or phone record this process wrote and still holds, written within 24 hours. A web record
+// is reported with `reason: web_cookie_derivable_from_token` and never vouched (6.99.29).
+
+import { Router } from 'express'
+import { timingSafeTokenEqual } from '../lib/token-auth.js'
+import { describeG2Turn, G2_TURN_ID_RE, type G2TurnProvenance } from '../lib/g2-turn-provenance.js'
+
+export function createG2TurnsRouter(deps: {
+  provenance: G2TurnProvenance
+  now?: () => number
+  /**
+   * 6.99.29: the pairing token. With it, only a request that presents X-Cos-Token is answered: the
+   * /api gate also admits a COS Control Web browser by its cookie, and the verifier runs on this Mac
+   * with the token. Absent: whatever the gate admitted (the 6.66 tests mount the gate alone).
+   */
+  apiToken?: () => string
+}): Router {
+  const router = Router()
+  const now = deps.now ?? Date.now
+  // 6.99.29: one handler, two paths. `/turn-provenance` names what it is now that web turns are
+  // recorded too (reported, never vouched: lib/g2-turn-provenance.ts); `/g2-turns` stays for
+  // verify_g2_turn.py and every caller of the 6.66 design.
+  router.get(['/g2-turns/:turnId', '/turn-provenance/:turnId'], async (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    if (deps.apiToken) {
+      let expected = ''
+      try { expected = deps.apiToken() } catch { expected = '' }
+      if (!expected || !timingSafeTokenEqual(req.headers['x-cos-token'], expected)) return void res.status(401).json({ found: false, error: 'token_required' })
+    }
+    const turnId = String(req.params.turnId ?? '')
+    if (!G2_TURN_ID_RE.test(turnId)) return void res.status(400).json({ found: false, error: 'invalid_turn_id' })
+    try {
+      const answer = await describeG2Turn(deps.provenance, turnId, now())
+      if (!answer) return void res.status(404).json({ found: false, turnId })
+      res.json(answer)
+    } catch (error) {
+      console.error(`[g2-turns] lookup failed: ${error instanceof Error ? error.message : error}`)
+      res.status(500).json({ found: false, error: 'lookup_failed' })
+    }
+  })
+  return router
+}