thinkpool-pair 0.7.289 → 0.7.291

package/bridge.mjs

@@ -76,7 +76,7 @@ import { writeLaneArtifact, digestSlice, appendDigest, resumeLane } from './flow
 import { createFlowWorktree, worktreeSpec } from './flow-worktree.mjs'
 import { startPreview, stopAllPreviews, previews } from './flow-preview.mjs'
 import { ViewportManager, createViewportTools, sharedViewportBrowser } from './viewport.mjs'
-import { deleteDesignAssetDraft, designPrompt, designTranscript, materializeDesignAsset, resolveDesignSource, resolveManifestDesignSource, restoreDesignSources, syncRealtimeAuth, validateDesignBatchRequest } from './design-edit.mjs'
+import { deleteDesignAssetDraft, designPrompt, designTranscript, materializeDesignAsset, refreshDesignSource, resolveManifestDesignSource, restoreDesignSources, syncRealtimeAuth, validateDesignBatchRequest } from './design-edit.mjs'
 // FL-M9 — per-lane preview servers leak (one per done lane, never stopped until shutdown).
 // Lane previews are keyed `lane:<flowId>:<laneId>`; stop a whole flow's set when it assembles
 // (the assembled preview supersedes them) or when a lane is reverted.
@@ -120,6 +120,7 @@ import { supersedeDispatchLease } from './dispatch-lease.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, ImageEventQueue, imageQueueConfig, uploadCodeImage as uploadCodeImageRequest, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
+import { createLatestReplayPump, requestedReplayIds } from './replay-transport.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'
@@ -574,6 +575,7 @@ if (process.stdin.isTTY && !headless && process.env.THINKPOOL_PAIR_AUTOUPDATE !=
 }
 const name = process.env.TP_NAME || os.userInfo().username || 'host'
 const BRIDGE_ID = (randomUUID?.().slice(0,8)) || 'bridgexx'
+const BRIDGE_STARTED_AT = Date.now()
 // host: this machine's short label — os.hostname() with any DNS/domain suffix
 // stripped and capped ~24 chars. A /code room can be served by different bridges
 // over time (Max's Mac vs Conrad's Linux box); the client uses this to show WHICH
@@ -957,6 +959,13 @@ function beginStructuredTurn(entry, now = Date.now()) {
   return true
 }
 
