Summary
During a full /impeccable home-page build (Cursor agent, macOS), the finish step stalled on screenshot capture because the agent invoked Playwright to install Chromium. The download reached 100%, then the process sat silent for several minutes with no further progress. I had to pause the session and manually ask the agent to switch to a different approach before work could continue.
This blocked the new-work.md finish handoff that requires desktop + mobile screenshots for impeccable-finish-reviewer.
Environment
- OS: macOS (darwin 25.3.0)
- Node: v26.4.0
- Project: greenfield Astro site (
ekihana-stand), Impeccable skill ~4.0.4
- Playwright:
npx playwright@1.49.1 install chromium + npx playwright screenshot ...
What happened
- Agent reached finish inspection in
reference/new-work.md and needed .impeccable/screenshots/mobile-home.png + desktop-home.png.
- Agent ran Playwright install + screenshot (no shipped Impeccable screenshot script was used).
- Install output showed the Chromium zip download at 100% (~122 MB), then no further progress for 6+ minutes.
- Process inspection showed:
oopDownloadBrowserMain.js still running- Full zip present in
/var/folders/.../playwright-download-chromium-mac15-arm64-1148.zip
- Extract target
~/Library/Caches/ms-playwright/chromium-1148/ still nearly empty (~432 KB)
__dirlock present under ~/Library/Caches/ms-playwright/
- Restarting the install did not complete within a reasonable window either; session time was burning with no screenshots and no finish reviewer input.
User impact
- Workflow blocked at the finish screenshot step — cannot spawn
impeccable-finish-reviewer with valid captures.
- Manual intervention required: I paused the agent and explicitly asked it to use another method.
- Workaround that worked: agent switched to
puppeteer-core + system Google Chrome (/Applications/Google Chrome.app/...), no Playwright browser download. Screenshots landed in ~10s.
Related issues observed (same session, separate root cause)
After screenshots finally worked, the first captures were wrong pages (unrelated Impeccable marketing HTML) because stale Astro/Vite processes were bound to localhost ports and returned generic Vite error pages. That is a port/zombie-server problem, not Playwright itself — but it made the finish reviewer reject the captures until ports were cleaned and the correct build was served.
There is also overlap with #435 (silent failure when puppeteer absent) — here the engine existed via system Chrome, but the finish flow does not document that path.
Why this feels like an Impeccable gap
reference/new-work.md requires screenshot capture before finish reviewer, but the skill does not ship a screenshot helper for that step.reference/critique.md says to prefer native/harness browser capture before hand-rolling Playwright/Puppeteer — agents still default to Playwright install when no native tool is obvious.scripts/detector/engines/browser/detect-url.mjs already knows how to launch system Chrome via channel: 'chrome' (Windows) / bundled fallback — that pattern is not reused for finish screenshots.
Suggestions
- Ship a finish screenshot script (e.g.
scripts/capture-screenshots.mjs) using puppeteer-core + system Chrome/Safari fallback, with explicit page verification (title or marker text) before writing PNGs.
- Document the fallback in
new-work.md finish section so agents do not attempt a fresh Playwright browser download mid-build.
- If Playwright remains acceptable: detect post-download extract stalls (timeout + actionable error) and recommend system-browser fallback instead of blocking for minutes after a misleading 100% bar.
- Optional: mention port hygiene (
astro dev stop, zombie listeners) when capturing from localhost — wrong-port captures invalidated our first finish review.
Expected behavior
Finish screenshot capture should complete reliably on macOS without downloading a Playwright browser bundle, or fail fast with a documented fallback. Users should not need to pause an agent session and manually redirect it to an alternate toolchain.
Actual behavior
Playwright install appeared stuck after download completion; finish review blocked until manual user intervention and a puppeteer-core workaround.
Happy to provide logs, terminal output, or the workaround script path if useful. Repro is intermittent on the install stall, but the missing documented fallback is reproducible whenever an agent chooses Playwright for finish captures.
Summary
During a full
/impeccablehome-page build (Cursor agent, macOS), the finish step stalled on screenshot capture because the agent invoked Playwright to install Chromium. The download reached 100%, then the process sat silent for several minutes with no further progress. I had to pause the session and manually ask the agent to switch to a different approach before work could continue.This blocked the
new-work.mdfinish handoff that requires desktop + mobile screenshots forimpeccable-finish-reviewer.Environment
ekihana-stand), Impeccable skill ~4.0.4npx playwright@1.49.1 install chromium+npx playwright screenshot ...What happened
reference/new-work.mdand needed.impeccable/screenshots/mobile-home.png+desktop-home.png.oopDownloadBrowserMain.jsstill running/var/folders/.../playwright-download-chromium-mac15-arm64-1148.zip~/Library/Caches/ms-playwright/chromium-1148/still nearly empty (~432 KB)__dirlockpresent under~/Library/Caches/ms-playwright/User impact
impeccable-finish-reviewerwith valid captures.puppeteer-core+ system Google Chrome (/Applications/Google Chrome.app/...), no Playwright browser download. Screenshots landed in ~10s.Related issues observed (same session, separate root cause)
After screenshots finally worked, the first captures were wrong pages (unrelated Impeccable marketing HTML) because stale Astro/Vite processes were bound to localhost ports and returned generic Vite error pages. That is a port/zombie-server problem, not Playwright itself — but it made the finish reviewer reject the captures until ports were cleaned and the correct build was served.
There is also overlap with #435 (silent failure when puppeteer absent) — here the engine existed via system Chrome, but the finish flow does not document that path.
Why this feels like an Impeccable gap
reference/new-work.mdrequires screenshot capture before finish reviewer, but the skill does not ship a screenshot helper for that step.reference/critique.mdsays to prefer native/harness browser capture before hand-rolling Playwright/Puppeteer — agents still default to Playwright install when no native tool is obvious.scripts/detector/engines/browser/detect-url.mjsalready knows how to launch system Chrome viachannel: 'chrome'(Windows) / bundled fallback — that pattern is not reused for finish screenshots.Suggestions
scripts/capture-screenshots.mjs) usingpuppeteer-core+ system Chrome/Safari fallback, with explicit page verification (title or marker text) before writing PNGs.new-work.mdfinish section so agents do not attempt a fresh Playwright browser download mid-build.astro dev stop, zombie listeners) when capturing from localhost — wrong-port captures invalidated our first finish review.Expected behavior
Finish screenshot capture should complete reliably on macOS without downloading a Playwright browser bundle, or fail fast with a documented fallback. Users should not need to pause an agent session and manually redirect it to an alternate toolchain.
Actual behavior
Playwright install appeared stuck after download completion; finish review blocked until manual user intervention and a puppeteer-core workaround.
Happy to provide logs, terminal output, or the workaround script path if useful. Repro is intermittent on the install stall, but the missing documented fallback is reproducible whenever an agent chooses Playwright for finish captures.