@joeytheman/gemini-mcp-tool 2.2.0 → 2.3.1

package/dist/__tests__/live-pass.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
+import { execFileSync } from 'child_process';
 vi.mock('../utils/logger.js', () => ({
     Logger: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), log: vi.fn(), toolInvocation: vi.fn() },
 }));
@@ -16,15 +17,24 @@ const cleanSnapshot = (root = '/repo') => ({
     truncated: false,
 });
 const mockSnapshotWorkingTree = vi.fn().mockReturnValue(cleanSnapshot());
+const mockCountAgyModelSteps = vi.fn(async (_conversationId) => null);
+vi.mock('../utils/agyModelSteps.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, countAgyModelSteps: (id) => mockCountAgyModelSteps(id) };
+});
 vi.mock('../utils/gitStatusGuard.js', async (importOriginal) => {
     const actual = await importOriginal();
     return { ...actual, snapshotWorkingTree: (...args) => mockSnapshotWorkingTree(...args) };
 });
-import { livePassTool, livePassArgsSchema, livePassResultSchema, LIVE_PASS_RESULT_JSON_SCHEMA, buildLivePassPrompt, frameFileName, prescribedFrameNames, validateFrames, checkCoverage, deriveVerdict, runPublishCommand, } from '../tools/live-pass.tool.js';
-import { ERROR_MESSAGES, LIVE_PASS, MODELS } from '../constants.js';
+import { livePassTool, livePassArgsSchema, livePassResultSchema, LIVE_PASS_RESULT_JSON_SCHEMA, buildLivePassPrompt, frameFileName, prescribedFrameNames, prescribedTargetFiles, formatLayoutSection, readLayoutChecks, validateFrames, checkCoverage, deriveVerdict, runPublishCommand, writeCaptureScripts, } from '../tools/live-pass.tool.js';
+import { ERROR_MESSAGES, LAYOUT_CHECK_SNIPPET, LIVE_PASS, MODELS } from '../constants.js';
+import { readLayoutCheck } from '../utils/layoutCheck.js';
+import { buildCaptureScript, SCROLL_OVERFLOW_SNIPPET } from '../utils/captureScript.js';
 import { makeTempDir, cleanupTempDirs } from './utils/test-helpers.js';
 // ------------------------------------------------------------------ helpers
 const makeWorkDir = () => makeTempDir('live-pass');