+function advanceStructuredTurn(entry, now = Date.now()) {
+  entry._turnRev = (Number(entry._turnRev) || 0) + 1
+  entry._turnStart = now
+  entry._busyAnn = true
+  return true
+}
+
 function stampStructuredTurn(entry, event) {
   if (event && event.turnRev == null && Number(entry?._turnRev) > 0) event.turnRev = entry._turnRev
   return event
@@ -1064,17 +1073,21 @@ const defendFrame = (event, payload) => {
   return p
 }
 
-const bcast = (event, payload, ch = channel) => {
+const bcastAwait = async (event, payload, ch = channel) => {
   if (event === 'pty-out' || event === 'code-event') lastActivity = Date.now()
   payload = defendFrame(event, payload)
   try {
     if (ch.channelAdapter?.canPush?.() ?? true) {
-      ch.send({ type: 'broadcast', event, payload })
+      return await ch.send({ type: 'broadcast', event, payload })
     } else {
-      ch.httpSend(event, payload).catch(() => { /* offline — replay covers it */ })
+      return await ch.httpSend(event, payload)
     }
-  } catch { /* noop */ }
+  } catch { return null /* offline — replay covers it */ }
 }
+const bcast = (event, payload, ch = channel) => { void bcastAwait(event, payload, ch) }
+const replayPump = createLatestReplayPump({
+  send: ({ event, payload }) => bcastAwait(event, payload),
+})
 
 // Per-room terminal display names (id -> label), set by the web's `term-rename`.
 // Persisted on the host so a rename is cross-device + survives a bridge restart;
@@ -1093,7 +1106,7 @@ const announce = () => {
   const provNames = providerNameMap()
   const rev = ++announceRev
   return bcast('bridge', {
-    v: 2, name, bridge_id: BRIDGE_ID, rev, repo: repoLabel, branch: readBranch(),
+    v: 2, name, bridge_id: BRIDGE_ID, started_at: BRIDGE_STARTED_AT, rev, repo: repoLabel, branch: readBranch(),
     // sdkWarn: the auto-pulled agent SDK failed its boot compatibility smoke test —
     // surfaced so the room can show a banner (turns may misbehave; pin a good SDK).
     ...(sdkStatus.ok === false ? { sdkWarn: `${sdkStatus.version}: ${sdkStatus.reason}` } : {}),
@@ -1415,7 +1428,7 @@ const finishDesign = (term, state, extra = {}) => {
 const maybeVerifyDesign = (term) => {
   const active = designActive.get(term)
   if (!active?.resultOk || !active.proof) return
-  finishDesign(term, 'verified-live', { message: 'Verified at desktop and mobile.', artifact: active.proof, canRestore: true })
+  finishDesign(term, 'verified-live', { message: 'Verified at desktop and mobile.', artifact: active.proof, canRestore: active.record.sourceKind !== 'preview' })
 }
 
 function pumpDesign(term) {
@@ -1433,7 +1446,7 @@ function pumpDesign(term) {
   if (lane.session?.turnActive) return
   queue.shift()
   const current = designArtifacts.get(next.record.previewId)
-  const live = current && resolveDesignSource(current.sourcePath, current.workspaceRoot)
+  const live = current && refreshDesignSource(current)
   if (!current || !live || live.revision !== next.record.revision) {
     designStatus({ previewId: next.record.previewId, requestId: next.request.cid, state: 'stale', message: 'The artifact changed. Reselect the element.' })
     return pumpDesign(term)
@@ -1488,7 +1501,7 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
   if (!m?.slug) return
   const producer = trustedDesignSource ? sessions.get(term) : null
   const designRecord = producer
-    ? resolveManifestDesignSource(m, producer.cwd || process.cwd())
+    ? resolveManifestDesignSource(m, producer.cwd || process.cwd(), { box })
     : null
   // 2026-07-07: these used to swallow read errors silently — a transient
   // unreadable file (race with the render script, permissions, mid-write)
@@ -1542,8 +1555,11 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
       const dual = !!(paths?.html && paths?.desktop && paths?.mobile && m.desktop && m.mobile)
       const expectedRevision = active?.restoreRecord?.revision
       const revisionProvesChange = expectedRevision ? designRecord.revision === expectedRevision : designRecord.revision !== active?.record?.revision
-      if (correlated && dual && designRecord.sourcePath === active.record.sourcePath && revisionProvesChange) {
-        designRestore.set(designRecord.previewId, { priorRecord: active.record, request: active.request })
+      const sameTarget = active?.record?.sourceKind === 'preview'
+        ? designRecord.sourceKind === 'preview' && designRecord.captureKey === active.record.captureKey
+        : designRecord.sourcePath === active?.record?.sourcePath
+      if (correlated && dual && sameTarget && revisionProvesChange) {
+        if (active.record.sourceKind !== 'preview') designRestore.set(designRecord.previewId, { priorRecord: active.record, request: active.request })
         active.proof = artifact
         maybeVerifyDesign(term)
       }
@@ -2126,7 +2142,14 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   if (restoredDesigns.length) process.stderr.write(`\n  ◆ restored ${restoredDesigns.length} Thinkpool Design artifact${restoredDesigns.length === 1 ? '' : 's'} (${id.slice(0, 8)}).\n`)
   // Visual QA runs in the bridge process, outside either agent runtime's sandbox.
   // It remains scoped to this lane's cwd and private mockup outbox.
-  entry.viewport = new ViewportManager({ workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox })
+  entry.viewport = new ViewportManager({
+    workspaceRoot: cwd || process.cwd(), ownerId: id, outbox: mockupOutbox,
+    designContext: () => {
+      const active = designActive.get(id)
+      if (!active || active.record.sourceKind !== 'preview') return null
+      return { requestId: active.request.cid, parentRevision: active.record.revision, captureKey: active.record.captureKey }
+    },
+  })
   if (entry.log.length) process.stderr.write(`\n  ◆ restored ${entry.log.length} prior events (${id.slice(0, 8)})${resume ? ' + resuming live context' : ''}.\n`)
   // Persist the permission mode alongside the transcript so a bridge restart
   // restores the session in the SAME mode (a bypass room stays bypass on resume).
@@ -2866,6 +2889,20 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // per-machine default (provider.mjs/applyProviderEnv). null for built-in/unknown → the
     // default Claude env is left exactly as-is (unchanged path).
     env: { ...process.env, ...buildConductorEnv({ flowSessionId, mode }), ...(resolveProviderEnv(provider) || {}), TP_MOCKUP_OUTBOX: mockupOutbox },
+    onTurnStart: (options = {}) => {
+      // Hermes promotes /queue items internally, without a second code-turn.
+      // Advance the lifecycle before its first output and publish the deferred
+      // human line under the new turn revision, keeping all viewers converged.
+      if (entry._busyAnn === true) advanceStructuredTurn(entry)
+      else beginStructuredTurn(entry)
+      const queuedEcho = options._thinkpoolQueuedEcho
+      if (queuedEcho) {
+        const evt = { kind: 'you', ...queuedEcho }
+        pushLog(entry, evt)
+        bcast('code-event', { term: id, evt })
+      }
+      announce()
+    },
     onEvent: (evt) => {
       if (!classifyCodeEvent(evt).known) {
         // Never archive or replay an unknown provider payload as a known fact. Do
@@ -2923,7 +2960,9 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // replay-union dedupes ONLY by cid, and SDK events carry none — without an
       // id, an event that arrives both live AND in a reconnect replay renders
       // twice (the 2026-06-19 duplicate-message bug). See event-id.mjs.
-      const busyChanged = syncStructuredTurn(entry)
+      const continuesQueued = runtime === 'hermes' && (evt.kind === 'result' || evt.kind === 'error') && (entry.session?.queuedDepth || 0) > 0
+      if (continuesQueued) evt.continuesQueued = true
+      const busyChanged = continuesQueued ? false : syncStructuredTurn(entry)
       stampStructuredTurn(entry, evt)
       stampEvent(evt)
       const stalledChanged = evt.kind === 'stalled' ? !entry.stalled : !!entry.stalled
@@ -3641,14 +3680,17 @@ channel
     // Flush pending bytes first so the replay is complete up to "now"; both
     // ride the same ordered socket, so the client sees replay-then-live.
     flushAll()
-    for (const [id, t] of terms) {
+    const to = payload?.to ?? null
+    const requestId = String(payload?.requestId || randomUUID?.() || `${Date.now()}`)
+    const frames = []
+    for (const [id, t] of requestedReplayIds(terms, payload?.terms, payload?.priority)) {
       if (!t.scrollback) continue
       // Cap scrollback too — a huge PTY buffer would blow the same frame limit.
       const sb = t.scrollback.length > 100000 ? t.scrollback.slice(-100000) : t.scrollback
-      bcast('pty-replay', {
-        to: payload?.to ?? null, term: id,
+      frames.push({ event: 'pty-replay', payload: {
+        to, term: id, requestId,
         b64: Buffer.from(sb, 'utf8').toString('base64'),
-      })
+      } })
     }
     // Structured sessions replay their event log (reader rebuilds from it).
     // C1 (RT-2): send only the tail past the client's per-term cursor (seqHi) when
@@ -3659,14 +3701,13 @@ channel
     // cursor) still gets the full log.
     // Hydrate the viewed lane first. Other terminals still warm in the background,
     // but cannot queue ahead of the transcript the person is waiting to see.
-    const replaySessions = [...sessions.entries()].sort(([a], [b]) =>
-      a === payload?.priority ? -1 : b === payload?.priority ? 1 : 0)
+    const replaySessions = requestedReplayIds(sessions, payload?.terms, payload?.priority)
     for (const [id, s] of replaySessions) {
       // An explicit empty replay is an acknowledgement, not data. It lets mixed
       // clients clear their loading cover even if they missed the announce's
       // hasTranscript:false state.
       if (!s.log.length) {
-        bcast('code-replay', { to: payload?.to ?? null, term: id, events: [], empty: true })
+        frames.push({ event: 'code-replay', payload: { to, term: id, requestId, chunkIndex: 0, chunkCount: 1, events: [], empty: true } })
         continue
       }
       const from = Number(payload?.cursors?.[id]) || 0
@@ -3706,10 +3747,14 @@ channel
       // trimmedBefore rides the FIRST (oldest) chunk only — the later chunks are contiguous
       // with it, so a stamp there would read as a second, phantom gap. Same rule as
       // lastUsage above and hasMore on history-page below.
-      let firstChunk = true
-      for (const events of chunks) {
-        bcast('code-replay', { to: payload?.to ?? null, term: id, events, ...(ahead ? { reset: true } : {}), ...(firstChunk && trimmedBefore != null ? { trimmedBefore } : {}), ...(firstChunk && s.lastUsage?.ctx ? { lastUsage: s.lastUsage } : {}) })
-        firstChunk = false
+      for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+        const events = chunks[chunkIndex]
+        frames.push({ event: 'code-replay', payload: {
+          to, term: id, requestId, chunkIndex, chunkCount: chunks.length, events,
+          ...(ahead ? { reset: true } : {}),
+          ...(chunkIndex === 0 && trimmedBefore != null ? { trimmedBefore } : {}),
+          ...(chunkIndex === 0 && s.lastUsage?.ctx ? { lastUsage: s.lastUsage } : {}),
+        } })
       }
     }
     // Re-send any still-pending permission/question cards. They ride a one-shot
@@ -3718,10 +3763,15 @@ channel
     // (unanswered) tool row — the AskUserQuestion "vanished on reconnect" bug. Only
     // truly-unresolved cards remain in `pending` (resolved ones are deleted), and
     // the client dedupes code-perm-req by id, so this can't resurrect an answered one.
-    for (const [, s] of sessions) {
-      for (const [, p] of s.pending) bcast('code-perm-req', p.payload)
-    }
-    announce()
+    // One awaited frame per event-loop turn. A newer request from this viewer
+    // replaces every unsent frame from the older one, so visibility/online races
+    // cannot multiply a cold replay into several concurrent megabyte bursts.
+    replayPump.enqueue(to || '*', frames, async () => {
+      for (const [, s] of sessions) {
+        for (const [, p] of s.pending) await bcastAwait('code-perm-req', p.payload)
+      }
+      announce()
+    })
   })
   // "Load earlier history": serve an OLDER page from the durable JSONL archive (the
   // events the in-memory 2000-cap evicted). beforeSeq anchors the page at the client's
@@ -3740,11 +3790,12 @@ channel
     if (!servesHistoryPage({ payloadHost: payload?.host, bridgeName: name, hasSession: sessions.has(id), hasArchive: hasDurableArchive(room, id) })) return
     const { events, hasMore } = readDurablePage(room, id, Number(payload?.beforeSeq) || null, 200)
     const to = payload?.to ?? null
-    if (!events.length) { bcast('history-page', { to, term: id, events: [], hasMore: false }); return }
+    const requestId = String(payload?.requestId || randomUUID?.() || `${Date.now()}`)
+    if (!events.length) { bcast('history-page', { to, term: id, requestId, chunkIndex: 0, chunkCount: 1, events: [], hasMore: false }); return }
     const chunks = chunkReplayEvents(events.map((e) => boundEventForBroadcast(e)))
     // hasMore rides only the FIRST (oldest) chunk so the client sets the floor flag once
     // from the true page boundary; later chunks are just more of the same page.
-    chunks.forEach((evs, i) => bcast('history-page', { to, term: id, events: evs, hasMore: i === 0 ? hasMore : true }))
+    chunks.forEach((evs, i) => bcast('history-page', { to, term: id, requestId, chunkIndex: i, chunkCount: chunks.length, events: evs, hasMore: i === 0 ? hasMore : true }))
   })
   .on('broadcast', { event: 'file-put' }, ({ payload }) => {
     if (!payload?.id || !payload?.url) return
@@ -4020,13 +4071,24 @@ channel
     const nativeImages = s.runtime === 'codex' || s.runtime === 'hermes'
       ? await waitForNativeImages(payload.files, { updir: UPDIR })
       : []
+    const deferHermesQueueEcho = s.runtime === 'hermes' && s.session.turnActive && /^\s*\/queue\s+/i.test(text)
+    const turnOptions = {
+      ...(nativeImages.length ? { images: nativeImages } : {}),
+      ...(deferHermesQueueEcho && !payload.silent ? { _thinkpoolQueuedEcho: {
+        text: payload.body != null ? String(payload.body) : text,
+        cid: payload.cid,
+        by: payload.by,
+        ...(Array.isArray(payload.files) && payload.files.length ? { files: payload.files } : {}),
+        ...(Array.isArray(payload.pastes) && payload.pastes.length ? { pastes: payload.pastes } : {}),
+      } } : {}),
+    }
     // Sample the runtime before dispatch so a missed prior falling edge cannot
     // make this genuinely new turn inherit the previous turn's revision.
     syncStructuredTurn(s)
-    const accepted = s.session.sendTurn(sendText, nativeImages.length ? { images: nativeImages } : undefined)
+    const accepted = s.session.sendTurn(sendText, Object.keys(turnOptions).length ? turnOptions : undefined)
     if (accepted === false) syncStructuredTurn(s)
     else beginStructuredTurn(s)
-    echoYou()
+    if (!deferHermesQueueEcho || accepted === false) echoYou()
     if (accepted === false) {
       // A runtime that did not accept a turn must still close the optimistic
       // user-line lifecycle. Without this boundary the client truthfully shows
@@ -4302,7 +4364,7 @@ channel
   .subscribe(async status => {
     if (status === 'SUBSCRIBED') {
       realtimeHealthy = true; brokenSince = 0
-      trackPresence({ name, role: 'bridge', bridge_id: BRIDGE_ID })
+      trackPresence({ name, role: 'bridge', bridge_id: BRIDGE_ID, started_at: BRIDGE_STARTED_AT })
       const startCmd = attachedCmd || autoAgent   // autoAgent: account-mode auto-open (headless)
       if (startCmd && !terms.size && !sessions.size) {
         // Claude + structured mode → Agent SDK session; everything else → PTY.
@@ -4704,7 +4766,7 @@ const seenDesignRequests = new Set()
 designChannel
   .on('broadcast', { event: 'design-capability' }, ({ payload }) => {
     const record = payload?.previewId && designArtifacts.get(String(payload.previewId))
-    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    const live = record && refreshDesignSource(record)
     const ok = !!record && !!live && live.revision === record.revision && record.revision === payload?.revision && sessions.has(record.term)
     designChannel.send({ type: 'broadcast', event: 'design-capability-res', payload: { previewId: String(payload?.previewId || ''), revision: String(payload?.revision || ''), ok } })
   })
@@ -4759,7 +4821,7 @@ designChannel
     const requestId = String(payload?.cid || '').slice(0, 80)
     const record = designArtifacts.get(previewId)
     const restore = designRestore.get(previewId)
-    const live = record && resolveDesignSource(record.sourcePath, record.workspaceRoot)
+    const live = record && refreshDesignSource(record)
     if (!requestId || !record || !restore?.priorRecord?.backupPath || !live || live.revision !== record.revision || payload?.revision !== record.revision) {
       designStatus({ previewId, requestId, state: 'stale', message: 'That verified revision can no longer be restored safely.' })
       return

package/design-edit.mjs

@@ -50,15 +50,49 @@ export function resolveDesignSource(file, workspaceRoot) {
   return { previewId, revision, sourcePath, workspaceRoot: root, source }
 }
 
+export function resolvePreviewDesignSource(manifest, workspaceRoot, box) {
+  if (!manifest || manifest.sourceKind !== 'preview' || !manifest.snapshot || !workspaceRoot || !box) return null
+  let sourcePath, root, outbox
+  try {
+    sourcePath = fs.realpathSync(manifest.snapshot)
+    root = fs.realpathSync(workspaceRoot)
+    outbox = fs.realpathSync(box)
+    const stat = fs.statSync(sourcePath)
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) return null
+  } catch { return null }
+  const rel = path.relative(outbox, sourcePath)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || path.extname(sourcePath).toLowerCase() !== '.html') return null
+  const route = clean(manifest.route || '/', 500)
+  const previewRoot = clean(manifest.previewRoot || 'dist', 500)
+  const captureKey = clean(manifest.captureKey, 1000)
+  if (!route.startsWith('/') || !captureKey || captureKey !== JSON.stringify([previewRoot, route])) return null
+  const source = fs.readFileSync(sourcePath, 'utf8')
+  const revision = sourceRevision(source)
+  const previewId = crypto.createHash('sha256')
+    .update(`${root}\0${captureKey}\0${revision}`)
+    .digest('base64url').slice(0, 32)
+  return { sourceKind: 'preview', previewId, revision, sourcePath, workspaceRoot: root, source, outbox, route, previewRoot, captureKey }
+}
+
 // Older lane worktrees predate the explicit `source` manifest field and emit the
 // authored mockup path as `html` only. Preserve the explicit field when present;
 // otherwise let the same containment/generated-output checks decide whether the
 // HTML path is canonical editable source or view-only render evidence.
-export function resolveManifestDesignSource(manifest, workspaceRoot) {
+export function resolveManifestDesignSource(manifest, workspaceRoot, { box } = {}) {
   if (!manifest || typeof manifest !== 'object') return null
+  if (manifest.sourceKind === 'preview') return resolvePreviewDesignSource(manifest, workspaceRoot, box)
   return resolveDesignSource(manifest.source || manifest.html, workspaceRoot)
 }
 
+export function refreshDesignSource(record) {
+  if (!record) return null
+  if (record.sourceKind !== 'preview') return resolveDesignSource(record.sourcePath, record.workspaceRoot)
+  return resolvePreviewDesignSource({
+    sourceKind: 'preview', snapshot: record.sourcePath, route: record.route,
+    previewRoot: record.previewRoot, captureKey: record.captureKey,
+  }, record.workspaceRoot, record.outbox)
+}
+
 // Design provenance is intentionally host-only, but it must survive a bridge
 // restart. Rebuild the in-memory registry from manifests already written by the
 // trusted lane render workflow; do not re-upload or re-broadcast old cards.
@@ -79,7 +113,7 @@ export function restoreDesignSources(box, workspaceRoot, term, limit = 100) {
   for (const { file } of files) {
     try {
       const manifest = JSON.parse(fs.readFileSync(file, 'utf8'))
-      const record = resolveManifestDesignSource(manifest, workspaceRoot)
+      const record = resolveManifestDesignSource(manifest, workspaceRoot, { box })
       if (!record) continue
       Object.assign(record, {
         term,
@@ -256,5 +290,8 @@ export function designPrompt({ record, request, by, restore = false, priorRecord
     : batch
       ? batch.map((edit, index) => `Edit ${index + 1} of ${batch.length} · ${edit.mode}\nSelected element:\n${JSON.stringify(edit.target, null, 2)}\n\n${designAction(edit)}`).join('\n\n---\n\n')
       : `Selected element:\n${JSON.stringify(request.target, null, 2)}\n\n${designAction(request)}`
+  if (record.sourceKind === 'preview') {
+    return `A room member used ThinkPool Design Mode on a rendered application preview. This is an authorized source edit in your current workspace.\n\nRendered snapshot (read-only evidence): ${record.sourcePath}\nApplication workspace: ${record.workspaceRoot}\nPreview root: ${record.previewRoot}\nPreview route: ${record.route}\nExpected snapshot revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the rendered snapshot and confirm the selected element still matches before editing.\n- Do not edit the snapshot. Locate the represented element in the application source inside the workspace and make the smallest source change that produces the requested result.\n- If the selector, text, or surrounding structure does not identify one application source location unambiguously, stop without editing and explain that the person must reselect it.\n${batch ? '- Apply the queued edits in order in one source pass, then build and capture once after the full batch.' : '- Apply only the requested change, then build and capture once.'}\n- Preserve the product page faithfully: keep its real copy, structure, fonts, assets, spacing, responsive behavior, and unrelated source unchanged.\n- Run the project build, then use preview_start with root ${record.previewRoot} and preview_capture with path ${record.route}, both viewports, and title ${JSON.stringify(record.title || record.slug || 'Design preview')}. The bridge correlates that capture to this request.\n- Do not claim the edit is verified until the room receives the new desktop and mobile capture.\n- If the build or capture fails, report the failure instead of substituting a screenshot-only result.`
+  }
   return `A room member used ThinkPool Design Mode on the artifact below. This is an authorized source edit in your current workspace.\n\nArtifact source: ${record.sourcePath}\nWorkspace: ${record.workspaceRoot}\nExpected source revision: ${record.revision}\nRequested by: ${clean(by || 'A room member', 120)}\nOperation: ${restore ? 'restore the immediately previous verified Design Mode revision' : batch ? `${batch.length} queued edits in one batch` : request.mode}\n\n${work}\n\nRules:\n- Re-read the exact artifact source and confirm its revision/content still matches every selected element before editing.\n${batch ? '- Apply the queued edits in order in one source pass, then render once after the full batch.' : '- Apply only the requested change, then render the result once.'}\n- Edit the canonical source above; do not search for or edit a different plausible file.\n- Preserve the represented product page faithfully: keep its real copy, structure, fonts, assets, spacing, and responsive behavior except for the selected edits. Never replace it with generic mockup content.\n- Preserve unrelated content and styling.\n- Use the existing mockup render workflow to produce both desktop and mobile captures after the edit. Run it with TP_DESIGN_REQUEST_ID=${request.cid} and TP_DESIGN_PARENT_REVISION=${record.revision} in the command environment so the proof correlates to this request.\n- Do not claim this is live until both captures succeed and the room receives the manifest.\n- If any target is stale or ambiguous, stop without editing and explain that the person must reselect it.`
 }

package/hermes-session.mjs

@@ -68,7 +68,7 @@ export function startHermesSession({
   command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
   mcpHttpFactory = startCodexMcpHttp, lazy = false, hermesRole = null,
   crossPostGate = null, didSpawnTarget = null, crossRoomPostGate = null, effort = 'high',
-  admitStart = null,
+  admitStart = null, onTurnStart = null,
 } = {}) {
   let activeCwd = cwd
   const requestedModel = model || null
@@ -503,6 +503,7 @@ export function startHermesSession({
         const next = queuedTurns.shift()
         const turnId = ++activeTurnId
         turnActive = true
+        try { onTurnStart?.(next.options || {}) } catch { /* observer cannot break the FIFO */ }
         try { await runPrompt(next.text, next.options, { steering: false, turnId, promptIndex: next.promptIndex, forceFull: next.forceFull }) }
         catch (error) { turnActive = false; emit({ kind: 'error', message: `Hermes queued turn failed: ${error?.message || error}`, recoverable: true }) }
       }
@@ -514,6 +515,7 @@ export function startHermesSession({
   return {
     get sessionId() { return sessionId },
     get turnActive() { return turnActive },
+    get queuedDepth() { return queuedTurns.length },
     get canSteer() { return !!client?.alive },
     get started() { return started },
     get models() { return [] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.289",
+  "version": "0.7.291",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -49,6 +49,7 @@
     "pair-control-authority.mjs",
     "event-id.mjs",
     "event-bounds.mjs",
+    "replay-transport.mjs",
     "plan-meters.mjs",
     "recap.mjs",
     "transcript-sanitize.mjs",

package/replay-transport.mjs

@@ -0,0 +1,64 @@
+// Replay transport policy. Reconnects are allowed to supersede older work for
+// the same viewer, and frames are deliberately paced so live events and Stop /
+// permission traffic are not trapped behind a multi-megabyte replay burst.
+
+export function requestedReplayIds(entries, terms, priority) {
+  const requested = Array.isArray(terms) ? new Set(terms.filter(Boolean)) : null
+  return [...entries]
+    .filter(([id]) => !requested || requested.has(id))
+    .sort(([a], [b]) => a === priority ? -1 : b === priority ? 1 : 0)
+}
+
+const defaultYield = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+export function createLatestReplayPump({ send, yieldTurn = defaultYield } = {}) {
+  if (typeof send !== 'function') throw new TypeError('replay pump requires send(frame)')
+  const viewers = new Map()
+
+  const run = async (viewer, state) => {
+    if (state.running) return
+    state.running = true
+    try {
+      while (state.frames.length) {
+        const generation = state.generation
+        const frame = state.frames.shift()
+        await send(frame)
+        await yieldTurn()
+        // enqueue() replaces the remaining frames. The send already in flight is
+        // allowed to finish; nothing older can start after the replacement.
+        if (generation !== state.generation) continue
+      }
+      const done = state.onDone
+      state.onDone = null
+      if (done) await done()
+    } finally {
+      state.running = false
+      if (state.frames.length) void run(viewer, state)
+      else if (viewers.get(viewer) === state) viewers.delete(viewer)
+    }
+  }
+
+  return {
+    enqueue(viewer, frames, onDone = null) {
+      const key = String(viewer || '*')
+      const state = viewers.get(key) || { generation: 0, frames: [], onDone: null, running: false }
+      state.generation += 1
+      state.frames = Array.isArray(frames) ? [...frames] : []
+      state.onDone = typeof onDone === 'function' ? onDone : null
+      viewers.set(key, state)
+      void run(key, state)
+      return state.generation
+    },
+    cancel(viewer) {
+      const state = viewers.get(String(viewer || '*'))
+      if (!state) return false
+      state.generation += 1
+      state.frames = []
+      state.onDone = null
+      return true
+    },
+    pending(viewer) {
+      return viewers.get(String(viewer || '*'))?.frames.length || 0
+    },
+  }
+}

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 8,
+  "bundleVersion": 9,
   "contracts": [
     {
       "id": "room-coordination",
@@ -168,9 +168,9 @@
     },
     {
       "id": "design-workspace",
-      "version": 3,
-      "interactionPrompt": "DESIGN EDITING MODEL: a trusted source-backed mockup card offers Edit in Design. That explicit action—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, that lane edits the canonical authored HTML, and a successful desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. A preview_capture card is visual evidence, not an editable Design artifact. For direction rounds, deliver every option as its own source-backed Design card; a multi-option gallery may accompany them for comparison but must never be the only editable artifact.",
-      "turnReminder": "DESIGN ROUTE: authored HTML must produce a source-backed Thinkpool Design card with verified desktop and mobile renders. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For direction rounds, deliver every option as a separate source-backed Design card; gallery navigation is not a substitute for separately editable artifacts. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
+      "version": 4,
+      "interactionPrompt": "DESIGN EDITING MODEL: every bridge preview_capture card and every trusted source-backed mockup card offers Edit in Design. The bridge freezes a safe rendered-DOM snapshot for application previews; Design edits are then applied by the producing lane to the real application source and verified by a fresh correlated desktop+mobile capture. For authored HTML, the producing lane edits the canonical HTML source directly. Edit in Design—not ordinary Preview or unrelated artifact delivery—arms a persistent room-level Design workspace, opens the artifact directly in editable mode, and adds Design · Page name beneath the producing terminal in its Ensemble row for both partners; it creates no terminal, agent runtime, or worker slot. The virtual lane can be closed from that Ensemble row without deleting the artifact. Once armed, the Design lane reopens the active artifact at its latest verified revision without another agent turn, history search, HTML/path request, or re-selection. Design is the default canvas there and Preview is only a temporary interaction mode. Direct text, supported movement, and selected-image changes auto-stage as optimistic drafts in the bounded changes queue; queued edits can be reopened, revised, or removed before Apply. Apply changes sends the ordered batch once to the producing lane, and a successful correlated desktop+mobile render advances the verified revision for the room. Never call a staged draft saved or live. For direction rounds, deliver every option as its own Design card; a multi-option gallery may accompany the cards for comparison but must never be the only editable artifact.",
+      "turnReminder": "DESIGN ROUTE: preview_capture and authored HTML must produce editable Thinkpool Design cards with verified desktop and mobile renders. Edit in Design explicitly arms the persistent Design workspace and adds its virtual Design · Page beneath the producing terminal in the Ensemble row; Preview alone does not arm it. For direction rounds, deliver every option as a separate Design card; gallery navigation is not a substitute for separately editable artifacts. Do not duplicate the card renders as inline PNGs. Use inline PNG evidence only when no interactive Design artifact is available.",
       "impact": [
         {"path": "src/pages/code/design/"},
         {"path": "src/pages/code/structured.jsx", "diffPattern": "Edit in Design|openMockup|tp-mockup-view|sourceKnown"},

package/viewport.mjs

@@ -26,6 +26,7 @@ export const DEFAULT_VIEWPORTS = Object.freeze({
 const MAX_CAPTURE_HEIGHT = 20000
 const MAX_SETTLE_MS = 5000
 const CDP_TIMEOUT_MS = 12000
+const MAX_PORTABLE_SNAPSHOT_BYTES = 1_900_000
 
 const isInside = (parent, child) => {
   const rel = path.relative(parent, child)
@@ -267,6 +268,79 @@ export class CdpBrowser {
     })
   }
 
+  async snapshot({ url, viewport = DEFAULT_VIEWPORTS.desktop, waitMs = 300 }) {
+    return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
+      // Freeze the rendered DOM, not the build entry document. A Vite/React entry
+      // depends on root-relative chunks and often boots to an empty shell in a
+      // sandboxed srcDoc; the settled DOM plus same-origin CSS/assets is portable.
+      const expression = `(async () => {
+        const clone = document.documentElement.cloneNode(true);
+        clone.querySelectorAll('script,link[rel="modulepreload"],link[rel="preload"]').forEach((node) => node.remove());
+        clone.querySelectorAll('*').forEach((node) => {
+          for (const attr of [...node.attributes]) if (/^on/i.test(attr.name)) node.removeAttribute(attr.name);
+          if (node instanceof HTMLInputElement) node.removeAttribute('value');
+          if (node instanceof HTMLTextAreaElement) node.textContent = '';
+        });
+        const css = [];
+        for (const sheet of [...document.styleSheets]) {
+          try { css.push([...sheet.cssRules].map((rule) => rule.cssText).join('\\n')); } catch {}
+        }
+        clone.querySelectorAll('style,link[rel="stylesheet"]').forEach((node) => node.remove());
+        const head = clone.querySelector('head') || clone.insertBefore(document.createElement('head'), clone.firstChild);
+        const style = document.createElement('style');
+        style.setAttribute('data-thinkpool-snapshot', '');
+        style.textContent = css.join('\\n');
+        head.appendChild(style);
+
+        const assetUrls = new Set();
+        const remember = (raw) => {
+          if (!raw || /^(data:|blob:|#)/i.test(raw)) return;
+          try {
+            const absolute = new URL(raw, location.href);
+            if (absolute.origin === location.origin) assetUrls.add(absolute.href);
+          } catch {}
+        };
+        clone.querySelectorAll('[src],[poster]').forEach((node) => {
+          remember(node.getAttribute('src'));
+          remember(node.getAttribute('poster'));
+        });
+        for (const match of style.textContent.matchAll(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi)) remember(match[2]);
+
+        const replacements = new Map();
+        let inlinedBytes = 0;
+        for (const absolute of assetUrls) {
+          try {
+            const response = await fetch(absolute);
+            const buffer = await response.arrayBuffer();
+            if (!response.ok || buffer.byteLength > 512000 || inlinedBytes + buffer.byteLength > 1000000) continue;
+            const bytes = new Uint8Array(buffer);
+            let binary = '';
+            for (let offset = 0; offset < bytes.length; offset += 0x8000) binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+            replacements.set(absolute, 'data:' + (response.headers.get('content-type') || 'application/octet-stream') + ';base64,' + btoa(binary));
+            inlinedBytes += buffer.byteLength;
+          } catch {}
+        }
+        const replaceAsset = (raw) => {
+          try { return replacements.get(new URL(raw, location.href).href) || raw; } catch { return raw; }
+        };
+        clone.querySelectorAll('[src],[poster]').forEach((node) => {
+          for (const name of ['src', 'poster']) if (node.hasAttribute(name)) node.setAttribute(name, replaceAsset(node.getAttribute(name)));
+          node.removeAttribute('srcset');
+        });
+        style.textContent = style.textContent.replace(/url\\(\\s*(['"]?)([^'"\\)]+)\\1\\s*\\)/gi, (_all, quote, raw) => 'url("' + replaceAsset(raw) + '")');
+        return '<!doctype html>\\n' + clone.outerHTML;
+      })()`
+      const result = await pipe.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId)
+      if (result.exceptionDetails || typeof result.result?.value !== 'string') {
+        const detail = result.exceptionDetails?.exception?.description || result.exceptionDetails?.text || result.result?.description
+        throw new Error(`Could not freeze the rendered preview for Design${detail ? `: ${detail}` : '.'}`)
+      }
+      const html = result.result.value
+      if (!html.trim() || Buffer.byteLength(html) > MAX_PORTABLE_SNAPSHOT_BYTES) throw new Error('The rendered preview is too large to make editable.')
+      return html
+    })
+  }
+
   async inspect({ url, viewport = DEFAULT_VIEWPORTS.mobile, selector, waitMs = 300 }) {
     return this.withPage({ url, viewport, waitMs }, async ({ pipe, sessionId }) => {
       const expression = `(() => {
@@ -302,12 +376,13 @@ export class CdpBrowser {
 export const sharedViewportBrowser = new CdpBrowser()
 
 export class ViewportManager {
-  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview } = {}) {
+  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null } = {}) {
     this.workspaceRoot = path.resolve(workspaceRoot || process.cwd())
     this.ownerId = ownerId || randomUUID()
     this.outbox = outbox || path.join(os.tmpdir(), 'thinkpool-viewport-captures', this.ownerId)
     this.browser = browser
     this.startPreviewImpl = startPreviewImpl
+    this.designContext = typeof designContext === 'function' ? designContext : () => null
     this.previewId = `viewport:${this.ownerId}`
     this.preview = null
     this.root = null
@@ -344,7 +419,8 @@ export class ViewportManager {
   }
 
   async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300 } = {}) {
-    const url = this.pageUrl(route)
+    const normalizedRoute = normalizeRoute(route)
+    const url = this.pageUrl(normalizedRoute)
     const names = viewports === 'both' ? ['desktop', 'mobile'] : [viewports]
     if (names.some((name) => !DEFAULT_VIEWPORTS[name])) throw new Error('viewports must be "both", "desktop", or "mobile".')
     await fsp.mkdir(this.outbox, { recursive: true })
@@ -356,20 +432,28 @@ export class ViewportManager {
       await fsp.writeFile(file, result.png)
       captures[name] = { ...result, file }
     }
-    // A preview root may be a multi-file build. Its index.html is not a portable
-    // artifact: root-relative chunks cannot reliably boot when that text is later
-    // injected into a sandboxed srcDoc (Windows Edge exposed the permanent loader).
-    // preview_capture is therefore screenshot-only evidence. Editable mockups use
-    // render.sh's explicit trusted `source` contract instead.
+    const snapshotViewport = names.includes('desktop') ? DEFAULT_VIEWPORTS.desktop : DEFAULT_VIEWPORTS[names[0]]
+    const snapshot = await this.browser.snapshot({ url, viewport: snapshotViewport, waitMs })
+    const snapshotPath = path.join(this.outbox, `${slug}--source.html`)
+    await fsp.writeFile(snapshotPath, snapshot)
+    const workspace = await fsp.realpath(this.workspaceRoot)
+    const previewRoot = path.relative(workspace, this.root) || '.'
+    const captureKey = JSON.stringify([previewRoot, normalizedRoute])
+    const active = this.designContext() || null
+    const correlation = active?.captureKey === captureKey
+      ? { designRequestId: active.requestId, parentRevision: active.parentRevision }
+      : {}
     const manifest = {
       slug, title: String(title || 'Viewport capture').slice(0, 120),
       desktop: captures.desktop?.file || '', mobile: captures.mobile?.file || '', ts: Date.now(),
+      sourceKind: 'preview', snapshot: snapshotPath, previewRoot, route: normalizedRoute, captureKey,
+      ...correlation,
     }
     const manifestPath = path.join(this.outbox, `${slug}.json`)
     const tmp = `${manifestPath}.tmp`
     await fsp.writeFile(tmp, JSON.stringify(manifest))
     await fsp.rename(tmp, manifestPath)
-    return { url, slug, manifestPath, captures }
+    return { url, slug, manifestPath, captures, snapshotPath }
   }
 
   inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {