@gotcos/glasses-server 6.48.0 → 6.48.2

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

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

@@ -13,11 +13,17 @@ import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readd
 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 { turnFromTail, type SessionStreamProvider, type TurnFromTail } 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
+/**
+ * Bytes of transcript tail read to decide whether the last turn ended. 512 KiB, not 64:
+ * on the release Mac 3 of the 10 newest Desktop transcripts end in a ~76 KB bookkeeping
+ * row (a `prompt_snapshot` attachment) AFTER the terminal record, and a 64 KiB tail read
+ * only that row, saw no conversation record, and held the queue for the 30 s backstop
+ * (QA, 2026-09-15). The read is one `pread` per decision; nothing here streams.
+ */
+export const TURN_END_TAIL_BYTES = 512 * 1024
 
 function queueDir(): string {
   const dir = dataPath('thread-turn-queue')
@@ -62,6 +68,46 @@ export function writeQueue(provider: string, threadId: string, queue: readonly Q
   atomicWriteFileSync(queuePath(provider, threadId), `${JSON.stringify(queue, null, 2)}\n`)
 }
 
+/**
+ * How many WAITING follow-ups a list/detail row should show (6.48.1).
+ *
+ * Queue files are named with the native thread id (often a full UUID). Claude
+ * list rows stay on the registry's 8-character form until a transcript match
+ * expands them. An exact match always wins; an 8-character id is allowed to
+ * count a unique prefix among waiting queues of that provider, and an
+ * ambiguous prefix counts as zero rather than guessing.
+ *
+ * PURE: the store builds the input from disk; this decides the number.
+ */
+export function queuedWaitingForSession(
+  queues: ReadonlyArray<{ provider: string; threadId: string; waiting: number }>,
+  provider: string, sessionId: string,
+): number {
+  const id = sessionId.toLowerCase()
+  const rows = queues.filter(q => q.provider === provider && q.waiting > 0)
+  const exact = rows.find(q => q.threadId.toLowerCase() === id)
+  if (exact) return exact.waiting
+  if (id.length !== 8) return 0
+  const prefixed = rows.filter(q => q.threadId.toLowerCase().startsWith(id))
+  const owners = new Set(prefixed.map(q => q.threadId.toLowerCase()))
+  if (owners.size !== 1) return 0
+  return prefixed[0]!.waiting
+}
+
+/** One lookup for a whole list/search request: one directory read, then O(1) per row. */
+export function queuedWaitingLookup(now: number): (provider: string, sessionId: string) => number {
+  const queues = queuedThreadKeys().map(({ provider, threadId }) => ({
+    provider,
+    threadId,
+    waiting: readQueue(provider, threadId, now).filter(t => t.status === 'waiting').length,
+  }))
+  return (provider, sessionId) => queuedWaitingForSession(queues, provider, sessionId)
+}
+
+export function queuedTurnsFields(count: number): { queued_turns?: number } {
+  return count > 0 ? { queued_turns: count } : {}
+}
+
 /** Every thread with a queue file, for the drain sweep. */
 export function queuedThreadKeys(): Array<{ provider: string; threadId: string }> {
   try {
@@ -83,24 +129,32 @@ export function queuedThreadKeys(): Array<{ provider: string; threadId: string }
 /**
  * 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.
+ * 6.48.1: decided by `turnFromTail`, the transcript's own rule (a terminal
+ * `stop_reason` with no tool_use awaiting its result, a `result` row, or a user
+ * interrupt). It replaced the status-draft loop here because a Desktop transcript
+ * writes no `result` row, so the old rule could only ever say "ended" for a
+ * `claude -p` run and every Desktop Continue waited the 30 s idle backstop (measured
+ * 2026-09-15: 0 of 30 newest transcripts carry one). The live feed still narrates
+ * from `draftsFromLine`; the two are pinned to agree on recorded tails.
  *
  * 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.
  */
+/** The full tail verdict, for callers that need to know OPEN as well as ended. Null on any doubt. */
+export function transcriptTurnVerdict(provider: SessionStreamProvider, path: string | null): TurnFromTail | null {
+  const lines = readTail(path)
+  return lines === null ? null : turnFromTail(provider, lines)
+}
+
 export function transcriptTurnEnded(provider: SessionStreamProvider, path: string | null): boolean {
-  if (!path || !existsSync(path)) return false
+  return transcriptTurnVerdict(provider, path)?.ended === true
+}
+
+/** The bounded tail as lines, with the same two open flags; null when it cannot be read. */
+function readTail(path: string | null): string[] | null {
+  if (!path || !existsSync(path)) return null
   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
@@ -110,18 +164,11 @@ export function transcriptTurnEnded(provider: SessionStreamProvider, path: strin
       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
+      return lines
     } finally {
       closeSync(fd)
     }
   } catch {
-    return false
+    return null
   }
 }

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

@@ -53,11 +53,15 @@
 // ---------------------------------------------------------------------------
 // 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` /
+// of someone's reasoning. The precise signal is the turn ENDING. For Claude that is the
+// engine's own Stop hook followed by the registry flipping `idle` (6.48.1; a Desktop
+// transcript carries no `result` record, and the Stop alone is 12-38 s early while the
+// Stop hooks run), else the transcript's newest assistant record with a terminal
+// `stop_reason` and no pending tool (`turnFromTail`); Codex writes `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.
+// event, and positive evidence of an OPEN turn outranks it. 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 =
@@ -186,6 +190,14 @@ export interface DrainObservation {
   turnEnded: boolean
   /** The 30s transcript clock. `idle` is the backstop when no terminal record lands. */
   activity: 'working' | 'idle' | 'unknown'
+  /**
+   * 6.48.1: POSITIVE evidence the turn is still open (a tool_use awaiting its result, a
+   * prompt newer than the last reply, or the hooks saying the turn has not stopped),
+   * bounded by the caller to a recent window. It outranks the idle backstop: a 40 s tool
+   * leaves the transcript untouched for 40 s, and "idle for 30 s" used to deliver a
+   * follow-up straight into that live turn (measured 2026-09-15 on the 6.48.1 live proof).
+   */
+  turnOpen?: boolean
   /** The gate's reason when `attachable` is false. Carried ONLY so a fence -- the one
    *  hold a clock cannot end -- can be given a longer life than a busy thread. */
   reason?: string | null
@@ -218,6 +230,10 @@ export function drainDecision(
   // 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.
+  // Positive evidence the turn is OPEN outranks a terminal record older than it: a prompt
+  // queued at the desk during the Stop hooks dequeues after them, and the tail's newest
+  // terminal record cannot see it (QA, 2026-09-15).
+  if (seen.turnOpen === true) return 'hold'
   if (seen.turnEnded) return 'deliver'
   return seen.activity === 'idle' ? 'deliver' : 'hold'
 }