thinkpool-pair 0.7.245 → 0.7.246

package/bridge.mjs

@@ -57,6 +57,7 @@ import { probeHermesRuntime } from './hermes-probe.mjs'
 import { canonicalRoomFilePath, waitForNativeImages } from './codex-images.mjs'
 import { createManagedLaneWorktree, removeManagedLaneWorktree } from './lane-worktree.mjs'
 import { commandOnPath } from './agent-detect.mjs'
+import { requiresSdkAdmission, sdkSmokePassed } from './sdk-admission.mjs'
 
 const STRUCTURED_MODES = new Set(['default', 'acceptEdits', 'plan', 'review', 'bypassPermissions'])
 import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, FLOW_CODEX_CONDUCTOR_PROMPT, FLOW_CODEX_LANE_PROMPT, buildConductorEnv, assembleCrossWaveContext, buildLanePrompt } from './flow-conductor.mjs'
@@ -109,7 +110,7 @@ import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSP
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage } from './session-store.mjs'
-import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
+import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, ImageEventQueue, imageQueueConfig, uploadCodeImage as uploadCodeImageRequest, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
 import { classifyCodeEvent, unknownCodeEventNotice } from './code-event-contract.mjs'
 import { fetchPairControlDeliveryAuthority } from './pair-control-authority.mjs'
 import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantTextSince, sideContextBlock, sideSnapshot } from './side-lane.mjs'
@@ -122,6 +123,7 @@ import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE } from './
 // Override with TP_SUPABASE_URL / TP_SUPABASE_ANON if you ever need to.
 const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || DEFAULT_SUPABASE_URL
 const WEB_BASE      = process.env.TP_WEB_BASE      || 'https://thinkpool.io'
+const IMAGE_QUEUE_CONFIG = imageQueueConfig()
 
 // The anon key is RESOLVED, not baked. It used to be a string literal here, and
 // that literal now sits in 224 published tarballs on 224 users' laptops: disable
@@ -361,10 +363,9 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
 // The SDK tracks a caret (^0.3.x), so a restart can auto-pull a NEW SDK, and its
 // interrupt/turn API has broken between 0.3.x minors before. Smoke-test the API
 // surface (offline, no tokens) the FIRST time a given SDK version is seen, so a
-// bad one is caught + surfaced loudly (stderr + the announce banner) instead of
-// silently breaking turns. sdkStatus feeds the announce. Fully guarded — a check
-// error never blocks serving.
-const SMOKE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), 'sdk-smoke.mjs')
+// bad one is caught before a room can serve turns. Account/service commands remain
+// available so the operator can repair the installation.
+const SMOKE_PATH = process.env.TP_SDK_SMOKE_PATH || path.join(path.dirname(fileURLToPath(import.meta.url)), 'sdk-smoke.mjs')
 let sdkStatus = { ok: null, version: 'unknown', reason: '' }
 function currentSdkVersion() {
   try {
@@ -382,7 +383,7 @@ function runSmoke() {
   catch (e) { return (e.stdout || '').toString().trim() || `SMOKE:FAIL:${currentSdkVersion()}:${e.code === 'ETIMEDOUT' ? 'timeout' : (e.message || 'run error').slice(0, 80)}` }
 }
 if (argv[0] === 'verify-sdk') {
-  const out = runSmoke(); console.log(out); process.exit(/^SMOKE:PASS/.test(out) ? 0 : 1)
+  const out = runSmoke(); console.log(out); process.exit(sdkSmokePassed(out) ? 0 : 1)
 }
 function checkSdkCompat() {
   const dir = path.join(os.homedir(), '.thinkpool-pair'); const okFile = path.join(dir, 'sdk-ok')
@@ -397,10 +398,9 @@ function checkSdkCompat() {
   } else {
     sdkStatus = { ok: false, version: (m && m[2]) || version, reason: (m && m[3]) || 'unknown' }
     try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'sdk-bad'), `${sdkStatus.version}: ${sdkStatus.reason}`) } catch { /* noop */ }
-    process.stderr.write(`\n  ⚠⚠ agent SDK v${sdkStatus.version} FAILED the compatibility smoke test — ${sdkStatus.reason}.\n  ⚠⚠ turns may misbehave. Pin a known-good SDK + restart:\n     bridge/package.json → "@anthropic-ai/claude-agent-sdk": "<good version>", then republish + Restart & update.\n`)
+    process.stderr.write(`\n  ⛔ agent SDK v${sdkStatus.version} FAILED the compatibility smoke test — ${sdkStatus.reason}.\n  ⛔ refusing to serve agent turns. Repair or pin a known-good SDK, then restart.\n`)
   }
 }
