@gotcos/glasses-server 6.36.6 → 6.36.8

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## Unreleased
 
+## 6.36.8
+- **The queue now covers the refusal that actually fires.** Device diagnostics, once the
+  path was finally instrumented, recorded `native_target_busy` on every Continue that
+  reached the server — never `native_thread_working`, which is what 6.36.7 was built
+  around. Selecting Continue SUCCEEDS and mints a binding; if the dictation is not
+  completed the binding lingers to its TTL, and every Continue inside that window
+  refuses. Twelve such bindings had stacked up on one thread over an evening.
+- `native_target_busy` and `native_turn_in_progress` are now queueable. Both are
+  transient by construction — a clock clears them — and both are COS's OWN bookkeeping
+  rather than a foreign process holding the thread. Delivery still re-runs the full
+  gate, so nothing about the safety model changes.
+- `native_target_fenced` is deliberately NOT queueable: "may or may not have been
+  delivered" cannot be resolved by waiting, and queueing it risks a duplicate turn in a
+  real conversation.
+
+
+## 6.36.7
+- **A turn spoken at a busy thread is now queued instead of refused.** Miles: "if
+  there's a session that's still running, that would just put it into the queue the same
+  way that the user has the ability to do so." The thread was never stuck — measured at
+  the moment he asked, its transcript mtime was 3s old against a 30s window, so the gate
+  correctly read `working`. That is the trap: while you are talking to an agent in a
+  thread, it is CONTINUOUSLY working, so Continue was unreachable for exactly the thread
+  you most want to continue and Fork was the only door.
+- **This does not weaken the attach gate, which is the whole design.** The queue defers
+  to the gate rather than bypassing it: delivery re-runs the full occupancy check and
+  can still refuse. Several tests exist only to prove that negative.
+- Only occupancy reasons are queueable. A structural refusal — unsupported provider,
+  malformed id, attach switched off — still refuses immediately, because telling someone
+  their turn is queued when it can never run is worse than refusing it.
+- **Delivery re-enters through the front door**, over loopback to this server's own
+  attach and turn routes. Those carry the gate, the target fence, the per-target claim,
+  the watermark, the idempotency ledger and the child-pid accounting; a second copy in a
+  background worker would be a second place for the gate to drift.
+- **The watermark exemption, approved explicitly by Miles.** A queued turn drains after
+  the thread has moved on — that is what it waited for — so its binding is minted fresh
+  at delivery. Checked as normal, a queue would fail 100% of the time. An interactive
+  turn still gets the full divergence check.
+- Ready means the turn ENDED (`result` / `turn_complete`, detected with the same parser
+  the live stream uses), with the 30s idle clock as a backstop so a holder that dies
+  cannot wedge the queue. Thirty seconds of silence alone would fire during a long tool
+  call and inject into the middle of a turn.
+- Durable under the data home, so it survives a server update and a pocketed phone. The
+  attempt count is persisted BEFORE each delivery, so a crash mid-flight cannot reset
+  the ceiling and retry forever. Six-hour TTL, 8 waiting per thread, 5 attempts, and a
+  cancel route for the × control.
+
+
 ## 6.36.6
 - **The session digest follows the thread instead of its opening.** Miles, from the
   lens: "It's currently showing a legacy session that I had over a day ago... The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.36.6",
+  "version": "6.36.8",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -24,6 +24,7 @@ import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import {
   createAgentSessionBindingsRouter,
+
   threadAttachEnabled,
 } from './routes/agent-session-bindings.js'
 import { AgentSessionBindingRegistry } from './lib/agent-session-binding-registry.js'
@@ -33,7 +34,7 @@ import { realAttachedWorkspaceDeps, resolveAttachedWorkspace } from './lib/attac
 import { deliverAttachedTurn, realAttachedTurnDeps } from './lib/attached-provider-adapter.js'
 import { forkThread, realForkDeps } from './lib/fork-thread.js'
 import { nativeHead, realNativeHeadDeps } from './lib/native-head.js'
-import { threadOccupancy } from './lib/thread-occupancy.js'
+import { threadOccupancy, holderActivity } from './lib/thread-occupancy.js'
 import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter } from './routes/transcribe-stream.js'
 import { meetingRouter, resumeMeetingFinalizationJobs } from './routes/meeting.js'
@@ -104,6 +105,12 @@ import {
 } from './lib/maintenance-lifecycle.js'
 
 const app = express()
+import { createThreadTurnQueueRouter, drainAllThreads } from './routes/thread-turn-queue.js'
+import { transcriptTurnEnded } from './lib/thread-turn-queue-store.js'
+import { transcriptPathFor } from './lib/native-head.js'
+import { deliverQueuedTurnOverLoopback } from './lib/thread-turn-queue-deliver.js'
+import type { QueuedThreadTurn } from './lib/thread-turn-queue.js'
+
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
 
 // Mode detection — COS mode when a full pipeline directory is configured.
