@gotcos/glasses-server 6.48.0 → 6.48.1

package/server/lib/session-signal-store.ts

@@ -60,7 +60,7 @@ export interface SessionSignal {
   turnOpen: boolean
   turnStartedAt: number | null
   promptId: string | null
-  /** Stamped by the newest Stop: `state_since` for an idle row. (6.48.1's B6 occupancy clause will compare it to the transcript.) */
+  /** Stamped by the newest Stop: `state_since` for an idle row, and the instant the B6 occupancy clause and the drain gate compare with the registry's `statusUpdatedAt` (6.48.1). */
   stopAt: number | null
   waiting: WaitingSignal | null
   failure: FailureSignal | null
@@ -74,6 +74,12 @@ export interface SessionSignal {
   compactions: number
   /** Events from a COS-spawned child on this id, kept out of the phase. */
   childEvents: number
+  /**
+   * The registry's `entrypoint` for this session (`claude-desktop`, `cli`, `sdk-cli`), read
+   * from `~/.claude/sessions` while the process is alive; null until seen. A `claude -p` job
+   * registers as `sdk-cli` (measured 2026-09-15), which is how `/runs` tells a job from a tab.
+   */
+  entrypoint: string | null
   /** Hooks have been seen for this session: the row may say `state_source: hook`. */
   hooksSeen: true
 }
@@ -120,12 +126,26 @@ function fresh(env: HookEnvelope): SessionSignal {
     keepWarm: false,
     compactions: 0,
     childEvents: 0,
+    entrypoint: null,
     hooksSeen: true,
   }
 }
 
 const str = (v: unknown): string | null => (typeof v === 'string' && v.length > 0 ? v : null)
 
+/**
+ * 6.48.1. A tool runs only inside a turn, so a MAIN-THREAD tool event (no `agent_id`) is
+ * evidence the turn is open even when its UserPromptSubmit was never seen: a tab adopted
+ * mid-turn when the hooks were installed (2.1.272 reloads hooks on the settings change,
+ * measured 2026-09-15 16:16) read `idle` from the hooks while the registry said busy. A
+ * sub-agent's tool events carry `agent_id` and say nothing about the main thread, and a
+ * tool event after SessionEnd is a child's, never the tab's.
+ */
+function turnOpenedByTool(prev: SessionSignal, p: Record<string, unknown>, at: number): Partial<SessionSignal> {
+  if (prev.turnOpen || prev.ended || str(p.agent_id)) return {}
+  return { turnOpen: true, turnStartedAt: prev.turnStartedAt ?? at }
+}
+
 /** Waiting kinds a PostToolUse of the same tool resolves without a fingerprint match. */
 const TOOL_WAITING: Record<string, WaitingKind> = { AskUserQuestion: 'question', ExitPlanMode: 'plan' }
 
@@ -193,7 +213,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
           waiting: { kind, detail: tool.target, toolName: tool.name, fingerprint: tool.fingerprint, since: env.ts, requestId: null },
         }
       }
