thinkpool-pair 0.7.306 → 0.7.308

package/README.md

@@ -81,7 +81,8 @@ their own sandbox cannot bind localhost or launch Chrome:
 - `preview_start` serves a built directory inside that lane's workspace
   (`dist` by default; it must contain `index.html`).
 - `preview_capture` returns exact desktop (1440×900) and mobile (390×844)
-  screenshots to the agent and surfaces them in the room.
+  screenshots to the agent. A complete pair is queued as a room card after the
+  agent's final response; a single-viewport capture remains tool evidence only.
 - `preview_inspect` returns rendered DOM text, document size, and optional
   selector geometry at either viewport.
 - `preview_stop` releases the preview port.

package/account.mjs

@@ -28,6 +28,22 @@ const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./pack
 
 const BRIDGE = fileURLToPath(new URL('./bridge.mjs', import.meta.url))
 
+// Startup can spend several seconds waiting on the cross-process refresh lock or
+// backing off after a transient auth failure. Those sleeps are intentionally unref'd
+// once the supervisor is running, but before Realtime + the 15s tick exist they leave
+// an unresolved top-level await as Node's only work; Node 22 exits 13 with
+// "Detected unsettled top-level await". Hold one referenced timer only for bootstrap,
+// then release it as soon as the supervisor's real lifetime interval exists.
+export function createStartupAnchor({ set = setInterval, clear = clearInterval } = {}) {
+  const timer = set(() => {}, 60_000)
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    clear(timer)
+  }
+}
+
 // ── single-instance lock ────────────────────────────────────────────────────
 // Two account supervisors on one machine share ONE ~/.thinkpool-pair/auth.json
 // refresh token and race its rotation — which on 2026-06-17 deleted a live Pro
@@ -360,6 +376,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     console.error('\n  ◇ An account bridge is already running on this machine\n    (~/.thinkpool-pair/account.lock). Not starting a second — two would race\n    your saved login. Stop the other one first, or share a single room with\n    `npx thinkpool-pair <ROOM>`.\n')
     process.exit(0)
   }
+  const releaseStartupAnchor = createStartupAnchor()
   // F2: NEVER exit(1) on a refresh failure. The old code exited 1 here, and launchd
   // KeepAlive respawned us within seconds → refresh again → the 16× crash storm (and,
   // worse, hammering the refresh path burns rotations and can revoke the token family).
@@ -1043,6 +1060,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
 
   await tick()
   const iv = setInterval(tick, 15000)
+  releaseStartupAnchor()
   const updateTimers = []   // auto-update poll/apply timers — cleared in stop() so none fire post-exit
   let stopping = false
 

package/bridge.mjs

@@ -77,7 +77,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, refreshDesignSource, resolveManifestDesignSource, restoreDesignSources, syncRealtimeAuth, validateDesignBatchRequest } from './design-edit.mjs'
+import { deleteDesignAssetDraft, designPrompt, designTranscript, materializeDesignAsset, refreshDesignSource, resolveManifestDesignSource, resolveManifestDisplaySource, 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.
@@ -128,6 +128,7 @@ import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantText
 import { planMeterLine } from './plan-meters.mjs'
 import { priceForModel } from './model-prices.mjs'
 import { makeThrottledTrack } from './presence.mjs'
+import { MockupDeliveryQueue, completeMockupManifest, isMockupDeliveryBoundary } from './mockup-delivery.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
 import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE, THINKPOOL_PROMPT_BUNDLE } from './thinkpool-room-prompt.mjs'
 
@@ -248,7 +249,12 @@ if (argv[0] === 'install-service' || argv[0] === 'uninstall-service') {
   // always-on service); --auto-update opts into @latest tracking. (2026-06-22)
   const autoUpdate = argv.includes('--auto-update')
   const svc = await import('./service.mjs')
-  if (argv[0] === 'install-service') svc.installService(svcRoom, svcCmd, { autoUpdate })
+  if (argv[0] === 'install-service') {
+    const ok = autoUpdate
+      ? svc.installService(svcRoom, svcCmd, { autoUpdate })
+      : await svc.installAndConfirmService(svcRoom, svcCmd)
+    process.exit(ok === false ? 1 : 0)
+  }
   else svc.uninstallService(svcRoom)
   process.exit(0)
 }
@@ -349,10 +355,9 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
       child.on('exit', (code) => process.exit(code == null ? 0 : code))
     }),
     serveAccountForeground: async () => { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) },