@@ -491,6 +498,66 @@ app.use('/api', claudeSessionsRouter)
 // Registered AFTER agentSessionsRouter deliberately: its paths are 2 and 4 segments
 // (`/agent-sessions/bindings`, `/agent-sessions/:provider/:threadId/attachability`)
 // and cannot shadow that router's `/agent-sessions/:provider/:id` transcript route.
+// ---------------------------------------------------------------------------
+// QUEUED THREAD TURNS
+// ---------------------------------------------------------------------------
+// A turn spoken at a thread that is busy right now is PARKED instead of refused, and
+// delivered when the thread frees. Miles, 2026-08-17: "if there's a session that's
+// still running, that would just put it into the queue the same way that the user has
+// the ability to do so."
+//
+// Registered only when attach is enabled, on the SAME flag as the write routes: a
+// queue whose delivery path does not exist would accept turns it can never send.
+//
+// DELIVERY GOES BACK IN THROUGH THE FRONT DOOR, over loopback to this server's own
+// attach + turn routes. Those two carry the occupancy gate, the target fence, the
+// per-target claim, the divergence watermark, the idempotency ledger and the child-pid
+// accounting; a second copy of that sequence in a background worker is a second place
+// for the gate to drift. One request per delivered turn, at a handful of turns a day,
+// buys the guarantee that the queue CANNOT weaken the gate even by accident.
+if (threadAttachEnabled()) {
+  const queueDeps = {
+    occupancy: (provider: string, threadId: string) => {
+      try {
+        const v = threadOccupancy(provider, threadId, occupancyProbes, occupancyDirs)
+        return { attachable: v.attachable === true, reason: v.reason ?? null }
+      } catch {
+        // A throwing probe is not an open door.
+        return { attachable: false, reason: 'probe_failed' }
+      }
+    },
+    turnEnded: (provider: string, threadId: string) => {
+      if (provider !== 'claude' && provider !== 'codex') return false
+      try {
+        return transcriptTurnEnded(provider, transcriptPathFor(provider, threadId, nativeHeadDeps))
+      } catch {
+        return false
+      }
+    },
+    activity: (provider: string, threadId: string): 'working' | 'idle' | 'unknown' => {
+      try {
+        const read = occupancyProbes.transcriptMtimeMs
+        return typeof read === 'function'
+          ? holderActivity(read(provider as 'claude' | 'codex', threadId), Date.now())
+          : 'unknown'
+      } catch {
+        return 'unknown'
+      }
+    },
+    deliver: (turn: QueuedThreadTurn) => deliverQueuedTurnOverLoopback(turn, PORT, API_TOKEN),
+    now: () => Date.now(),
+  }
+  app.use('/api', createThreadTurnQueueRouter(queueDeps))
+
+  // Every 20s. Fast enough that a freed thread drains while the user is still looking
+  // at the pending row, slow enough to be nothing: the sweep does no work at all when
+  // no queue file exists. Unref'd so it never holds the process open.
+  const queueDrainTimer = setInterval(() => {
+    void drainAllThreads(queueDeps).catch(() => { /* the next sweep retries */ })
+  }, 20_000)
+  queueDrainTimer.unref()
+}
+
 app.use('/api', createAgentSessionBindingsRouter({
   probes: occupancyProbes,
   dirs: occupancyDirs,

package/server/lib/thread-turn-queue-deliver.ts

@@ -0,0 +1,106 @@
+// Delivering a queued turn by re-entering this server's own attach + turn routes.
+//
+// WHY LOOPBACK AND NOT A DIRECT CALL. Delivery is not "post a prompt". It is the
+// occupancy gate, the target fence, the per-target claim, the divergence watermark, the
+// idempotency ledger and the child-pid accounting -- a long, ordered sequence in
+// agent-session-bindings.ts where every branch exists because something once went
+// wrong. Re-implementing it here would create a second place for the gate to drift, and
+// the drift would be invisible until the day it mattered. Going back in through the
+// front door means the gate runs exactly once, in its existing home, and this file
+// cannot weaken it even by accident.
+//
+// The cost is one loopback request per delivered turn, at a volume of a handful a day.
+//
+// THE WATERMARK EXEMPTION LIVES HERE, and nowhere else. A queued turn drains after the
+// thread has moved on -- that is what it waited for -- so its binding is minted FRESH
+// at delivery against the thread as it stands. The turn is therefore always composed
+// against a current baseline, which is what the user meant by queueing it: "append this
+// to whatever the thread is when it frees". An interactive turn still gets the full
+// divergence check, because there the user composed against a state they were looking
+// at and a silent change is genuinely surprising. Miles approved this explicitly.
+//
+// FAILS CLOSED, AND AMBIGUITY IS A FAILURE. Anything other than a clean admission
+// resolves `ok: false`, which returns the turn to the queue rather than marking it
+// sent. The caller bounds retries; the danger to avoid here is the opposite one --
+// reporting success for a turn that may not have landed, which loses it silently.
+
+import { request } from 'node:http'
+import type { QueuedThreadTurn } from './thread-turn-queue.js'
+
+/** Per-request ceiling. Attach and turn both answer immediately; the turn route
+ *  admits with 202 and does the long work in the background. */
+const DELIVER_TIMEOUT_MS = 15_000
+
+interface LoopbackReply { status: number; body: Record<string, unknown> }
+
+function post(port: number, token: string, path: string, payload: unknown): Promise<LoopbackReply> {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(payload)
+    const req = request({
+      host: '127.0.0.1',
+      port,
+      path,
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(data),
+        // The header the rest of COS authenticates with. NOT `Authorization: Bearer`.
+        'X-Cos-Token': token,
+      },
+      timeout: DELIVER_TIMEOUT_MS,
+    }, res => {
+      let raw = ''
+      res.on('data', c => { raw += c })
+      res.on('end', () => {
+        let body: Record<string, unknown> = {}
+        try { body = raw ? JSON.parse(raw) as Record<string, unknown> : {} } catch { /* non-JSON is a failure below */ }
+        resolve({ status: res.statusCode ?? 0, body })
+      })
+    })
+    req.on('timeout', () => { req.destroy(new Error('deliver_timeout')) })
+    req.on('error', reject)
+    req.write(data)
+    req.end()
+  })
+}
+
+/**
+ * Attach, then send. Returns `ok` only on a provable admission.
+ *
+ * The attach is what re-baselines the watermark: it reads the thread's head digest as
+ * it is NOW, so the turn that follows cannot be refused for divergence that happened
+ * while the turn was waiting.
+ */
+export async function deliverQueuedTurnOverLoopback(
+  turn: QueuedThreadTurn,
+  port: number,
+  token: string,
+): Promise<{ ok: boolean; reason?: string }> {
+  try {
+    const attach = await post(
+      port, token,
+      `/api/agent-sessions/${encodeURIComponent(turn.provider)}/${encodeURIComponent(turn.threadId)}/attach`,
+      { cosSessionId: turn.cosSessionId },
+    )
+    if (attach.status !== 200 && attach.status !== 201) {
+      // The gate said no at drain time. Not an error -- the queue holds and tries again.
+      return { ok: false, reason: String(attach.body.error ?? `attach_${attach.status}`) }
+    }
+    const bindingId = typeof attach.body.bindingId === 'string' ? attach.body.bindingId : ''
+    if (!bindingId) return { ok: false, reason: 'attach_no_binding' }
+
+    const sent = await post(
+      port, token,
+      `/api/agent-sessions/bindings/${encodeURIComponent(bindingId)}/turns`,
+      // `clientTurnId` is carried through unchanged so the turn route's own
+      // idempotency ledger recognises a re-delivery of the SAME turn. Without it a
+      // retry after an ambiguous response would put the sentence in twice.
+      { clientTurnId: turn.clientTurnId, prompt: turn.prompt },
+    )
+    // 202 is the success shape: admitted, delivered in the background, poll the ledger.
+    if (sent.status === 202 || sent.status === 200) return { ok: true }
+    return { ok: false, reason: String(sent.body.error ?? `turn_${sent.status}`) }
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : 'deliver_failed' }
+  }
+}

package/server/lib/thread-turn-queue-store.ts

@@ -0,0 +1,127 @@
+// Durable storage for queued thread turns, and the terminal-record probe.
+//
+// SEPARATE FROM THE DECISIONS. `thread-turn-queue.ts` is pure and holds every rule;
+// this file only reads and writes. That split is what lets the rules be tested by
+// execution instead of by reading them.
+//
+// ONE FILE PER THREAD, under the data home so it survives a server update -- the
+// generation directory is replaced wholesale on every Update Server, and a queue that
+// lived there would be silently emptied by a routine upgrade. Same lesson as the
+// stranded voice profiles.
+
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+import { atomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { draftsFromLine, type SessionStreamProvider } from './session-stream-events.js'
+import { pruneQueue, type QueuedThreadTurn } from './thread-turn-queue.js'
+
+/** Bytes of transcript tail read to decide whether the last turn ended. */
+export const TURN_END_TAIL_BYTES = 64 * 1024
+
+function queueDir(): string {
+  const dir = dataPath('thread-turn-queue')
+  try { mkdirSync(dir, { recursive: true }) } catch { /* the write below reports it */ }
+  return dir
+}
+
+/**
+ * One file per (provider, thread).
+ *
+ * The thread id is validated by the caller before it reaches here, but it is still
+ * sanitised: this value becomes a PATH, and a route that forgets its guard must not
+ * turn into a directory traversal.
+ */
+export function queuePath(provider: string, threadId: string): string {
+  const safe = `${provider}-${threadId}`.replace(/[^A-Za-z0-9._-]/g, '_')
+  return join(queueDir(), `${safe}.json`)
+}
+
+/** The queue for a thread, pruned. A missing or corrupt file reads as empty. */
+export function readQueue(provider: string, threadId: string, now: number): QueuedThreadTurn[] {
+  const path = queuePath(provider, threadId)
+  if (!existsSync(path)) return []
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'))
+    if (!Array.isArray(parsed)) return []
+    // Corrupt rows are dropped individually rather than discarding the whole queue:
+    // one bad record must not lose the other turns someone is waiting on.
+    const rows = parsed.filter((r): r is QueuedThreadTurn =>
+      !!r && typeof r === 'object'
+      && typeof (r as QueuedThreadTurn).clientTurnId === 'string'
+      && typeof (r as QueuedThreadTurn).prompt === 'string'
+      && typeof (r as QueuedThreadTurn).queuedAt === 'number')
+    return pruneQueue(rows, now)
+  } catch {
+    return []
+  }
+}
+
+/** Replace a thread's queue. Atomic, so a crash mid-write cannot truncate it. */
+export function writeQueue(provider: string, threadId: string, queue: readonly QueuedThreadTurn[]): void {
+  atomicWriteFileSync(queuePath(provider, threadId), `${JSON.stringify(queue, null, 2)}\n`)
+}
+
+/** Every thread with a queue file, for the drain sweep. */
+export function queuedThreadKeys(): Array<{ provider: string; threadId: string }> {
+  try {
+    return readdirSync(queueDir())
+      .filter(f => f.endsWith('.json'))
+      .map(f => {
+        const base = f.slice(0, -5)
+        const dash = base.indexOf('-')
+        return dash > 0
+          ? { provider: base.slice(0, dash), threadId: base.slice(dash + 1) }
+          : null
+      })
+      .filter((v): v is { provider: string; threadId: string } => v !== null)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Did the holder's last turn END?
+ *
+ * REUSES `draftsFromLine`, the same parser the live stream uses, so "the turn ended"
+ * means exactly here what it means there. Hand-rolling a second `type === 'result'`
+ * check is how two definitions of done drift apart.
+ *
+ * Reads a bounded tail, newest record wins. Returns false on any doubt -- an
+ * unreadable transcript is not evidence a turn finished, and false only means the
+ * queue HOLDS, which is always the safe answer.
+ */
+export function transcriptTurnEnded(provider: SessionStreamProvider, path: string | null): boolean {
+  if (!path || !existsSync(path)) return false
+  try {
+    // BOTH flags, and both are load-bearing -- hazard-invariants.test.ts enforces
+    // them and each is right on its own terms. O_NOFOLLOW: a symlinked `<id>.jsonl`
+    // could point at any file on disk and would be parsed here as a transcript.
+    // O_NONBLOCK: `openSync` on a FIFO with no writer NEVER RETURNS, and it is a
+    // synchronous syscall on Node's single thread, so one planted path would stop
+    // health, meeting save and transcribe-stream along with this drain. That one is
+    // recorded in the repo as three reproductions of the same bug, >34s to SIGKILL.
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    try {
+      const size = fstatSync(fd).size
+      const start = Math.max(0, size - TURN_END_TAIL_BYTES)
+      const buf = Buffer.alloc(size - start)
+      readSync(fd, buf, 0, buf.length, start)
+      const lines = buf.toString('utf-8').split('\n')
+      // The first line of a tail read is almost always a fragment.
+      if (start > 0) lines.shift()
+      let ended = false
+      for (const line of lines) {
+        if (!line.trim()) continue
+        for (const draft of draftsFromLine(provider, line)) {
+          if (draft.kind === 'status') ended = draft.state === 'done'
+        }
+      }
+      return ended
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return false
+  }
+}

package/server/lib/thread-turn-queue.ts

@@ -0,0 +1,235 @@
+// A turn spoken at a thread that is busy right now, held until it is not.
+//
+// ---------------------------------------------------------------------------
+// WHY
+// ---------------------------------------------------------------------------
+// Miles, 2026-08-17, looking at a thread he could not continue: "This thread, the
+// COS-glasses server, has actually completed, but it's still locked. Ideally, what would
+// happen is if there's a session that's still running, that would just put it into the
+// queue the same way that the user has the ability to do so." His example was his own
+// desktop: he typed into a running turn and Claude Code queued it, pending, with a
+// cancel control.
+//
+// The thread was not stuck. Measured at the moment he asked: transcript mtime 3s old
+// against a 30s window, so `holderActivity` was `working` -- correctly, because a COS
+// session was writing to it. That is the trap: while you are talking to an agent in a
+// thread, that thread is CONTINUOUSLY working, so Continue is unreachable for exactly
+// the thread you most want to continue, and Fork is the only door.
+//
+// ---------------------------------------------------------------------------
+// THIS DOES NOT WEAKEN THE ATTACH GATE, AND THAT IS THE WHOLE DESIGN
+// ---------------------------------------------------------------------------
+// The gate refuses to WRITE into a thread another process holds. A queue does not
+// bypass it -- it defers to it. Nothing here decides a turn may be delivered; delivery
+// re-runs the full occupancy check at drain time and can still refuse. So parking is
+// safe by construction, and the only reasons that should still refuse outright are the
+// ones that can NEVER clear.
+//
+// That is the split `queueableRefusal` encodes: an occupancy reason describes a
+// condition that may pass, a structural reason describes a thread that will never be
+// continuable no matter how long anyone waits. Telling someone their turn is queued
+// when it can never run is worse than refusing.
+//
+// ---------------------------------------------------------------------------
+// THE WATERMARK EXEMPTION -- Miles approved this explicitly
+// ---------------------------------------------------------------------------
+// A binding carries a content watermark, and a write is refused with
+// `native_thread_changed` when the thread's head digest moved since the turn was
+// composed. A queued turn drains AFTER more has been written, by definition -- that is
+// what it was waiting for -- so the watermark has ALWAYS moved by then. Checked as
+// normal, a queue would fail 100% of the time.
+//
+// So a drained turn re-baselines the watermark at delivery. This is a deliberate,
+// scoped exemption, and its justification is the user's intent: queueing means "append
+// this to whatever the thread is when it frees", which is exactly what the desktop
+// queue does. It is NOT a general relaxation -- an interactive turn still gets the full
+// divergence check, because there the user composed against a state they were looking
+// at and a silent change is genuinely surprising.
+//
+// Miles, asked directly before this was built: "Yeah, this is a fine exemption."
+//
+// ---------------------------------------------------------------------------
+// WHAT MAKES A TURN READY, AND WHY NOT "IDLE"
+// ---------------------------------------------------------------------------
+// Thirty seconds of transcript silence is the wrong trigger on its own: a long tool
+// call goes quiet mid-turn, and draining there would inject a message into the middle
+// of someone's reasoning. The precise signal is the turn ENDING, which is observable in
+// the transcript itself -- Claude writes a `result` record, Codex a `task_complete` /
+// `turn_complete`. The idle clock stays as a BACKSTOP for a holder that dies or a
+// provider that writes no terminal record, so a queue cannot wedge forever on a missing
+// event. Same reasoning as the session-trail handoff, one layer down.
+
+/** Terminal-ish states a queued turn can reach. `waiting` is the only live one. */
+export type QueuedTurnStatus =
+  | 'waiting'
+  | 'delivering'
+  | 'delivered'
+  | 'refused'
+  | 'expired'
+  | 'cancelled'
+
+export interface QueuedThreadTurn {
+  /** Idempotency key, poll key, and row identity -- the same one the phone's pending
+   *  ledger already tracks, so a queued turn needs no new client vocabulary. */
+  clientTurnId: string
+  cosSessionId: string
+  provider: string
+  threadId: string
+  prompt: string
+  queuedAt: number
+  status: QueuedTurnStatus
+  /** Delivery attempts made. Bounded so a permanently-refusing target cannot spin. */
+  attempts: number
+  /** The SERVER's reason for a terminal outcome. Never the client's wording. */
+  reason?: string
+  settledAt?: number
+}
+
+/**
+ * How long a waiting turn stays valid.
+ *
+ * Six hours, not indefinite. A turn is a thing someone SAID, and saying it into a
+ * thread twelve hours later is not what they meant -- the context they were replying to
+ * is gone. Expiry is reported, never silent.
+ */
+export const QUEUED_TURN_TTL_MS = 6 * 60 * 60 * 1000
+
+/** Waiting turns per thread. Small: this is a queue, not a backlog. */
+export const MAX_QUEUED_PER_THREAD = 8
+
+/**
+ * Delivery attempts before a turn is given up on.
+ *
+ * A drain that keeps failing is not going to start working, and a queue that retries
+ * forever is a write loop against someone else's session.
+ */
+export const MAX_DELIVERY_ATTEMPTS = 5
+
+/**
+ * Occupancy reasons a turn may WAIT on, versus ones that must refuse now.
+ *
+ * The distinction is whether the condition can ever pass. `native_thread_working` is
+ * the common one and obviously transient. The `unknown`-shaped reasons are included
+ * deliberately: they mean the scan could not SEE, which is a refusal for a write but
+ * not a reason to discard something the user said -- and delivery re-runs the gate, so
+ * a queue on an unmeasurable thread simply never drains and expires honestly.
+ *
+ * Everything absent from this set is STRUCTURAL: a provider COS cannot continue, a
+ * malformed id, or the write feature being switched off. None of those pass with time,
+ * and queueing against them would be a lie told politely.
+ */
+const QUEUEABLE_REFUSALS: ReadonlySet<string> = new Set([
+  'native_thread_working',
+  // COS'S OWN LEFTOVER BINDING, and the reason this feature did not work for a day.
+  // Proven from device diagnostics 2026-08-17: every Continue that reached the server
+  // was refused `native_target_busy` ("already attached to another COS chat"), never
+  // `native_thread_working`. Selecting Continue SUCCEEDS and mints a binding; if the
+  // dictation is not completed the binding lingers to its TTL, and every Continue in
+  // that window refuses. Twelve such bindings had stacked up on one thread.
+  //
+  // It belongs here because it is transient BY CONSTRUCTION -- the binding expires on
+  // a clock -- and because it is COS's own bookkeeping, not a foreign process holding
+  // the thread. Queueing waits it out, and delivery re-runs the whole gate as always.
+  'native_target_busy',
+  // Same shape: a COS turn is mid-flight on this thread and will finish.
+  'native_turn_in_progress',
+  'live_desktop_process',
+  'thread_busy',
+  'binding_conflict',
+  'detector_unavailable',
+  'registry_unreadable',
+  'unverifiable_process_start',
+  'unverifiable_liveness_socket',
+  'probe_failed',
+])
+
+/** Can a turn refused for this reason be parked, or must it refuse now? */
+export function queueableRefusal(reason: string | null | undefined): boolean {
+  return typeof reason === 'string' && QUEUEABLE_REFUSALS.has(reason)
+}
+
+/** What the drainer observed about the thread this tick. */
+export interface DrainObservation {
+  /** The full occupancy gate re-run. Delivery NEVER happens on a false. */
+  attachable: boolean
+  /**
+   * Did the holder's last transcript record end a turn (`result`, `turn_complete`)?
+   * The precise signal, when the provider writes one.
+   */
+  turnEnded: boolean
+  /** The 30s transcript clock. `idle` is the backstop when no terminal record lands. */
+  activity: 'working' | 'idle' | 'unknown'
+}
+
+export type DrainDecision = 'deliver' | 'hold' | 'expire' | 'give_up'
+
+/**
+ * Should this waiting turn go now?
+ *
+ * PURE, and every branch resolves. Order matters: expiry and the attempt ceiling are
+ * checked BEFORE readiness, so a turn that has run out of time or tries cannot be
+ * delivered by a lucky tick.
+ */
+export function drainDecision(
+  turn: Pick<QueuedThreadTurn, 'status' | 'queuedAt' | 'attempts'>,
+  seen: DrainObservation,
+  now: number,
+  ttlMs: number = QUEUED_TURN_TTL_MS,
+): DrainDecision {
+  if (turn.status !== 'waiting') return 'hold'
+  if (!Number.isFinite(now) || !Number.isFinite(turn.queuedAt)) return 'hold'
+  if (now - turn.queuedAt >= ttlMs) return 'expire'
+  if (turn.attempts >= MAX_DELIVERY_ATTEMPTS) return 'give_up'
+  // THE GATE, unweakened. Everything below is about WHEN, never about whether.
+  if (!seen.attachable) return 'hold'
+  // Turn-ended is the precise signal; idle is the backstop for a holder that wrote no
+  // terminal record. `working` holds even when attachable, because attachable only says
+  // no one else owns it -- it does not say a turn is not mid-flight.
+  if (seen.turnEnded) return 'deliver'
+  return seen.activity === 'idle' ? 'deliver' : 'hold'
+}
+
+/**
+ * Admit a turn to the queue, or say why not.
+ *
+ * Rejects a duplicate `clientTurnId` rather than parking a second copy: the id is an
+ * idempotency key, and a phone that retries after a dropped response must not put the
+ * same sentence into a real conversation twice.
+ */
+export function admitToQueue(
+  existing: readonly QueuedThreadTurn[],
+  turn: QueuedThreadTurn,
+): { ok: true; queue: QueuedThreadTurn[] } | { ok: false; reason: string } {
+  if (!turn.clientTurnId || !turn.prompt.trim()) return { ok: false, reason: 'invalid_request' }
+  if (existing.some(t => t.clientTurnId === turn.clientTurnId)) {
+    return { ok: false, reason: 'duplicate_turn' }
+  }
+  const waiting = existing.filter(t => t.status === 'waiting')
+  if (waiting.length >= MAX_QUEUED_PER_THREAD) return { ok: false, reason: 'queue_full' }
+  return { ok: true, queue: [...existing, turn] }
+}
+
+/**
+ * Drop rows nobody needs any more.
+ *
+ * Settled rows are kept briefly so the phone's poll can still see the outcome -- a row
+ * that vanishes reads as "lost", which is the one answer a pending ledger must never
+ * give. Waiting rows are never pruned here; only `drainDecision` retires those, so
+ * there is exactly one place a live turn can die.
+ */
+export function pruneQueue(
+  queue: readonly QueuedThreadTurn[],
+  now: number,
+  settledRetentionMs: number = 30 * 60 * 1000,
+): QueuedThreadTurn[] {
+  return queue.filter(t => {
+    if (t.status === 'waiting' || t.status === 'delivering') return true
+    const settled = typeof t.settledAt === 'number' ? t.settledAt : t.queuedAt
+    return now - settled < settledRetentionMs
+  })
+}
+
+/** Where a waiting turn sits, for the phone's row copy. `0` when it is next. */
+export function queuePosition(queue: readonly QueuedThreadTurn[], clientTurnId: string): number {
+  return queue.filter(t => t.status === 'waiting').findIndex(t => t.clientTurnId === clientTurnId)
+}

package/server/routes/thread-turn-queue.ts

@@ -0,0 +1,223 @@
+// Routes and drainer for turns spoken at a busy thread.
+//
+// WHY THE DRAINER CALLS THE SERVER'S OWN ROUTES OVER LOOPBACK, which looks odd until
+// you look at what it would otherwise have to copy. Delivery is not "post a prompt": it
+// is the occupancy gate, the target fence, the per-target claim, the divergence
+// watermark, the idempotency ledger, and the child-pid accounting -- roughly 370 lines
+// of ordering in agent-session-bindings.ts, where every branch exists because something
+// once went wrong. A second copy of that in a background worker is a second place for
+// the gate to drift, and the drift would be invisible until it mattered.
+//
+// So the drainer re-enters through the front door. The gate runs exactly once, in its
+// existing home, and this file cannot weaken it even by accident -- the strongest form
+// of "does not weaken the attach gate" available. It costs one loopback request per
+// delivered turn, at a volume of a handful per day.
+//
+// EVERY DEPENDENCY IS INJECTED so the whole path is testable without a live server.
+
+import { Router, type Request, type Response } from 'express'
+import {
+  admitToQueue, drainDecision, queueableRefusal, queuePosition,
+  MAX_DELIVERY_ATTEMPTS, type DrainObservation, type QueuedThreadTurn,
+} from '../lib/thread-turn-queue.js'
+import { readQueue, writeQueue, queuedThreadKeys } from '../lib/thread-turn-queue-store.js'
+
+export interface ThreadTurnQueueDeps {
+  /** Re-runs the FULL occupancy gate. The drainer never decides attachability itself. */
+  occupancy: (provider: string, threadId: string) => { attachable: boolean; reason: string | null }
+  /** Did the holder's last transcript record end a turn? */
+  turnEnded: (provider: string, threadId: string) => boolean
+  /** The 30s transcript clock, as a backstop. */
+  activity: (provider: string, threadId: string) => 'working' | 'idle' | 'unknown'
+  /**
+   * Deliver one turn. Production wires this to a loopback attach + turn.
+   *
+   * Resolves `{ ok: true }` only when the turn was provably admitted. Anything
+   * ambiguous must resolve `ok: false` with a reason: an unknown delivery that is
+   * retried puts the same sentence into a real conversation twice.
+   */
+  deliver: (turn: QueuedThreadTurn) => Promise<{ ok: boolean; reason?: string }>
+  now: () => number
+}
+
+/** Public shape of a queued turn. No prompt echo beyond a short preview. */
+function publicRow(turn: QueuedThreadTurn, position: number): Record<string, unknown> {
+  return {
+    clientTurnId: turn.clientTurnId,
+    status: turn.status,
+    queuedAt: turn.queuedAt,
+    attempts: turn.attempts,
+    position: turn.status === 'waiting' ? position : -1,
+    preview: turn.prompt.length > 80 ? `${turn.prompt.slice(0, 79)}…` : turn.prompt,
+    ...(turn.reason ? { reason: turn.reason } : {}),
+    ...(turn.settledAt ? { settledAt: turn.settledAt } : {}),
+  }
+}
+
+/**
+ * One drain pass over one thread.
+ *
+ * Exported for the test and for the sweep. Sequential by design: two turns to the same
+ * thread must not race, and the second one's readiness is decided AFTER the first has
+ * landed, because the first makes the thread busy again.
+ */
+export async function drainThread(
+  provider: string,
+  threadId: string,
+  deps: ThreadTurnQueueDeps,
+): Promise<{ delivered: number; held: number; retired: number }> {
+  const now = deps.now()
+  const queue = readQueue(provider, threadId, now)
+  if (queue.length === 0) return { delivered: 0, held: 0, retired: 0 }
+
+  let delivered = 0, held = 0, retired = 0
+  let dirty = false
+
+  for (const turn of queue) {
+    if (turn.status !== 'waiting') continue
+
+    // Observed FRESH for each turn: delivering one makes the thread busy again, so a
+    // verdict from the top of the loop would be stale by the second item.
+    const gate = deps.occupancy(provider, threadId)
+    const seen: DrainObservation = {
+      attachable: gate.attachable,
+      turnEnded: deps.turnEnded(provider, threadId),
+      activity: deps.activity(provider, threadId),
+    }
+    const decision = drainDecision(turn, seen, deps.now())
+
+    if (decision === 'hold') { held += 1; continue }
+    if (decision === 'expire' || decision === 'give_up') {
+      turn.status = decision === 'expire' ? 'expired' : 'refused'
+      turn.reason = decision === 'expire' ? 'queued_turn_expired' : 'delivery_attempts_exhausted'
+      turn.settledAt = deps.now()
+      retired += 1; dirty = true
+      continue
+    }
+
+    // ATTEMPT IS RECORDED BEFORE THE CALL, and persisted. A delivery that crashes the
+    // process mid-flight must not come back with its attempt count unchanged and try
+    // forever; the ceiling only bounds anything if it survives the crash it is bounding.
+    turn.attempts += 1
+    turn.status = 'delivering'
+    writeQueue(provider, threadId, queue)
+    dirty = true
+
+    let outcome: { ok: boolean; reason?: string }
+    try {
+      outcome = await deps.deliver(turn)
+    } catch (error) {
+      outcome = { ok: false, reason: error instanceof Error ? error.message : 'deliver_threw' }
+    }
+
+    if (outcome.ok) {
+      turn.status = 'delivered'
+      turn.settledAt = deps.now()
+      delivered += 1
+    } else if (turn.attempts >= MAX_DELIVERY_ATTEMPTS) {
+      turn.status = 'refused'
+      turn.reason = outcome.reason ?? 'delivery_failed'
+      turn.settledAt = deps.now()
+      retired += 1
+    } else {
+      // Back to waiting for the next sweep. A failure that is not terminal is a
+      // failure to deliver NOW, not a failure of the turn.
+      turn.status = 'waiting'
+      turn.reason = outcome.reason
+      held += 1
+    }
+  }
+
+  if (dirty) writeQueue(provider, threadId, queue)
+  return { delivered, held, retired }
+}
+
+/** One pass over every thread holding a queue. */
+export async function drainAllThreads(deps: ThreadTurnQueueDeps): Promise<number> {
+  let delivered = 0
+  for (const { provider, threadId } of queuedThreadKeys()) {
+    try {
+      delivered += (await drainThread(provider, threadId, deps)).delivered
+    } catch (error) {
+      // One bad thread must not stop the sweep for every other thread.
+      console.error(`[thread-turn-queue] drain failed for ${provider}: ${error instanceof Error ? error.message : error}`)
+    }
+  }
+  return delivered
+}
+
+export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
+  const router = Router()
+
+  // POST — park a turn for a thread that is busy right now.
+  router.post('/agent-sessions/:provider/:threadId/queued-turns', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    const provider = String(req.params.provider ?? '')
+    const threadId = String(req.params.threadId ?? '')
+    const body = (req.body ?? {}) as Record<string, unknown>
+    const clientTurnId = typeof body.clientTurnId === 'string' ? body.clientTurnId : ''
+    const cosSessionId = typeof body.cosSessionId === 'string' ? body.cosSessionId : ''
+    const prompt = typeof body.prompt === 'string' ? body.prompt : ''
+    if (!clientTurnId || !cosSessionId || !prompt.trim()) {
+      return res.status(400).json({ error: 'invalid_request' })
+    }
+
+    // THE GATE DECIDES WHETHER PARKING IS EVEN HONEST. A structural refusal can never
+    // clear, and telling someone their turn is queued when it can never run is worse
+    // than refusing it. An attachable thread is not queued either -- it is sent now,
+    // through the ordinary route, which the client does on this 409.
+    const gate = deps.occupancy(provider, threadId)
+    if (gate.attachable) return res.status(409).json({ error: 'thread_free', hint: 'send_now' })
+    if (!queueableRefusal(gate.reason)) {
+      return res.status(423).json({ error: gate.reason ?? 'probe_failed', queueable: false })
+    }
+
+    const now = deps.now()
+    const queue = readQueue(provider, threadId, now)
+    const admitted = admitToQueue(queue, {
+      clientTurnId, cosSessionId, provider, threadId, prompt,
+      queuedAt: now, status: 'waiting', attempts: 0,
+    })
+    if (!admitted.ok) return res.status(409).json({ error: admitted.reason })
+
+    writeQueue(provider, threadId, admitted.queue)
+    return res.status(202).json({
+      queued: true,
+      clientTurnId,
+      position: queuePosition(admitted.queue, clientTurnId),
+      waitingOn: gate.reason,
+    })
+  })
+
+  // GET — what is waiting, for the pending row on the lens.
+  router.get('/agent-sessions/:provider/:threadId/queued-turns', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    const provider = String(req.params.provider ?? '')
+    const threadId = String(req.params.threadId ?? '')
+    const queue = readQueue(provider, threadId, deps.now())
+    return res.json({ turns: queue.map(t => publicRow(t, queuePosition(queue, t.clientTurnId))) })
+  })
+
+  // DELETE — the cancel control, the same affordance the desktop queue offers.
+  router.delete('/agent-sessions/:provider/:threadId/queued-turns/:clientTurnId', (req: Request, res: Response) => {
+    res.set('Cache-Control', 'private, no-store')
+    const provider = String(req.params.provider ?? '')
+    const threadId = String(req.params.threadId ?? '')
+    const clientTurnId = String(req.params.clientTurnId ?? '')
+    const now = deps.now()
+    const queue = readQueue(provider, threadId, now)
+    const row = queue.find(t => t.clientTurnId === clientTurnId)
+    if (!row) return res.status(404).json({ error: 'unknown_turn' })
+    // A turn already handed to the adapter cannot be recalled, and saying otherwise
+    // would be the one lie this whole feature exists to avoid.
+    if (row.status === 'delivering') return res.status(409).json({ error: 'already_delivering' })
+    if (row.status === 'waiting') {
+      row.status = 'cancelled'
+      row.settledAt = now
+      writeQueue(provider, threadId, queue)
+    }
+    return res.json({ cancelled: true, clientTurnId, status: row.status })
+  })
+
+  return router
+}