-      return { ...next, lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
+      return { ...next, ...turnOpenedByTool(next, p, env.ts), lastTool: tool.name || next.lastTool, lastToolAt: env.ts }
     }
     case 'PermissionRequest': {
       const tool = toolFacts(p)
@@ -216,7 +236,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
       const tool = toolFacts(p)
       const waiting = next.waiting && resolvesWaiting(next.waiting, env.event, tool.name, tool.fingerprint) ? null : next.waiting
       const ran = env.event !== 'PermissionDenied'
-      return { ...next, waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
+      return { ...next, ...turnOpenedByTool(next, p, env.ts), waiting, ...(ran ? { lastTool: tool.name || next.lastTool, lastToolAt: env.ts } : {}) }
     }
     case 'Notification': {
       const type = str(p.notification_type) ?? ''
@@ -259,7 +279,7 @@ export function applyHookEvent(prev: SessionSignal | undefined, env: HookEnvelop
   }
 }
 
-export type SignalListener = (signal: SessionSignal, env: HookEnvelope) => void
+export type SignalListener = (signal: SessionSignal, env: HookEnvelope, child: boolean) => void
 
 /** Records older than this after a SessionEnd are dropped; Control keeps its own ledger. */
 export const SIGNAL_PRUNE_AFTER_END_MS = 6 * 60 * 60_000
@@ -278,14 +298,22 @@ export class SessionSignalStore {
   apply(env: HookEnvelope, child?: boolean): SessionSignal {
     const next = applyHookEvent(this.signals.get(env.sessionId), env, this.ctx, child)
     this.signals.set(env.sessionId, next)
+    const isChild = child ?? this.ctx.isCosSpawnedPid(env.ppid)
     for (const listener of this.listeners) {
-      try { listener(next, env) } catch (error) {
+      try { listener(next, env, isChild) } catch (error) {
         console.error(`[session-signals] listener failed: ${error instanceof Error ? error.message : error}`)
       }
     }
     return next
   }
 
+  /** The registry's entrypoint, once the runtime has read it; a no-op for an unknown session. */
+  setEntrypoint(sessionId: string, entrypoint: string | null): void {
+    const current = this.signals.get(sessionId)
+    if (!current || !entrypoint || current.entrypoint === entrypoint) return
+    this.signals.set(sessionId, { ...current, entrypoint })
+  }
+
   /** RESERVED FOR 6.48.2 (the permission broker); no caller in 6.48.0. Attach the broker's
    *  minted id so rows can carry `pending_permission_id`. */
   attachPermissionRequestId(sessionId: string, requestId: string | null): void {

package/server/lib/session-state-derive.ts

@@ -64,6 +64,14 @@ export interface DeriveInput {
   registry: RegistryFacts | undefined
   transcript: TranscriptFacts | undefined
   now: number
+  /**
+   * A COS-spawned turn (Continue, a queued follow-up, a job) is writing this session
+   * RIGHT NOW (`isAttachedTurnActive`). Its hook events are classified as a child's and
+   * kept out of the phase, so without this the tab's last state (idle after its Stop)
+   * would be reported while COS itself is generating (QA, 2026-09-15: the shipped lens
+   * drops the trail on `idle`). Running, source `transcript`: it is our own write.
+   */
+  attachedTurn?: boolean
   /** The previous derive's `deadScans`, so the two-scan rule survives between polls. */
   prevDeadScans?: number
   /** The previous derive's `deadSince`. */
@@ -100,6 +108,10 @@ export function deriveSessionState(input: DeriveInput): DerivedSessionState {
   const hooksSilent = !!signal && now - signal.lastEventAt > HOOK_SILENCE_MS
   const carry = { deadScans, deadSince }
 
+  if (input.attachedTurn === true) {
+    return { agent_state: 'running', state_source: 'transcript', state_since: iso(transcript?.lastActivityAt ?? signal?.lastEventAt ?? now), ...carry, ...replyOf(signal) }
+  }
+
   // A dead pid on two scans at least DEAD_GRACE_MS apart ends the row whatever the hooks
   // last said, unless a hook event is newer than the registry's last movement (a resumed
   // tab under a new pid).
@@ -195,6 +207,32 @@ function waitStillStands(since: number, registry: RegistryFacts | undefined, tra
   return true
 }
 
+/**
+ * The fields a `status` draft carries (6.48.1): the row fields minus the permission id
+ * (slice 4's, never on the stream) and with `last_reply` only on an idle state, where a
+ * feed renders "Idle, last reply: …". A typed projection, so a new row field cannot reach
+ * the wire by accident.
+ */
+export function derivedStatusFields(derived: DerivedSessionState): {
+  agent_state: AgentState
+  state_source: StateSource
+  state_since: string
+  waiting_kind?: WaitingKind
+  waiting_detail?: string
+  failure?: string
+  last_reply?: string
+} {
+  return {
+    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 } : {}),
+    ...(derived.agent_state === 'idle' && derived.last_reply ? { last_reply: derived.last_reply } : {}),
+  }
+}
+
 /** The additive row fields, ready to spread onto a list or detail entry. */
 export function derivedRowFields(derived: DerivedSessionState | undefined): Record<string, unknown> {
   if (!derived) return {}

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`. */