+const PNG = fs.readFileSync(new URL('./fixtures/images/pixel.png', import.meta.url));
+const JPEG = fs.readFileSync(new URL('./fixtures/images/pixel.jpg', import.meta.url));
 const HOME_TARGET = {
     screen: 'home',
     state: 'default',
@@ -59,15 +69,37 @@ function makeResult(overrides = {}) {
 }
 const CLEAN_VALIDATION = { checks: [], okFiles: [], problems: [], notes: [], unreportedCaptures: [] };
 const CLEAN_COVERAGE = { uncovered: [], skipped: [], extraFrames: [] };
-function writeFrameFile(artifactDir, name) {
+function writeFrameFile(artifactDir, name, contents) {
     fs.mkdirSync(artifactDir, { recursive: true });
     const file = path.join(artifactDir, name);
-    fs.writeFileSync(file, 'PNG');
+    fs.writeFileSync(file, contents ?? (/\.png$/i.test(name) ? PNG : /\.jpe?g$/i.test(name) ? JPEG : 'not an image'));
     return file;
 }
 function writeManifest(artifactDir, frames) {
     fs.writeFileSync(path.join(artifactDir, LIVE_PASS.MANIFEST_FILE), JSON.stringify({ run_started: new Date().toISOString(), driver: 'playwright', frames, skipped: [] }));
 }
+function makeLayoutReport(overrides = {}) {
+    return {
+        check: LIVE_PASS.LAYOUT_CHECK_ID,
+        viewport: { width: 390, height: 844 },
+        found: 0,
+        entries: [],
+        clamped: [],
+        ...overrides,
+    };
+}
+const SPILL_ENTRY = {
+    kind: 'text-spill',
+    text: 'Uploaded to the studio wins wall',
+    testID: 'label',
+    rect: { x: 0, y: 0, width: 320, height: 20 },
+};
+function writeLayoutFile(artifactDir, frameName, contents) {
+    fs.mkdirSync(artifactDir, { recursive: true });
+    const file = path.join(artifactDir, frameName.replace(/\.png$/, LIVE_PASS.LAYOUT_FILE_SUFFIX));
+    fs.writeFileSync(file, typeof contents === 'string' ? contents : JSON.stringify(contents, null, 2));
+    return file;
+}
 function envelope(structured, overrides = {}) {
     return {
         conversation_id: 'conv-abc',
@@ -97,6 +129,10 @@ describe('livePassArgsSchema', () => {
         workingDirectory: '/tmp/project',
         driver: 'playwright',
     };
+    it('asks the caller\'s brief for the start URL and any link a user arrives by, with its source', () => {
+        expect(livePassArgsSchema.shape.brief.description).toContain("the app's start URL or app id, any link a user arrives by (an invite, email or share link) with where it comes from");
+        expect(livePassArgsSchema.shape.brief.description).not.toMatch(/entry url/i);
+    });
     it('applies the documented defaults', () => {
         const parsed = livePassArgsSchema.parse(minimal);
         expect(parsed.yolo).toBe(true);
@@ -122,6 +158,17 @@ describe('livePassArgsSchema', () => {
         });
         expect(parsed.targets).toHaveLength(2);
     });
+    it('rejects a playwright target whose viewport is not WxH, and lets maestro name a form factor', () => {
+        const phone = { ...HOME_TARGET, viewport: 'iPhone 15' };
+        const web = livePassArgsSchema.safeParse({ ...minimal, targets: [HOME_TARGET, phone] });
+        const native = livePassArgsSchema.safeParse({ ...minimal, driver: 'maestro', targets: [phone] });
+        expect(web.success).toBe(false);
+        expect(web.error?.issues).toEqual([expect.objectContaining({
+                path: ['targets', 1, 'viewport'],
+                message: `${ERROR_MESSAGES.LIVE_PASS_WEB_VIEWPORT}. Received 'iPhone 15'.`,
+            })]);
+        expect(native.success).toBe(true);
+    });
 });
 describe('LIVE_PASS_RESULT_JSON_SCHEMA', () => {
     it('has no $schema key and requires every result section', () => {
@@ -135,6 +182,11 @@ describe('LIVE_PASS_RESULT_JSON_SCHEMA', () => {
         const frames = LIVE_PASS_RESULT_JSON_SCHEMA.properties.frames;
         expect(frames.items.required).toEqual(expect.arrayContaining(['file', 'expected', 'observed', 'verdict']));
     });
+    it('offers link_source on a frame without requiring it', () => {
+        const frames = LIVE_PASS_RESULT_JSON_SCHEMA.properties.frames;
+        expect(frames.items.properties.link_source.type).toBe('string');
+        expect(frames.items.required).not.toContain('link_source');
+    });
 });
 // ------------------------------------------------------------------- prompt
 describe('frameFileName', () => {
@@ -162,10 +214,11 @@ describe('frameFileName', () => {
 });
 describe('buildLivePassPrompt', () => {
     const base = {
-        brief: 'Base URL http://localhost:8123; marker: footer BRANCH: smoke',
+        brief: 'Start URL http://localhost:8123; marker: footer BRANCH: feat/orders',
         targets: [HOME_TARGET, { ...HOME_TARGET, state: 'offline', expected: 'offline notice plus Retry' }],
         workingDirectory: '/work/tree',
         artifactDir: '/work/tree/.live-pass/run1',
+        checkout: { branch: 'feat/orders', head: '0123456789abcdef0123456789abcdef01234567' },
     };
     it('renders the targets as a numbered list with their expected state', () => {
         const prompt = buildLivePassPrompt({ ...base, driver: 'playwright', resumed: false });
@@ -176,9 +229,15 @@ describe('buildLivePassPrompt', () => {
     });
     it('carries the playwright procedure and the evidence discipline', () => {
         const prompt = buildLivePassPrompt({ ...base, driver: 'playwright', resumed: false });
-        expect(prompt).toContain('browser_take_screenshot');
+        expect(prompt).toContain('Capture it: browser_run_code_unsafe with filename set to the exact absolute path printed as "capture:" for that target below. Never pass code, never write, edit or read a capture file');
         expect(prompt).toContain('/work/tree/.live-pass/run1');
-        expect(prompt).toContain('never use fullPage');
+        expect(prompt).toContain('If a capture returns an error, add the target to "skipped" with the error text. Never fall back to browser_take_screenshot.');
+        expect(prompt).toContain('The capture sets the target\'s viewport and grows a scrolling screen taller, a few times at most and up to 4000 px, until its scroll area fits; a screen that still scrolls after that is shot as it stands.');
+        expect(prompt).toContain('an added "; layout not measured: <error>" or "; viewport not restored: <error>" still saved the frame.');
+        expect(prompt).not.toContain('full height');
+        expect(prompt).not.toContain('browser_resize');
+        expect(prompt).not.toContain('fullPage');
+        expect(prompt).not.toContain('320x568');
         expect(prompt).toContain('answer is ONLY the schema JSON');
         expect(prompt).toContain('a spinner, blank page, skeleton, error, or the wrong screen is a FAIL');
         expect(prompt).toContain('PASSES when it shows that state with everything "expected" names');
@@ -205,6 +264,7 @@ describe('buildLivePassPrompt', () => {
         expect(prompt).toContain('xcrun simctl io');
         expect(prompt).toContain('Never use take_screenshot for evidence');
         expect(prompt).not.toContain('browser_take_screenshot');
+        expect(prompt).not.toContain('browser_run_code_unsafe');
     });
     it('adds the delta paragraph only for a resumed pass', () => {
         const fresh = buildLivePassPrompt({ ...base, driver: 'playwright', resumed: false });
@@ -215,6 +275,296 @@ describe('buildLivePassPrompt', () => {
         expect(resumed).toContain('Never put an improvement in "findings" or "regressions"');
     });
 });
+describe('buildLivePassPrompt: context Gemini used to dig for', () => {
+    const base = {
+        brief: 'Start URL http://localhost:8123; marker: footer BRANCH: feat/orders',
+        targets: [HOME_TARGET, { ...HOME_TARGET, state: 'offline', expected: 'offline notice plus Retry' }],
+        workingDirectory: '/work/tree',
+        artifactDir: '/work/tree/.live-pass/run1',
+        checkout: { branch: 'feat/orders', head: '0123456789abcdef0123456789abcdef01234567' },
+        resumed: false,
+    };
+    it('prints the branch and HEAD read in code, and forbids running git to find them', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).toContain('- Checkout under test: feat/orders at 0123456789abcdef0123456789abcdef01234567. Read for you, so never run git.');
+        expect(prompt).toContain('The checkout above is context. Set BLOCKED over it only when the marker names a branch or commit that contradicts it. A detached HEAD never contradicts a branch name, and a short commit hash matches the full one it begins.');
+    });
+    it('names a detached HEAD instead of a branch', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright', checkout: { branch: null, head: 'abc1234' } });
+        expect(prompt).toContain('- Checkout under test: a detached HEAD at abc1234.');
+    });
+    it('falls back to the brief marker when the working directory is not a git checkout', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright', checkout: null });
+        expect(prompt).toContain("- Checkout under test: not a git checkout with a commit, so rely on the brief's marker alone.");
+    });
+    it('carries a parameter cheat sheet for every playwright tool the procedure uses', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).toContain('## Tool cheat sheet (the installed parameters: never read tool schemas or Playwright source)');
+        for (const line of [
+            '- browser_navigate {url}',
+            '- browser_click {target, element?, doubleClick?, button?, modifiers?}',
+            '- browser_type {target, text, submit?, slowly?}',
+            '- browser_fill_form {fields: [{target, name, type: textbox | checkbox | radio | combobox | slider, value}]}',
+            '- browser_select_option {target, values: [...]}',
+            '- browser_press_key {key}',
+            '- browser_handle_dialog {accept, promptText?}',
+            '- browser_wait_for {text? | textGone? | time?}',
+            '- browser_find {text | regex}',
+            '- browser_snapshot {target?, depth?, boxes?}',
+            '- browser_run_code_unsafe {filename}: filename is absolute.',
+            '- browser_evaluate {function, filename}: the return value is written to filename as JSON instead of returned to you.',
+        ]) {
+            expect(prompt).toContain(line);
+        }
+        expect(prompt).not.toContain('- browser_take_screenshot');
+        expect(prompt).toContain('a unique selector such as [data-testid="save"]');
+        expect(prompt).not.toContain('- inspect_screen {device_id}');
+    });
+    it('carries the maestro tool cheat sheet for the maestro driver instead', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'maestro' });
+        for (const line of [
+            '- list_devices {}',
+            '- run {device_id, yaml, env?}',
+            '- inspect_screen {device_id}',
+            '- take_screenshot {device_id}: returns an image inline; never evidence.',
+            '- cheat_sheet {}',
+        ]) {
+            expect(prompt).toContain(line);
+        }
+        expect(prompt).not.toContain('- browser_click {');
+    });
+    it('tells a web pass to answer native dialogs right after the triggering click', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).toContain('Native dialogs such as window.confirm and window.alert block the page: accept or dismiss each with browser_handle_dialog right after the click that opened it.');
+    });
+    it.each(['playwright', 'maestro'])('forbids code, database and git reads for the %s driver', (driver) => {
+        const prompt = buildLivePassPrompt({ ...base, driver });
+        expect(prompt).toContain('Never read product source, tests, docs, config, tool schemas or tool source. Never query a database.');
+        expect(prompt).toContain("Never run a shell command except the capture command the procedure names and removing a stale file at a target's own \"file:\" path.");
+        expect(prompt).toContain('Never read code to work out why something failed. Report what you saw.');
+        expect(prompt).toContain('never run a git command.');
+        expect(prompt).toContain('It is only where you run: read, list and glob nothing outside the artifact directory.');
+        expect(prompt).not.toContain('Working directory (read-only)');
+    });
+    it.each(['playwright', 'maestro'])('opens the %s app once and reaches every other target by taps from the previous screen', (driver) => {
+        const prompt = buildLivePassPrompt({ ...base, driver });
+        expect(prompt).toContain('## User path\n- The pass opens the app once, at its start URL (or by launching it on a device), as the brief names it.');
+        expect(prompt).toContain('- Every other target is reached by taps from the previous screen: sign in through the sign-in form, tap through the navigation, and fill and submit forms. Any other URL or deep link in the brief is context, never a navigation target.');
+        expect(prompt).toContain('- A reload, only where the brief makes one part of the path, opens the URL the page is already on.');
+        expect(prompt).toContain('- No script that clicks, navigates, or sets storage, cookies or app state for you.');
+    });
+    it.each(['playwright', 'maestro'])('lets a %s target begin at its own link only when the brief names the link the user arrives by, and has the frame quote its source', (driver) => {
+        const prompt = buildLivePassPrompt({ ...base, driver });
+        expect(prompt).toContain('- A target may begin at a link of its own only when the brief says the user arrives by that link, such as an invite, email or share link, and names where the link comes from. Open it as following that link would, and quote the brief\'s words naming the source in that frame\'s "link_source".');
+    });
+    it.each(['playwright', 'maestro'])('leaves no per-target entry URL or URL jump anywhere in the %s prompt', (driver) => {
+        const prompt = buildLivePassPrompt({ ...base, driver });
+        expect(prompt).not.toMatch(/entry url/i);
+        expect(prompt).not.toContain('deeper URL');
+        expect(prompt).not.toContain('walk on from wherever');
+        expect(prompt).not.toContain('Never use openLink to skip a user step.');
+    });
+    it('sends a web pass\'s browser_navigate only where the user path allows, and keeps browser_evaluate and run_code to the printed save functions and capture files', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).not.toContain("browser_navigate to the target's route");
+        expect(prompt).toContain('browser_navigate opens only the URLs the "User path" section allows.\nFor each target, in order:\n- Reach it as the "User path" section says.');
+        expect(prompt).toContain('browser_evaluate runs only the "save layout:" functions and browser_run_code_unsafe only the "capture:" files. Neither is used to click, type, navigate, or set storage, cookies or app state.');
+    });
+    it('has a maestro pass launch the app only at the start and openLink only for a link arrival', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'maestro' });
+        expect(prompt).toContain('- Reach each state as the "User path" section says, with inline YAML flows: launchApp only to open the app at the start, then tapOn and inputText; openLink only for a link arrival that section allows.');
+    });
+    it('locates web controls by testID, then browser_find, then a scoped snapshot', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).toContain('Locate each control cheaply, in this order: a testID the brief names, as target [data-testid="<testID>"]; then browser_find with its visible label; then browser_snapshot with a target and a small depth scoped to that region. Never take a full-page snapshot just to look around');
+    });
+    it.each(['playwright', 'maestro'])('reports a %s dead end with the broken step, and a missing fact as skipped', (driver) => {
+        const prompt = buildLivePassPrompt({ ...base, driver });
+        expect(prompt).toContain('add it to "skipped" with the step where the path broke, such as "step 3: tapped Save, nothing happened". A dead end a user would hit is also a finding.');
+        expect(prompt).toContain('add the target to "skipped" with "brief missing: <the fact>". Never search the code for it.');
+    });
+    it('prints each web target its own capture file, layout file and save function, and neither page snippet', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'playwright' });
+        expect(prompt).toContain([
+            '   file: /work/tree/.live-pass/run1/home-default-390x844.png',
+            '   capture: /work/tree/.live-pass/run1/home-default-390x844.capture.js',
+            '   layout: /work/tree/.live-pass/run1/home-default-390x844.layout.json',
+            '   save layout: () => window.__livePassLayout?.["home-default-390x844.png"]',
+        ].join('\n'));
+        expect(prompt).toContain([
+            '   file: /work/tree/.live-pass/run1/home-offline-390x844.png',
+            '   capture: /work/tree/.live-pass/run1/home-offline-390x844.capture.js',
+            '   layout: /work/tree/.live-pass/run1/home-offline-390x844.layout.json',
+            '   save layout: () => window.__livePassLayout?.["home-offline-390x844.png"]',
+        ].join('\n'));
+        expect(prompt).toContain('browser_evaluate with function set to the "save layout:" function printed for that target, copied verbatim, and filename set to the exact absolute path printed as "layout:" for that target. Do not open that file or report on it');
+        expect(prompt).not.toContain(LAYOUT_CHECK_SNIPPET);
+        expect(prompt).not.toContain(SCROLL_OVERFLOW_SNIPPET);
+        expect(prompt).not.toContain('getBoundingClientRect');
+    });
+    it('asks a maestro pass for no capture file or layout check', () => {
+        const prompt = buildLivePassPrompt({ ...base, driver: 'maestro' });
+        expect(prompt).not.toContain('capture:');
+        expect(prompt).not.toContain('layout:');
+        expect(prompt).not.toContain(LAYOUT_CHECK_SNIPPET);
+        expect(prompt).not.toContain(SCROLL_OVERFLOW_SNIPPET);
+    });
+});
+describe('prescribedTargetFiles', () => {
+    it('puts each capture and layout file next to its frame, sharing the frame stem and its collision suffix', () => {
+        const targets = [
+            { ...HOME_TARGET, screen: 'settings/profile' },
+            { ...HOME_TARGET, screen: 'settings-profile' },
+        ];
+        const files = prescribedTargetFiles(targets, '/art');
+        expect([...files.values()]).toEqual([
+            {
+                frameName: 'settings-profile-default-390x844.png',
+                frame: '/art/settings-profile-default-390x844.png',
+                capture: '/art/settings-profile-default-390x844.capture.js',
+                layout: '/art/settings-profile-default-390x844.layout.json',
+            },
+            {
+                frameName: 'settings-profile-default-390x844-2.png',
+                frame: '/art/settings-profile-default-390x844-2.png',
+                capture: '/art/settings-profile-default-390x844-2.capture.js',
+                layout: '/art/settings-profile-default-390x844-2.layout.json',
+            },
+        ]);
+    });
+});
+// ------------------------------------------------------------ layout checks
+describe('readLayoutCheck', () => {
+    const frameName = frameFileName(HOME_TARGET);
+    it('accepts a fresh, schema-valid file inside the artifact directory', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const report = makeLayoutReport({ found: 1, entries: [SPILL_ENTRY] });
+        const file = writeLayoutFile(artifactDir, frameName, report);
+        const check = readLayoutCheck(file, artifactDir, Date.now());
+        expect(check).toEqual({ file, status: 'OK', report });
+    });
+    it('reports a file that was never written as MISSING', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        fs.mkdirSync(artifactDir, { recursive: true });
+        const file = path.join(artifactDir, 'home-default-390x844.layout.json');
+        expect(readLayoutCheck(file, artifactDir, Date.now())).toEqual({ file, status: 'MISSING', problem: 'not written' });
+    });
+    it('reports a file left over from an earlier run as STALE', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, makeLayoutReport());
+        const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
+        fs.utimesSync(file, yesterday, yesterday);
+        expect(readLayoutCheck(file, artifactDir, Date.now())).toEqual({ file, status: 'STALE', problem: 'predates this run' });
+    });
+    it('accepts a file written within the freshness tolerance before the run clock', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, makeLayoutReport());
+        const runStartMs = fs.statSync(file).mtimeMs + LIVE_PASS.FRESHNESS_TOLERANCE_MS - 1;
+        expect(readLayoutCheck(file, artifactDir, runStartMs).status).toBe('OK');
+    });
+    it('reports a prescribed path symlinked out of the artifact directory as OUTSIDE', () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, 'frames');
+        fs.mkdirSync(artifactDir, { recursive: true });
+        const outside = writeLayoutFile(makeWorkDir(), frameName, makeLayoutReport());
+        const prescribed = path.join(artifactDir, path.basename(outside));
+        fs.symlinkSync(outside, prescribed);
+        expect(readLayoutCheck(prescribed, artifactDir, Date.now())).toEqual({
+            file: outside,
+            status: 'OUTSIDE',
+            problem: 'resolves outside the artifact directory',
+        });
+    });
+    it('reports an empty file as MALFORMED', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, '');
+        expect(readLayoutCheck(file, artifactDir, Date.now())).toEqual({ file, status: 'MALFORMED', problem: 'empty' });
+    });
+    it('reports a result measured at another width than the frame as MISMATCHED', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, makeLayoutReport({ viewport: { width: 1280, height: 800 } }));
+        expect(readLayoutCheck(file, artifactDir, Date.now(), 390)).toEqual({
+            file,
+            status: 'MISMATCHED',
+            problem: 'measured at width 1280, but the frame is 390 wide',
+        });
+    });
+    it('accepts a result measured at the frame width whatever the height, since a scrolling frame is resized taller', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const report = makeLayoutReport({ viewport: { width: 390, height: 2210 } });
+        const file = writeLayoutFile(artifactDir, frameName, report);
+        expect(readLayoutCheck(file, artifactDir, Date.now(), 390)).toEqual({ file, status: 'OK', report });
+    });
+    it('reports a file that is not JSON as MALFORMED', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, 'undefined');
+        expect(readLayoutCheck(file, artifactDir, Date.now())).toEqual({ file, status: 'MALFORMED', problem: 'not valid JSON' });
+    });
+    it.each([
+        ['another check id', { ...makeLayoutReport(), check: 'layout-check/0' }, 'check'],
+        ['an unknown kind', makeLayoutReport({ found: 1, entries: [{ ...SPILL_ENTRY, kind: 'ugly' }] }), 'entries.0.kind'],
+        ['text longer than 80 characters', makeLayoutReport({ found: 1, entries: [{ ...SPILL_ENTRY, text: 'x'.repeat(81) }] }), 'entries.0.text'],
+        ['more than 50 entries', makeLayoutReport({ found: 51, entries: Array(51).fill(SPILL_ENTRY) }), 'entries'],
+        ['a defect kind in the clamped list', makeLayoutReport({ clamped: [SPILL_ENTRY] }), 'clamped.0.kind'],
+    ])('reports a result with %s as MALFORMED', (_label, contents, issuePath) => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameName, contents);
+        const check = readLayoutCheck(file, artifactDir, Date.now());
+        expect(check.status).toBe('MALFORMED');
+        expect(check.report).toBeUndefined();
+        expect(check.problem).toContain(`not a ${LIVE_PASS.LAYOUT_CHECK_ID} result (${issuePath}:`);
+    });
+});
+describe('formatLayoutSection', () => {
+    it('lists each frame\'s entries, its intentional caps apart, a clean frame, and a frame never run', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const offline = { ...HOME_TARGET, state: 'offline' };
+        const empty = { ...HOME_TARGET, state: 'empty' };
+        writeLayoutFile(artifactDir, frameFileName(HOME_TARGET), makeLayoutReport({
+            found: 1,
+            entries: [SPILL_ENTRY],
+            clamped: [{ kind: 'text-clamped', text: 'Costume checklist', testID: null, rect: { x: 0, y: 40, width: 200, height: 40 } }],
+        }));
+        writeLayoutFile(artifactDir, frameFileName(offline), makeLayoutReport());
+        const section = formatLayoutSection(readLayoutChecks([HOME_TARGET, offline, empty], artifactDir, Date.now()));
+        expect(section).toBe([
+            '## Layout checks (measured in the page)',
+            '- home / default / 390x844: 1 entry',
+            '  - text-spill "Uploaded to the studio wins wall" testID=label at 0,0 320x20',
+            '  - capped (line clamp / ellipsis): text-clamped "Costume checklist" at 0,40 200x40',
+            '- home / offline / 390x844: clean',
+            `- home / empty / 390x844: not run (MISSING: ${path.join(artifactDir, 'home-empty-390x844.layout.json')} not written)`,
+        ].join('\n'));
+    });
+    it('shows a frame measured at the wrong width as not run, with both widths', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeLayoutFile(artifactDir, frameFileName(HOME_TARGET), makeLayoutReport({
+            viewport: { width: 1280, height: 800 }, found: 1, entries: [SPILL_ENTRY],
+        }));
+        const section = formatLayoutSection(readLayoutChecks([HOME_TARGET], artifactDir, Date.now()));
+        expect(section).toBe([
+            '## Layout checks (measured in the page)',
+            `- home / default / 390x844: not run (MISMATCHED: ${file} measured at width 1280, but the frame is 390 wide)`,
+        ].join('\n'));
+    });
+    it('marks a frame a framework dev overlay covered as polluted', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const overlay = { kind: 'dev-overlay', text: 'Uncaught Error', testID: null, rect: { x: 0, y: 0, width: 390, height: 844 } };
+        writeLayoutFile(artifactDir, frameFileName(HOME_TARGET), makeLayoutReport({ found: 1, entries: [overlay] }));
+        const section = formatLayoutSection(readLayoutChecks([HOME_TARGET], artifactDir, Date.now()));
+        expect(section).toBe([
+            '## Layout checks (measured in the page)',
+            '- home / default / 390x844: 1 entry (a framework dev overlay was on screen: this frame is polluted)',
+            '  - dev-overlay "Uncaught Error" at 0,0 390x844',
+        ].join('\n'));
+    });
+    it('says when the snippet found more entries than it listed', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        writeLayoutFile(artifactDir, frameFileName(HOME_TARGET), makeLayoutReport({ found: 73, entries: [SPILL_ENTRY] }));
+        const section = formatLayoutSection(readLayoutChecks([HOME_TARGET], artifactDir, Date.now()));
+        expect(section).toContain('- home / default / 390x844: 73 entries (73 found, first 1 listed)');
+    });
+});
 // --------------------------------------------------------------- validation
 describe('validateFrames', () => {
     it('accepts a fresh, non-empty frame inside the artifact directory', () => {
@@ -226,6 +576,14 @@ describe('validateFrames', () => {
         expect(validation.okFiles).toEqual([file]);
         expect(validation.problems).toEqual([]);
     });
+    it.each(['jpg', 'jpeg'])('accepts a real .%s frame', extension => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeFrameFile(artifactDir, `home-default.${extension}`);
+        writeManifest(artifactDir, [{ file }]);
+        const validation = validateFrames(makeResult({ frames: [makeFrame({ file })] }), artifactDir, Date.now());
+        expect(validation.checks[0].status).toBe('OK');
+        expect(validation.okFiles).toEqual([file]);
+    });
     it.each([
         ['MISSING', (dir) => path.join(dir, 'never-written.png')],
         ['EMPTY', (dir) => {
@@ -270,6 +628,32 @@ describe('validateFrames', () => {
         expect(validation.notes.join('\n')).toContain('MISNAMED');
         expect(validation.notes.join('\n')).toContain(frameFileName(HOME_TARGET));
     });
+    it.each([
+        ['a capture file', 'home-default-390x844.capture.js'],
+        ['a layout file', 'home-default-390x844.layout.json'],
+        ['text with a PNG extension', 'home-default-390x844.png'],
+        ['text with a JPEG extension', 'home-default-390x844.jpg'],
+    ])('rejects %s reported as a frame as NOT_IMAGE, and fails the pass', (_label, name) => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeFrameFile(artifactDir, name, 'not an image');
+        writeManifest(artifactDir, [{ file }]);
+        const result = makeResult({ frames: [makeFrame({ file })] });
+        const validation = validateFrames(result, artifactDir, Date.now(), [HOME_TARGET]);
+        const decision = deriveVerdict({ result, validation, coverage: CLEAN_COVERAGE, deniedActions: '' });
+        expect(validation.checks[0].status).toBe('NOT_IMAGE');
+        expect(validation.okFiles).toEqual([]);
+        expect(validation.problems).toEqual([`NOT_IMAGE: ${file} (home / default)`]);
+        expect(decision.verdict).toBe('FAIL');
+        expect(decision.reasons).toEqual([`NOT_IMAGE: ${file} (home / default)`]);
+    });
+    it('rejects JPEG bytes renamed to .png', () => {
+        const artifactDir = path.join(makeWorkDir(), 'frames');
+        const file = writeFrameFile(artifactDir, 'home-default-390x844.png', JPEG);
+        writeManifest(artifactDir, [{ file }]);
+        const validation = validateFrames(makeResult({ frames: [makeFrame({ file })] }), artifactDir, Date.now());
+        expect(validation.checks[0].status).toBe('NOT_IMAGE');
+        expect(validation.okFiles).toEqual([]);
+    });
     it('treats a directory reported as a frame as MISSING', () => {
         const artifactDir = path.join(makeWorkDir(), 'frames');
         const file = path.join(artifactDir, 'home-default.png');
@@ -713,10 +1097,150 @@ describe('live-pass execute', () => {
         expect(report).toContain('src/app/index.tsx');
     });
 });
+describe('live-pass execute: checkout, turns and layout checks', () => {
+    function passWithOneFrame(artifactDir, layout) {
+        mockExecuteAgyJson.mockImplementation(async () => {
+            const file = writeFrameFile(artifactDir, frameFileName(HOME_TARGET));
+            if (layout !== undefined)
+                writeLayoutFile(artifactDir, frameFileName(HOME_TARGET), layout);
+            writeManifest(artifactDir, [{ file }]);
+            return envelope(makeResult({ frames: [makeFrame({ file })] }), { num_turns: 9 });
+        });
+    }
+    it('reads the branch and HEAD of a git working directory into the prompt', async () => {
+        const workDir = makeWorkDir();
+        const git = (...args) => execFileSync('git', args, { cwd: workDir, encoding: 'utf-8' }).trim();
+        git('init', '--quiet', '--initial-branch', 'feat/served');
+        git('-c', 'user.email=t@example.com', '-c', 'user.name=t', 'commit', '--quiet', '--allow-empty', '-m', 'seed');
+        const head = git('rev-parse', 'HEAD');
+        mockExecuteAgyJson.mockResolvedValue(envelope(makeResult()));
+        await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir });
+        expect(mockExecuteAgyJson.mock.calls[0][0]).toContain(`- Checkout under test: feat/served at ${head}. Read for you, so never run git.`);
+    });
+    it('runs on a working directory that is not a git checkout', async () => {
+        const workDir = makeWorkDir();
+        mockExecuteAgyJson.mockResolvedValue(envelope(makeResult()));
+        await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir });
+        expect(mockExecuteAgyJson.mock.calls[0][0]).toContain("- Checkout under test: not a git checkout with a commit, so rely on the brief's marker alone.");
+    });
+    it("prints Gemini's model steps per frame, read from agy's store for this conversation, under the usage line", async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        passWithOneFrame(artifactDir);
+        mockCountAgyModelSteps.mockResolvedValueOnce(18);
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(mockCountAgyModelSteps).toHaveBeenLastCalledWith('conv-abc');
+        expect(report).toMatch(/\nUsage: 9 turns [^\n]*\n\nGemini steps: 18 \(18 per frame, 1 frame\)\n/);
+    });
+    it('prints the quoted link source under a frame that began at a link the user arrives by', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        mockExecuteAgyJson.mockImplementation(async () => {
+            const file = writeFrameFile(artifactDir, frameFileName(HOME_TARGET));
+            writeManifest(artifactDir, [{ file }]);
+            return envelope(makeResult({ frames: [makeFrame({ file, link_source: 'the invite email the studio owner sends' })] }));
+        });
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(report).toContain(`  file: ${path.join(artifactDir, frameFileName(HOME_TARGET))}\n  arrived by link: the invite email the studio owner sends\n  expected: heading 'Hello'`);
+    });
+    it('prints no link line under a frame reached by taps', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        passWithOneFrame(artifactDir);
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(report).toContain(`  file: ${path.join(artifactDir, frameFileName(HOME_TARGET))}\n  expected: heading 'Hello'`);
+        expect(report).not.toContain('arrived by link');
+    });
+    it('reports layout defects for the caller to judge without changing a PASS', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        passWithOneFrame(artifactDir, makeLayoutReport({ found: 1, entries: [SPILL_ENTRY] }));
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(report).toContain('# Live pass: PASS\n');
+        expect(report).toContain('## Why\n- none');
+        expect(report).toContain('## Layout checks (measured in the page)\n- home / default / 390x844: 1 entry\n  - text-spill "Uploaded to the studio wins wall" testID=label at 0,0 320x20');
+    });
+    it.each([
+        ['missing', undefined, 'MISSING'],
+        ['malformed', '{"check":', 'MALFORMED'],
+    ])('shows a %s layout file as not run, and still passes', async (_label, layout, status) => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        passWithOneFrame(artifactDir, layout);
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(report).toContain('# Live pass: PASS\n');
+        expect(report).toContain(`- home / default / 390x844: not run (${status}: `);
+        expect(report).not.toContain('layout.json (home');
+    });
+    it('never feeds layout entries into the derived verdict', async () => {
+        const workDir = makeWorkDir();
+        const clean = path.join(workDir, '.live-pass', 'clean');
+        const defective = path.join(workDir, '.live-pass', 'defective');
+        passWithOneFrame(clean, makeLayoutReport());
+        const cleanReport = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir: clean });
+        passWithOneFrame(defective, makeLayoutReport({ found: 50, entries: Array(50).fill(SPILL_ENTRY) }));
+        const defectiveReport = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir: defective });
+        expect(defectiveReport).toContain('- home / default / 390x844: 50 entries');
+        expect(cleanReport).toContain('- home / default / 390x844: clean');
+        const verdictAndWhy = (report) => report.slice(report.indexOf('# Live pass'), report.indexOf('## Served-branch check'));
+        expect(verdictAndWhy(defectiveReport).replace(defective, clean)).toBe(verdictAndWhy(cleanReport));
+    });
+    it('writes one capture script per web target at its prescribed path before agy runs', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        const wide = { ...HOME_TARGET, viewport: '1280x800' };
+        let writtenBeforeAgy = [];
+        mockExecuteAgyJson.mockImplementation(async () => {
+            writtenBeforeAgy = fs.readdirSync(artifactDir).sort();
+            return envelope(makeResult());
+        });
+        await run({ targets: [HOME_TARGET, wide], brief: 'b', driver: 'playwright', workingDirectory: workDir, artifactDir });
+        expect(writtenBeforeAgy).toEqual(['home-default-1280x800.capture.js', 'home-default-390x844.capture.js']);
+        for (const [stem, viewport] of [['home-default-390x844', { width: 390, height: 844 }], ['home-default-1280x800', { width: 1280, height: 800 }]]) {
+            expect(fs.readFileSync(path.join(artifactDir, `${stem}.capture.js`), 'utf-8')).toBe(buildCaptureScript({
+                viewport, frameFile: path.join(artifactDir, `${stem}.png`), key: `${stem}.png`,
+            }));
+        }
+    });
+    it('replaces a symlink at a capture path with a regular file, leaving the link\'s target untouched', () => {
+        const artifactDir = makeWorkDir();
+        const outside = path.join(makeWorkDir(), 'victim.txt');
+        fs.writeFileSync(outside, 'keep me');
+        const capture = path.join(artifactDir, 'home-default-390x844.capture.js');
+        fs.symlinkSync(outside, capture);
+        writeCaptureScripts([HOME_TARGET], artifactDir);
+        expect(fs.readFileSync(outside, 'utf-8')).toBe('keep me');
+        expect(fs.lstatSync(capture).isFile()).toBe(true);
+    });
+    it('writes no capture script for a maestro pass', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        mockExecuteAgyJson.mockResolvedValue(envelope(makeResult()));
+        await run({ targets: [HOME_TARGET], brief: 'b', driver: 'maestro', workingDirectory: workDir, artifactDir });
+        expect(fs.readdirSync(artifactDir)).toEqual([]);
+    });
+    it('refuses to write a capture script for a viewport that is not WxH', () => {
+        const artifactDir = makeWorkDir();
+        expect(() => writeCaptureScripts([{ ...HOME_TARGET, viewport: 'iPhone 15' }], artifactDir))
+            .toThrow(`${ERROR_MESSAGES.LIVE_PASS_WEB_VIEWPORT}. Received 'iPhone 15'.`);
+        expect(fs.readdirSync(artifactDir)).toEqual([]);
+    });
+    it('adds no layout section to a maestro pass', async () => {
+        const workDir = makeWorkDir();
+        const artifactDir = path.join(workDir, '.live-pass', 'run1');
+        passWithOneFrame(artifactDir);
+        const report = await run({ targets: [HOME_TARGET], brief: 'b', driver: 'maestro', workingDirectory: workDir, artifactDir });
+        expect(report).not.toContain('Layout checks');
+    });
+});
 describe('livePassResultSchema', () => {
     it('accepts a fresh pass with empty delta arrays', () => {
         expect(livePassResultSchema.safeParse(makeResult()).success).toBe(true);
     });
+    it('accepts a frame with a link_source and one without', () => {
+        const result = makeResult({ frames: [makeFrame(), makeFrame({ file: '/tmp/invite.png', link_source: 'the share link a teammate texts' })] });
+        expect(livePassResultSchema.safeParse(result).success).toBe(true);
+    });
     it('rejects a frame verdict outside PASS/FAIL', () => {
         const result = makeResult({ frames: [makeFrame({ verdict: 'BLOCKED' })] });
         expect(livePassResultSchema.safeParse(result).success).toBe(false);