@gotcos/glasses-server 6.47.0 → 6.48.1

package/server/lib/session-stream-bus.ts

@@ -21,16 +21,92 @@
 //
 // So: same transport, own keyspace. This module is deliberately small.
 //
-// NO REPLAY BUFFER HERE EITHER, and that is a decision rather than an omission. A
-// reconnecting client resumes LIVE and its 5s/15s/60s poll is what fills the gap it
-// missed; the contract gives it `seq` precisely so it can SEE the gap. Retaining a
-// per-session ring would add memory that grows with the number of sessions ever
-// opened, to duplicate a fallback that already exists and already works.
+// A BOUNDED REPLAY RING PER STREAMED SESSION (6.48.1), and why the earlier "no ring"
+// decision moved. `seq` stays per connection, so a shipped client still sees its gaps;
+// a new client ALSO reads `cursor`, monotonic per session for this server's life, and
+// reconnects with `?after=<cursor>` to be handed what it missed instead of a fresh
+// seed. The ring holds the last RING_MAX published events, keeps the ACTIVE TURN whole
+// (from its newest `prompt` draft onward, up to RING_HARD_MAX) and is dropped with the
+// session's last subscriber plus a linger, so memory is bounded by streamed sessions,
+// not by sessions ever opened. Even Terminal 0.10.4 ships the same shape (500-event
+// ring, replay on reconnect, the active turn always retained).
 
 import type { SessionStreamDraft } from './session-stream-events.js'
 
-/** A draft with the publish instant stamped. `seq` stays per connection. */
-export type PublishedSessionEvent = SessionStreamDraft & { at: number }
+/** A draft with the publish instant stamped. `seq` stays per connection; `cursor` is per session within `epoch`. */
+export type PublishedSessionEvent = SessionStreamDraft & { at: number; cursor?: number; epoch?: number }
+
+/**
+ * Cursors are meaningful only within one server life: a client holding a cursor from
+ * before a restart would otherwise be handed the wrong events from a fresh ring with no
+ * gap to notice (QA, 2026-09-15). Every event carries the epoch, and the SSE `id:` line
+ * is `<epoch>.<cursor>`; the route refuses to replay across epochs.
+ */
+export const RING_EPOCH = Date.now()
+
+/** Events the ring keeps per session. */
+export const RING_MAX = 500
+/** The active turn is never cut short of this. */
+export const RING_HARD_MAX = 2_000
+/** A session's ring outlives its last subscriber this long, so a reconnect finds the gap. */
+export const RING_LINGER_MS = 5 * 60_000
+
+interface Ring {
+  events: Array<PublishedSessionEvent & { cursor: number }>
+  nextCursor: number
+  /** Index into `events` of the newest prompt draft, or -1. */
+  turnStart: number
+  emptySince: number | null
+}
+
+const rings = new Map<string, Ring>()
+
+function ringFor(key: string): Ring {
+  let ring = rings.get(key)
+  if (!ring) {
+    ring = { events: [], nextCursor: 1, turnStart: -1, emptySince: null }
+    rings.set(key, ring)
+  }
+  return ring
+}
+
+function remember(key: string, event: PublishedSessionEvent): PublishedSessionEvent & { cursor: number } {
+  const ring = ringFor(key)
+  const stamped = { ...event, cursor: ring.nextCursor++, epoch: RING_EPOCH }
+  ring.events.push(stamped)
+  if (stamped.kind === 'prompt') ring.turnStart = ring.events.length - 1
+  // Trim the oldest, but never into the active turn until the hard cap.
+  while (ring.events.length > RING_MAX) {
+    if (ring.turnStart === 0 && ring.events.length <= RING_HARD_MAX) break
+    ring.events.shift()
+    if (ring.turnStart >= 0) ring.turnStart--
+  }
+  return stamped
+}
+
+/** Events published to this session after `afterCursor`, oldest first. Empty for an unknown session. */
+export function replaySessionStream(key: string, afterCursor: number): Array<PublishedSessionEvent & { cursor: number }> {
+  const ring = rings.get(key)
+  if (!ring) return []
+  const after = Number.isFinite(afterCursor) ? afterCursor : 0
+  return ring.events.filter(e => e.cursor > after)
+}
+
+/** The ring's oldest and newest cursors, so a client can tell a replay from a reseed. */
+export function ringBounds(key: string): { oldest: number; newest: number } | null {
+  const ring = rings.get(key)
+  if (!ring || ring.events.length === 0) return null
+  return { oldest: ring.events[0].cursor, newest: ring.events[ring.events.length - 1].cursor }
+}
+
+/** Drop rings whose session has had no subscriber for the linger. Called by the route on release. */
+export function sweepSessionRings(nowMs = Date.now()): number {
+  let dropped = 0
+  for (const [key, ring] of rings) {
+    if (ring.emptySince !== null && nowMs - ring.emptySince > RING_LINGER_MS) { rings.delete(key); dropped++ }
+  }
+  return dropped
+}
 
 export type SessionStreamListener = (event: PublishedSessionEvent) => void
 