-try { checkSdkCompat() } catch (e) { process.stderr.write(`  ⚠ SDK smoke check skipped: ${e.message}\n`) }
 
 if (!argv[0] || argv[0].startsWith('-')) { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) }
 
@@ -418,6 +418,10 @@ if (!/^[A-Z0-9_-]{2,32}$/.test(room)) {
   console.error(`refused: invalid room code ${JSON.stringify(room)} (expected 2–32 alphanumerics, dash, or underscore)`)
   process.exit(1)
 }
+if (requiresSdkAdmission(argv)) {
+  checkSdkCompat()
+  if (!sdkStatus.ok) process.exit(1)
+}
 // ── Supervisor mode (--supervise / --keep-alive): keep the bridge alive across
 // crashes. We re-exec ourselves without the flag and respawn the child on any
 // non-clean exit with exponential backoff. Zero-dependency, cross-platform. With
@@ -1503,38 +1507,30 @@ watchOutbox(MOCKUP_OUTBOX, () => [...sessions.keys()][0] || attachedId || [...te
 // { type:'image', path } ref. The persisted log + every replay then carry the path,
 // never base64; the web client mints a signed URL on render (structured.jsx, same
 // as the mockup thumbs). Spec: docs/specs/2026-06-26-code-agent-images.md
-async function uploadCodeImage(term, cid, im) {
-  const headers = { 'Content-Type': 'application/json' }
-  if (codeAuthToken) headers.Authorization = `Bearer ${codeAuthToken}`
-  const res = await fetch(`${WEB_BASE}/api/code-image`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ code: room, term, cid, idx: im.idx, mediaType: im.mediaType, b64: im.b64 }),
+async function uploadCodeImage(term, cid, im, activeUploads) {
+  return uploadCodeImageRequest({
+    webBase: WEB_BASE,
+    room,
+    authToken: codeAuthToken,
+    term,
+    cid,
+    image: im,
+    timeoutMs: IMAGE_QUEUE_CONFIG.uploadTimeoutMs,
+    activeUploads,
   })
-  if (!res.ok) throw new Error(`code-image ${res.status}`)
-  const { path } = await res.json()
-  if (!path) throw new Error('code-image: no path')
-  return path
 }
-// Defer an image-bearing tool_result behind a per-session upload chain (preserves
-// arrival order among images), then log + broadcast the URL-only event through the
-// normal path. pushLog is the single seq-assignment point, so the deferred event
-// still gets a contiguous seq at chain-resolution time; its ts was stamped at
-// arrival, so it sorts into place. On upload failure the block degrades to the same
-// render-safe text placeholder — base64 is NEVER logged, broadcast, or persisted.
+// Every structured event enters one per-session emission boundary. With no upload in
+// flight the fast path stays synchronous; after an image, later tool/results wait in
+// runtime order. The queue owns timeout, raw-base64 budgets, and teardown degradation.
 function deferImageEvent(entry, id, evt, imgs, emitTail) {
-  entry.imageChain = (entry.imageChain || Promise.resolve()).then(async () => {
-    for (const im of imgs) {
-      try {
-        const path = await uploadCodeImage(id, evt.cid, im)
-        evt.content[im.idx] = { type: 'image', path, mediaType: im.mediaType }
-      } catch (e) {
-        process.stderr.write(`\n  ◇ screenshot upload failed (${e?.message || e}).\n`)
-        evt.content[im.idx] = { type: 'text', text: '[screenshot omitted — upload failed]' }
-      }
-    }
-    emitTail(evt)
-  }).catch(() => {})
+  entry.imageQueue ||= new ImageEventQueue({
+    maxPending: IMAGE_QUEUE_CONFIG.maxPending,
+    maxBytes: IMAGE_QUEUE_CONFIG.maxBytes,
+    upload: (queuedEvt, im, activeUploads) => uploadCodeImage(id, queuedEvt.cid, im, activeUploads),
+    onUploadError: (e) => process.stderr.write(`\n  ◇ screenshot upload failed (${e?.message || e}).\n`),
+    onOverload: ({ maxPending, maxBytes }) => process.stderr.write(`\n  ◇ screenshot omitted (image queue cap: ${maxPending} pending / ${maxBytes} encoded bytes).\n`),
+  })
+  entry.imageQueue.enqueue(evt, imgs, emitTail)
 }
 // Fire-and-forget: drop a closed term's screenshots from Storage so they don't
 // outlive the room (COGS). Per-term scope — never touches a sibling term's images.
@@ -2715,6 +2711,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           message: evt.message,
           recap: recoveryRecap,
           reopen: (carryRecap) => {
+            entry.imageQueue?.close()
             try { entry.mockupWatcher?.close() } catch { /* noop */ }
             sessions.delete(id)
             openStructured({
@@ -2988,10 +2985,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // (live OR replay). Lift it to Storage FIRST, then emit the URL-only event —
       // so the persisted log + replay carry a path, never base64. Order/seq stay
       // intact: pushLog (inside emitTail) is the single seq point, called when the
-      // upload resolves. Other kinds emit synchronously, unchanged.
+      // upload resolves. Later events share the same queue; otherwise a closing
+      // result could overtake its delayed tool_result (BH-DATA-003).
       const imgs = inlineImageBlocks(evt)
-      if (imgs.length) { deferImageEvent(entry, id, evt, imgs, emitTail); return }
-      emitTail(evt)
+      deferImageEvent(entry, id, evt, imgs, emitTail)
     },
     requestPermission: (req) => new Promise((resolve) => {
       // FLOW conductor plan → intercept (no generic card). The plan JSON rides
@@ -3147,6 +3144,7 @@ function acceptEditsPending(s) {
 function respawnStructured(id, provider) {
   const s = sessions.get(id)
   if (!s) return false
+  s.imageQueue?.close()
   // Capture the lane's identity for re-open (NOT resume — fresh SDK session).
   // NOTE the deliberate absence of `model`: a respawn crosses a provider boundary,
   // and the old lane's model id means nothing on the new backend. Carrying it sent
@@ -3210,6 +3208,7 @@ function endStructured(id) {
   if (!id) return
   const s = sessions.get(id)
   if (s) {
+    s.imageQueue?.close()
     drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }
@@ -4565,6 +4564,7 @@ async function shutdown(code = 0, farewell = true) {
   // Flush structured session state synchronously BEFORE ending sessions. saveSession
   // debounces ~1.5s, so without this any events since the last write are lost on exit
   // (Contract #2). writeFileSync, well inside the 1500ms hard-exit backstop above.
+  for (const s of sessions.values()) { try { s.imageQueue?.close() } catch { /* noop */ } }
   for (const s of sessions.values()) { try { s.flush?.() } catch { /* noop */ } }
   for (const t of terms.values()) { try { t.term.kill() } catch { /* noop */ } }
   for (const s of sessions.values()) { try { s.session.end() } catch { /* noop */ } }

package/event-id.mjs

@@ -210,6 +210,237 @@ export function inlineImageBlocks(evt) {
   return out
 }
 
+// One ordered emission boundary for structured-session events while agent screenshots
+// are lifted out of inline base64. This stays import-safe: bridge.mjs owns room/auth
+// state; these definitions own deadlines, bounded reservations, ordering, and teardown.
+export const SCREENSHOT_OMITTED = '[screenshot omitted — upload failed]'
+export const DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS = 15_000
+export const DEFAULT_IMAGE_QUEUE_MAX_PENDING = 4
+export const DEFAULT_IMAGE_QUEUE_MAX_BYTES = 16_000_000
+
+const sanePositiveInt = (value, fallback) => {
+  const n = Number(value)
+  return Number.isSafeInteger(n) && n > 0 ? n : fallback
+}
+
+export function imageQueueConfig(env = process.env) {
+  return {
+    uploadTimeoutMs: sanePositiveInt(env.TP_CODE_IMAGE_UPLOAD_TIMEOUT_MS, DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS),
+    maxPending: sanePositiveInt(env.TP_CODE_IMAGE_QUEUE_MAX_PENDING, DEFAULT_IMAGE_QUEUE_MAX_PENDING),
+    maxBytes: sanePositiveInt(env.TP_CODE_IMAGE_QUEUE_MAX_BYTES, DEFAULT_IMAGE_QUEUE_MAX_BYTES),
+  }
+}
+
+// Deadline covers fetch AND response parsing. Promise.race is deliberate: AbortSignal is
+// still passed to real fetch, but an injected/broken fetch that ignores it cannot pin the
+// ordered queue forever. activeUploads lets session teardown cancel the deadline now.
+export async function uploadCodeImage({
+  webBase,
+  room,
+  authToken,
+  term,
+  cid,
+  image,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS,
+  activeUploads = new Set(),
+}) {
+  const controller = new AbortController()
+  let timer = null
+  let rejectCancel = null
+  let settled = false
+
+  const cancelled = new Promise((_, reject) => { rejectCancel = reject })
+  const handle = {
+    cancel(reason = new Error('code-image upload cancelled')) {
+      if (settled) return
+      if (timer) { clearTimeout(timer); timer = null }
+      try { controller.abort(reason) } catch { /* AbortController is best-effort */ }
+      rejectCancel(reason instanceof Error ? reason : new Error(String(reason)))
+    },
+  }
+  activeUploads.add(handle)
+  timer = setTimeout(() => handle.cancel(new Error(`code-image upload timed out after ${timeoutMs}ms`)), timeoutMs)
+  timer.unref?.()
+
+  const headers = { 'Content-Type': 'application/json' }
+  if (authToken) headers.Authorization = `Bearer ${authToken}`
+  const request = (async () => {
+    const res = await fetchImpl(`${webBase}/api/code-image`, {
+      method: 'POST',
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({ code: room, term, cid, idx: image.idx, mediaType: image.mediaType, b64: image.b64 }),
+    })
+    if (!res.ok) throw new Error(`code-image ${res.status}`)
+    const { path } = await res.json()
+    if (!path) throw new Error('code-image: no path')
+    return path
+  })()
+
+  try {
+    return await Promise.race([request, cancelled])
+  } finally {
+    settled = true
+    if (timer) clearTimeout(timer)
+    activeUploads.delete(handle)
+  }
+}
+
+const encodedImageBytes = (image) => Buffer.byteLength(String(image?.b64 || ''), 'ascii')
+
+function stripRawImages(evt, images, placeholder) {
+  for (const image of images) {
+    const block = Array.isArray(evt?.content) ? evt.content[image.idx] : null
+    if (block?.source?.type === 'base64' || image.b64) {
+      evt.content[image.idx] = { type: 'text', text: placeholder }
+    }
+    image.b64 = ''
+  }
+}
+
+export class ImageEventQueue {
+  constructor({
+    upload,
+    maxPending = DEFAULT_IMAGE_QUEUE_MAX_PENDING,
+    maxBytes = DEFAULT_IMAGE_QUEUE_MAX_BYTES,
+    placeholder = SCREENSHOT_OMITTED,
+    onUploadError = () => {},
+    onOverload = () => {},
+  }) {
+    if (typeof upload !== 'function') throw new TypeError('ImageEventQueue requires upload')
+    this.upload = upload
+    this.maxPending = sanePositiveInt(maxPending, DEFAULT_IMAGE_QUEUE_MAX_PENDING)
+    this.maxBytes = sanePositiveInt(maxBytes, DEFAULT_IMAGE_QUEUE_MAX_BYTES)
+    this.placeholder = placeholder
+    this.onUploadError = onUploadError
+    this.onOverload = onOverload
+    this.pendingCount = 0
+    this.pendingBytes = 0
+    this.peakPendingCount = 0
+    this.peakPendingBytes = 0
+    this.activeUploads = new Set()
+    this.tasks = new Set()
+    this.tail = Promise.resolve()
+    this.closed = false
+    this.overloadNotified = false
+  }
+
+  stats() {
+    return {
+      pendingCount: this.pendingCount,
+      pendingBytes: this.pendingBytes,
+      peakPendingCount: this.peakPendingCount,
+      peakPendingBytes: this.peakPendingBytes,
+      activeUploads: this.activeUploads.size,
+      queuedEvents: this.tasks.size,
+    }
+  }
+
+  enqueue(evt, images, emitTail) {
+    if (this.closed || typeof emitTail !== 'function') return false
+    const imgs = Array.isArray(images) ? images : []
+    const count = imgs.length
+    const bytes = imgs.reduce((sum, image) => sum + encodedImageBytes(image), 0)
+    const accepted = count > 0 &&
+      this.pendingCount + count <= this.maxPending &&
+      this.pendingBytes + bytes <= this.maxBytes
+
+    if (count && accepted) {
+      for (const image of imgs) {
+        image._queueBytes = encodedImageBytes(image)
+        image._queueReserved = true
+      }
+      this.pendingCount += count
+      this.pendingBytes += bytes
+      this.peakPendingCount = Math.max(this.peakPendingCount, this.pendingCount)
+      this.peakPendingBytes = Math.max(this.peakPendingBytes, this.pendingBytes)
+    } else if (count) {
+      // Critical memory boundary: discard raw base64 BEFORE this event can join a
+      // chain blocked behind an earlier upload.
+      stripRawImages(evt, imgs, this.placeholder)
+      if (!this.overloadNotified) {
+        this.overloadNotified = true
+        this.onOverload({ count, bytes, maxPending: this.maxPending, maxBytes: this.maxBytes })
+      }
+    }
+
+    // Preserve the old synchronous fast path when no image upload is ahead of us.
+    if (!accepted && this.tasks.size === 0) {
+      emitTail(evt)
+      return true
+    }
+
+    const task = { evt, images: imgs, emitTail, accepted, emitted: false, done: false }
+    this.tasks.add(task)
+    this.tail = this.tail.catch(() => {}).then(() => this._run(task))
+    return true
+  }
+
+  async _run(task) {
+    if (task.done || this.closed) return
+    try {
+      if (task.accepted) {
+        for (const image of task.images) {
+          if (!image._queueReserved || this.closed) continue
+          try {
+            const path = await this.upload(task.evt, image, this.activeUploads)
+            task.evt.content[image.idx] = { type: 'image', path, mediaType: image.mediaType }
+          } catch (error) {
+            task.evt.content[image.idx] = { type: 'text', text: this.placeholder }
+            if (!this.closed) this.onUploadError(error)
+          } finally {
+            image.b64 = ''
+            this._release(image)
+          }
+        }
+      }
+      if (!this.closed && !task.emitted) {
+        task.emitTail(task.evt)
+        task.emitted = true
+      }
+    } finally {
+      task.done = true
+      this.tasks.delete(task)
+    }
+  }
+
+  _release(image) {
+    if (!image?._queueReserved) return
+    image._queueReserved = false
+    this.pendingCount = Math.max(0, this.pendingCount - 1)
+    this.pendingBytes = Math.max(0, this.pendingBytes - (image._queueBytes || 0))
+    image._queueBytes = 0
+  }
+
+  async idle() {
+    await this.tail.catch(() => {})
+  }
+
+  // Session close/provider switch/shutdown is synchronous. Cancel active deadlines,
+  // replace any still-raw image, and flush queued tails in insertion order before the
+  // owner persists/deletes the entry. Later promise continuations see done/closed.
+  close({ flush = true } = {}) {
+    if (this.closed) return
+    this.closed = true
+    const reason = new Error('code-image queue closed')
+    for (const upload of this.activeUploads) upload.cancel(reason)
+    this.activeUploads.clear()
+    for (const task of this.tasks) {
+      stripRawImages(task.evt, task.images, this.placeholder)
+      for (const image of task.images) this._release(image)
+      if (flush && !task.emitted) {
+        try { task.emitTail(task.evt) } catch { /* teardown must continue */ }
+        task.emitted = true
+      }
+      task.done = true
+    }
+    this.tasks.clear()
+    this.pendingCount = 0
+    this.pendingBytes = 0
+  }
+}
+
 // Pure aggregation for the /usage report — replay a session's retained log events and
 // fold every completed turn (kind:'result' with usage) into per-model + total token/cost
 // sums. No side effects, import-safe (bridge/test-usage-summary.mjs exercises it), so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.245",
+  "version": "0.7.246",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -9,6 +9,8 @@
   "files": [
     "bridge.mjs",
     "sdk-smoke.mjs",
+    "sdk-admission.mjs",
+    "sdk-admission.mjs",
     "launcher.mjs",
     "byok-detect.mjs",
     "context-windows.mjs",

package/sdk-admission.mjs

@@ -0,0 +1,9 @@
+// SDK checks protect agent-serving room processes only. Account/service commands
+// remain available so an operator can inspect or repair a bad SDK installation.
+export function requiresSdkAdmission(argv) {
+  return Boolean(argv?.[0]) && argv[0] !== 'verify-sdk'
+}
+
+export function sdkSmokePassed(output) {
+  return /^SMOKE:PASS:[^:\n]+(?:\n|$)/.test(String(output || ''))
+}

package/session-store.mjs

@@ -11,6 +11,7 @@
 import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
+import { SPAWN } from './cross-terminal.mjs'
 
 // TP_PAIR_ROOT override exists for tests + sandboxes so they never touch the real
 // ~/.thinkpool-pair store. Read LIVE per call (not captured at module load) so a test
@@ -35,9 +36,51 @@ const archiveDir = (room) => path.join(dir(room), '.archive')
 // Only resume the live SDK context for recent sessions — an expired session id
 // fails ("No conversation found"); past this window we restore transcript only.
 const RESUME_MAX_AGE_MS = 12 * 60 * 60 * 1000
-const KEEP = 8   // newest N UNNAMED session files per room (named are immune — see prune)
+// A live snapshot exists precisely so a live structured lane can survive a bridge
+// restart. Keep every lane the bridge can admit. Explicitly closed lanes move to
+// .archive/, so closed/history retention stays separate from this live set.
+export const LIVE_SESSION_MAX = SPAWN.machineMax
 
-function ensureDir(room) { try { fs.mkdirSync(dir(room), { recursive: true }) } catch { /* noop */ } }
+function ensureDir(room) { fs.mkdirSync(dir(room), { recursive: true }) }
+
+// Commit a replacement through a sibling file so a restart never observes a torn
+// final record. The temp file is fsynced before the same-directory rename: readers
+// see the complete previous value or the complete replacement, never a half-write.
+// This is shared by session JSON plus the restart-critical names and PTY metadata.
+let tempSerial = 0
+let beforeAtomicRenameForTest = null
+function atomicCommit(file, contents) {
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp.${process.pid}.${Date.now()}.${tempSerial++}`)
+  let fd = null
+  try {
+    fd = fs.openSync(tmp, 'wx', 0o600)
+    // fs.writeSync may legally write fewer bytes than requested. Never fsync and
+    // promote a partial temp file over the last good snapshot.
+    const bytes = Buffer.from(contents)
+    for (let offset = 0; offset < bytes.length;) {
+      const written = fs.writeSync(fd, bytes, offset, bytes.length - offset)
+      if (written <= 0) throw new Error(`short write while committing ${file}`)
+      offset += written
+    }
+    fs.fsyncSync(fd)
+    fs.closeSync(fd); fd = null
+    beforeAtomicRenameForTest?.({ file, tmp })
+    fs.renameSync(tmp, file)
+    return true
+  } catch (error) {
+    try { if (fd != null) fs.closeSync(fd) } catch { /* best effort */ }
+    try { fs.rmSync(tmp, { force: true }) } catch { /* best effort */ }
+    throw error
+  }
+}
+// Direct persistence tests inject a crash-equivalent immediately before rename.
+// Production never configures this hook.
+export function setAtomicCommitHookForTest(hook) {
+  beforeAtomicRenameForTest = typeof hook === 'function' ? hook : null
+}
+function persistenceError(action, file, error) {
+  console.error(`[thinkpool-pair session-store] ${action} failed for ${file}: ${error?.message || error}`)
+}
 // Move a session file into <room>/.archive/ instead of unlinking it. Archived files
 // are OUTSIDE the readdirSync(dir) path loadAll/listRecs read, so a bridge restart
 // never resurrects them — but they survive on disk for manual recovery. This is the
@@ -50,7 +93,11 @@ function archive(room, file) {
     const base = path.basename(file)
     const dst = path.join(archiveDir(room), `${base}.${Date.now()}`)
     fs.renameSync(file, dst)
-  } catch { /* noop */ }
+    return true
+  } catch (error) {
+    persistenceError('archive session snapshot', file, error)
+    return false
+  }
 }
 function listRecs(room) {
   try {
@@ -65,7 +112,12 @@ function listRecs(room) {
           // truncated log's first event ts drifts far from real creation. Load-time only.
           try { const s = fs.statSync(p); r._bt = s.birthtimeMs || s.mtimeMs || 0 } catch { r._bt = 0 }
           return r
-        } catch { return null }
+        } catch (error) {
+          // Keep the damaged file in place for recovery; never silently make a
+          // restart look like a deliberately closed lane.
+          persistenceError('parse session snapshot', p, error)
+          return null
+        }
       })
       .filter(Boolean)
   } catch { return [] }
@@ -80,8 +132,8 @@ function prune(room) {
     // Only UNNAMED sessions are eligible for prune. A named terminal is deliberate
     // user intent (a project) and must never be silently destroyed by churn.
     const prunable = files.filter((x) => { const id = namedId(x.p); return !id || !names[id] })
-    prunable.slice(KEEP).forEach((x) => archive(room, x.p))
-  } catch { /* noop */ }
+    prunable.slice(LIVE_SESSION_MAX).forEach((x) => archive(room, x.p))
+  } catch (error) { persistenceError('prune live session snapshots', dir(room), error) }
 }
 
 // ── Durable append-only event log (unbounded history; the <id>.json snapshot is
@@ -210,14 +262,23 @@ export function readDurablePage(room, id, beforeSeq, limit = 200) {
 
 const timers = new Map()
 function write(room, id, data) {
-  try { ensureDir(room); fs.writeFileSync(path.join(dir(room), `${id}.json`), JSON.stringify({ ...data, id, savedAt: Date.now() })); prune(room) } catch { /* noop */ }
+  const file = path.join(dir(room), `${id}.json`)
+  try {
+    ensureDir(room)
+    atomicCommit(file, JSON.stringify({ ...data, id, savedAt: Date.now() }))
+    prune(room)
+    return true
+  } catch (error) {
+    persistenceError('write session snapshot', file, error)
+    return false
+  }
 }
 // Debounced — events arrive in bursts; one write per ~1.5s is plenty.
 export function saveSession(room, id, data) {
   clearTimeout(timers.get(id))
   timers.set(id, setTimeout(() => write(room, id, data), 1500))
 }
-export function flushSession(room, id, data) { clearTimeout(timers.get(id)); write(room, id, data) }
+export function flushSession(room, id, data) { clearTimeout(timers.get(id)); return write(room, id, data) }
 // User-initiated close: cancel any pending debounced save and move the on-disk
 // record to .archive/ so a later loadAll() (bridge restart) can't resurrect a
 // closed terminal — but the transcript stays recoverable. PTY ids never have an
@@ -225,7 +286,8 @@ export function flushSession(room, id, data) { clearTimeout(timers.get(id)); wri
 export function deleteSession(room, id) {
   clearTimeout(timers.get(id)); timers.delete(id)
   const p = path.join(dir(room), `${id}.json`)
-  try { if (fs.existsSync(p)) archive(room, p) } catch { /* noop */ }
+  try { return !fs.existsSync(p) || archive(room, p) }
+  catch (error) { persistenceError('archive closed session snapshot', p, error); return false }
 }
 
 // Most-recently-saved structured session for the room (drives attached restore).
@@ -240,7 +302,7 @@ export function canResume(rec) {
 // EVERY saved session for the room, oldest→newest (so tabs reappear in order).
 // Drives resume-ALL on a bridge restart — without this only the latest session
 // came back and every backgrounded terminal died on restart despite its state
-// sitting on disk. Bounded by KEEP (prune keeps the newest 8).
+// sitting on disk. Bounded by LIVE_SESSION_MAX, exactly the admission capacity.
 export function loadAll(room) {
   return listRecs(room).sort((a, b) => (a.savedAt || 0) - (b.savedAt || 0))
 }
@@ -254,7 +316,9 @@ export function loadPtyId(room) {
   try { return fs.readFileSync(ptyFile(room), 'utf8').trim() || null } catch { return null }
 }
 export function savePtyId(room, id) {
-  try { ensureDir(room); fs.writeFileSync(ptyFile(room), String(id)) } catch { /* noop */ }
+  const file = ptyFile(room)
+  try { ensureDir(room); atomicCommit(file, String(id)); return true }
+  catch (error) { persistenceError('write PTY id', file, error); return false }
 }
 
 // Per-room terminal display names (terminal id -> label), set via the web's
@@ -265,8 +329,15 @@ export function savePtyId(room, id) {
 // (NOT *.json) so it never lands in listRecs/loadAll.
 const namesFile = (room) => path.join(dir(room), '.names')
 export function loadNames(room) {
-  try { return JSON.parse(fs.readFileSync(namesFile(room), 'utf8')) || {} } catch { return {} }
+  const file = namesFile(room)
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) || {} }
+  catch (error) {
+    if (error?.code !== 'ENOENT') persistenceError('parse terminal names', file, error)
+    return {}
+  }
 }
 export function saveNames(room, names) {
-  try { ensureDir(room); fs.writeFileSync(namesFile(room), JSON.stringify(names || {})) } catch { /* noop */ }
+  const file = namesFile(room)
+  try { ensureDir(room); atomicCommit(file, JSON.stringify(names || {})); return true }
+  catch (error) { persistenceError('write terminal names', file, error); return false }
 }