fix(preview): keep snapshots slim unless the agent asks

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[gbarros-dev]

preview_snapshot dumped the accessibility tree, console, and network on every inspect. preview_wait_for also matched sidebar chrome, so agents thought a page was ready when only a nav label matched.

Snapshots default to URL, main-landmark text, visible controls, and a PNG. AX, console, and network load only when include asks. Wait searches main by default and requires a visible locator.

Split out of closed#7127.

Tests: vp test run packages/contracts/src/preview.test.ts

Implemented with Grok 4.6 through Grok CLI.

---

Note

Medium Risk
Changes default MCP/desktop snapshot shape and debugger domain wiring; agents or integrations that assumed always-on diagnostics may break until they pass include.

Overview
Preview automation snapshots are slim by default.preview_snapshot and desktop IPC now accept optional include (ax, console, network); without it callers get URL, main-landmark visible text, interactive elements, action timeline, and PNG only. CDP accessibility, log, and network domains are enabled on demand per control session instead of on every attach.

preview_wait_for is scoped to real page content. Text and locator matching default to the main landmark (plus modal/overlay roots); optional scope: "document" searches the full page. Locator waits require visibility and skip dialog trigger slots.

Snapshot harvesting adds stable element ids, pointer-cursor table/layout nodes, and CDP screenshot fallback when capturePage fails. accessibilityTree is optional in the contract.

Breaking for consumers: anything expecting full AX/console/network on every snapshot must pass include.

^{Reviewed by Cursor Bugbot for commit 3755a33. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Make preview snapshots slim by default and scope preview_wait_for to main landmark

• Snapshots now require explicit include values (ax, console, network) to return diagnostic data. Default snapshots omit the accessibility tree and return empty console and network arrays.
• preview_wait_for defaults to the main landmark scope. It searches overlay roots, traverses shadow DOM, and ignores invisible elements unless scope is set to document.
• Adds a CDP Page.captureScreenshot fallback to captureAutomationSnapshot when Electron's capturePage fails.
• Refactors withControlSession in Manager.ts to resolve WebContents internally and re-check session validity before executing callbacks.
• Behavioral Change: existing preview_wait_for calls relying on matches outside the main landmark or within invisible nodes will fail unless scope: "document" is passed.

^{Macroscope summarized 3755a33.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8834cb66-be84-4273-a921-43d3e4b089ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect service conventions review: two findings on the desktop preview snapshot path. Details inline.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the default preview snapshot payload and wait_for matching behavior across the MCP, web, IPC, and desktop automation layers, rather than only adding an opt-in path. It also includes unresolved control-session lifecycle and stale-webview risks that require human assessment.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

🟡 Mediumpreview/Manager.ts:1421

Automation requests that fail in requireWebContents or ensureControlSession leave a permanent running entry in actionTimeline, so later snapshots report an action that never completes. withControlSession records the event before those calls, but installs Effect.onExit(finalize) only around execute; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes failed/interrupted.

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/preview/Manager.ts around line 1421:
Automation requests that fail in `requireWebContents` or `ensureControlSession` leave a permanent `running` entry in `actionTimeline`, so later snapshots report an action that never completes. `withControlSession` records the event before those calls, but installs `Effect.onExit(finalize)` only around `execute`; install finalization around the entire operation (or otherwise finalize these early failures) so the entry becomes `failed`/`interrupted`.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}

[cursor]

Stale webview used after re-ensure

Medium Severity

withControlSession re-reads the tab after the first ensureControlSession, then can await a second ensure and still pass the pre-await activeWc into execute. A swap (or the detach-before-publish window of the first swap) leaves click, type, and snapshot talking to a guest the tab no longer owns.

^{Triggered by learned rule: PreviewManager: re-read tab state from tabsRef after mutations, don't use stale snapshots}

^{Reviewed by Cursor Bugbot for commit 3755a33. Configure here.}