thinkpool-pair 0.7.175 → 0.7.177

package/agent-notify.mjs

@@ -0,0 +1,131 @@
+/* ─────────────────────────────────────────────────────────────
+   bridge/agent-notify.mjs — the PURE decision layer for agent push events.
+
+   The bridge is the only process that knows a turn ended or a permission
+   card went unanswered. It can't call /api/notify-code directly (that
+   endpoint is webhook-secret-gated and this is a published npm package), so
+   it writes a compact `__agent` row into code_messages and lets the existing
+   push_notify_on_code_message trigger fan it out.
+
+   Everything that DECIDES whether to write such a row lives here, with no
+   I/O, so bridge/agent-notify.test.mjs can exercise it without a room, a
+   socket, or a wall clock.
+
+   Spec: docs/specs/2026-07-09-code-notifications-rework.md (Slice 3)
+   ───────────────────────────────────────────────────────────── */
+
+// A turn shorter than this means somebody was almost certainly watching it —
+// pushing "done" 4 seconds after they hit enter is noise, not news.
+export const DEFAULT_MIN_TURN_MS = 30_000
+
+// How long a permission card may sit unanswered before we assume nobody is
+// looking at the room and push. Short enough to be useful, long enough that
+// the common case (you're right there, you click it) never fires.
+export const DEFAULT_PERM_GRACE_MS = 20_000
+
+// Push copy is a banner, not a transcript.
+export const SUMMARY_MAX = 200
+
+/* A lane is USER-FACING when a human opened it and is waiting on it.
+   - spawnedBy: a Dispatch worker lane an agent fanned out. Its owner is
+     another agent; the human never asked for it directly.
+   - flowTaskKey: a Flow slice lane. Same reasoning — the conductor collects
+     it, and a 12-lane flow would fan 12 banners at one person.
+   Both run in inherited/bypass modes almost always, so they also rarely
+   raise permission cards. The conductor lane itself (flowSessionId but no
+   flowTaskKey) IS user-facing — that's the one a human is watching. */
+export function isUserFacingLane(entry) {
+  if (!entry) return false
+  return !entry.spawnedBy && !entry.flowTaskKey
+}
+
+/* Collapse whitespace, clip, ellipsize. Never throws on non-strings. */
+export function clipSummary(text, max = SUMMARY_MAX) {
+  if (text == null) return ''
+  const s = String(text).replace(/\s+/g, ' ').trim()
+  if (s.length <= max) return s
+  return s.slice(0, max).replace(/\s+\S*$/, '').trimEnd() + '…'
+}
+
+/* Should a settled turn produce a `turn-done` event row?
+
+   No when: the lane isn't user-facing · the user pressed Stop (subtype
+   'aborted' — they know it's over, they're the one who ended it) · the turn
+   was short enough that somebody was plainly watching · we never saw the
+   turn start (startedAt null → a stray `error` event outside any turn, e.g.
+   the SDK-regression warning emitted at init).
+
+   `error` turns DO notify — with the same neutral copy as a success. Max's
+   call: "the agent stopped" is the news; the reason is in the room. */
+export function shouldNotifyTurnDone({ entry, subtype, startedAt, now, minTurnMs = DEFAULT_MIN_TURN_MS }) {
+  if (!isUserFacingLane(entry)) return false
+  if (subtype === 'aborted') return false
+  if (!startedAt) return false
+  if (!Number.isFinite(now)) return false
+  return (now - startedAt) >= minTurnMs
+}
+
+/* The one-line "what is it asking me" for a permission card.
+   AskUserQuestion cards carry `questions`; ordinary tool cards degrade to
+   `<ToolName> <first meaningful arg>`, matching the local stderr line. */
+export function permissionSummary(payload) {
+  const p = payload || {}
+  const qs = Array.isArray(p.questions) ? p.questions.map(q => q?.question).filter(Boolean) : []
+  if (qs.length) return clipSummary(qs.join(' / '))
+  if (p.risk === 'plan') return clipSummary(p.plan ? `Plan ready: ${p.plan}` : 'A plan is ready for review')
+  const i = p.input
+  const arg = i && (i.command || i.file_path || i.path || i.pattern || i.url || i.query || i.description)
+  const name = p.toolName || 'A tool'
+  return clipSummary(arg ? `${name} ${arg}` : name)
+}
+
+/* Per-session permission-card notifier.
+
+   arm(id, payload)  — a card was raised. Start the grace timer.
+   resolve(id)       — the card was answered (human click, mode-flip
+                       auto-approval, or a drain-to-deny). If its timer had
+                       already FIRED we pushed a banner, so retract it.
+   clearAll()        — turn ended / session died. Every outstanding card is
+                       dead; retract anything we announced.
+
+   Timers are injected so the unit test drives them synchronously. onFire /
+   onRetract are fire-and-forget (they end up as REST inserts); a throw in
+   either must never take the bridge down. */
+export function createPermNotifier({
+  graceMs = DEFAULT_PERM_GRACE_MS,
+  onFire = () => {},
+  onRetract = () => {},
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
+  const cards = new Map()   // id → { timer, fired, payload }
+  const safe = (fn, id, payload) => { try { fn(id, payload) } catch { /* never break the turn */ } }
+
+  const settle = (id) => {
+    const rec = cards.get(id)
+    if (!rec) return
+    if (rec.timer) { try { clearTimer(rec.timer) } catch { /* noop */ } }
+    cards.delete(id)
+    if (rec.fired) safe(onRetract, id, rec.payload)
+  }
+
+  return {
+    arm(id, payload) {
+      if (!id || cards.has(id)) return
+      const rec = { timer: null, fired: false, payload }
+      rec.timer = setTimer(() => {
+        rec.timer = null
+        rec.fired = true
+        safe(onFire, id, payload)
+      }, graceMs)
+      // Never hold the process open on a permission timer.
+      try { rec.timer?.unref?.() } catch { /* not a node timer (test double) */ }
+      cards.set(id, rec)
+    },
+    resolve: settle,
+    clearAll() { for (const id of [...cards.keys()]) settle(id) },
+    // test/debug introspection only
+    size: () => cards.size,
+    fired: (id) => !!cards.get(id)?.fired,
+  }
+}

package/bridge.mjs

@@ -39,6 +39,9 @@ import { randomUUID } from 'node:crypto'
 import { createClient } from '@supabase/supabase-js'
 import { serveDecision, fetchServeRow, refusalMessage, gateFailAction } from './serve-consent.mjs'
 import { reapTerminalRow as _reapTerminalRow } from './reap-terminal.mjs'
+// Slice 3 — the pure decision layer for agent push events (turn-done / needs-input).
+// Unit-tested in bridge/agent-notify.test.mjs; everything with I/O stays here.
+import { createPermNotifier, shouldNotifyTurnDone, permissionSummary, clipSummary, isUserFacingLane, DEFAULT_MIN_TURN_MS } from './agent-notify.mjs'
 // resolveProviderEnv(id) → {ANTHROPIC_BASE_URL,ANTHROPIC_AUTH_TOKEN,ANTHROPIC_MODEL} for a
 // registered custom provider, or null for the built-in/unknown (leave the default env intact).
 // Multi-provider BYOK slice 1: a lane spawned with a `provider` id runs on that endpoint.
@@ -763,6 +766,46 @@ async function budgetRpc (fn, args) {
   const t = await r.text()
   return t ? JSON.parse(t) : null
 }
+
+// ── Agent push events — spec docs/specs/2026-07-09-code-notifications-rework.md (Slice 3).
+// The bridge is the only process that knows a turn ended or a permission card went
+// unanswered, and it CANNOT call /api/notify-code (webhook-secret-gated; this is a
+// published npm package). So it writes a compact `__agent` row into code_messages with
+// the SAME authed REST path budgetRpc uses; the existing push_notify_on_code_message
+// trigger fans it out and api/notify-code.js routes on payload.__agent.
+//
+// Durable by construction: the row is also the transport-neutral event log the iPhone
+// sender will read, and it feeds get_code_unread_counts for free.
+//
+// Fire-and-forget in the strictest sense — an anon bridge (no codeAuthToken/uid), a
+// dead network, or a 4xx must never surface in the turn. TP_AGENT_NOTIFY_OFF=1 kills
+// the whole path. The web client filters `ae:` rows out of its seed/replay (Slice 2),
+// so an old client paired with a new bridge renders nothing new.
+const AGENT_NOTIFY_OFF = process.env.TP_AGENT_NOTIFY_OFF === '1'
+const MIN_TURN_MS = Number(process.env.TP_NOTIFY_MIN_TURN_MS) > 0
+  ? Number(process.env.TP_NOTIFY_MIN_TURN_MS) : DEFAULT_MIN_TURN_MS
+function persistAgentEvent (payload) {
+  if (AGENT_NOTIFY_OFF || !codeAuthToken || !myServeUid || !room) return
+  const row = {
+    id: `ae:${randomUUID()}`,
+    session_code: room,
+    author_id: myServeUid,
+    payload: { __agent: true, ts: Date.now(), ...payload },
+  }
+  fetch(`${SUPABASE_URL}/rest/v1/code_messages`, {
+    method: 'POST',
+    headers: {
+      apikey: SUPABASE_ANON,
+      Authorization: `Bearer ${codeAuthToken}`,
+      'Content-Type': 'application/json',
+      Prefer: 'return=minimal',
+    },
+    body: JSON.stringify(row),
+  }).then((r) => {
+    if (!r.ok && process.env.TP_DEBUG) process.stderr.write(`\n  ◆ agent-event insert ${r.status}\n`)
+  }).catch(() => { /* best-effort — a missed banner is not worth a stack trace */ })
+}
+
 // Fire-and-forget: fold a completed turn's output tokens into the room's durable monthly
 // ledger. output_tokens = the billed reasoning+output spend the indicator already tracks.
 function recordRoomSpend (tokens) {
@@ -1542,6 +1585,13 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
     // order (not readdir/filesystem order). Legacy recs (no openedAt) derive it from the
     // first transcript event ts, so even the first post-fix restart is ordered right.
     openedAt: openedAt || (Array.isArray(log) ? (log.find((e) => e?.ts)?.ts || 0) : 0) || Date.now() }
+  // Slice 3 — a permission card left unanswered past the grace window pushes
+  // "<lane> — needs you: <what>"; answering it anywhere retracts the banner
+  // everywhere. Worker/flow lanes are excluded at arm() time (isUserFacingLane).
+  entry.permNotifier = createPermNotifier({
+    onFire:    (_cardId, summary) => persistAgentEvent({ kind: 'needs-input',    term: id, termName: termNames[id] || null, summary }),
+    onRetract: (_cardId)          => persistAgentEvent({ kind: 'needs-resolved', term: id, termName: termNames[id] || null }),
+  })
   // C1 (RT-2): per-term contiguous seq counter. Seeded from the restored log's max
   // so a bridge restart resumes ABOVE every persisted seq — fresh events never reuse
   // an old seq, which is what keeps the between-turns restart dup-free (see
@@ -2135,8 +2185,11 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
       // roster broadcast (delivered to every subscriber) instead of sniffing the live
       // code-event stream a passive dashboard channel misses. Covers every turn path
       // (normal, spawn, flow lane, cross-room) since they all flow through onEvent.
+      // The RISING edge is also where a turn's wall clock starts — the only place the
+      // bridge sees "this lane just began working". `result`/`error` reads it to decide
+      // whether the turn was long enough that nobody was watching (Slice 3).
       { const busyNow = entry.session?.turnActive ?? false
-        if (busyNow !== entry._busyAnn) { entry._busyAnn = busyNow; announce() } }
+        if (busyNow !== entry._busyAnn) { if (busyNow) entry._turnStart = Date.now(); entry._busyAnn = busyNow; announce() } }
       // Capture this session's current MODEL (resolved full id, with version — from
       // system/result `model` or usage `ctx.model`) and the SDK's supported-model
       // LIST (from the `models` event) so the announce carries them to EVERY device.
