@gotcos/glasses-server 6.34.0 → 6.36.0

package/CHANGELOG.md

@@ -2219,6 +2219,118 @@ unsaved capture, and makes batch status stop lying about finished work.
 
 # Changelog
 
+## [6.36.0] - 2026-08-17
+
+### Sessions push instead of being polled
+
+A new SSE route streams what an agent session is doing, so the glasses stop
+re-asking every five seconds. Two cases, and the difference between them is real
+rather than something the UI papers over.
+
+- **`GET /api/agent-sessions/:provider/:sessionId/stream`** — one event per step
+  (`tool` / `prose` / `status` / `heartbeat`), a monotonic `seq` so a client can
+  see loss, and a heartbeat at least every 20s so silence is evidence rather than
+  ambiguity. Authenticated like every other route; `COS_SESSION_STREAM_ENABLED=0`
+  turns it off.
+- **A turn COS started streams from the pipe.** The child already ran with
+  `--output-format stream-json --verbose`; its stdout was read only to confirm a
+  session id and then discarded. It is now teed to the bus as well, and the id
+  scan is untouched.
+- **A session in a desktop window gets row-level push.** COS never spawned that
+  process and has no pipe to it, so the transcript file is the only observable.
+  It is tailed forward from a byte offset, one `stat` per second per OPEN view,
+  and each new record is emitted through the same grammar and envelope. Claude
+  writes a complete record per message, so a long reply lands all at once when it
+  finishes. **That asymmetry cannot be engineered away from a file** and the
+  contract does not claim otherwise.
+- **`fs.watch` was rejected deliberately.** On macOS it coalesces bursts and, on
+  an atomic replace, keeps watching the old inode and simply stops firing — a
+  watcher that goes silent is indistinguishable from a session that went quiet,
+  which is the failure class this repo keeps paying for. A `stat` poll cannot
+  miss a write because it does not observe writes; it observes size, and size is
+  cumulative.
+- **A record too large to stream hands the session back to the poll.** One record
+  in a real transcript on this machine is 1,239,046 bytes. The tail reads up to 4
+  MiB per TICK, so any record up to that arrives intact; a bigger one ends the
+  response with a terminal `done` instead of stalling. Skipping it was tried
+  first and was wrong twice: it wedged (the good record behind the oversized one
+  was skipped too, on every tick, forever — zero events, not even a status) and,
+  even working, it would have silently dropped a reply the user was waiting for.
+- **One watcher per session, ref-counted.** Two glasses on one session is not two
+  pollers on an 81 MB file, and a double release does not tear down a tail
+  another subscriber still holds.
+
+Needs COS Glasses 6.8.372 to be visible. An older app never calls the route.
+
+## [6.35.0] - 2026-08-16
+
+### The newest assistant reply arrives whole instead of at 160 characters
+
+- **The defect.** Miles opened a session on the glasses and the newest reply was cut
+  off mid-sentence. The session detail payload had NO full-text field: it carried
+  `discussion_summary` (180 chars) and `discussion_digest` (2000), and the newest
+  reply appeared only as the `Latest:` line inside the digest, produced by
+  `proseSnippet` at **160 characters** with a bare `slice` that stops mid-word and
+  prints nothing to say it stopped. An 1821-character reply reached the wire as 160
+  characters. The other 1661 never left the Mac. Polling was never the suspect: no
+  poll can deliver bytes the server did not send.
+- **New field `latest_reply` on `GET /api/agent-sessions/:provider/:sessionId`,
+  bounded at 4000 characters.** The number is measured, not guessed. Across 8,387
+  assistant replies in the 60 most recent transcripts on this Mac: p50 153, p75 291,
+  p90 1,627, p95 2,412, p99 3,405, max 21,757. The old 160-char cap delivered only
+  **52.7%** of replies whole. 4000 delivers **99.58%** (35 of 8,387 cut). 6000 would
+  buy 0.26 of a point for 50% more bytes on every fetch, and the reader paginates at
+  roughly 200 chars, so 4000 is at most 20 swipes of deliberate reading.
+- **A dedicated field, not a bigger slice of the digest.** Three caps sit in series
+  here (`proseSnippet` 160, `DIGEST_TURN_MAX` 220, `DISCUSSION_DIGEST_MAX` 2000) and
+  the digest reserves its `Latest:` block FIRST, so a longer reply inside that budget
+  starves the user turns it is supposed to sit beside. Two fields, two jobs.
+- **Truncation is now visible.** `latest_reply` ends in an ellipsis when it does have
+  to cut. `proseSnippet` keeps its old bare 160-char slice, pinned by a test.
+- **ADDITIVE. An older app keeps working.** Nothing was removed or renamed:
+  `discussion_summary` and `discussion_digest` still carry exactly what they carried,
+  the digest still holds its own 160-char `Latest:` line, and a client that never
+  learns the new key renders what it rendered before. Proven over real HTTP rather
+  than by reading the route source.
+
+### Two latent hazards in the same path, both closed
+
+- **"Latest" can no longer be a line from the session's opening.** An oversized
+  transcript is read head-then-tail into one loop, and the newest reply was plain
+  last-write-wins across both windows. A session whose tail window happened to hold
+  no assistant prose, which is ordinary when the last 768 KiB are giant tool results,
+  kept whichever assistant row the HEAD saw and published it labelled `Latest:`. A
+  line from the start of the session, presented as its current state. Silently wrong,
+  and worse than truncation because truncation is at least visible. Lines are now
+  tagged with the window they came from and only the window ending at EOF can claim
+  to be latest; with nothing there the honest answer is nothing, and the digest drops
+  its `Latest:` block rather than filling it with the wrong turn. A whole-file read
+  is all tail, so small sessions are unchanged.
+- **A record larger than the tail window no longer empties the tail.** The tail opens
+  at `size - 768 KiB`, mid-record, and the leading fragment is discarded by design.
+  When the FINAL record is bigger than the window, that fragment is the only thing in
+  it: nothing parses, and the tail contributes no recent turns and no reply at all.
+  Not hypothetical: 14 records over 768 KiB exist in a 60-transcript sample on this
+  Mac, the largest 1,239,045 bytes, 1.58x the window. The tail now reaches back up to
+  one further MiB to open at a real record boundary, and stops reaching past that so
+  a pathological record cannot pull an unbounded read into memory.
+- **Measured, not asserted:** both hazards are LATENT today. Every transcript
+  currently over the 32 MiB read ceiling has 8 to 19 assistant rows in its tail, so
+  neither is firing right now. They are mechanisms, closed before they fire.
+
+### Notes
+
+- One behaviour change beyond the additive field, and it is the point of the fix: on
+  a truncated read whose tail holds no assistant prose, `discussion_summary` and the
+  digest's `Latest:` block are now EMPTY where they used to carry a line from the
+  session's opening. That removes wrong content, not content.
+- A mutation that survived is recorded rather than buried. An early draft clamped the
+  tail start at `headBytes` to avoid double counting, and no test reached it. It was
+  both untested and wrong: `lastRecordStart` returns the LAST record's start and that
+  record always runs to EOF, so the head can only ever see a prefix it discards, and
+  the clamp only threw away the record the reach exists to recover. The clamp is
+  gone, a test now covers the case, and re-adding it fails.
+
 ## [6.34.0] - 2026-08-16
 
 ### A continued turn now runs with the session's own permissions