-    // install / uninstall are NOT terminal — they do their work, print their notes,
-    // and return to the menu. A confirmed update closes the launcher instead: its
-    // in-memory package version is stale while the new service runs independently.
-    installService: ({ room = null, agentCmd } = {}) => { svc.installService(room, agentCmd ? [agentCmd] : []) },
+    // Confirmed installs/updates close the launcher: the service is independently
+    // running and another menu cycle can only race it. Failures return to the menu.
+    installService: ({ room = null, agentCmd } = {}) => svc.installAndConfirmService(room, agentCmd ? [agentCmd] : []),
     uninstallService: ({ room = null } = {}) => { svc.uninstallService(room) },
     restartService: ({ room = null } = {}) => { svc.restartService(room) },
     // The menu waits for OS-level proof before claiming success. In-service web
@@ -1549,37 +1554,49 @@ function pumpDesign(term) {
 // landed in *is* its provenance. (Before: a per-room outbox + a "first session
 // in the Map" guess meant closing the generating terminal moved the cards to
 // whatever terminal was now first — they leaked into Terminal 1.)
-const handleManifest = async (box, file, term, trustedDesignSource = false) => {
+const writeMockupReceipt = (box, slug, ok, status) => {
+  try {
+    const rc = path.join(box, `${slug}.receipt.json`)
+    const tmp = `${rc}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify({ ok, status, ts: Date.now() }))
+    fs.renameSync(tmp, rc)
+  } catch { /* receipts are best-effort */ }
+}
+
+const prepareManifest = (box, file, term, trustedDesignSource = false) => {
   // Ignore our own delivery receipts — writing <slug>.receipt.json into the
   // watched outbox re-fires fs.watch; without this guard it would re-trigger
   // handleManifest in a loop (it still ends in .json). Must come first.
-  if (!file || file.endsWith('.receipt.json') || !file.endsWith('.json')) return
+  if (!file || file.endsWith('.receipt.json') || !file.endsWith('.json')) return null
   const full = path.join(box, file)
   let stat
-  try { stat = fs.statSync(full) } catch { return }            // tmp/removed mid-write
+  try { stat = fs.statSync(full) } catch { return null }       // tmp/removed mid-write
   const slug = file.replace(/\.json$/, '')
-  // Delivery receipt (atomic tmp+mv) so render.sh can confirm the card actually
-  // reached the room — written on success AND failure. Best-effort: a receipt
-  // that can't be written just leaves render.sh at "delivery unconfirmed".
-  const writeReceipt = (ok, status) => {
-    try {
-      const rc = path.join(box, `${slug}.receipt.json`)
-      const tmp = `${rc}.tmp`
-      fs.writeFileSync(tmp, JSON.stringify({ ok, status, ts: Date.now() }))
-      fs.renameSync(tmp, rc)
-    } catch { /* receipts are best-effort */ }
-  }
   const seenKey = `${term}/${slug}`
-  if (mockupSeen.get(seenKey) === stat.mtimeMs) return         // already handled
+  if (mockupSeen.get(seenKey) === stat.mtimeMs) return null    // already handled
   mockupSeen.set(seenKey, stat.mtimeMs)
-  if (!term) return                                            // nothing to attach the card to yet
+  if (!term) return null                                       // nothing to attach the card to yet
   let m
-  try { m = JSON.parse(fs.readFileSync(full, 'utf8')) } catch { return }
-  if (!m?.slug) return
+  try { m = JSON.parse(fs.readFileSync(full, 'utf8')) } catch { return null }
+  if (!m?.slug) return null
+  if (!completeMockupManifest(m, { isReadyFile: (asset) => {
+    try { const ready = fs.statSync(asset); return ready.isFile() && ready.size > 0 } catch { return false }
+  } })) {
+    writeMockupReceipt(box, slug, false, 'incomplete')
+    process.stderr.write(`\n  ◇ mockup "${m.title || m.slug}" is incomplete — desktop, mobile, and source are all required.\n`)
+    return null
+  }
+  return { box, file, term, trustedDesignSource, slug, m }
+}
+
+const handleManifest = async ({ box, term, trustedDesignSource = false, slug, m }) => {
   const producer = trustedDesignSource ? sessions.get(term) : null
   const designRecord = producer
     ? resolveManifestDesignSource(m, producer.cwd || process.cwd(), { box })
     : null
+  const displaySource = designRecord
+    ? resolveManifestDisplaySource(m, designRecord, { box })
+    : null
   // 2026-07-07: these used to swallow read errors silently — a transient
   // unreadable file (race with the render script, permissions, mid-write)
   // meant the manifest still POSTed with that field missing, and nothing
@@ -1594,6 +1611,15 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
     catch (e) { if (p) process.stderr.write(`\n  ◇ mockup asset unreadable: ${p} (${e?.code || e?.message || e})\n`); return null }
   }
   const cid = randomUUID()
+  // The card belongs after the final agent response, not at render time. This
+  // timestamp is also persisted by /api/code-mockup, so reload ordering matches
+  // the live transcript instead of jumping the card back above the answer.
+  const deliveryTs = Date.now()
+  if (designRecord && !displaySource) {
+    writeMockupReceipt(box, slug, false, 'invalid-snapshot')
+    process.stderr.write(`\n  ◇ mockup "${m.slug}" rendered snapshot was not trusted.\n`)
+    return
+  }
   try {
     const mockupHeaders = { 'Content-Type': 'application/json' }
     // Authenticate as the owner so the server can attribute the persisted row to a
@@ -1604,19 +1630,19 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
       method: 'POST',
       headers: mockupHeaders,
       body: JSON.stringify({
-        code: room, slug: m.slug, title: m.title, cid, ts: m.ts, term,
-        desktopPng: readB64(m.desktop), mobilePng: readB64(m.mobile), html: designRecord ? designRecord.source : readTxt(m.html),
+        code: room, slug: m.slug, title: m.title, cid, ts: deliveryTs, term,
+        desktopPng: readB64(m.desktop), mobilePng: readB64(m.mobile), html: designRecord ? displaySource : readTxt(m.html),
         ...(designRecord ? { previewId: designRecord.previewId, revision: designRecord.revision, sourceKnown: true } : {}),
       }),
     })
     if (!res.ok) {
-      writeReceipt(false, res.status)
+      writeMockupReceipt(box, slug, false, res.status)
       process.stderr.write(`\n  ◇ mockup "${m.slug}" upload failed (${res.status}).\n`); return
     }
     const uploaded = await res.json()
     const { paths } = uploaded
     const designAccepted = !!(designRecord && uploaded?.payload?.sourceKnown)
-    const artifact = { kind: 'mockup', __struct: true, cid, term, slug: m.slug, title: m.title || m.slug, ts: m.ts, paths,
+    const artifact = { kind: 'mockup', __struct: true, cid, term, slug: m.slug, title: m.title || m.slug, ts: deliveryTs, paths,
       ...(designAccepted ? { previewId: designRecord.previewId, revision: designRecord.revision, sourceKnown: true } : {}) }
     if (designAccepted) {
       Object.assign(designRecord, { term, slug: m.slug, title: m.title || m.slug, desktop: m.desktop, mobile: m.mobile })
@@ -1642,19 +1668,35 @@ const handleManifest = async (box, file, term, trustedDesignSource = false) => {
       }
     }
     bcast('code-event', { term, evt: artifact })
-    writeReceipt(true, 200)
+    writeMockupReceipt(box, slug, true, 200)
     process.stderr.write(`\n  ◆ mockup "${m.title || m.slug}" pushed to the room.\n`)
   } catch (e) {
-    writeReceipt(false, 'error')
+    writeMockupReceipt(box, slug, false, 'error')
     process.stderr.write(`\n  ◇ mockup "${m.slug}" send failed: ${e?.message || e}\n`)
   }
 }
+
+const mockupDeliveries = new MockupDeliveryQueue({ deliver: handleManifest })
+
+function receiveManifest(box, file, term, trustedDesignSource = false) {
+  const item = prepareManifest(box, file, term, trustedDesignSource)
+  if (!item) return
+  const lane = sessions.get(term)
+  const active = !!lane && (lane._busyAnn === true || lane.session?.turnActive === true)
+  const accepted = mockupDeliveries.enqueue(term, item, { active })
+  if (accepted.queued) {
+    writeMockupReceipt(box, item.slug, true, 'queued')
+    process.stderr.write(`\n  ◆ mockup "${item.m.title || item.m.slug}" ready — queued after the final response.\n`)
+  } else {
+    accepted.delivery.catch(() => {})
+  }
+}
 // Watch one outbox dir; `ownerFn()` resolves which terminal owns a manifest
 // dropped there (lazily, per event). Returns the FSWatcher so per-session/term
 // watchers can be torn down when their owner ends. Safe to call repeatedly.
 function watchOutbox(box, ownerFn, trustedDesignSource = false) {
   try { fs.mkdirSync(box, { recursive: true }) } catch { return null }
-  try { return fs.watch(box, (_evt, file) => { handleManifest(box, file, ownerFn(), trustedDesignSource).catch(() => {}) }) }
+  try { return fs.watch(box, (_evt, file) => receiveManifest(box, file, ownerFn(), trustedDesignSource)) }
   catch { return null }   // fs.watch unsupported — mockups simply won't auto-surface
 }
 // A per-owner outbox lives at MOCKUP_OUTBOX/<kind>/<id> and is handed to that
@@ -3053,6 +3095,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       // after the final queued boundary.
       const terminalBoundary = !continuesQueued && evt.kind === 'result'
       const busyChanged = terminalBoundary ? settleLaneBusy(entry) : syncStructuredTurn(entry)
+      const mockupDeliveryBoundary = isMockupDeliveryBoundary(evt, { turnActive: entry.session?.turnActive === true })
       stampStructuredTurn(entry, evt)
       stampEvent(evt)
       const stalledChanged = evt.kind === 'stalled' ? !entry.stalled : !!entry.stalled
@@ -3306,6 +3349,12 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
         bcast('code-event', { term: id, evt: e })
         printLocal(e)
         if (!chrome) persist()
+        // Result/error has now crossed the same ordered emission boundary as the
+        // final assistant text (including the image queue). Only now may ready
+        // mockups be uploaded, persisted, and broadcast below that answer.
+        if (mockupDeliveryBoundary) {
+          queueMicrotask(() => { mockupDeliveries.flush(id).catch(() => {}) })
+        }
       }
       // A tool_result carrying an inline base64 image can't ride a broadcast frame
       // (live OR replay). Lift it to Storage FIRST, then emit the URL-only event —
@@ -3542,6 +3591,7 @@ function endStructured(id) {
   const s = sessions.get(id)
   if (s) {
     s.imageQueue?.close()
+    mockupDeliveries.clear(id)
     drainPending(s)
     try { s.session?.end() } catch { /* noop */ }
     try { s.mockupWatcher?.close() } catch { /* noop */ }

package/design-edit.mjs

@@ -84,6 +84,25 @@ export function resolveManifestDesignSource(manifest, workspaceRoot, { box } = {
   return resolveDesignSource(manifest.source || manifest.html, workspaceRoot)
 }
 
+// Authored mockups keep two representations: the canonical workspace source the
+// producing lane edits, and a settled inert DOM snapshot the Design viewer shows.
+// Snapshot paths are accepted only from this lane's private outbox so a crafted
+// manifest cannot upload an arbitrary host file as room-visible HTML.
+export function resolveManifestDisplaySource(manifest, record, { box } = {}) {
+  if (!record) return null
+  if (record.sourceKind === 'preview' || !manifest?.snapshot) return record.source
+  let snapshotPath, outbox
+  try {
+    snapshotPath = fs.realpathSync(manifest.snapshot)
+    outbox = fs.realpathSync(box)
+    const stat = fs.statSync(snapshotPath)
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) return null
+  } catch { return null }
+  const rel = path.relative(outbox, snapshotPath)
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel) || path.extname(snapshotPath).toLowerCase() !== '.html') return null
+  return fs.readFileSync(snapshotPath, 'utf8')
+}
+
 export function refreshDesignSource(record) {
   if (!record) return null
   if (record.sourceKind !== 'preview') return resolveDesignSource(record.sourcePath, record.workspaceRoot)

package/launcher.mjs

@@ -277,7 +277,13 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
     const pick = items[await askChoice('choose', items)]
     if (pick.key === 'quit') return
     if (pick.key === 'serve') { if (await ensureLoggedIn()) await actions.serveAccountForeground() }
-    else if (pick.key === 'service') { if (await ensureLoggedIn()) { await actions.installService({ room: null }); resync() } }
+    else if (pick.key === 'service') {
+      if (await ensureLoggedIn()) {
+        const installed = await actions.installService({ room: null })
+        if (installed === true) return
+        resync()
+      }
+    }
     else if (pick.key === 'restart') {
       const updated = await actions.restartUpdateService({ room: null })
       // The launcher process cannot update its own in-memory VERSION. Returning to

package/mockup-delivery.mjs

@@ -0,0 +1,50 @@
+// Turn-scoped delivery boundary for room mockups.
+//
+// A render can finish several tool calls before the agent's final answer. Sending
+// its card immediately makes the answer land below it, forcing a phone user to
+// scroll back up. Keep active-turn artifacts private until the transcript's real
+// terminal boundary has been emitted, then deliver them in render order.
+export function completeMockupManifest(manifest, { isReadyFile } = {}) {
+  if (typeof isReadyFile !== 'function') throw new TypeError('completeMockupManifest requires isReadyFile')
+  const files = [manifest?.desktop, manifest?.mobile, manifest?.snapshot || manifest?.source || manifest?.html]
+  return files.every((file) => !!file && isReadyFile(file))
+}
+
+export function isMockupDeliveryBoundary(event, { turnActive = false } = {}) {
+  if (!event || event.continuesQueued) return false
+  if (event.kind === 'result') return true
+  return event.kind === 'error' && !turnActive
+}
+
+export class MockupDeliveryQueue {
+  constructor({ deliver } = {}) {
+    if (typeof deliver !== 'function') throw new TypeError('MockupDeliveryQueue requires deliver')
+    this.deliver = deliver
+    this.pending = new Map()
+  }
+
+  enqueue(owner, item, { active = false } = {}) {
+    if (!owner || !active) return { queued: false, delivery: Promise.resolve().then(() => this.deliver(item)) }
+    const queue = this.pending.get(owner) || []
+    queue.push(item)
+    this.pending.set(owner, queue)
+    return { queued: true, delivery: null }
+  }
+
+  count(owner) {
+    return (this.pending.get(owner) || []).length
+  }
+
+  async flush(owner) {
+    const queue = this.pending.get(owner) || []
+    this.pending.delete(owner)
+    for (const item of queue) await this.deliver(item)
+    return queue.length
+  }
+
+  clear(owner) {
+    const count = this.count(owner)
+    this.pending.delete(owner)
+    return count
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.306",
+  "version": "0.7.308",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -69,6 +69,7 @@
     "flow-models.mjs",
     "flow-host-revert.mjs",
     "flow-preview.mjs",
+    "mockup-delivery.mjs",
     "viewport.mjs",
     "design-edit.mjs",
     "flow-review.mjs",

package/service.mjs

@@ -456,6 +456,65 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
   return true
 }
 
+// Interactive installs must not present an armed launchd helper as a completed
+// background service. installService() intentionally returns after staging because
+// an in-service update may tear down its caller; this menu/CLI primitive waits for the
+// helper receipt AND the exact live runtime before returning success.
+export async function installAndConfirmService(room, cmdArgs = [], {
+  platform = process.platform,
+  version = VERSION,
+  staleProof = true,
+  install = installService,
+  exec = execSync,
+  snapshot = serviceRuntimeSnapshot,
+  readStatus = () => {
+    try { return JSON.parse(fs.readFileSync(path.join(os.homedir(), '.thinkpool-pair', 'update-status.json'), 'utf8')) } catch { return null }
+  },
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  timeoutMs = 55000,
+  pollMs = 250,
+  stderr = process.stderr,
+} = {}) {
+  if (install(room, cmdArgs, { version, staleProof }) === false) return false
+
+  const confirmation = () => {
+    const live = snapshot(room, { platform, exec })
+    if (live?.version === version) {
+      stderr.write(`  ✓ bridge install confirmed — running v${version}.\n`)
+      return true
+    }
+    return false
+  }
+
+  // systemd's restart is synchronous. Windows cannot prove a live Startup process,
+  // so this exact-runtime confirmation is used only where a service manager exists.
+  if (platform !== 'darwin') {
+    if (platform === 'win32') return true
+    const confirmed = confirmation()
+    if (!confirmed) stderr.write(`  ⚠ install v${version} was not confirmed: the service manager cannot prove that runtime is running.\n`)
+    return confirmed
+  }
+
+  const deadline = now() + Math.max(0, Number(timeoutMs) || 0)
+  const expectedTarget = label(room)
+  for (;;) {
+    const status = readStatus()
+    if (status && typeof status === 'object' && status.target === expectedTarget && status.version === version) {
+      if (status.ok === false) {
+        stderr.write(`  ⚠ install v${version} was not confirmed: ${status.error || 'the launchd handoff failed'}.\n`)
+        return false
+      }
+      if (status.ok === true && confirmation()) return true
+    }
+    if (now() >= deadline) {
+      stderr.write(`  ⚠ install v${version} timed out waiting for launchd confirmation; no running service was proven.\n`)
+      return false
+    }
+    await sleep(Math.max(1, Number(pollMs) || 1))
+  }
+}
+
 // Restart an already-installed boot-persistent service. launchd/systemd relaunch
 // the stable runtime (or legacy auto-update npx command), so active sessions resume
 // from disk. Use it to recover a wedged bridge or re-read provider.json.

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 10,
+  "bundleVersion": 11,
   "contracts": [
     {
       "id": "room-coordination",
@@ -88,13 +88,13 @@
     },
     {
       "id": "visual-proof",
-      "version": 2,
+      "version": 3,
       "routes": [
         {
           "id": "visual-proof",
           "tools": ["preview_start", "preview_capture", "preview_inspect", "preview_stop"],
           "trigger": "\\b(ui|ux|visual|design|frontend|html|css|page|route|mockup|screenshot|responsive|desktop|mobile|preview)\\b",
-          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser, so authenticated app routes require an authenticated visual harness; if a room route resolves to the signed-out invitation, the capture is rejected and no mockup card is created. Surface PNG evidence only when no interactive source-backed Design card is displayed."
+          "prompt": "For built visual work, run the build, use preview_start, preview_capture at desktop and mobile, preview_inspect when rendered state matters, and preview_stop when finished. preview_capture uses a fresh isolated browser, so authenticated app routes require an authenticated visual harness; if a room route resolves to the signed-out invitation, the capture is rejected and no mockup card is created. A room card requires complete desktop and mobile evidence and is delivered after the final agent response; partial captures remain tool evidence only. Surface PNG evidence only when no interactive source-backed Design card is displayed."
         }
       ],
       "impact": [
@@ -168,9 +168,9 @@
     },
     {
       "id": "design-workspace",
-      "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.",
+      "version": 5,
+      "interactionPrompt": "DESIGN EDITING MODEL: every complete 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 authored 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. When a person asks for many mockups or options that can share a surface, prefer one source-backed multi-option board or gallery in one file and one card so they can compare together; create separate files/cards only when the person explicitly requests independently editable artifacts or the options cannot be represented faithfully together.",
+      "turnReminder": "DESIGN ROUTE: preview_capture and authored HTML must produce editable Thinkpool Design cards with verified desktop and mobile renders. Cards are delivered after the final agent response so they remain the newest transcript item. 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 large direction sets, consolidate compatible options into one source-backed comparison board/gallery and one card; use separate files/cards only when independent editing is explicitly requested or technically necessary. 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

@@ -458,17 +458,24 @@ export class ViewportManager {
     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,
+    // A room card is a finished artifact, not a partial verification frame. A
+    // one-viewport request still returns useful MCP image evidence, but only the
+    // exact desktop+mobile pair gets a manifest and enters the turn-final queue.
+    const cardReady = !!(captures.desktop && captures.mobile)
+    let manifestPath = null
+    if (cardReady) {
+      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,
+      }
+      manifestPath = path.join(this.outbox, `${slug}.json`)
+      const tmp = `${manifestPath}.tmp`
+      await fsp.writeFile(tmp, JSON.stringify(manifest))
+      await fsp.rename(tmp, manifestPath)
     }
-    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, snapshotPath }
+    return { url, slug, manifestPath, captures, snapshotPath, cardReady }
   }
 
   inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {
@@ -502,7 +509,7 @@ export function createViewportTools({ tool, z, manager }) {
     ),
     tool(
       'preview_capture',
-      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Authenticated app routes require an authenticated visual harness; a room route that resolves to the signed-out invitation is rejected. Successful captures return PNGs to your vision context and surface a mockup card in the ThinkPool room.',
+      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Defaults to both and full-page. Authenticated app routes require an authenticated visual harness; a room route that resolves to the signed-out invitation is rejected. Captures always return PNG evidence; only a complete desktop+mobile capture surfaces a mockup card, after the agent final response.',
       {
         path: z.string().max(500).optional().describe('route within the preview, e.g. / or /settings; never a full URL'),
         viewports: z.enum(['both', 'desktop', 'mobile']).optional(),
@@ -516,7 +523,10 @@ export function createViewportTools({ tool, z, manager }) {
             route: args?.path || '/', viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
             fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300,
           })
-          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. A room preview card is being delivered.` }]
+          const delivery = result.cardReady
+            ? 'The complete room preview card is queued after your final response.'
+            : 'This is partial viewport evidence only; no room card was created.'
+          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. ${delivery}` }]
           for (const [name, capture] of Object.entries(result.captures)) {
             content.push({ type: 'text', text: `${name}: ${capture.width}×${capture.height}${capture.capped ? ' (height capped)' : ''}` })
             content.push({ type: 'image', data: capture.png.toString('base64'), mimeType: 'image/png' })