@@ -2247,6 +2300,30 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
         bcast('code-event', { term: id, evt: { kind: 'compact', status: 'done', ts: Date.now() } })
         entry.compactBy = null
       }
+      // ── Slice 3: the turn settled. Two things happen, in this order.
+      //   1. Every outstanding permission card on this lane is now dead (the SDK
+      //      won't ask again for a turn that ended) — clearAll retracts any
+      //      "needs you" banner we already pushed. Do this even for aborted turns
+      //      and non-user-facing lanes: a stale card can never fire later.
+      //   2. If the turn ran long enough that nobody was plausibly watching, and
+      //      the lane is one a human opened, and they didn't press Stop — write a
+      //      `turn-done` event row. An `error` turn uses the same neutral copy.
+      // _turnStart is cleared unconditionally so a stray post-settle event can't
+      // re-notify off a stale stamp.
+      if (evt.kind === 'result' || evt.kind === 'error') {
+        const startedAt = entry._turnStart
+        entry._turnStart = null
+        entry.permNotifier?.clearAll()
+        if (shouldNotifyTurnDone({ entry, subtype: evt.subtype, startedAt, now: Date.now(), minTurnMs: MIN_TURN_MS })) {
+          persistAgentEvent({
+            kind: 'turn-done',
+            term: id,
+            termName: termNames[id] || null,
+            summary: clipSummary(evt.kind === 'result' ? evt.resultText : evt.message),
+            subtype: evt.subtype || (evt.kind === 'error' ? 'error' : null),
+          })
+        }
+      }
       // Single tail: stamp into the log (transcript kinds only), broadcast live,
       // print locally, persist. Shared so a deferred image event re-enters it once
       // its base64 has been lifted to a Storage path (see deferImageEvent).