package/package.json

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

package/server/index.ts

@@ -19,6 +19,8 @@ import { providerProofRouter } from './routes/provider-proof.js'
 import { transcribeRouter } from './routes/transcribe.js'
 import { sessionIndexRouter } from './routes/session-index.js'
 import { agentSessionsRouter } from './routes/agent-sessions.js'
+import { agentSessionStreamRouter } from './routes/agent-session-stream.js'
+import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import {
   createAgentSessionBindingsRouter,
@@ -384,23 +386,45 @@ const deliverAttachedTurnForRoute = async (request: {
     return { attachable: verdict.attachable, reason: verdict.reason }
   })
 
-  return deliverAttachedTurn({
+  // PHASE 1 OF SESSION STREAMING. The child already writes `--output-format
+  // stream-json`; this is the only place that stream reaches anything other than the
+  // adapter's id scanner. Opened before the spawn so a subscriber that connects mid
+  // turn sees `working` rather than silence, and closed in a `finally` because the
+  // duplicate-suppression gate it holds must be released on EVERY exit path -- a stuck
+  // gate would silence Phase 2 for that session permanently.
+  const live = createAttachedTurnStream({
     provider: request.provider,
-    nativeThreadId: request.nativeThreadId,
-    prompt: request.prompt,
-    cwd: workspace.path,
-    // The only policy this build accepts. The adapter refuses anything else and
-    // asserts no bypass/always-approve flag reaches the argv (plan 4.7).
-    policy: 'read_only',
-    deps: {
-      ...base,
-      // `startMs` is deliberately unused: the adapter already probed it as a GATE
-      // (a null there aborts before this is reached), and the route probes again
-      // as the recorder. One record, one authority.
-      recordSpawn: (pid: number, _startMs: number) =>
-        request.onSpawn(pid) ? 'recorded' : 'route_refused_ownership',
-    },
+    sessionId: request.nativeThreadId,
   })
+
+  try {
+    const result = await deliverAttachedTurn({
+      provider: request.provider,
+      nativeThreadId: request.nativeThreadId,
+      prompt: request.prompt,
+      cwd: workspace.path,
+      // The only policy this build accepts. The adapter refuses anything else and
+      // asserts no bypass/always-approve flag reaches the argv (plan 4.7).
+      policy: 'read_only',
+      deps: {
+        ...base,
+        // `startMs` is deliberately unused: the adapter already probed it as a GATE
+        // (a null there aborts before this is reached), and the route probes again
+        // as the recorder. One record, one authority.
+        recordSpawn: (pid: number, _startMs: number) =>
+          request.onSpawn(pid) ? 'recorded' : 'route_refused_ownership',
+        observeStdout: chunk => live.observeStdout(chunk),
+      },
+    })
+    // `done` only for a turn the adapter proved landed. Anything else is `idle`: the
+    // session stopped working, and claiming a completion we could not verify is the
+    // kind of invention the rest of this feature refuses to make.
+    live.finish(result && typeof result === 'object' && (result as { ok?: unknown }).ok === true ? 'done' : 'idle')
+    return result
+  } catch (error) {
+    live.finish('idle')
+    throw error
+  }
 }
 
 /**
@@ -454,6 +478,11 @@ app.use('/api', transcribeRouter)
 app.use('/api', sessionIndexRouter)
 // Claude + Codex + Cursor transcripts from this Mac. Same 7-day window as Control.
 app.use('/api', agentSessionsRouter)
+// The live view of one of those sessions. Four segments ending in a literal `stream`,
+// so it cannot shadow the three-segment transcript route above or the bindings
+// router's `/attachability` below. READ-ONLY, and deliberately NOT behind
+// COS_THREAD_ATTACH_ENABLED -- see the header of the route for why.
+app.use('/api', agentSessionStreamRouter)
 // Presence view of Claude Code sessions on this Mac. Dark unless
 // COS_CLAUDE_SESSIONS_ENABLED=1 — it projects another product's 0700 state dir.
 app.use('/api', claudeSessionsRouter)

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

@@ -122,13 +122,55 @@ export function firstLineTitle(text: string): string {
   return line.slice(0, 80)
 }
 
+/** Fenced code, tags and runs of whitespace out; one line of prose left. Shared so
+ *  `proseSnippet` and `latestAssistantReply` can never disagree about what the prose
+ *  of a record IS — only about how much of it they keep. */
+function proseBody(text: string): string {
+  const body = text.replace(/```[\s\S]*?```/g, ' ')
+  return body.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+}
+
 export function proseSnippet(text: string, max = 160): string {
-  let body = text.replace(/```[\s\S]*?```/g, ' ')
-  body = body.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+  const body = proseBody(text)
   if (!body || isWrapperPrompt(body)) return ''
   return body.slice(0, max)
 }
 
+/**
+ * How much of the newest assistant reply crosses the wire, whole.
+ *
+ * MEASURED, not guessed. Across 8,387 assistant replies in the 60 most recent
+ * transcripts on this Mac: p50 153, p75 291, p90 1,627, p95 2,412, p99 3,405,
+ * max 21,757. The 160-char snippet that used to be the ONLY assistant text on the
+ * detail payload delivered 52.7% of replies whole — it cut nearly half of them, and
+ * cut them mid-word with no ellipsis. 4,000 delivers 99.58% whole (35 of 8,387 cut).
+ *
+ * WHY NOT HIGHER. 6,000 buys 0.26 of a percentage point for 50% more bytes on every
+ * detail fetch, and the ceiling is what a pathological reply costs, not what a
+ * typical one costs. The reader paginates at ~200 chars, so 4,000 is at most 20
+ * swipes of deliberate reading; 21,757 would be 109. Bounded on purpose: this
+ * crosses a phone radio and renders on a 576x288 HUD.
+ *
+ * WHY NOT LOWER. 2,000 would still cut 7.5% of replies, and Miles's 1,821-char reply
+ * — the one that started this — sits inside the band that a 2,000 cap leaves with no
+ * headroom at all.
+ */
+export const LATEST_REPLY_MAX = 4000
+
+/**
+ * The newest assistant reply, whole.
+ *
+ * Same cleaning as `proseSnippet`, a far larger budget, and — when it does have to
+ * cut — an ellipsis, so a truncated reply is VISIBLY truncated. `proseSnippet` ends
+ * in a bare `slice`, which is how 1,821 characters became 160 with nothing on screen
+ * to say so.
+ */
+export function latestAssistantReply(text: string, max = LATEST_REPLY_MAX): string {
+  const body = proseBody(text)
+  if (!body || isWrapperPrompt(body)) return ''
+  return body.length <= max ? body : `${body.slice(0, max - 1)}…`
+}
+
 export function composeDiscussionSummary(input: {
   title?: string
   firstPrompt?: string
@@ -1034,6 +1076,92 @@ export const PARTIAL_HEAD_BYTES = 256 * 1024
  *  follow-up continues from. */
 export const PARTIAL_TAIL_BYTES = 768 * 1024
 
+/**
+ * Extra bytes the tail window may reach BACKWARDS to open at a record boundary.
+ *
+ * A single JSONL record can be larger than the whole tail window. Measured on this
+ * Mac: 14 records over 768 KiB in a 60-transcript sample, the largest 1,239,045
+ * bytes — 1.58x the window. When the record that straddles the window start is the
+ * FINAL record, the window holds no complete record at all: `parseJsonLine` rejects
+ * the one fragment it gets and the tail contributes NOTHING. No recent turns, and no
+ * latest reply, at exactly the moment the user opened the session to see what just
+ * happened. Reaching back one more MiB recovers the record instead.
+ *
+ * BOUNDED, because the point is to survive a big record and not to be dragged into an
+ * unbounded read by a pathological one. Past this the tail keeps its ordinary start
+ * and the loss stays honest rather than becoming a wrong "Latest".
+ */
+export const PARTIAL_TAIL_MAX_EXTRA_BYTES = 1024 * 1024
+
+async function readRange(path: string, start: number, end: number): Promise<Buffer> {
+  if (end < start) return Buffer.alloc(0)
+  const chunks: Buffer[] = []
+  for await (const chunk of createReadStream(path, { start, end })) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+  }
+  return Buffer.concat(chunks)
+}
+
+/**
+ * Where the LAST record in the file begins, found by walking back from EOF to the
+ * newline that closed the record before it.
+ *
+ * Cheap in the ordinary case: the last record is small, so the first 64 KiB chunk
+ * contains the boundary and the walk stops immediately. Returns -1 when no boundary
+ * turns up within `limit` bytes, which is the signal to stop reaching.
+ */
+export async function lastRecordStart(path: string, size: number, limit: number): Promise<number> {
+  if (size <= 0) return -1
+  const CHUNK = 64 * 1024
+  // A terminating newline CLOSES the last record; it does not open one. Counting it
+  // would report the last record as starting at EOF and find every window empty.
+  const tailByte = await readRange(path, size - 1, size - 1)
+  const searchEnd = tailByte.length === 1 && tailByte[0] === 0x0a ? size - 1 : size
+  if (searchEnd <= 0) return -1
+  const floor = Math.max(0, size - limit)
+  let pos = searchEnd
+  while (pos > floor) {
+    const start = Math.max(floor, pos - CHUNK)
+    const buf = await readRange(path, start, pos - 1)
+    const idx = buf.lastIndexOf(0x0a)
+    if (idx >= 0) return start + idx + 1
+    pos = start
+  }
+  // Reached the front of the file without a newline: the whole file is one record.
+  return floor === 0 ? 0 : -1
+}
+
+/**
+ * The byte offset the tail window opens at.
+ *
+ * Normally `size - tailBytes`, mid-record, and the leading fragment is discarded by
+ * design. The exception this exists for is a final record BIGGER than the window,
+ * where discarding the fragment discards the entire tail.
+ */
+export async function tailWindowStart(
+  path: string,
+  size: number,
+  headBytes: number,
+  tailBytes: number,
+  extraBytes: number,
+): Promise<number> {
+  const preferred = Math.max(headBytes, size - tailBytes)
+  const boundary = await lastRecordStart(path, size, tailBytes + extraBytes)
+  // A boundary at or after the ordinary start means at least one complete record
+  // already falls inside the window. Nothing to recover; keep the cheaper read.
+  if (boundary < 0 || boundary >= preferred) return preferred
+  // Reaching back BEHIND `headBytes` is allowed, and the instinct to clamp it here is
+  // wrong — an earlier draft did clamp, which silently threw away the very record
+  // this function exists to recover whenever the final record began inside the head
+  // window. It cannot double-count: `boundary` is the start of the LAST record, and
+  // the last record always runs to EOF, which is past `maxBytes` and therefore past
+  // `headBytes`. The head pass can only ever see a prefix of it, arriving as a
+  // trailing partial line that `parseJsonLine` rejects. Every record the head reads
+  // WHOLE ends before `boundary`, so the tail never re-yields one. The read stays
+  // bounded because `lastRecordStart` only looks back `tailBytes + extraBytes`.
+  return boundary
+}
+
 /**
  * Lines of a transcript, reading the WHOLE file when it fits and head+tail when it
  * does not.
@@ -1049,6 +1177,19 @@ export const PARTIAL_TAIL_BYTES = 768 * 1024
  * `parseJsonLine` returns null for it and the caller's loop skips it, which is why
  * this can slice at an arbitrary byte offset and stay correct.
  */
+/**
+ * One transcript line, tagged with the window it came from.
+ *
+ * `tail` means "this line is in the window that ends at EOF". A whole-file read is
+ * all tail, which is what makes the consumer's rule uniform: anything claiming to be
+ * the LATEST state of a session must come from a tail line, no `truncated` special
+ * case at the call site.
+ */
+export interface AgentSessionLine {
+  text: string
+  tail: boolean
+}
+
 export async function* agentSessionLines(
   path: string,
   size: number,
@@ -1060,19 +1201,27 @@ export async function* agentSessionLines(
   // windowing removed. It did exactly that until a mutation caught it.
   headBytes = PARTIAL_HEAD_BYTES,
   tailBytes = PARTIAL_TAIL_BYTES,
-): AsyncGenerator<string> {
+  extraBytes = PARTIAL_TAIL_MAX_EXTRA_BYTES,
+): AsyncGenerator<AgentSessionLine> {
   if (size <= maxBytes) {
-    yield* createInterface({ input: createReadStream(path), crlfDelay: Infinity })
+    for await (const text of createInterface({ input: createReadStream(path), crlfDelay: Infinity })) {
+      yield { text, tail: true }
+    }
     return
   }
-  yield* createInterface({
+  for await (const text of createInterface({
     input: createReadStream(path, { start: 0, end: headBytes - 1 }),
     crlfDelay: Infinity,
-  })
-  yield* createInterface({
-    input: createReadStream(path, { start: Math.max(headBytes, size - tailBytes) }),
+  })) {
+    yield { text, tail: false }
+  }
+  const start = await tailWindowStart(path, size, headBytes, tailBytes, extraBytes)
+  for await (const text of createInterface({
+    input: createReadStream(path, { start }),
     crlfDelay: Infinity,
-  })
+  })) {
+    yield { text, tail: true }
+  }
 }
 
 export interface AgentSessionDetail {
@@ -1086,6 +1235,12 @@ export interface AgentSessionDetail {
   /** Deep, paginated body text for the detail page — up to 2000 chars. The list row
    *  keeps `discussion_summary` at 180. Older clients ignore this field. */
   discussion_digest: string
+  /** The newest assistant reply, whole, up to `LATEST_REPLY_MAX`. Its own field
+   *  rather than a bigger slice of the digest: the digest's job is to summarize a
+   *  whole session inside 2000 chars, and a long reply competing for that budget
+   *  starves the user turns — `composeDiscussionDigest` reserves the Latest block
+   *  FIRST. Two fields, two jobs. Older clients ignore this one. */
+  latest_reply: string
   user_message_count: number
   assistant_message_count: number
   omitted_tools: number
@@ -1110,6 +1265,7 @@ export async function parseAgentSession(
   let sessionId = path.split('/').pop()?.replace(/\.jsonl$/, '') || ''
   let firstPrompt = ''
   let latestAssistant = ''
+  let latestReply = ''
   let userCount = 0
   // Bounded sample for the deep digest: the opening turns plus a recent window.
   // The composer only ever renders head + as many recent as fit 2000 chars, so
@@ -1142,7 +1298,33 @@ export async function parseAgentSession(
   let assistantCount = 0
   let omittedTools = 0
 
-  for await (const line of agentSessionLines(path, st.size, maxBytes, opts.headBytes, opts.tailBytes)) {
+  /**
+   * Where the assistant left off — taken ONLY from the window that ends at EOF.
+   *
+   * An oversized transcript is read head-then-tail into one loop, and this used to be
+   * plain last-write-wins across both. So a session whose tail window happens to hold
+   * no assistant prose — entirely possible when the last 768 KiB are giant tool
+   * results — kept whichever assistant row the HEAD saw and published it under the
+   * label "Latest:". A line from the session's opening, presented as its current
+   * state. Silently wrong, and worse than truncation: truncation is visible.
+   *
+   * With nothing in the tail the honest answer is nothing, and the digest drops its
+   * Latest block rather than filling it with the wrong turn.
+   *
+   * The two fields move together, gated on the same snippet, so the summary line and
+   * the full reply can never come from different records.
+   */
+  const rememberAssistant = (text: string, fromTail: boolean): void => {
+    if (!fromTail) return
+    const snippet = proseSnippet(text)
+    if (!snippet) return
+    latestAssistant = snippet
+    latestReply = latestAssistantReply(text)
+  }
+
+  for await (const { text: line, tail } of agentSessionLines(
+    path, st.size, maxBytes, opts.headBytes, opts.tailBytes,
+  )) {
     const obj = parseJsonLine(line)
     if (!obj) continue
     if (provider === 'claude') {
@@ -1169,8 +1351,7 @@ export async function parseAgentSession(
         if (!title) title = firstLineTitle(text)
       } else {
         assistantCount += 1
-        const snippet = proseSnippet(text)
-        if (snippet) latestAssistant = snippet
+        rememberAssistant(text, tail)
       }
     } else if (provider === 'codex') {
       if (obj.type === 'session_meta' && obj.payload && typeof obj.payload === 'object') {
@@ -1193,8 +1374,7 @@ export async function parseAgentSession(
       if (!text || isWrapperPrompt(text)) continue
       if (payload.role === 'assistant') {
         assistantCount += 1
-        const snippet = proseSnippet(text)
-        if (snippet) latestAssistant = snippet
+        rememberAssistant(text, tail)
       } else {
         userCount += 1
         collectTurn(text)
@@ -1219,8 +1399,7 @@ export async function parseAgentSession(
         }
       } else {
         assistantCount += 1
-        const snippet = proseSnippet(text)
-        if (snippet) latestAssistant = snippet
+        rememberAssistant(text, tail)
       }
     }
   }
@@ -1253,6 +1432,7 @@ export async function parseAgentSession(
       totalTurns: truncated ? undefined : userCount,
       truncated,
     }),
+    latest_reply: latestReply,
     user_message_count: userCount,
     assistant_message_count: assistantCount,
     omitted_tools: omittedTools,

package/server/lib/attached-provider-adapter.ts

@@ -462,6 +462,25 @@ export interface AttachedTurnDeps {
    * and prove the turn is refused with zero spawns. Production never sets it.
    */
   buildArgs?: (provider: AttachedProvider, nativeThreadId: string, cwd: string) => string[]
+  /**
+   * A PASSIVE reader of the child's stdout. Optional; omitted changes nothing.
+   *
+   * The turn already spawns with `--output-format stream-json --verbose`, and this
+   * module reads that stream for exactly one thing: proving the returned session id
+   * matches the target. Everything else is discarded. This hook is how the live view
+   * gets a copy without that scan being touched.
+   *
+   * IT IS AN OBSERVER AND IS TREATED AS ONE. Registered as a SECOND `data` listener,
+   * AFTER the scanner, so the scanner runs first on every chunk. It shares no state
+   * with the scanner, it cannot influence any outcome, and a throw from it is caught
+   * and dropped rather than reaching `emit()` where it would starve the listener that
+   * matters. When absent, no second listener is registered at all, which is byte for
+   * byte the behaviour every existing caller and test already has.
+   *
+   * DELIBERATELY NOT A TRANSFORM. It returns nothing, so there is no shape in which a
+   * future edit can let it modify what the scan sees.
+   */
+  observeStdout?: (chunk: string) => void
 }
 
 export interface AttachedTurnRequest {
@@ -1144,6 +1163,26 @@ function driveChild(input: DriveInput): Promise<AttachedTurnResult> {
       return settleFailure('adapter_internal_error', { detail: 'wire_failed' })
     }
 
+    // --- the passive tee, wired LAST and in its own try ------------------------
+    // Its own try/catch, outside the block above, is the point: a stdout that refuses
+    // a second listener must cost the OBSERVER, not the turn. Inside that block the
+    // same throw would hit `wire_failed` and refuse a delivery for the sake of a view.
+    try {
+      const observe = deps.observeStdout
+      if (typeof observe === 'function' && child.stdout) {
+        child.stdout.on('data', (chunk: any) => {
+          try {
+            observe(typeof chunk === 'string' ? chunk : String(chunk))
+          } catch {
+            // Never rethrown. A throw here propagates out of `emit()` and would stop
+            // every later listener on this stream.
+          }
+        })
+      }
+    } catch {
+      /* the turn proceeds unobserved, which is the correct direction */
+    }
+
     // --- bounded budget ------------------------------------------------------
     deadline = setTimeout(() => {
       timedOut = true