@@ -78,6 +154,7 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
   const set = existing ?? new Set<SessionStreamListener>()
   set.add(listener)
   listeners.set(key, set)
+  ringFor(key).emptySince = null
 
   let released = false
   return () => {
@@ -88,7 +165,12 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
     const current = listeners.get(key)
     if (!current) return
     current.delete(listener)
-    if (current.size === 0) listeners.delete(key)
+    if (current.size === 0) {
+      listeners.delete(key)
+      const ring = rings.get(key)
+      if (ring) ring.emptySince = Date.now()
+      sweepSessionRings()
+    }
   }
 }
 
@@ -103,7 +185,8 @@ export function subscribeSessionStream(key: string, listener: SessionStreamListe
 export function publishSessionStream(key: string, draft: SessionStreamDraft, at: number = Date.now()): number {
   const set = listeners.get(key)
   if (!set || set.size === 0) return 0
-  const event: PublishedSessionEvent = { ...draft, at }
+  // Remembered BEFORE fan-out, so a listener that reads the ring sees this event too.
+  const event: PublishedSessionEvent = remember(key, { ...draft, at })
   let delivered = 0
   for (const listener of [...set]) {
     try {
@@ -147,4 +230,5 @@ export function isAttachedTurnActive(key: string): boolean {
 export function __resetSessionStreamBusForTests(): void {
   listeners.clear()
   attachedTurns.clear()
+  rings.clear()
 }

package/server/lib/session-stream-events.ts

@@ -457,6 +457,150 @@ export function draftsFromLine(provider: SessionStreamProvider, line: string): S
   return draftsFromRecord(provider, parsed)
 }
 
+/**
+ * Did the newest turn in this transcript tail END? (6.48.1)
+ *
+ * THE RULE THE HARNESS USES, read against real Desktop transcripts on this Mac
+ * (2026-09-15): a Desktop session writes no `type:'result'` row at all (0 of 30 newest
+ * transcripts), so the status-draft rule above can only ever say "ended" for a
+ * `claude -p` run. What every Claude transcript DOES carry is `message.stop_reason` on
+ * each assistant record: `tool_use` while tools run, `end_turn` when the reply is done.
+ *
+ *   ended     the newest assistant record's stop_reason is terminal (end_turn,
+ *             stop_sequence, max_tokens, refusal) and no tool_use it issued is still
+ *             waiting for its tool_result; or a `result` row; or the user interrupted
+ *             (`[Request interrupted by user`), which ends the turn without a reply.
+ *   open      a user prompt newer than the last terminal reply (a `<task-notification>`
+ *             included: the model answers it), or a tool_use with no result yet.
+ *
+ * Skipped: `isMeta` and `isCompactSummary` rows (injected context, not a prompt), tool
+ * results, and the bookkeeping rows (`system`, `last-prompt`, `attachment`, `mode`...).
+ * Codex keeps its event rule (task_complete / turn_complete end, task_started opens).
+ *
+ * PURE, like everything else here. The queue store reads the tail; this decides.
+ */
+export const TERMINAL_STOP_REASONS: ReadonlySet<string> = new Set(['end_turn', 'stop_sequence', 'max_tokens', 'refusal'])
+
+export type TurnFromTail = { ended: boolean; reason: 'terminal_stop' | 'result_row' | 'interrupted' | 'codex_complete' | 'prompt_open' | 'prompt_queued' | 'tool_pending' | 'no_evidence' }
+
+export function turnFromTail(provider: SessionStreamProvider, lines: readonly string[]): TurnFromTail {
+  let verdict: TurnFromTail = { ended: false, reason: 'no_evidence' }
+  const pendingToolUses = new Set<string>()
+  for (const line of lines) {
+    const trimmed = typeof line === 'string' ? line.trim() : ''
+    if (!trimmed || trimmed[0] !== '{') continue
+    let record: unknown
+    try { record = JSON.parse(trimmed) } catch { continue }
+    const r = asRecord(record)
+    if (!r) continue
+
+    if (provider === 'codex') {
+      for (const draft of draftsFromRecord('codex', r)) {
+        if (draft.kind === 'status') verdict = draft.state === 'done' ? { ended: true, reason: 'codex_complete' } : { ended: false, reason: 'prompt_open' }
+      }
+      continue
+    }
+
+    const type = typeof r.type === 'string' ? r.type : ''
+    if (type === 'result') { verdict = { ended: true, reason: 'result_row' }; pendingToolUses.clear(); continue }
+    // A prompt typed while the Stop hooks run is QUEUED, not submitted (Claude writes a
+    // `queue-operation` row); it dequeues once the hooks return and the model answers it.
+    // The turn is not over until then (QA, 2026-09-15). The dequeue is followed by the
+    // user row itself, which the next branch reads.
+    if (type === 'queue-operation') {
+      if (r.operation === 'enqueue') verdict = { ended: false, reason: 'prompt_queued' }
+      continue
+    }
+    // Injected context is not a prompt, except a cross-session message (`promptSource:
+    // 'system'`), which the model answers as a turn.
+    if (r.isCompactSummary === true) continue
+    if (r.isMeta === true && r.promptSource !== 'system') continue
+    const message = asRecord(r.message)
+    if (!message) continue
+    const content = Array.isArray(message.content) ? message.content : typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : []
+    const blocks = content.map(asRecord).filter((b): b is Record<string, unknown> => b !== null)
+
+    if (type === 'user' || message.role === 'user') {
+      const results = blocks.filter(b => b.type === 'tool_result')
+      if (results.length > 0) {
+        for (const b of results) if (typeof b.tool_use_id === 'string') pendingToolUses.delete(b.tool_use_id)
+        continue
+      }
+      const text = blocks.filter(b => b.type === 'text' || b.type === undefined).map(b => (typeof b.text === 'string' ? b.text : '')).join(' ')
+      if (/\[Request interrupted by user/.test(text)) { verdict = { ended: true, reason: 'interrupted' }; pendingToolUses.clear(); continue }
+      if (text.trim().length === 0) continue
+      verdict = { ended: false, reason: 'prompt_open' }
+      continue
+    }
+
+    if (type === 'assistant' || message.role === 'assistant') {
+      for (const b of blocks) if (b.type === 'tool_use' && typeof b.id === 'string') pendingToolUses.add(b.id)
+      const stop = typeof message.stop_reason === 'string' ? message.stop_reason : ''
+      if (TERMINAL_STOP_REASONS.has(stop)) {
+        verdict = pendingToolUses.size === 0 ? { ended: true, reason: 'terminal_stop' } : { ended: false, reason: 'tool_pending' }
+      } else if (stop === 'tool_use' || pendingToolUses.size > 0) {
+        verdict = { ended: false, reason: 'tool_pending' }
+      }
+    }
+  }
+  return verdict
+}
+
+/**
+ * The derived session state on a `status` draft (6.48.1).
+ *
+ * EXTRA FIELDS ON THE EXISTING KIND, NEVER A NEW KIND: every shipped EHPK drops an
+ * unknown `kind` before its `seq` accounting and paints a "missed N" gap per event
+ * (validation round 1, B2). The shipped parser keeps `seq` and strips unknown fields
+ * on a `status` draft (canary 8), so an old client renders exactly as before and a
+ * new one reads the state line off the same event.
+ *
+ * `state` keeps its closed vocabulary. The table:
+ *   running -> working      waiting -> working (+ waiting_kind/detail)
+ *   idle    -> idle         failed  -> idle (+ failure)      ended -> done
+ *
+ * `done` on open flips the client to its digest body, which is intended for a session
+ * whose engine said SessionEnd. An ATTACHED COS TURN WINS (QA, 2026-09-15): the deriver
+ * is told `attachedTurn` and answers `running` for as long as the child is writing, so
+ * a Continue's trail is never handed off mid-stream by the tab's older Stop or by a
+ * child's own SessionEnd; the engine's state resumes the moment the turn detaches.
+ *
+ * `last_reply` rides only an idle state (the feed's "Idle, last reply: …" line).
+ */
+export interface DerivedStatusFields {
+  agent_state: 'running' | 'waiting' | 'idle' | 'failed' | 'ended'
+  state_source: 'hook' | 'registry' | 'transcript'
+  state_since: string
+  waiting_kind?: string
+  waiting_detail?: string
+  failure?: string
+  last_reply?: string
+}
+
+export type StatusDraftWithDerived = { kind: 'status'; state: SessionStreamState } & Partial<DerivedStatusFields>
+
+export function statusDraftWithDerived(
+  draft: { kind: 'status'; state: SessionStreamState },
+  derived: DerivedStatusFields | undefined,
+): StatusDraftWithDerived {
+  if (!derived) return draft
+  const state: SessionStreamState =
+    derived.agent_state === 'running' || derived.agent_state === 'waiting' ? 'working'
+    : derived.agent_state === 'ended' ? 'done'
+    : 'idle'
+  return {
+    kind: 'status',
+    state,
+    agent_state: derived.agent_state,
+    state_source: derived.state_source,
+    state_since: derived.state_since,
+    ...(derived.waiting_kind ? { waiting_kind: derived.waiting_kind } : {}),
+    ...(derived.waiting_detail !== undefined ? { waiting_detail: derived.waiting_detail } : {}),
+    ...(derived.failure ? { failure: derived.failure } : {}),
+    ...(state === 'idle' && derived.last_reply ? { last_reply: derived.last_reply } : {}),
+  }
+}
+
 /** Draft plus transport stamps, in the field order the contract shows. */
 export function stampSessionEvent(draft: SessionStreamDraft, seq: number, at: number): SessionStreamEvent {
   return { seq, at, ...draft }

package/server/lib/thread-drain-kick.ts

@@ -0,0 +1,153 @@
+// The Stop-driven drain kick (6.48.1).
+//
+// Before this, a queued follow-up waited for the 20 s sweep AND the holder's 30 s idle
+// window: measured 35 s or more from the turn's end to delivery. The hooks now say the
+// exact moment a turn ends (Stop), so the queue is drained THEN.
+//
+// ONE DRAIN IN FLIGHT, EXACTLY ONE FOLLOW-UP. The 20 s timer and the Stop kick share
+// this guard, so a Stop landing during a sweep cannot start a second sweep that reads
+// the same queue file and delivers the same sentence twice; it schedules one more pass
+// after the current one, and a burst of Stops collapses into that one pass.
+//
+// A kick is spent only when a queue file exists for that session: a Stop on a session
+// nobody queued for costs a directory listing and nothing else. The match is the full
+// session id: a Claude queue file is always keyed by the full UUID, because the attach
+// gate refuses anything else as `invalid_thread_id` before a turn can be queued, and
+// every hook envelope carries the full id (QA, 2026-09-15: the 8-character branch this
+// used to carry was unreachable).
+//
+// The sweep itself runs on the NEXT macrotask, never inside the caller: a kick arrives
+// from the signal store inside the spool sweep, and the drain's synchronous head (a
+// registry scan, a `ps` per owner, a tail read) belongs after that sweep and after the
+// stream listeners for the same Stop have written their line.
+
+export interface DrainKickDeps {
+  /** The sweep. Resolves the number delivered; rejects are swallowed here. */
+  drain: () => Promise<number>
+  /** Thread ids with a queue file right now, any provider. */
+  queuedThreadIds: () => string[]
+}
+
+export interface DrainKick {
+  /** Run the sweep, or fold into the one in flight. Resolves when THIS request's pass has run. */
+  sweep(): Promise<void>
+  /** A session's turn ended: sweep (next macrotask) if a queue names it. Returns true when a sweep was requested. */
+  kick(sessionId: string): boolean
+  /**
+   * Kick once `ready()` answers true, polling every `everyMs` for up to `maxMs`; a kick
+   * at Stop time is too early when the engine closes the turn only after its Stop hooks
+   * (12-38 s on the release Mac), and nothing fires a hook when they return. Returns
+   * false at once when no queue names the session, so an unqueued Stop costs nothing.
+   */
+  kickWhen(sessionId: string, ready: () => boolean, opts?: { everyMs?: number; maxMs?: number }): boolean
+  /** For health: passes run, kicks spent, kicks folded into a running pass, waits open. */
+  stats(): { passes: number; kicks: number; folded: number; inFlight: boolean; waiting: number }
+}
+
+export const KICK_POLL_MS = 1_000
+export const KICK_WAIT_MAX_MS = 60_000
+
+/** The facts the kick plan reads off a session signal after one hook event. */
+export interface KickSignalFacts {
+  turnOpen: boolean
+  subagentsOpen: number
+  ended: unknown
+  stopAt: number | null
+}
+
+/** What one hook event asks of the kick: nothing, a kick now, or a kick once the registry says idle after `stopAt`. */
+export type KickPlan = { kind: 'kick' } | { kind: 'kick_when_registry_idle'; stopAt: number } | null
+
+/**
+ * The composition root's rule, pure so it is pinned (QA N1, 2026-09-15):
+ *
+ *  - a COS child's own SessionEnd frees the thread for the NEXT queued turn at once
+ *    (without it a chained follow-up waited for the 20 s timer); nothing else a child
+ *    does kicks, since its Stop is the turn this server is delivering;
+ *  - the tab's Stop kicks once the registry flips idle after it (the Stop hooks have
+ *    returned); a Stop with the turn still open, a sub-agent still open, or the session
+ *    ended asks nothing;
+ *  - a SubagentStop never kicks: a background sub-agent finishing after the Stop is
+ *    answered by the model in a turn of its own, whose Stop kicks, and neither the hook
+ *    short-circuit nor the B6 clause vouches for a session whose newest event is a
+ *    SubagentStop, so a kick there could only fall through to the 30 s backstop.
+ */
+export function kickPlanFor(signal: KickSignalFacts, event: string, eventTs: number, child: boolean): KickPlan {
+  if (child) return event === 'SessionEnd' ? { kind: 'kick' } : null
+  if (event !== 'Stop') return null
+  if (signal.turnOpen || signal.subagentsOpen > 0 || signal.ended) return null
+  return { kind: 'kick_when_registry_idle', stopAt: typeof signal.stopAt === 'number' ? signal.stopAt : eventTs }
+}
+
+export function createDrainKick(deps: DrainKickDeps): DrainKick {
+  let inFlight: Promise<void> | null = null
+  let followUp: Promise<void> | null = null
+  const stats = { passes: 0, kicks: 0, folded: 0 }
+
+  const runOnce = async (): Promise<void> => {
+    stats.passes++
+    try { await deps.drain() } catch { /* the next pass retries; the sweep logs its own errors */ }
+  }
+
+  const sweep = (): Promise<void> => {
+    if (!inFlight) {
+      inFlight = runOnce().finally(() => { inFlight = null })
+      return inFlight
+    }
+    // Exactly one follow-up pass, however many requests arrive while the first runs.
+    if (!followUp) {
+      stats.folded++
+      const current = inFlight
+      followUp = current.then(() => { followUp = null; return sweep() })
+    } else {
+      stats.folded++
+    }
+    return followUp
+  }
+
+  const queueNames = (sessionId: string): boolean => {
+    const id = sessionId.toLowerCase()
+    return deps.queuedThreadIds().some(t => t.toLowerCase() === id)
+  }
+
+  const waits = new Map<string, ReturnType<typeof setInterval>>()
+
+  const kick = (sessionId: string): boolean => {
+    if (!queueNames(sessionId)) return false
+    stats.kicks++
+    setImmediate(() => { void sweep() })
+    return true
+  }
+
+  return {
+    sweep,
+    kick,
+    kickWhen(sessionId: string, ready: () => boolean, opts = {}): boolean {
+      if (!queueNames(sessionId)) return false
+      const key = sessionId.toLowerCase()
+      const existing = waits.get(key)
+      if (existing) { clearInterval(existing); waits.delete(key) }
+      let readyNow = false
+      try { readyNow = ready() } catch { readyNow = false }
+      if (readyNow) return kick(sessionId)
+      const everyMs = opts.everyMs ?? KICK_POLL_MS
+      const maxMs = opts.maxMs ?? KICK_WAIT_MAX_MS
+      const startedAt = Date.now()
+      const timer = setInterval(() => {
+        let ok = false
+        try { ok = ready() } catch { ok = false }
+        if (ok || Date.now() - startedAt >= maxMs) {
+          clearInterval(timer)
+          waits.delete(key)
+          // Past the wait the sweep still runs: the gate decides, and the 20 s timer would
+          // have anyway. Nothing here can deliver; only the gate can.
+          kick(sessionId)
+        }
+      }, everyMs)
+      timer.unref?.()
+      waits.set(key, timer)
+      return true
+    },
+    stats: () => ({ ...stats, inFlight: inFlight !== null, waiting: waits.size }),
+  }
+}

package/server/lib/thread-occupancy.ts

@@ -150,6 +150,23 @@ export interface OccupancyProbes {
    * safety property here.
    */
   transcriptMtimeMs?: (provider: OccupancyProvider, threadId: string) => number | null
+  /**
+   * THE B6 CLAUSE (6.48.1). Epoch ms of the holder's newest hook `Stop`, ONLY when the
+   * engine itself has closed the turn: that Stop is the session's newest hook event, no
+   * sub-agent is open, the session has not ended, AND the registry record says `idle`
+   * with `statusUpdatedAt` at or after the Stop (Claude flips it only when every Stop
+   * hook has returned, 12-38 s after the Stop on the release Mac, which is when a prompt
+   * queued at the desk would dequeue). Null otherwise, and always null for Codex.
+   * OPTIONAL, and its absence is the default: attached by `withHookTurnClock` at the
+   * composition root only when `COS_SESSION_HOOKS` is on, so the pure gate never reads
+   * the environment.
+   *
+   * What it buys: a foreign Desktop holder whose turn the engine has closed reads `idle`
+   * at once instead of after the 30 s transcript window. The transcript's mtime is not
+   * consulted: the bookkeeping rows Claude writes as the hooks finish are exactly what
+   * makes the file look busy at the moment it is safest to attach.
+   */
+  holderTurnEndedAtMs?: (provider: OccupancyProvider, threadId: string) => number | null
   /**
    * Cursor Agent CLI session at `~/.cursor/chats/<hash>/<id>/`, or null when
    * that id is not exactly one continuable chats dir. Occupancy MUST NOT import
@@ -237,6 +254,7 @@ export function isActiveRecently(mtimeMs: number | null | undefined, nowMs: numb
  */
 export type HolderActivity = 'working' | 'idle' | 'unknown'
 
+
 export function holderActivity(mtimeMs: number | null | undefined, nowMs: number): HolderActivity {
   if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs)) return 'unknown'
   if (!Number.isFinite(nowMs)) return 'unknown'
@@ -261,11 +279,28 @@ function readHolderActivity(
   nowMs: number,
 ): HolderActivity {
   if (typeof probes.transcriptMtimeMs !== 'function') return 'unknown'
+  let mtime: number | null
   try {
-    return holderActivity(probes.transcriptMtimeMs(provider, threadId), nowMs)
+    mtime = probes.transcriptMtimeMs(provider, threadId)
   } catch {
     return 'unknown'
   }
+  const activity = holderActivity(mtime, nowMs)
+  if (activity !== 'working') return activity
+  // THE B6 CLAUSE. Only a `working` verdict is revisited, only for Claude, only with a
+  // real clock behind it, and only when the hook probe VOUCHES that the engine closed
+  // the turn (null is strict). `unknown` stays unknown: the clause narrows a refusal,
+  // never a doubt.
+  if (provider !== 'claude' || typeof probes.holderTurnEndedAtMs !== 'function' || typeof mtime !== 'number') return activity
+  let stopAt: number | null
+  try {
+    stopAt = probes.holderTurnEndedAtMs(provider, threadId)
+  } catch {
+    return activity
+  }
+  if (typeof stopAt !== 'number' || !Number.isFinite(stopAt)) return activity
+  if (stopAt > nowMs + ACTIVE_RECENTLY_WINDOW_MS) return activity
+  return 'idle'
 }
 
 /** A Claude registry filename is exactly `<pid>.json`. Not `*.json`. */

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

@@ -26,6 +26,7 @@
 
 import { request } from 'node:http'
 import type { QueuedThreadTurn } from './thread-turn-queue.js'
+import { targetKey } from './agent-session-binding-store.js'
 
 /** Per-request ceiling. Attach and turn both answer immediately; the turn route
  *  admits with 202 and does the long work in the background. */
@@ -97,16 +98,26 @@ export async function deliverQueuedTurnOverLoopback(
     }
     const bindingId = typeof attach.body.bindingId === 'string' ? attach.body.bindingId : ''
     if (!bindingId) return { ok: false, reason: 'attach_no_binding' }
-
+    // 6.48.1: the turns route has required `epoch` and `targetKey` since the binding
+    // hardening, and refused this body as `invalid_request` (retryable, so the turn was
+    // refunded and held forever: every drained follow-up since then never landed; found by
+    // the 6.48.1 live proof, 2026-09-15). The epoch is the one the attach just minted and
+    // the target key is the server's own function of (provider, native id), exactly what
+    // the phone sends.
+    const epoch = typeof attach.body.epoch === 'number' && Number.isInteger(attach.body.epoch) && attach.body.epoch >= 1 ? attach.body.epoch : null
+    if (epoch === null) return { ok: false, reason: 'attach_no_epoch' }
+    const boundTo = typeof attach.body.boundTo === 'string' ? attach.body.boundTo : undefined
     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 },
+      {
+        clientTurnId: turn.clientTurnId,
+        prompt: turn.prompt,
+        epoch,
+        targetKey: targetKey(turn.provider, turn.threadId),
+        ...(boundTo ? { boundTo } : {}),
+      },
     )
-    // 202 is the success shape: admitted, delivered in the background, poll the ledger.
     if (sent.status === 202 || sent.status === 200) return { ok: true }
     // Same defect on the turn leg: `refuseTurn` emits `reason`/`reasonCopy`/`retryable`
     // and no `error`. `retryable` is the server's OWN judgement about this refusal --