@@ -2281,6 +2358,13 @@ function openStructured({ id, model, resume, log, commands, mode, spawnedBy, rol
       const payload = { term: id, id: req.id, toolName: req.toolName, input: req.input, risk: req.risk, plan: req.plan, questions: req.questions }
       entry.pending.set(req.id, { resolve, payload })
       bcast('code-perm-req', payload)
+      // Slice 3 — arm the grace timer. Fires a "needs you" push only if the card is
+      // STILL unanswered 20s from now (you're not in the room). Every resolve path —
+      // the code-perm broadcast, drainPending, and the bypass/acceptEdits mode-flip
+      // auto-approvals — calls permNotifier.resolve(id), which retracts the banner
+      // if it had fired. Worker + flow-slice lanes are skipped: their cards belong to
+      // an agent's fan-out, and a 12-lane flow would fan 12 banners at one person.
+      if (isUserFacingLane(entry)) entry.permNotifier?.arm(req.id, permissionSummary(payload))
       process.stderr.write(req.risk === 'plan'
         ? `\n  ${A.mag}◆ plan ready — approve in the room.${A.rst}\n`
         : req.risk === 'ask'
@@ -2310,6 +2394,8 @@ function drainPending(s) {
   if (!s?.pending) return
   for (const [, p] of s.pending) { try { p.resolve('deny') } catch { /* noop */ } }
   s.pending.clear()
+  // Every card just died → retract any "needs you" banner they raised (Slice 3).
+  s.permNotifier?.clearAll()
 }
 
 // Switching a terminal to bypassPermissions must RETROACTIVELY clear the cards the
@@ -2329,6 +2415,7 @@ function allowPending(s) {
     if (p?.payload?.risk === 'plan' || p?.payload?.risk === 'ask') continue
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
+    s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
   }
 }
 
@@ -2347,6 +2434,7 @@ function acceptEditsPending(s) {
     if (!ACCEPT_EDIT_TOOLS.has(tn)) continue
     try { p.resolve('allow') } catch { /* noop */ }
     s.pending.delete(key)
+    s.permNotifier?.resolve(key)   // auto-approved → retract the "needs you" banner
   }
 }
 
@@ -2742,7 +2830,9 @@ channel
     const p = s && payload.id && s.pending.get(payload.id)
     // Pass the raw decision through — normal tools use allow/deny, plan cards
     // use run/accept/keep (claude-session interprets). Default deny on missing.
-    if (p) { s.pending.delete(payload.id); p.resolve(payload.decision || 'deny') }
+    // Answered from a device → retract the "needs you" banner on every OTHER device
+    // (permNotifier.resolve is a no-op unless its grace timer already fired).
+    if (p) { s.pending.delete(payload.id); s.permNotifier?.resolve(payload.id); p.resolve(payload.decision || 'deny') }
   })
   .on('broadcast', { event: 'code-abort' }, ({ payload }) => {
     const s = payload?.term && sessions.get(payload.term)

package/claude-session.mjs

@@ -978,7 +978,13 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
               }
               if (best) curModel = best
             }
