thinkpool-pair 0.7.306 → 0.7.307

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/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'
 
@@ -1549,37 +1550,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 +1607,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 +1626,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 +1664,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 +3091,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 +3345,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 +3587,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/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.307",
   "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/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' })