thinkpool-pair 0.7.358 → 0.7.360

package/service.mjs

@@ -26,6 +26,7 @@ import { hostMemoryAdmission } from './host-memory.mjs'
 import { readSupervisorReady, supervisorReadyMatches } from './supervisor-ready.mjs'
 import { pairCli } from './command-guidance.mjs'
 import { loadKeepAwakePreference } from './keep-awake.mjs'
+import { scheduledRunsEnabled } from './scheduled-runs.mjs'
 
 // Service identity. Account mode has no room → a single stable id so there's
 // exactly one account service per machine (a second install replaces it).
@@ -131,7 +132,7 @@ export function provisionRuntime(version, { exec = execSync, root = path.join(os
 
 // Pure artifact builder — returned shape is testable without side effects.
 // room falsy → ACCOUNT service (bare `thinkpool-pair`, auto-serves all sessions).
-export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate = false, version = VERSION, staleProof = false, runtimeEntry = null } = {}) {
+export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate = false, version = VERSION, staleProof = false, runtimeEntry = null, scheduledRuns = scheduledRunsEnabled() } = {}) {
   const npx = npxPath(platform)
   // Account mode discovers each room's own bound directory, so its supervisor must use
   // a stable home cwd. Persisting the caller's managed worktree here makes the service
@@ -161,6 +162,11 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   // In-process self-update (account.mjs / bridge.mjs) is gated on this env — only on when
   // the user explicitly opted into auto-update.
   const autoUpdateEnv = autoUpdate ? { THINKPOOL_PAIR_AUTOUPDATE: '1' } : {}
+  // Persistent services rebuild a deliberately tiny environment. Preserve this
+  // activation only as the exact boolean true; arbitrary caller values are omitted.
+  const scheduledRunsEnv = scheduledRuns === true
+    ? { darwin: '<key>TP_SCHEDULED_RUNS_ENABLED</key><string>1</string>', linux: 'Environment=TP_SCHEDULED_RUNS_ENABLED=1\n', win32: 'set "TP_SCHEDULED_RUNS_ENABLED=1"\r\n' }
+    : { darwin: '', linux: '', win32: '' }
 
   if (platform === 'darwin') {
     // launchd KeepAlive supervises. Stable runtimes execute directly; the legacy npx
@@ -187,7 +193,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   <key>WorkingDirectory</key><string>${xml(cwd)}</string>
   <key>StandardOutPath</key><string>${xml(log)}</string>
   <key>StandardErrorPath</key><string>${xml(log)}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${runtimeEntry ? '' : `<key>NPM_CONFIG_CACHE</key><string>${xml(npmCache)}</string>`}${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${runtimeEntry ? '' : `<key>NPM_CONFIG_CACHE</key><string>${xml(npmCache)}</string>`}${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}${scheduledRunsEnv.darwin}</dict>
 </dict></plist>\n`
     // The destructive reload is intentionally NOT represented as an inline `post`
     // command. installService stages this plist and hands the transaction to an
@@ -223,7 +229,7 @@ RestartSec=2
 RestartPreventExitStatus=0
 WorkingDirectory=${cwd}
 Environment=PATH=${servicePath}
-${runtimeEntry ? '' : `Environment=NPM_CONFIG_CACHE=${npmCache}\n`}${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}StandardOutput=append:${log}
+${runtimeEntry ? '' : `Environment=NPM_CONFIG_CACHE=${npmCache}\n`}${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}${scheduledRunsEnv.linux}StandardOutput=append:${log}
 StandardError=append:${log}
 
 [Install]
@@ -244,7 +250,7 @@ WantedBy=default.target
       : room
       ? ['npx', '-y', ...onlineFlag, verSpec, room, '--supervise', ...tail].join(' ')
       : ['npx', '-y', ...onlineFlag, verSpec].join(' ')
-    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${runtimeEntry ? '' : `set "NPM_CONFIG_CACHE=${npmCache}"\r\n`}${inner}\r\n`
+    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${runtimeEntry ? '' : `set "NPM_CONFIG_CACHE=${npmCache}"\r\n`}${scheduledRunsEnv.win32}${inner}\r\n`
     return { file, content, logDir, post: [], note: 'Installed to the Startup folder — runs at login' + (room ? ' with --supervise (auto-restart on crash).' : ' (account mode).') + ' Start it now without rebooting by double-clicking the .cmd, or run it from a terminal.' }
   }
 

package/session-store.mjs

@@ -292,6 +292,123 @@ export function deleteSession(room, id) {
   catch (error) { persistenceError('archive closed session snapshot', p, error); return false }
 }
 
+// Scheduled outcomes use a separate host outbox from live session snapshots.
+// A person may close the visible terminal while its idempotent database finish
+// is retrying; keeping the intent here lets a restart complete that write without
+// loadAll() resurrecting the deliberately closed terminal.
+const scheduledOutcomesFile = (room) => path.join(dir(room), '.scheduled-outcomes')
+const safeTerminalId = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/.test(value)
+const safeRunId = (value) => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/.test(value)
+const readScheduledOutcomeMap = (room) => {
+  try {
+    const value = JSON.parse(fs.readFileSync(scheduledOutcomesFile(room), 'utf8'))
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+  } catch { return {} }
+}
+// Pending entries from the original format are raw intents. Once the database
+// finish and recorded session snapshot are both durable, replace that raw entry
+// with a versioned acknowledgement tombstone before attempting deletion. The
+// tombstone is intentionally independent of the live/archived session record:
+// restart recovery can therefore identify an acknowledged exact run and retry
+// deletion only, without issuing another finish RPC or reclassifying its result.
+const scheduledOutcomeRecord = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null
+  if (value.v === 1 && value.state === 'acknowledged') {
+    const intent = value.intent
+    return intent && typeof intent === 'object' && !Array.isArray(intent) &&
+      safeRunId(intent.runId) && value.runId === intent.runId
+      ? { intent, acknowledged: true }
+      : null
+  }
+  return safeRunId(value.runId) ? { intent: value, acknowledged: false } : null
+}
+export function savePendingScheduledOutcome(room, terminalId, intent) {
+  if (!safeTerminalId(terminalId) || !intent || typeof intent !== 'object' || Array.isArray(intent) || !safeRunId(intent.runId)) return false
+  try {
+    ensureDir(room)
+    const pending = readScheduledOutcomeMap(room)
+    pending[terminalId] = intent
+    atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    return true
+  } catch (error) {
+    persistenceError('write scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+export function loadPendingScheduledOutcomes(room) {
+  return Object.entries(readScheduledOutcomeMap(room))
+    .map(([terminalId, value]) => ({ terminalId, record: scheduledOutcomeRecord(value) }))
+    .filter(({ terminalId, record }) => safeTerminalId(terminalId) && record)
+    .map(({ terminalId, record }) => ({
+      terminalId,
+      intent: record.intent,
+      ...(record.acknowledged ? { acknowledged: true } : {}),
+    }))
+    .slice(0, LIVE_SESSION_MAX)
+}
+export function loadPendingScheduledOutcome(room, terminalId) {
+  if (!safeTerminalId(terminalId)) return null
+  return scheduledOutcomeRecord(readScheduledOutcomeMap(room)[terminalId])?.intent || null
+}
+export function acknowledgePendingScheduledOutcome(room, terminalId, runId) {
+  if (!safeTerminalId(terminalId) || !safeRunId(runId)) return false
+  try {
+    const pending = readScheduledOutcomeMap(room)
+    const record = scheduledOutcomeRecord(pending[terminalId])
+    if (!record || record.intent.runId !== runId) return false
+    if (record.acknowledged) return true
+    pending[terminalId] = {
+      v: 1,
+      state: 'acknowledged',
+      runId,
+      intent: record.intent,
+    }
+    atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    return true
+  } catch (error) {
+    persistenceError('acknowledge scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+export function deletePendingScheduledOutcome(room, terminalId) {
+  if (!safeTerminalId(terminalId)) return false
+  try {
+    const pending = readScheduledOutcomeMap(room)
+    if (!(terminalId in pending)) return true
+    delete pending[terminalId]
+    if (Object.keys(pending).length) atomicCommit(scheduledOutcomesFile(room), JSON.stringify(pending))
+    else fs.rmSync(scheduledOutcomesFile(room), { force: true })
+    return true
+  } catch (error) {
+    persistenceError('delete scheduled outcome outbox', scheduledOutcomesFile(room), error)
+    return false
+  }
+}
+
+// A database acknowledgement is not locally committed until the corresponding
+// live-session snapshot has synchronously recorded scheduleOutcomeRecorded=true
+// AND the exact outbox is durably marked acknowledged. Keep deletion behind both
+// barriers so a restart always sees one of:
+//   1. pending outbox intent to replay idempotently;
+//   2. an acknowledged outbox tombstone to delete only; or
+//   3. a recorded session snapshot with no outbox.
+// `flushRecordedSnapshot` is intentionally injected by bridge.mjs because only
+// the live entry can produce its complete session payload.
+export function commitRecordedScheduledOutcome(room, terminalId, flushRecordedSnapshot) {
+  let snapshotRecorded = false
+  try {
+    snapshotRecorded = typeof flushRecordedSnapshot === 'function' && flushRecordedSnapshot() === true
+  } catch (error) {
+    persistenceError('record scheduled outcome in session snapshot', path.join(dir(room), `${terminalId}.json`), error)
+  }
+  if (!snapshotRecorded) return { ok: false, snapshotRecorded: false, outboxAcknowledged: false, outboxDeleted: false }
+  const intent = loadPendingScheduledOutcome(room, terminalId)
+  const outboxAcknowledged = acknowledgePendingScheduledOutcome(room, terminalId, intent?.runId)
+  if (!outboxAcknowledged) return { ok: false, snapshotRecorded: true, outboxAcknowledged: false, outboxDeleted: false }
+  const outboxDeleted = deletePendingScheduledOutcome(room, terminalId)
+  return { ok: outboxDeleted, snapshotRecorded: true, outboxAcknowledged: true, outboxDeleted }
+}
+
 // Most-recently-saved structured session for the room (drives attached restore).
 export function loadLatest(room) {
   const recs = listRecs(room).sort((a, b) => (b.savedAt || 0) - (a.savedAt || 0))

package/thinkpool-capabilities.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": 18,
+  "bundleVersion": 20,
   "contracts": [
     {
       "id": "room-coordination",
@@ -88,13 +88,13 @@
     },
     {
       "id": "visual-proof",
-      "version": 5,
+      "version": 6,
       "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. For an intentional application-preview Design card, use the project's source-aware Design build command when one exists (for example npm run build:design); otherwise build normally and keep selector-based source matching labeled as fallback. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, ordinary room broadcasts, and refresh-token access are blocked, while non-mutating roster/transcript snapshot requests are allowed. 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. Omit the preview path to render the current authenticated room; pass / explicitly only when the public landing page is intended. For an intentional application-preview Design card, use the project's source-aware Design build command when one exists (for example npm run build:design); otherwise build normally and keep selector-based source matching labeled as fallback. preview_capture uses a fresh isolated browser and is inline verification evidence by default; it must not create a transcript card. Set card=true only when the person asked for a mockup/Design artifact or the visual itself is an intentional deliverable that should remain editable in the transcript. A card requires settled meaningful content at both desktop and mobile, rejects loading/public-auth fallback shells, and is delivered after the final agent response. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, ordinary room broadcasts, and refresh-token access are blocked, while non-mutating roster/transcript snapshot requests are allowed. Surface PNG evidence only when no interactive source-backed Design card is displayed."
         }
       ],
       "impact": [
@@ -188,9 +188,9 @@
     },
     {
       "id": "design-workspace",
-      "version": 7,
-      "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 source-aware application previews, the bridge validates each opaque source identity against its contained host-only map and the current source-file hash before sharing an exact source location privately with the producing lane; uninstrumented elements keep the selector-based fallback, while stale or mismatched identities fail closed. 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: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. 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.",
+      "version": 8,
+      "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 source-aware application previews, the bridge validates each opaque source identity against its contained host-only map and the current source-file hash before sharing an exact source location privately with the producing lane; uninstrumented elements keep the selector-based fallback, while stale or mismatched identities fail closed. 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. A remote discrete selection may show one bounded, normalized location pulse in the partner's color; it never grants authority, persists an event, or loops. 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. Compare is available only for the exact immutable verified parent/current revision pair and uses its captured desktop or mobile images; staged, stale, cross-page, or incomplete pairs fail closed. Design visual runtimes honor live reduced motion, suspend when hidden or off-screen, cap DPR, and tear down deterministically. 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: intentional application-preview deliverables use preview_capture with card=true; correlated Design recaptures are recognized automatically. Authored HTML uses the source-backed render helper. Both must produce editable Thinkpool Design cards with verified desktop and mobile renders. Ordinary verification captures stay inline evidence and must not create cards. 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. Compare may expose only the exact immutable verified parent/current revision pair; never label a staged or incomplete capture verified. Remote selection pulses are one-shot collaboration receipts, not authority or ambient decoration. 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"},
@@ -203,6 +203,8 @@
         {"path": "src/pages/code/room.jsx", "pattern": "designLaneSelected"},
         {"path": "src/pages/code/design/DesignViewer.jsx", "pattern": "createPortal\\(surface, laneHost\\)"},
         {"path": "src/pages/code/design/DesignViewer.jsx", "pattern": "Apply \\${pendingEditCount}"},
+        {"path": "src/pages/code/design/workspace.js", "pattern": "resolveVerifiedDesignComparison"},
+        {"path": "src/pages/code/design/visual-runtime.js", "pattern": "DESIGN_VISUAL_RUNTIME_CONTRACT"},
         {"path": "src/pages/code/design/queue.js", "pattern": "designBatchPayload"},
         {"path": "bridge/design-edit.mjs", "pattern": "validateDesignBatchRequest"}
       ]

package/viewport.mjs

@@ -383,6 +383,8 @@ export class CdpBrowser {
             expression: `(() => {
               if (document.querySelector('#invitation-room-title')) return true;
               if (document.querySelector('#boot, .boot-loader')) return false;
+              const room = document.querySelector('[data-tp-preview-room-status]');
+              if (room?.dataset.tpPreviewRoomStatus === 'pending') return false;
               const loading = [...document.querySelectorAll('span')].some((node) => /^(loading session|restoring terminals…|connecting(?:…|\.\.\.))$/i.test((node.textContent || '').trim()));
               return !loading && (document.body?.innerText || '').trim().length > 1;
             })()`,
@@ -405,6 +407,7 @@ export class CdpBrowser {
                 loadingSession: [...document.querySelectorAll('span')].some((node) => (node.textContent || '').trim() === 'Loading session'),
                 connecting: [...document.querySelectorAll('span')].some((node) => (node.textContent || '').trim().toLowerCase() === 'connecting…'),
                 invitation: !!document.querySelector('#invitation-room-title'),
+                roomStatus: document.querySelector('[data-tp-preview-room-status]')?.dataset.tpPreviewRoomStatus || null,
                 heldLocks: locks.held?.length || 0,
                 pendingLocks: locks.pending?.length || 0,
               };
@@ -413,7 +416,7 @@ export class CdpBrowser {
             returnByValue: true,
           }, sessionId).catch(() => ({ result: { value: {} } }))
           const d = diagnostic.result?.value || {}
-          throw new Error(`Authenticated preview did not leave its loading state within 15 seconds (session=${d.sessionPresent ? 'present' : 'missing'}, inlineBoot=${d.inlineBoot ? 'yes' : 'no'}, loadingSession=${d.loadingSession ? 'yes' : 'no'}, connecting=${d.connecting ? 'yes' : 'no'}, authLocks=${d.heldLocks || 0}/${d.pendingLocks || 0}, invitation=${d.invitation ? 'yes' : 'no'}, reads=${authResponses.join(',') || 'none'}, local=${localResponses.join(',') || 'none'}, runtime=${runtimeExceptions.join(' | ') || 'none'}); no screenshot was created.`)
+          throw new Error(`Authenticated preview did not leave its loading state within 15 seconds (session=${d.sessionPresent ? 'present' : 'missing'}, inlineBoot=${d.inlineBoot ? 'yes' : 'no'}, loadingSession=${d.loadingSession ? 'yes' : 'no'}, connecting=${d.connecting ? 'yes' : 'no'}, roomStatus=${d.roomStatus || 'none'}, authLocks=${d.heldLocks || 0}/${d.pendingLocks || 0}, invitation=${d.invitation ? 'yes' : 'no'}, reads=${authResponses.join(',') || 'none'}, local=${localResponses.join(',') || 'none'}, runtime=${runtimeExceptions.join(' | ') || 'none'}); no screenshot was created.`)
         }
       }
       const settle = auth
@@ -585,9 +588,10 @@ export class CdpBrowser {
 export const sharedViewportBrowser = new CdpBrowser()
 
 export class ViewportManager {
-  constructor({ workspaceRoot, ownerId, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null, authContext = null } = {}) {
+  constructor({ workspaceRoot, ownerId, roomCode, outbox, browser = sharedViewportBrowser, startPreviewImpl = startPreview, designContext = null, authContext = null } = {}) {
     this.workspaceRoot = path.resolve(workspaceRoot || process.cwd())
     this.ownerId = ownerId || randomUUID()
+    this.roomCode = typeof roomCode === 'string' && roomCode.trim() ? roomCode.trim() : null
     this.outbox = outbox || path.join(os.tmpdir(), 'thinkpool-viewport-captures', this.ownerId)
     this.browser = browser
     this.startPreviewImpl = startPreviewImpl
@@ -623,6 +627,14 @@ export class ViewportManager {
     return this.preview
   }
 
+  defaultRoute() {
+    return this.roomCode ? `/?r=${encodeURIComponent(this.roomCode)}` : '/'
+  }
+
+  resolveRoute(route) {
+    return normalizeRoute(route ?? this.defaultRoute())
+  }
+
   pageUrl(route) {
     const preview = this.requirePreview()
     return new URL(normalizeRoute(route), preview.url).href
@@ -642,8 +654,8 @@ export class ViewportManager {
     }
   }
 
-  async capture({ route = '/', viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300, card = false } = {}) {
-    const normalizedRoute = normalizeRoute(route)
+  async capture({ route, viewports = 'both', title = 'Viewport capture', fullPage = true, waitMs = 300, card = false } = {}) {
+    const normalizedRoute = this.resolveRoute(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".')
@@ -704,12 +716,12 @@ export class ViewportManager {
       await fsp.writeFile(tmp, JSON.stringify(manifest))
       await fsp.rename(tmp, manifestPath)
     }
-    return { url, slug, manifestPath, captures, snapshotPath, cardReady }
+    return { url, route: normalizedRoute, slug, manifestPath, captures, snapshotPath, cardReady }
   }
 
-  async inspect({ route = '/', viewport = 'mobile', selector, waitMs = 300 } = {}) {
+  async inspect({ route, viewport = 'mobile', selector, waitMs = 300 } = {}) {
     if (!DEFAULT_VIEWPORTS[viewport]) throw new Error('viewport must be "desktop" or "mobile".')
-    const normalizedRoute = normalizeRoute(route)
+    const normalizedRoute = this.resolveRoute(route)
     return this.browser.inspect({
       url: this.pageUrl(normalizedRoute), viewport: DEFAULT_VIEWPORTS[viewport], selector, waitMs,
       auth: await this.previewAuth(normalizedRoute),
@@ -742,9 +754,9 @@ 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. Captures are inline verification evidence by default. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, and room broadcasts are blocked, apart from non-mutating roster/transcript snapshot requests. Set card=true only for a user-requested mockup or visual deliverable that should remain editable in the transcript; complete desktop+mobile settled content is then required and the card arrives after the final response.',
+      'Capture this lane preview in a fresh isolated browser at exact desktop (1440×900) and mobile (390×844) CSS viewports. Omit path to preview the current authenticated room; pass / explicitly for the public landing page. Defaults to both and full-page. Captures are inline verification evidence by default. Room and protected routes automatically use the bridge account as a read-only authenticated visual harness; external REST writes, presence, and room broadcasts are blocked, apart from non-mutating roster/transcript snapshot requests. Set card=true only for a user-requested mockup or visual deliverable that should remain editable in the transcript; complete desktop+mobile settled content is then required and the card arrives after the final response.',
       {
-        path: z.string().max(500).optional().describe('route within the preview, e.g. / or /settings; never a full URL'),
+        path: z.string().max(500).optional().describe('route within the preview; omit for the current authenticated room, or pass / for the public landing page; never a full URL'),
         viewports: z.enum(['both', 'desktop', 'mobile']).optional(),
         title: z.string().max(120).optional(),
         fullPage: z.boolean().optional(),
@@ -754,13 +766,13 @@ export function createViewportTools({ tool, z, manager }) {
       async (args) => {
         try {
           const result = await manager.capture({
-            route: args?.path || '/', viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
+            route: args?.path, viewports: args?.viewports || 'both', title: args?.title || 'Viewport capture',
             fullPage: args?.fullPage !== false, waitMs: args?.waitMs ?? 300, card: args?.card === true,
           })
           const delivery = result.cardReady
             ? 'The complete room preview card is queued after your final response.'
             : 'This is verification evidence only; no room card was created.'
-          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${args?.path || '/'}. ${delivery}` }]
+          const content = [{ type: 'text', text: `Captured ${Object.keys(result.captures).join(' + ')} for ${result.route}. ${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' })
@@ -771,16 +783,16 @@ export function createViewportTools({ tool, z, manager }) {
     ),
     tool(
       'preview_inspect',
-      'Inspect rendered DOM state in this lane preview at an exact desktop or mobile viewport. Returns page text, document dimensions, and optional selector text/geometry without changing the page.',
+      'Inspect rendered DOM state in this lane preview at an exact desktop or mobile viewport. Omit path for the current authenticated room; pass / explicitly for the public landing page. Returns page text, document dimensions, and optional selector text/geometry without changing the page.',
       {
-        path: z.string().max(500).optional().describe('route within the preview; never a full URL'),
+        path: z.string().max(500).optional().describe('route within the preview; omit for the current authenticated room, or pass / for the public landing page; never a full URL'),
         viewport: z.enum(['desktop', 'mobile']).optional(),
         selector: z.string().max(500).optional(),
         waitMs: z.number().int().min(0).max(MAX_SETTLE_MS).optional(),
       },
       async (args) => {
         try {
-          const result = await manager.inspect({ route: args?.path || '/', viewport: args?.viewport || 'mobile', selector: args?.selector, waitMs: args?.waitMs ?? 300 })
+          const result = await manager.inspect({ route: args?.path, viewport: args?.viewport || 'mobile', selector: args?.selector, waitMs: args?.waitMs ?? 300 })
           return textResult(JSON.stringify(result, null, 2))
         } catch (error) { return errorResult(error) }
       },