-            emit({ kind: 'result', subtype: m.subtype, sessionId, model: curModel, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns, durationMs: m.duration_ms ?? null, denials: Array.isArray(m.permission_denials) ? m.permission_denials.length : 0 })
+            // resultText: the SDK's final assistant text, clipped. The bridge folds it
+            // into the `turn-done` push body ("<lane> — done: <summary>") so a banner
+            // says what happened, not just that something did. Clipped + whitespace-
+            // collapsed here so neither the broadcast frame nor the persisted log grows
+            // by a full turn's prose. Absent on aborted/error results — nothing to say.
+            { const rt = typeof m.result === 'string' ? m.result.replace(/\s+/g, ' ').trim().slice(0, 200) : ''
+              emit({ kind: 'result', subtype: m.subtype, sessionId, model: curModel, costUsd: m.total_cost_usd, usage: m.usage, numTurns: m.num_turns, durationMs: m.duration_ms ?? null, denials: Array.isArray(m.permission_denials) ? m.permission_denials.length : 0, resultText: rt || null }) }
             // Arm the Haiku fallback: if Claude's own prompt_suggestion doesn't arrive within
             // the window, generate one from the last assistant reply. (Skip aborted turns.)
             if (sugTimer) clearTimeout(sugTimer)

package/event-id.mjs

