@gotcos/glasses-server 6.48.2 → 6.49.1

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 6.49.1
+
+Where a turn's time goes, and the two things the /qa pass on 6.49.0 found that made a follow-up wait or repeat.
+
+- **A lease yields.** A Continue binding held its thread for the whole 30 min TTL after its turn completed, and every client attaches per send (the phone on every Send, the queue drainer on every drain, the lens on every hold), so the second follow-up on a thread within half an hour was parked behind a binding nobody was using. Measured 2026-09-16: three phone follow-ups queued 17:19-17:28 landed at 17:52, the minute after the lens's binding expired, with the session idle throughout. Now an unpinned binding yields 90 s after its last turn ended (`IDLE_LEASE_YIELD_MS`): the next attach supersedes it in the same registry mutation, so the thread never has two live bindings and a late turn on the old one reads `binding_detached`. A binding with a turn in flight, or younger than 90 s (the lens attaches before the wearer dictates), still refuses `native_target_busy`. The queue drainer's `attachable` probe uses the same predicate, so it never holds behind a lease the attach would supersede.
+- **The turn ledger is per thread, not per binding.** A draft's idempotency key (app 6.9.487/488) can arrive through a new binding: the phone re-attaches on every Send, and a draft parked after `target_busy` drains through the drainer's own binding. `findTurn` read only that binding's rows, so the repeat was delivered again; QA reproduced it against the real registry. It now reads every binding of the same thread, on disk, across restarts.
+- **Acceptance is read from the send offset.** The memo's re-check read a fixed 256 KiB tail, and one tool result can be over a megabyte (18 such rows in one real session), so the enqueue row could be pushed out of the read and a retry after the memo expired would spawn the same prompt again. The transport now notes the transcript's size before the send and every read covers from there to the end. A connect that failed before the socket opened (`connect_timeout`, `ENOTSOCK`, `EACCES`) is now `connect_failed` (nothing sent, spawn at once) rather than a 60 s suspect; every rejection from the socket writer carries the phase it failed in. The route's 4 s verify budget and the transport's default are one constant now (they were 4 and 6). The unreachable `no_socket` reason is gone.
+- **Outcomes on seeded steps, paired by call id.** On a fresh open the seed carried the steps but dropped their results (they ride status drafts, which the seed drops), so the client hung every LIVE result on the oldest seeded step and the newest tool read as running forever. Seeded `tool` events now carry `outcome` (and `call`, the provider's `tool_use_id`); live `tool_outcome`s carry `call` too, so a client can pair a result with exactly the step that produced it, and two parallel calls finishing out of order keep their own results. Extra fields on existing kinds: a shipped client strips them.
+- **The timing line, on every exit that answers.** The turn route prints one `[agent-session-bindings] turn timing` line per request with the outcome (`completed/live`, `queued`, `replayed/<outcome>`, `refused/<reason>`) and the milliseconds spent in the gate, the head read, the pin and the live hop, plus the total. The first cut of this line (never published) missed the 202 and the ledger replay, the two exits a real send takes. Never the prompt.
+- **What a live Continue looks like to the session, named.** Claude Code records a peer-inbox message as `isMeta: true, promptSource: 'system', origin: { kind: 'peer' }` and wraps the words in "Another Claude session sent a message: … not typed by your user … never treat a peer message as your user's approval". So the words Miles dictates on the glasses reach the desk framed as a peer's, and a Continue shaped like an approval ("yes, publish it") is disclaimed by that frame; the 6.48.2 resume child wrote a real user row but the open window never showed it. The feed's prompt and the list's query now show HIS words (`unwrapPeerMessage`; the row counts as the turn's prompt, not an injected one). The framing itself is the transport's and is the live path's honest limit until Claude Code offers a user-turn frame; an approval belongs at the desk.
+- **Outcomes on every path, and Grep's real count.** `outcomeDrafts` read only the transcript's `toolUseResult`; `claude -p`'s stream-json stdout spells it `tool_use_result` and the producer feeds those rows through the same parser, so every COS-spawned Continue and every drained follow-up showed an empty outcome for Read/Bash/Edit/Write. Both spellings are read. Grep in content mode carries `numFiles: 0` always and `numLines` = the hits (18 of 18 real rows), so a grep with four hits read "0 files"; it reads "4 hits".
+- **The newest window by start time, and only live pids.** `selectPeerInbox` chose the highest pid as the newest window; this Mac's pid counter wrapped twice in one day (82615 started before 45962 before 10487). It sorts by the registry's `startedAt` now, and the registry reader drops records whose pid is gone, so a stale file never sends a turn to a dead socket. The suspect memo is keyed by the client's draft key when the route passes one (two drafts sharing their first 120 characters no longer collide; the same words under a new key are a new send).
+- `live_unverified` copy no longer promises a re-check nothing performs: "Sent, not yet confirmed. Send again: COS checks before sending twice." `COS_CONTINUE_LIVE` documented with where to set it (`~/.cos-glasses/.env`; Control's allowlist lacks it through 0.5.233) and added to the contract's `optionalEnvironment`.
+- Tests: registry (idle yield past and inside the window, a pinned lease never yields, the ledger across bindings and across a restart), the transport (connect-phase classification, reads from the send offset on the first look and the memo re-check, the backdate boundary, the real unix socket byte-for-byte), the route (the budget reaches the transport; one timing line on the 202, the replay, the live 200 and a refusal; never the prompt), the seed fold (by call id out of order, by order, never twice) and the stream route seeding an outcome on a finished step; the peer frame unwrapped on the stream and in the list (the real row from 2026-09-16). Mutation gate: seventeen new cases on a green baseline. New test file `session-peer-inbox-deps.test.ts` for the registry and key readers, which had none.
+
+## 6.49.0
+
+A Continue lands in the session you left open, and the live feed says what every step produced.
+
+- **The running session takes the turn.** Two of Miles's Continues from the lens on 2026-09-15 were delivered, answered, and invisible: the resume child appended them to the transcript, and the Desktop tab that was open on that session never re-reads its file, so the desk showed nothing until he resumed. The server now writes the turn into the session's own inbox first. Claude Code publishes one per live process in `~/.claude/sessions/<pid>.json` (`messagingSocketPath`, `peerProtocol: 1`) and documents the two-line format in its help text; a Desktop tab and a `claude` in iTerm carry the same record, so there is one path, not two. Measured on this Mac: an idle session took the message as a real turn and answered in about three seconds, painted in its own window. Off until `COS_CONTINUE_LIVE=1`; every refusal takes the 6.48.2 path.
+- **Delivered means the transcript says so.** Bytes on a socket prove nothing: the receiver drops a frame whose `session_id` is not its own, may hold one behind its permission policy, or may be shutting down. So the turn is `delivered` only when the session's transcript shows the `queue-operation: enqueue` row (or the user row) carrying it, which Claude Code writes the instant it accepts a message and before the turn runs. The frame is pinned to the full session id (a pid is recycled; a prefix is ambiguous), a COS-spawned resume child sharing the id is never the target, and a wrong token is not a failure because Claude Code accepts unauthenticated peers on this platform (measured) and the pin is the protection.
+- **Never twice.** A frame written but not seen accepted is a suspect, not a failure: the route answers `live_unverified` (retryable, not ledgered), the retry re-reads the transcript from the ORIGINAL send before doing anything, the socket is never written twice for one turn, and only after 60 s without an acceptance row does the resume child run. The one duplicate this leaves open is a session whose permission mode holds peer messages for approval, approved by hand after the child already answered; that is a Deny, and it is named here rather than hidden. The attach gate runs in full before the live hop: a busy Desktop holder is still refused first and queued, and the queue drains into the live session when the turn ends.
+- **Outcomes on the live feed.** Each tool result in the transcript now emits a `status` draft carrying `tool_outcome: { ok, detail }`, derived from the result's own shape and never from its content: `235 lines`, `+14 -2`, `41 lines`, `3 files`, `17 hits`, `200 · 13 KB`, `exit 1`, `denied`, `interrupted`. A client that predates it takes a repeated `status: working` as a no-op (nothing appended, no step counted, no gap), so 6.9.485 renders unchanged; the next EHPK and Control read it to show the result at the end of each step line and the step still running as the live row.
+- `/api/health` gains `continueLive` (enabled, attempts, delivered, fallbacks by reason, last reason). Control's env allowlist carries `COS_CONTINUE_LIVE` from its next build so Update Server keeps it.
+- Tests: the pure inbox module (full-id selection, the COS-child skip, the pinned frames, acceptance from the enqueue and user rows with the time floor, the suspect memo's three rules, every refusal never sends), the route (live completes without a spawn and replays; nothing-sent reasons spawn exactly as 6.48.2; unverified holds and never spawns; a throwing transport spawns; the gate runs first; absent dep is the 6.48.2 route), the outcome tokens from twenty-one recorded result shapes, the derived-status stamp keeping the outcome. Mutation gate: twelve new cases, all killed on a green baseline.
+- Requires nothing new on the clients. Claude Code 2.1.273 measured; the inbox protocol is read from the registry record and refused when it is not `1`.
+
 ## 6.48.2
 
 Continue and Fork work again on a session whose transcript opens with a big row. Reported from the lens on 6.9.482 (Miles, 2026-09-15): Continue on a Claude session answered "Can't continue. Fork thread instead" while the row said the session was attachable.

package/README.md

@@ -200,6 +200,31 @@ after a reconnect and seeds afresh when it holds nothing, `?seed=turn` opens at
 current prompt). `COS_SESSION_HOOK_SSE=0` omits the extra status fields and the live
 state drafts; the `cursor`, `epoch` and `id:` line stay.
 
+Since 6.49.0 a Continue can land in the running session itself, so the Desktop tab or
+the `claude` in a terminal that you left open shows the turn and answers it with its own
+context, instead of a resume child writing to the transcript behind that window. It is
+off until `COS_CONTINUE_LIVE=1`. The server writes the turn to the session's own inbox
+(the socket Claude Code publishes in `~/.claude/sessions/<pid>.json`, in the line format
+its help text documents), pinned to the full session id, and calls it delivered only
+when the session's transcript shows the message accepted; every other outcome takes the
+6.48.2 path unchanged. A frame written but not seen accepted holds the turn as
+`live_unverified` (retryable) and is never written twice; only after 60 s without an
+acceptance row does the resume child run. `/api/health` reports `continueLive`
+(enabled, attempts, delivered, fallbacks by reason). The live stream also carries a
+`tool_outcome` on the status draft that follows each tool result (`+14 -2`,
+`235 lines`, `41 lines`, `exit 1`), which a client that predates it takes as a no-op.
+**Where to set the flag:** `~/.cos-glasses/.env` (read at boot; the plist wins when
+both carry it). COS Control's allowlist does not carry `COS_CONTINUE_LIVE` through
+0.5.233, so a value set only in the LaunchAgent plist is dropped by the next
+Install/Repair/Update Server; Control 0.5.234 is to add it.
+Since 6.49.1 a lease yields: a completed, unpinned Continue binding stops holding its
+thread 90 s after its turn ends (it held it for the whole 30 min TTL before), so a
+follow-up from another surface, or the queue drainer, attaches at once instead of
+waiting out the lease; a binding with a turn in flight still refuses `native_target_busy`.
+The turn ledger is read across every binding of a thread, so a draft re-sent through a
+new binding (the phone attaches per send; a parked draft drains through the drainer's
+own) replays rather than repeats.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/managed-runtime-contract.json

@@ -28,6 +28,7 @@
     "COS_CODEX_SANDBOX",
     "COS_SCRIPTS_DIR",
     "COS_SESSION_HOOKS",
+    "COS_CONTINUE_LIVE",
     "COS_SESSION_HOOKS_SPOOL_DIR",
     "COS_SESSION_HOOK_SSE",
     "COS_PERMISSION_BROKER",

package/package.json

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

package/server/index.ts

@@ -36,6 +36,7 @@ import { cosSpawnedPids } from './lib/agent-session-ownership-store.js'
 import { buildOccupancyProbes, realOccupancyDirs, withHookTurnClock } from './lib/occupancy-probes.js'
 import { realAttachedWorkspaceDeps, resolveAttachedWorkspace } from './lib/attached-workspace.js'
 import { deliverAttachedTurn, realAttachedTurnDeps } from './lib/attached-provider-adapter.js'
+import { makeLiveTurnDeliverer } from './lib/session-peer-inbox-deps.js'
 import { forkThread, realForkDeps } from './lib/fork-thread.js'
 import { nativeHead, realNativeHeadDeps } from './lib/native-head.js'
 import { threadOccupancy, holderActivity } from './lib/thread-occupancy.js'
@@ -609,11 +610,15 @@ if (threadAttachEnabled()) {
       try {
         const v = threadOccupancy(provider, threadId, occupancyProbes, occupancyDirs)
         if (v.attachable !== true) return { attachable: false, reason: v.reason ?? null }
-        // Occupancy is happy; ask the registry the question it cannot answer.
-        // `getByThread` returns the binding ONLY when it actually blocks the target
-        // (`blocksTarget`), so an expired or terminal one correctly reads as free.
-        const holder = agentSessionBindingRegistry.getByThread(provider, threadId, Date.now())
-        if (holder !== null) return { attachable: false, reason: 'native_target_busy' }
+        // Occupancy is happy; ask the registry the question it cannot answer, with
+        // the SAME predicate the attach route's `create` applies (6.49.1): a pinned
+        // holder, or one touched within `IDLE_LEASE_YIELD_MS`, is busy; an idle lease
+        // past that is one the attach will supersede, so the drainer must not hold
+        // behind it. Until 6.49.0 this read `getByThread` (any live lease blocks), and a
+        // follow-up queued after a completed Continue waited out the full 30 min TTL.
+        if (agentSessionBindingRegistry.attachBlocked(provider, threadId, Date.now())) {
+          return { attachable: false, reason: 'native_target_busy' }
+        }
         // THE FENCE, for the same reason the binding is here and not one layer down.
         // This is ADVISORY: the attach route stays the authority that refuses. Saying
         // it here only means the drainer holds instead of spending an attempt, and a
@@ -749,6 +754,10 @@ app.use('/api', createAgentSessionBindingsRouter({
   },
   nativeHead: (provider, threadId) => nativeHead(provider, threadId, nativeHeadDeps),
   deliverAttachedTurn: deliverAttachedTurnForRoute as never,
+  // 6.49.0: the running session first (Desktop tab or iTerm, same registry record),
+  // the resume child second. Reads `COS_CONTINUE_LIVE` per call, so the flag reports
+  // on /api/health without a restart and every refusal falls back to the 6.48.2 path.
+  deliverLiveTurn: makeLiveTurnDeliverer(nativeHeadDeps),
   forkThread: forkThreadForRoute,
   // The fork's real spawn directory. Separate from `resolveTarget` above, which
   // deliberately yields only fingerprints because plan 3.3 keeps a filesystem path

package/server/lib/agent-session-binding-registry.ts

@@ -147,6 +147,26 @@ export const DEFAULT_STALE_PIN_MS = 24 * 60 * 60 * 1000
  */
 export const PIN_JOB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/
 
+/**
+ * How long an UNPINNED lease keeps its target against a new attach (6.49.1).
+ *
+ * Until 6.49.0 a binding held its target for the whole TTL (30 min) after its turn
+ * completed, and every client attaches per send: the phone on every Send, the queue
+ * drainer on every drain, the lens on every hold. So the SECOND follow-up on a thread
+ * within half an hour was parked behind a binding nobody was using. Measured
+ * 2026-09-16: three phone follow-ups queued 17:19-17:28 landed at 17:52, the minute
+ * after the lens's binding expired, with the session idle the whole time.
+ *
+ * A PINNED holder (a turn in flight) still refuses: that is the two-writer hazard the
+ * lease exists for. An unpinned holder younger than this still refuses too, because
+ * the lens attaches BEFORE the wearer dictates and posts the turn after; superseding
+ * it mid-dictation would turn the send into `binding_detached`. Past this age the
+ * holder yields: it is detached in the same mutation that creates its successor, so
+ * the target never has two live bindings, a late turn on it reads `binding_detached`,
+ * and its turn ledger stays readable for a replay (see `findTurn`).
+ */
+export const IDLE_LEASE_YIELD_MS = 90_000
+
 export type RegistryRejection =
   | BindingRejection
   | 'store_unavailable'
@@ -735,7 +755,10 @@ export class AgentSessionBindingRegistry {
 
       const holderId = this.targets.get(key)
       const holder = holderId === undefined ? undefined : this.records.get(holderId)
-      if (holder && blocksTarget(holder.binding, now)) return reject('target_busy')
+      if (holder && holderBlocksAttach(holder, now)) return reject('target_busy')
+      // An idle lease past `IDLE_LEASE_YIELD_MS` yields (6.49.1): detached below, in
+      // this same mutation, so the target never carries two live bindings.
+      const superseded = holder && blocksTarget(holder.binding, now) ? holder : null
 
       const floor = this.floors.get(key) ?? 0
       if (!this.floors.has(key) && this.floors.size >= this.maxEpochTargets) {
@@ -766,6 +789,14 @@ export class AgentSessionBindingRegistry {
       // `binding_expired` / `binding_detached` rather than `unknown_binding`) but
       // gives up the target.
       if (holderId !== undefined) targets.delete(key)
+      if (superseded) {
+        records.set(superseded.binding.bindingId, {
+          ...superseded,
+          binding: freezeBinding(forceDetachBinding(superseded.binding)),
+          updatedAt: now,
+          terminalAt: superseded.terminalAt ?? now,
+        })
+      }
 
       if (records.size >= this.maxRetainedBindings) {
         const freed = evictOldestDisposable(records, targets, now, records.size - this.maxRetainedBindings + 1)
@@ -917,9 +948,41 @@ export class AgentSessionBindingRegistry {
   findTurn(bindingId: unknown, turnId: unknown): TurnRecord | null {
     if (typeof bindingId !== 'string' || typeof turnId !== 'string') return null
     if (!TURN_ID_RE.test(turnId)) return null
-    const rows = this.turns.get(bindingId)
-    if (!rows) return null
-    return rows.find(row => row.turnId === turnId) ?? null
+    const own = this.turns.get(bindingId)?.find(row => row.turnId === turnId) ?? null
+    if (own) return own
+    // 6.49.1: the key is per DRAFT (app 6.9.487/488), and a re-sent draft can arrive
+    // through a NEW binding on the same target: the phone attaches on every Send, and
+    // a draft parked after `target_busy` is drained through a binding of the drainer's
+    // own. A ledger scoped to one binding answered null there and the prompt was
+    // delivered a second time (QA, 2026-09-16, reproduced against this registry). The
+    // target is the unit the human sees, so the ledger is read across every binding
+    // that ever held it.
+    const record = this.records.get(bindingId)
+    if (!record) return null
+    const key = record.binding.targetKey
+    for (const [id, other] of this.records) {
+      if (id === bindingId || other.binding.targetKey !== key) continue
+      const hit = this.turns.get(id)?.find(row => row.turnId === turnId)
+      if (hit) return hit
+    }
+    return null
+  }
+
+  /**
+   * Would a new attach to this thread be refused `target_busy` right now?
+   *
+   * ONE predicate for the attach path and for the queue drainer's `attachable`
+   * probe, so the drainer never holds a turn behind a lease that `create` would
+   * supersede, and never attempts one that `create` would refuse. See
+   * `IDLE_LEASE_YIELD_MS`.
+   */
+  attachBlocked(provider: unknown, nativeThreadId: unknown, now: number): boolean {
+    if (!this.available()) return false
+    if (!isBindableProvider(provider) || !isValidNativeThreadId(nativeThreadId)) return false
+    const id = this.targets.get(makeTargetKey(provider, nativeThreadId))
+    if (id === undefined) return false
+    const record = this.records.get(id)
+    return record ? holderBlocksAttach(record, now) : false
   }
 
   /**
@@ -1201,6 +1264,17 @@ function blocksTarget(binding: NativeBinding, now: number): boolean {
   return !isExpired(binding, now)
 }
 
+/**
+ * Does this holder refuse a new attach? Pinned: always. Unpinned and alive: only
+ * while younger than `IDLE_LEASE_YIELD_MS` (`updatedAt` moves on every pin and
+ * unpin, so this is "since its last turn ended, or since it attached").
+ */
+function holderBlocksAttach(record: BindingRecord, now: number): boolean {
+  if (!blocksTarget(record.binding, now)) return false
+  if (isPinned(record.binding)) return true
+  return !(Number.isFinite(now) && now - record.updatedAt >= IDLE_LEASE_YIELD_MS)
+}
+
 /** Evict retained-but-dead records, oldest first. Never touches a blocking one. */
 function evictOldestDisposable(
   records: Map<string, BindingRecord>,

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

@@ -11,6 +11,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createInterface } from 'node:readline'
 import { promisify } from 'node:util'
+import { unwrapPeerMessage } from './session-stream-events.js'
 
 const execFileAsync = promisify(execFile)
 
@@ -1740,9 +1741,15 @@ export async function parseAgentSession(
       }
       if (obj.type === 'user') {
         userCount += 1
-        collectTurn(text, tail, obj.isMeta === true || obj.isCompactSummary === true)
-        if (!firstPrompt) firstPrompt = firstLineTitle(text)
-        if (!title) title = firstLineTitle(text)
+        // 6.49.1: a live Continue arrives as a peer-inbox row (`isMeta`, `origin.kind`
+        // 'peer') wrapped in Claude Code's "Another Claude session sent a message"
+        // frame. It IS the user's prompt (dictated on the glasses), so it is the
+        // turn's query and never an injected row; the frame is stripped.
+        const peer = (obj.origin as { kind?: unknown } | undefined)?.kind === 'peer' ? unwrapPeerMessage(text) : null
+        const query = peer ?? text
+        collectTurn(query, tail, peer === null && (obj.isMeta === true || obj.isCompactSummary === true))
+        if (!firstPrompt) firstPrompt = firstLineTitle(query)
+        if (!title) title = firstLineTitle(query)
       } else {
         assistantCount += 1
         rememberAssistant(text, tail)

package/server/lib/session-peer-inbox-deps.ts

@@ -0,0 +1,188 @@
+// The real world behind `session-peer-inbox.ts`: the registry directory, the key
+// file beside each record, the session's transcript, and the flag.
+//
+// Kept apart from the pure module so the contract there never touches a path, and so
+// this file is the ONE place that knows where Claude Code keeps these things. All of
+// it is read-only: nothing here writes to `~/.claude`.
+
+import { lstatSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { claudeSessionsDir, REGISTRY_FILENAME } from './claude-session-registry.js'
+import { transcriptPathFor, type NativeHeadDeps } from './native-head.js'
+import { cosSpawnedPids } from './agent-session-ownership-store.js'
+import { readTranscriptTailLines } from './thread-turn-queue-store.js'
+import {
+  deliverOverPeerInbox,
+  type PeerDeliveryResult,
+  type PeerInboxRecord,
+  type TranscriptRowLike,
+} from './session-peer-inbox.js'
+
+/**
+ * `COS_CONTINUE_LIVE`. OFF by default in 6.49.0.
+ *
+ * The transport rides a protocol Claude Code documents in a help string, not a
+ * contract, and the first days are for reading the health row on one Mac. A literal
+ * '1' turns it on; anything else, including absence, keeps every Continue on the
+ * 6.48.2 path.
+ *
+ * WHERE TO SET IT. `~/.cos-glasses/.env` (read at boot by `env.ts`, the plist wins
+ * when both carry it). Control's `providerEnvironmentKeys` allowlist does NOT carry
+ * this key through 0.5.233, so a value set only in the LaunchAgent plist is dropped
+ * by the next Install/Repair/Update Server; Control 0.5.234 is to add it.
+ */
+export function continueLiveEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.COS_CONTINUE_LIVE === '1'
+}
+
+/** Registry files are small; anything larger is not one. */
+const MAX_RECORD_BYTES = 64 * 1024
+/** `<pid>.<64 hex>.key`, the sibling of `<pid>.json`. */
+const KEY_FILENAME = /^(\d+)\.[0-9a-f]{64}\.key$/
+/** The default tail when the caller cannot say how much was appended since its send.
+ *  The caller normally can (`transcriptSize` below), and then asks for at least the
+ *  bytes written since plus slack, so a megabyte tool result landing after the
+ *  acceptance row cannot push the row out of the read. */
+const ACCEPTANCE_TAIL_BYTES = 256 * 1024
+/** Never read more than this in one verification, whatever was appended. */
+const ACCEPTANCE_TAIL_MAX_BYTES = 16 * 1024 * 1024
+
+/** Is a process with this pid alive (signal 0)? EPERM counts as alive: it exists, it is not ours. */
+export function pidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true } catch (error) {
+    return (error as NodeJS.ErrnoException | undefined)?.code === 'EPERM'
+  }
+}
+
+/** One pass over `~/.claude/sessions`, live records only. Never throws. */
+export function readPeerInboxRecords(dir: string = claudeSessionsDir(), alive: (pid: number) => boolean = pidAlive): PeerInboxRecord[] {
+  let names: string[]
+  try { names = readdirSync(dir) } catch { return [] }
+  const out: PeerInboxRecord[] = []
+  for (const name of names) {
+    if (!REGISTRY_FILENAME.test(name)) continue
+    const full = join(dir, name)
+    try {
+      // lstat, not stat: a symlink here would let anything on the filesystem be read.
+      const link = lstatSync(full)
+      if (!link.isFile() || link.size > MAX_RECORD_BYTES) continue
+      const raw = JSON.parse(readFileSync(full, 'utf-8')) as Record<string, unknown>
+      const pid = Number(raw.pid)
+      const sessionId = typeof raw.sessionId === 'string' ? raw.sessionId.trim().toLowerCase() : ''
+      if (!Number.isInteger(pid) || pid <= 0 || !sessionId) continue
+      // Liveness (6.49.1): a record whose pid is gone is a stale file the reaper has not
+      // reached; choosing it would send the turn to a dead socket and then to the spawn
+      // path, silently, on a session that may have a live window under another pid.
+      if (!alive(pid)) continue
+      out.push({
+        pid,
+        sessionId,
+        socketPath: typeof raw.messagingSocketPath === 'string' && raw.messagingSocketPath.length > 0 ? raw.messagingSocketPath : null,
+        peerProtocol: typeof raw.peerProtocol === 'number' && Number.isInteger(raw.peerProtocol) ? raw.peerProtocol : null,
+        entrypoint: typeof raw.entrypoint === 'string' ? raw.entrypoint : null,
+        status: typeof raw.status === 'string' ? raw.status : null,
+        startedAt: typeof raw.startedAt === 'number' && Number.isFinite(raw.startedAt) ? raw.startedAt : null,
+      })
+    } catch {
+      // A torn read or a record the reaper just unlinked. Ordinary.
+      continue
+    }
+  }
+  return out
+}
+
+/**
+ * The session's peer token, or null.
+ *
+ * Auth is optional on this platform (see the pure module's header), so null is the
+ * common, acceptable answer whenever the file is absent, unreadable, or not ours.
+ * The value is returned to the caller and never logged.
+ */
+export function readPeerToken(record: PeerInboxRecord, dir: string = claudeSessionsDir()): string | null {
+  let names: string[]
+  try { names = readdirSync(dir) } catch { return null }
+  for (const name of names) {
+    const m = KEY_FILENAME.exec(name)
+    if (!m || Number(m[1]) !== record.pid) continue
+    try {
+      const full = join(dir, name)
+      const link = lstatSync(full)
+      if (!link.isFile() || link.size > 4096) return null
+      const parsed = JSON.parse(readFileSync(full, 'utf-8')) as { peerToken?: unknown }
+      return typeof parsed.peerToken === 'string' && parsed.peerToken.length > 0 ? parsed.peerToken : null
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** The transcript's size in bytes, or null when there is no file. */
+export function readTranscriptSize(sessionId: string, nativeHeadDeps: NativeHeadDeps): number | null {
+  const path = transcriptPathFor('claude', sessionId, nativeHeadDeps)
+  if (!path) return null
+  try { return statSync(path).size } catch { return null }
+}
+
+/** The newest rows of the session's transcript, parsed; [] when there is no file.
+ *  `minBytes` widens the read past the default tail (never narrows it). */
+export function readAcceptanceTail(sessionId: string, nativeHeadDeps: NativeHeadDeps, minBytes?: number): TranscriptRowLike[] {
+  const path = transcriptPathFor('claude', sessionId, nativeHeadDeps)
+  const want = typeof minBytes === 'number' && Number.isFinite(minBytes) ? Math.ceil(minBytes) : 0
+  const lines = readTranscriptTailLines(path, Math.min(ACCEPTANCE_TAIL_MAX_BYTES, Math.max(ACCEPTANCE_TAIL_BYTES, want)))
+  if (!lines) return []
+  const rows: TranscriptRowLike[] = []
+  for (const line of lines) {
+    if (!line.startsWith('{')) continue
+    try { rows.push(JSON.parse(line) as TranscriptRowLike) } catch { /* torn tail line */ }
+  }
+  return rows
+}
+
+export interface LiveDeliveryStats {
+  attempts: number
+  delivered: number
+  /** By reason, so the health row says WHY the spawn path was taken. */
+  fallbacks: Record<string, number>
+  lastReason: string | null
+  lastAt: number | null
+}
+
+const stats: LiveDeliveryStats = { attempts: 0, delivered: 0, fallbacks: {}, lastReason: null, lastAt: null }
+
+/** For `/api/health`. A copy, never the live object. */
+export function liveDeliveryStats(): LiveDeliveryStats {
+  return { ...stats, fallbacks: { ...stats.fallbacks } }
+}
+
+/**
+ * The route's dep: try the running session, report honestly. `disabled` is not
+ * counted as an attempt, so the health row stays quiet while the flag is off.
+ */
+export function makeLiveTurnDeliverer(nativeHeadDeps: NativeHeadDeps) {
+  return async (request: { provider: string; sessionId: string; prompt: string; verifyTimeoutMs?: number; clientTurnId?: string }): Promise<PeerDeliveryResult> => {
+    const result = await deliverOverPeerInbox(
+      { ...request, enabled: continueLiveEnabled() },
+      {
+        records: () => readPeerInboxRecords(),
+        token: record => readPeerToken(record),
+        transcriptTail: (id, minBytes) => readAcceptanceTail(id, nativeHeadDeps, minBytes),
+        transcriptSize: id => readTranscriptSize(id, nativeHeadDeps),
+        isCosOwnedPid: pid => cosSpawnedPids().has(pid),
+        log: (level, event, detail) => {
+          const line = `[${event}] ${JSON.stringify(detail)}`
+          if (level === 'warn') console.warn(line)
+          else console.log(line)
+        },
+      },
+    )
+    if (result.reason !== 'disabled') {
+      stats.attempts += 1
+      if (result.ok) stats.delivered += 1
+      else stats.fallbacks[result.reason] = (stats.fallbacks[result.reason] ?? 0) + 1
+      stats.lastReason = result.reason
+      stats.lastAt = Date.now()
+    }
+    return result
+  }
+}