@@ -249,67 +249,13 @@ export function usageReportLine (sessionModel, logEvents) {
   return `usage · ${turns} · ${perStr}${total}${cost} · tokens + cost only (no plan/rate-limit meters)`
 }
 
-// Default hard cap for the context-carry recap (chars of transcript body, framing extra).
-export const RECAP_CAP = 20000
-
-// Context-carry recap for a lane whose SDK memory CAN'T be resumed (a cross-provider
-// switch, or a bridge-restart restore where canResume() is false). Such a lane re-opens
-// under the SAME id with the visible transcript replayed but a FRESH, blank backend — so
-// the agent starts amnesiac mid-conversation (the 2026-07-08 lane 109d22e1 "this is the
-// first message in my lane" incident). Raw SDK resume can't cross a provider (signed
-// thinking blocks + provider-specific tool_use records get rejected by a foreign backend),
-// so we carry the conversation at the TEXT layer instead: synthesize a plain-text recap
-// from the saved log — the people's turns (`you`) + the assistant's own text replies
-// (`assistant` text blocks; thinking + tool_use are dropped, they don't survive a backend
-// hop and are noise) — newest-weighted under a hard char cap, framed so the agent RESUMES
-// rather than re-greets. Pure + import-safe (unit-tested in bridge/recap.test.mjs).
-//
-// capReplayEvents lesson (rooms died once on a multi-MB replay): the char cap keeps this
-// bounded in prose form too — an unbounded recap would be the same bug wearing a text hat.
-export function buildRecapFromLog(log, cap = RECAP_CAP) {
-  if (!Array.isArray(log) || !log.length) return ''
-  const budget = Math.max(0, Number.isFinite(cap) ? Math.floor(cap) : 0)
-  if (!budget) return ''
-  // Flatten the log to speaker-labelled turns, in order. `you` = a person in the room;
-  // `assistant` = this agent's own earlier reply (its text blocks only).
-  const turns = []
-  for (const e of log) {
-    if (!e || typeof e !== 'object') continue
-    if (e.kind === 'you') {
-      const t = String(e.text || '').trim()
-      if (t) turns.push({ who: 'PERSON', text: t })
-    } else if (e.kind === 'assistant') {
-      const t = (Array.isArray(e.blocks) ? e.blocks : [])
-        .filter((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.trim())
-        .map((b) => b.text.trim())
-        .join('\n')
-      if (t) turns.push({ who: 'YOU', text: t })
-    }
-  }
-  if (!turns.length) return ''
-  // Newest-weighted: walk from the end, keep whole turns until the char budget is spent,
-  // then restore chronological order. A single newest turn bigger than the whole budget is
-  // still kept (truncated) so the LIVE task is never dropped to the cap.
-  const kept = []
-  let used = 0
-  let omitted = false
-  for (let i = turns.length - 1; i >= 0; i--) {
-    let line = `${turns[i].who}: ${turns[i].text}`
-    if (used + line.length > budget) {
-      if (kept.length) { omitted = true; break }   // older turns exist but won't fit → note + stop
-      line = line.slice(0, budget)                  // newest turn alone overflows → clip, still include
-    }
-    kept.push(line)
-    used += line.length
-  }
-  kept.reverse()
-  const body = (omitted ? ['[…earlier messages omitted for length…]'] : []).concat(kept).join('\n\n')
-  return [
-    '[CONTEXT CARRY — you are RESUMING a live conversation after a model/provider switch]',
-    "Your session memory was reset by the switch, but this lane's conversation continued and the people already saw everything below. Do NOT re-greet, do NOT re-introduce yourself, and do NOT re-answer anything you already completed. Read the recap, then continue the work exactly where it left off. The LAST PERSON message with no completed answer below is your live task — pick it up.",
-    '',
-    '--- conversation so far (oldest → newest) ---',
-    body,
-    '--- end recap ---',
-  ].join('\n')
-}
+/* The context-carry recap moved to ./recap.mjs (ADR-0010 / S4, 2026-07-09).
+ *
+ * Why: the WEB CLIENT needs buildRecapFromLog to carry a lane's bridgeless
+ * conversation across a bridge wake, and this module imports `node:crypto` —
+ * unresolvable in a browser bundle. The pure half lives in an import-free file
+ * both sides can load; these re-exports keep every existing bridge-side import
+ * (`from './event-id.mjs'`) working untouched, including bridge/recap.test.mjs.
+ *
+ * recap.mjs must stay in bridge/package.json `files` — event-id.mjs imports it. */
+export { RECAP_CAP, buildRecapFromLog } from './recap.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.175",
+  "version": "0.7.177",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
     "claude-session.mjs",
     "turn-stall.mjs",
     "update-gate.mjs",
+    "agent-notify.mjs",
     "event-id.mjs",
+    "recap.mjs",
     "transcript-sanitize.mjs",
     "session-store.mjs",
     "cross-terminal.mjs",

package/recap.mjs

@@ -0,0 +1,112 @@
+/* recap.mjs — the text-layer context carry. PURE. NO IMPORTS. NO NODE BUILTINS.
+ *
+ * Extracted from event-id.mjs on 2026-07-09 (ADR-0010 / slice S4) for one reason:
+ * the WEB CLIENT needs this function now, and event-id.mjs imports `node:crypto`
+ * (for stampEvent's randomUUID default), which Vite cannot resolve for a browser
+ * bundle. Rather than write a second windower — the spec's §b instruction is
+ * literally "Do not write a second windower" — the pure half moves to its own
+ * file that both sides import.
+ *
+ *   bridge/event-id.mjs  re-exports these (every existing import keeps working)
+ *   src/pages/code/poolTurn.js  imports this file directly
+ *
+ * ⚠ KEEP THIS FILE FREE OF IMPORTS. The moment it imports `node:*`, the web build
+ * breaks. There is no lint rule for this; there is only this comment.
+ *
+ * ⚠ TARBALL: this file is imported by event-id.mjs, so it MUST appear in
+ * bridge/package.json `files`. A publish that omits it boots a bridge that
+ * crashes on `import './recap.mjs'`. (feedback_npm_tarball_completeness.)
+ */
+
+// Default hard cap for the context-carry recap (chars of transcript body, framing extra).
+export const RECAP_CAP = 20000
+
+/* Why a lane is being handed a recap instead of a resumed session. The framing text
+   differs because the LIE each one must avoid differs:
+
+   'switch' — a model/provider switch ended the SDK session. The agent's own memory is
+     gone but nothing else happened; the transcript above is entirely its own work.
+
+   'wake'  — ADR-0010 §d. The bridge was ASLEEP. The lane stayed alive and the people
+     kept talking to Pool (client-side BYOK, chat-only, no file access). So the recap
+     contains turns the agent DID NOT produce and work it DID NOT do. The framing has to
+     say that, and has to say that nothing ran on its behalf — otherwise the agent
+     assumes the plan below was already executed. That assumption is how "nothing
+     autofires" becomes a lie the agent tells itself. */
+const FRAMING = {
+  switch: {
+    header: '[CONTEXT CARRY — you are RESUMING a live conversation after a model/provider switch]',
+    body: "Your session memory was reset by the switch, but this lane's conversation continued and the people already saw everything below. Do NOT re-greet, do NOT re-introduce yourself, and do NOT re-answer anything you already completed. Read the recap, then continue the work exactly where it left off. The LAST PERSON message with no completed answer below is your live task — pick it up.",
+  },
+  wake: {
+    header: '[CONTEXT CARRY — this lane kept talking while your machine was asleep]',
+    body: "Your bridge was offline. The lane stayed open and the people in this room kept planning here with Pool — a chat-only assistant with no file access and no tools. Everything below already happened and they have all seen it. NOTHING WAS RUN ON YOUR BEHALF: no commands were executed, no files were changed, and no plan below has been carried out. Do NOT re-greet and do NOT re-answer what is already answered. Read the recap, then wait for the people to tell you what to do with it — the plan below is a plan, not an instruction you have already been given.",
+  },
+}
+
+/* Context-carry recap for a lane whose SDK memory CAN'T be resumed — a cross-provider
+   switch, a bridge-restart restore where canResume() is false, or (ADR-0010) a bridge
+   WAKE under a lane that spent the outage in Pool posture. Such a lane re-opens under the
+   SAME id with the visible transcript replayed but a FRESH, blank backend — so the agent
+   starts amnesiac mid-conversation (the 2026-07-08 lane 109d22e1 "this is the first
+   message in my lane" incident). Raw SDK resume can't cross a provider (signed thinking
+   blocks + provider-specific tool_use records get rejected by a foreign backend), so we
+   carry the conversation at the TEXT layer instead: synthesize a plain-text recap from the
+   saved log — the people's turns (`you`) + the assistant's own text replies (`assistant`
+   text blocks; thinking + tool_use are dropped, they don't survive a backend hop and are
+   noise) — newest-weighted under a hard char cap, framed so the agent RESUMES rather than
+   re-greets. Pure + import-safe (unit-tested in bridge/recap.test.mjs).
+
+   capReplayEvents lesson (rooms died once on a multi-MB replay): the char cap keeps this
+   bounded in prose form too — an unbounded recap would be the same bug wearing a text hat.
+
+   `reason` selects the framing only; the windowing is identical and the default
+   ('switch') is byte-for-byte what this function returned before the S4 extraction. */
+export function buildRecapFromLog(log, cap = RECAP_CAP, { reason = 'switch' } = {}) {
+  if (!Array.isArray(log) || !log.length) return ''
+  const budget = Math.max(0, Number.isFinite(cap) ? Math.floor(cap) : 0)
+  if (!budget) return ''
+  // Flatten the log to speaker-labelled turns, in order. `you` = a person in the room;
+  // `assistant` = this agent's own earlier reply (its text blocks only).
+  const turns = []
+  for (const e of log) {
+    if (!e || typeof e !== 'object') continue
+    if (e.kind === 'you') {
+      const t = String(e.text || '').trim()
+      if (t) turns.push({ who: 'PERSON', text: t })
+    } else if (e.kind === 'assistant') {
+      const t = (Array.isArray(e.blocks) ? e.blocks : [])
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.trim())
+        .map((b) => b.text.trim())
+        .join('\n')
+      if (t) turns.push({ who: 'YOU', text: t })
+    }
+  }
+  if (!turns.length) return ''
+  // Newest-weighted: walk from the end, keep whole turns until the char budget is spent,
+  // then restore chronological order. A single newest turn bigger than the whole budget is
+  // still kept (truncated) so the LIVE task is never dropped to the cap.
+  const kept = []
+  let used = 0
+  let omitted = false
+  for (let i = turns.length - 1; i >= 0; i--) {
+    let line = `${turns[i].who}: ${turns[i].text}`
+    if (used + line.length > budget) {
+      if (kept.length) { omitted = true; break }   // older turns exist but won't fit → note + stop
+      line = line.slice(0, budget)                  // newest turn alone overflows → clip, still include
+    }
+    kept.push(line)
+    used += line.length
+  }
+  kept.reverse()
+  const body = (omitted ? ['[…earlier messages omitted for length…]'] : []).concat(kept).join('\n\n')
+  const frame = FRAMING[reason] || FRAMING.switch
+  return [
+    frame.header,
+    frame.body,
+    '',
+    '--- conversation so far (oldest → newest) ---',
+    body,
+    '--- end recap ---',
+  ].join('\n')
+}