pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.js

@@ -1,486 +1,161 @@
 import { stat } from "node:fs/promises";
+import { setTimeout as sleepMs } from "node:timers/promises";
 import { isAbsolute, resolve } from "node:path";
-import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
-import { isBrowserIndependentRead } from "../../command-policy.js";
-import { boundElectronProbeString } from "../../electron/cdp.js";
+import { isCloseCommand } from "../../command-taxonomy.js";
 import { executableExistsOnPath } from "../../executable-path.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
-import { buildInspectOverlayStateAction, buildNextToolAction, withOptionalSessionArgs } from "../../results/next-actions.js";
-import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget } from "../../results/selector-recovery.js";
-import { extractRefSnapshotFromData, isAboutBlankUrl, normalizeComparableUrl } from "../../session-page-state.js";
-import { redactInvocationArgs, redactSensitiveText } from "../../runtime.js";
+import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget, } from "../../results/selector-recovery.js";
+import { isAboutBlankUrl, normalizeComparableUrl, } from "../../session-page-state.js";
 import { isRecord } from "../../parsing.js";
-import { extractBatchResultCommand, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, runSessionCommandData, } from "./session-state.js";
-import { getUpstreamEffectiveBatchSteps } from "../batch-stdin.js";
-import { getExplicitArtifactDestination } from "./artifact-paths.js";
-const ELECTRON_FILL_VERIFICATION_TIMEOUT_MS = 2_000;
-export function sleepMs(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+import { extractNavigationSummaryFromData, extractStringResultField, runSessionCommandData, } from "./session-state.js";
+export { redactTimeoutPartialProgress } from "./timeout-progress.js";
+export { sleepMs };
+function comparePriorNavigationUrl(priorUrl, url) {
+    return priorUrl !== undefined && priorUrl !== ""
+        ? normalizeComparableUrl(priorUrl) !== normalizeComparableUrl(url)
+        : undefined;
+}
+function reusableNavigationTitle(options, url) {
+    const prior = options.priorTarget;
+    return options.reusePriorTitle !== false &&
+        prior !== undefined &&
+        prior.title !== undefined &&
+        prior.title !== "" &&
+        normalizeComparableUrl(prior.url) === normalizeComparableUrl(url)
+        ? prior.title
+        : undefined;
 }
 export async function collectNavigationSummary(options) {
-    const url = extractStringResultField(await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }), "url");
-    if (!url || !/^[a-z][a-z0-9+.-]*:/i.test(url))
+    const url = extractStringResultField(await runSessionCommandData({
+        args: ["get", "url"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    }), "url");
+    if (url === undefined || url === "" || !/^[a-z][a-z0-9+.-]*:/i.test(url)) {
         return undefined;
-    const urlChanged = options.priorTarget?.url ? normalizeComparableUrl(options.priorTarget.url) !== normalizeComparableUrl(url) : undefined;
-    if (isAboutBlankUrl(url))
+    }
+    const urlChanged = comparePriorNavigationUrl(options.priorTarget?.url, url);
+    if (isAboutBlankUrl(url)) {
         return { url, ...(urlChanged !== undefined ? { urlChanged } : {}) };
+    }
     // Reuse the title already observed for this exact URL instead of spending a second probe. Titles can
     // change without a URL change on SPAs, but this summary is only a "last observed" page label; the URL
     // stays live-probed on every call.
-    if (options.reusePriorTitle !== false && options.priorTarget?.title && normalizeComparableUrl(options.priorTarget.url) === normalizeComparableUrl(url)) {
-        return { title: options.priorTarget.title, url, urlChanged: false };
+    const priorTitle = reusableNavigationTitle(options, url);
+    if (priorTitle !== undefined) {
+        return { title: priorTitle, url, urlChanged: false };
     }
-    const title = extractStringResultField(await runSessionCommandData({ args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }), "title");
+    const title = extractStringResultField(await runSessionCommandData({
+        args: ["get", "title"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    }), "title");
     return { title, url, ...(urlChanged !== undefined ? { urlChanged } : {}) };
 }
-function extractScrollPositionSnapshot(data) {
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    if (!isRecord(result))
-        return undefined;
-    const scrollX = typeof result.scrollX === "number" ? result.scrollX : undefined;
-    const scrollY = typeof result.scrollY === "number" ? result.scrollY : undefined;
-    const innerHeight = typeof result.innerHeight === "number" ? result.innerHeight : undefined;
-    const innerWidth = typeof result.innerWidth === "number" ? result.innerWidth : undefined;
-    const scrollHeight = typeof result.scrollHeight === "number" ? result.scrollHeight : undefined;
-    const scrollWidth = typeof result.scrollWidth === "number" ? result.scrollWidth : undefined;
-    if (scrollX === undefined || scrollY === undefined || innerHeight === undefined || innerWidth === undefined || scrollHeight === undefined || scrollWidth === undefined)
-        return undefined;
-    const containers = Array.isArray(result.containers)
-        ? result.containers.flatMap((entry, index) => {
-            if (!isRecord(entry))
-                return [];
-            const rawId = typeof entry.id === "string" ? entry.id : undefined;
-            const id = rawId && /^\d+:[a-z][a-z0-9-]*(?:\[role=[a-z-]+\])?$/i.test(rawId) ? rawId : `sample-${index}`;
-            const scrollTop = typeof entry.scrollTop === "number" ? entry.scrollTop : undefined;
-            const scrollLeft = typeof entry.scrollLeft === "number" ? entry.scrollLeft : undefined;
-            return scrollTop !== undefined && scrollLeft !== undefined ? [{ id, scrollLeft, scrollTop }] : [];
-        })
-        : [];
-    return { containerCount: typeof result.containerCount === "number" ? result.containerCount : containers.length, containers, innerHeight, innerWidth, scrollHeight, scrollWidth, scrollX, scrollY };
-}
-const SCROLL_POSITION_EVAL = `(() => {
-  const viewport = {
-    scrollX: window.scrollX,
-    scrollY: window.scrollY,
-    innerHeight: window.innerHeight,
-    innerWidth: window.innerWidth,
-    scrollHeight: Math.max(document.documentElement?.scrollHeight || 0, document.body?.scrollHeight || 0),
-    scrollWidth: Math.max(document.documentElement?.scrollWidth || 0, document.body?.scrollWidth || 0),
-  };
-  const describe = (element, index) => {
-    const role = element.getAttribute("role") || "";
-    const id = element.tagName.toLowerCase();
-    return { id: String(index) + ":" + id + (role ? "[role=" + role + "]" : ""), scrollTop: element.scrollTop, scrollLeft: element.scrollLeft, area: element.clientWidth * element.clientHeight };
-  };
-  const containers = Array.from(document.querySelectorAll("body *"))
-    .filter((element) => element instanceof HTMLElement && (element.scrollHeight > element.clientHeight + 1 || element.scrollWidth > element.clientWidth + 1))
-    .map(describe)
-    .sort((left, right) => right.area - left.area)
-    .slice(0, 10)
-    .map(({ area, ...entry }) => entry);
-  return { ...viewport, containerCount: containers.length, containers };
-})()`;
-export async function collectScrollPositionSnapshot(options) {
-    return extractScrollPositionSnapshot(await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: SCROLL_POSITION_EVAL }));
-}
-function sameScrollPositionSnapshot(left, right) {
-    return left.scrollX === right.scrollX && left.scrollY === right.scrollY && left.scrollHeight === right.scrollHeight && left.scrollWidth === right.scrollWidth && left.containers.length === right.containers.length && left.containers.every((container, index) => {
-        const other = right.containers[index];
-        return other?.id === container.id && other.scrollTop === container.scrollTop && other.scrollLeft === container.scrollLeft;
-    });
-}
-export function buildUnsupportedScrollIntoViewRecovery(options) {
-    if (!["scrollintoview", "scrollinto"].includes(options.commandTokens[0] ?? "") || options.commandTokens.some((token) => token === "--help" || token === "-h"))
-        return undefined;
-    const match = /^text=(.+)$/s.exec(options.commandTokens[1] ?? "");
-    if (!match)
-        return undefined;
-    const text = redactSensitiveText(match[1]);
-    return {
-        error: "scrollintoview accepts a CSS selector, xpath=..., or a current @e… ref; text=... is not supported and can falsely report success without moving the page.",
-        nextActions: [
-            { id: "scroll-semantic-text-target", params: { args: withOptionalSessionArgs(options.sessionName, ["find", "text", text, "hover"]) }, reason: "Use the upstream semantic text locator; hover resolves and scrolls the matched element into view.", safety: "Hover may open a tooltip or menu. Use the snapshot/ref recovery instead when hover state could affect the workflow.", tool: "agent_browser" },
-            { id: "refresh-refs-for-scroll-target", params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) }, reason: "Capture a current element ref, then retry scrollintoview with that @e… ref.", safety: "Read-only snapshot; choose the intended current ref before retrying the scroll.", tool: "agent_browser" },
-        ],
-    };
-}
-export function buildScrollNoopDiagnostic(before, after) {
-    if (!before || !after || !sameScrollPositionSnapshot(before, after))
-        return undefined;
-    return {
-        after,
-        before,
-        message: "Scroll reported success, but the viewport and sampled scrollable containers did not change position.",
-        reason: "no-observed-scroll-position-change",
-        recommendations: [
-            "Run snapshot -i or screenshot to confirm what is visible before choosing the next action.",
-            "On dashboards and panes with nested scrolling, use scrollintoview <@ref> for a visible target or target the actual scrollable region instead of repeating page scrolls.",
-        ],
-    };
-}
-export function buildScrollNoopNextActions(sessionName) {
-    return [
-        { id: "inspect-after-noop-scroll", params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) }, reason: "Refresh interactive refs and inspect whether the intended target is inside a nested scroll container.", safety: "Do not assume repeated page scrolls will move dashboard panels or nested panes.", tool: "agent_browser" },
-        { id: "verify-noop-scroll-visually", params: { args: withOptionalSessionArgs(sessionName, ["screenshot"]) }, reason: "Capture the current viewport to verify whether the scroll actually changed visible content.", safety: "Use screenshot evidence before concluding a dense dashboard did or did not move.", tool: "agent_browser" },
-    ];
-}
-export function formatScrollNoopDiagnosticText(diagnostic) {
-    if (!diagnostic)
-        return undefined;
-    return ["Scroll diagnostic: no observed scroll movement.", `Reason: ${diagnostic.message}`, `Sampled scrollable containers: ${diagnostic.after.containers.length}/${diagnostic.after.containerCount}.`, ...diagnostic.recommendations.map((recommendation) => `- ${recommendation}`)].join("\n");
-}
-const COMBOBOX_FOCUS_EVAL = `(() => {
-  const isVisible = (element) => {
-    if (!(element instanceof HTMLElement)) return false;
-    const style = window.getComputedStyle(element);
-    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false;
-    return element.getClientRects().length > 0;
-  };
-  const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
-  const role = active?.getAttribute("role") || undefined;
-  const hasPopup = active?.getAttribute("aria-haspopup") || undefined;
-  const expanded = active?.getAttribute("aria-expanded") || undefined;
-  const tagName = active?.tagName.toLowerCase();
-  const name = (active?.getAttribute("aria-label") || active?.getAttribute("placeholder") || active?.getAttribute("title") || active?.textContent || "").trim().slice(0, 80) || undefined;
-  const visibleListboxCount = Array.from(document.querySelectorAll('[role="listbox"], [role="menu"]')).filter(isVisible).length;
-  const visibleOptionCount = Array.from(document.querySelectorAll('[role="option"], option, [role="menuitem"]')).filter(isVisible).length;
-  const comboboxLike = role === "combobox" || hasPopup === "listbox" || hasPopup === "menu" || tagName === "select" || active?.getAttribute("aria-autocomplete") !== null;
-  return { activeElement: active ? { expanded, hasPopup, name, role, tagName } : undefined, comboboxLike, visibleListboxCount, visibleOptionCount };
-})()`;
-function extractComboboxFocusDiagnostic(data) {
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    if (!isRecord(result) || result.comboboxLike !== true || !isRecord(result.activeElement))
-        return undefined;
-    const visibleListboxCount = typeof result.visibleListboxCount === "number" ? result.visibleListboxCount : 0;
-    const visibleOptionCount = typeof result.visibleOptionCount === "number" ? result.visibleOptionCount : 0;
-    const expanded = typeof result.activeElement.expanded === "string" ? result.activeElement.expanded : undefined;
-    if ((expanded !== "false" && expanded !== "true") || visibleListboxCount > 0 || visibleOptionCount > 0)
-        return undefined;
-    return {
-        activeElement: {
-            expanded,
-            hasPopup: typeof result.activeElement.hasPopup === "string" ? result.activeElement.hasPopup : undefined,
-            name: typeof result.activeElement.name === "string" ? redactSensitiveText(result.activeElement.name) : undefined,
-            role: typeof result.activeElement.role === "string" ? result.activeElement.role : undefined,
-            tagName: typeof result.activeElement.tagName === "string" ? result.activeElement.tagName : undefined,
-        },
-        message: "A combobox-like control is focused, but no listbox or option elements are visibly open.",
-        reason: "focused-combobox-without-visible-options",
-        recommendations: ["Run snapshot -i to inspect whether options appeared under a different role or portal.", "Try ArrowDown or Enter to open the option list before selecting, or use select/visible option refs when available."],
-        visibleListboxCount,
-        visibleOptionCount,
-    };
-}
-function isComboboxFocusDiagnosticCommand(command, commandTokens) {
-    const explicitlyTargetsCombobox = commandTokens.some((token) => /^(?:combobox|listbox)$/i.test(token));
-    if (!explicitlyTargetsCombobox)
-        return false;
-    if (command === "click" || command === "fill")
-        return true;
-    return command === "find" && commandTokens.some((token) => ["click", "fill"].includes(token));
-}
-function getCompiledSemanticActionRoleValue(compiled) {
-    if (compiled.locator !== "role")
-        return undefined;
-    const findIndex = compiled.args.indexOf("find");
-    if (findIndex < 0 || compiled.args[findIndex + 1] !== "role")
-        return undefined;
-    return compiled.args[findIndex + 2];
-}
-function isComboboxFocusDiagnosticSemanticAction(compiled) {
-    if (!compiled || !["click", "fill"].includes(compiled.action))
-        return false;
-    return /^(?:combobox|listbox)$/i.test(getCompiledSemanticActionRoleValue(compiled) ?? "");
-}
-export async function collectComboboxFocusDiagnostic(options) {
-    if (!isComboboxFocusDiagnosticCommand(options.command, options.commandTokens) && !isComboboxFocusDiagnosticSemanticAction(options.semanticAction))
-        return undefined;
-    return extractComboboxFocusDiagnostic(await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: COMBOBOX_FOCUS_EVAL }));
-}
-export function buildComboboxFocusNextActions(sessionName) {
-    return [
-        { id: "inspect-focused-combobox", params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) }, reason: "Inspect the focused combobox and any portal/listbox refs before choosing an option.", safety: "Prefer visible option refs or select when a native/selectable option list is exposed.", tool: "agent_browser" },
-        { id: "try-open-combobox-with-arrow", params: { args: withOptionalSessionArgs(sessionName, ["press", "ArrowDown"]) }, reason: "Many searchable comboboxes open their option list with ArrowDown after focus.", safety: "Use only when the focused combobox is still the intended control, then re-snapshot before selecting.", tool: "agent_browser" },
-        { id: "try-open-combobox-with-enter", params: { args: withOptionalSessionArgs(sessionName, ["press", "Enter"]) }, reason: "Some comboboxes open or confirm their option list with Enter after focus.", safety: "Enter may select a highlighted/default option; prefer ArrowDown first unless Enter is the app's expected opener.", tool: "agent_browser" },
-    ];
-}
-export function formatComboboxFocusDiagnosticText(diagnostic) {
-    if (!diagnostic)
-        return undefined;
-    const label = diagnostic.activeElement.name ? ` (${diagnostic.activeElement.name})` : "";
-    return [`Combobox diagnostic: focused combobox did not expose visible options${label}.`, `Reason: ${diagnostic.message}`, ...diagnostic.recommendations.map((recommendation) => `- ${recommendation}`)].join("\n");
-}
+export { collectScrollPositionSnapshot, buildUnsupportedScrollIntoViewRecovery, buildScrollNoopDiagnostic, buildScrollNoopNextActions, formatScrollNoopDiagnosticText, collectComboboxFocusDiagnostic, buildComboboxFocusNextActions, formatComboboxFocusDiagnosticText, } from "./interaction-diagnostics.js";
 function getRecordStartLikeCommand(command, commandTokens) {
-    if (command !== "record")
+    if (command !== "record") {
         return undefined;
+    }
     const subcommand = commandTokens[1]?.toLowerCase();
-    if (subcommand === "start")
+    if (subcommand === "start") {
         return "record start";
-    if (subcommand === "restart")
+    }
+    if (subcommand === "restart") {
         return "record restart";
+    }
     return undefined;
 }
 export async function collectRecordingDependencyWarning(options) {
-    if (!options.succeeded)
-        return undefined;
-    const recordCommand = getRecordStartLikeCommand(options.command, options.commandTokens);
-    if (!recordCommand)
-        return undefined;
-    if (await executableExistsOnPath("ffmpeg"))
-        return undefined;
-    return { command: recordCommand, dependency: "ffmpeg", message: `${recordCommand} reported a pending recording, but ffmpeg is not on PATH. Its output is unverified; install ffmpeg before starting a new recording.`, reason: "ffmpeg-missing-for-recording", recommendations: ["Install ffmpeg before recording; on macOS with Homebrew, brew install ffmpeg or brew install ffmpeg-full.", "Stop this recording, check the result, and start a new recording after ensuring Pi can find ffmpeg on PATH."] };
-}
-export function formatRecordingDependencyWarningText(warning) {
-    if (!warning)
+    if (!options.succeeded) {
         return undefined;
-    return ["Recording dependency warning: ffmpeg not found on PATH.", `Reason: ${warning.message}`, ...warning.recommendations.map((recommendation) => `- ${recommendation}`)].join("\n");
-}
-function getSnapshotRefRecord(data) {
-    return isRecord(data) && isRecord(data.refs) ? data.refs : undefined;
-}
-const OVERLAY_CLOSE_NAME_PATTERN = /(?:\b(?:close|dismiss|no thanks|not now|maybe later|hide|skip|continue without|x)\b|^\s*×\s*$)/i;
-const OVERLAY_CONTEXT_ROLES = new Set(["alertdialog", "dialog"]);
-const OVERLAY_ACTION_ROLES = new Set(["button", "link", "menuitem"]);
-const OVERLAY_BLOCKER_CANDIDATE_LIMIT = 3;
-function getOverlayBlockerCandidates(snapshotData) {
-    const refs = getSnapshotRefRecord(snapshotData);
-    if (!refs)
-        return [];
-    const hasOverlayContext = Object.values(refs).some((entry) => isRecord(entry) && OVERLAY_CONTEXT_ROLES.has((typeof entry.role === "string" ? entry.role : "").toLowerCase()));
-    if (!hasOverlayContext)
-        return [];
-    const candidates = [];
-    for (const [ref, entry] of Object.entries(refs)) {
-        if (!/^e\d+$/.test(ref) || !isRecord(entry))
-            continue;
-        const role = typeof entry.role === "string" ? entry.role : undefined;
-        const name = typeof entry.name === "string" ? entry.name : undefined;
-        if (!role || !OVERLAY_ACTION_ROLES.has(role.toLowerCase()) || !name || !OVERLAY_CLOSE_NAME_PATTERN.test(name))
-            continue;
-        candidates.push({ args: ["click", `@${ref}`], name, reason: `Visible ${role} ${JSON.stringify(name)} appears in a snapshot that also contains overlay/banner/dialog context.`, ref: `@${ref}`, role });
-        if (candidates.length >= OVERLAY_BLOCKER_CANDIDATE_LIMIT)
-            break;
     }
-    return candidates;
-}
-export function formatOverlayBlockerText(diagnostic) {
-    return ["Possible overlay blockers:", ...diagnostic.candidates.map((candidate) => `- ${candidate.ref}${candidate.role ? ` ${candidate.role}` : ""}${candidate.name ? ` ${JSON.stringify(candidate.name)}` : ""}: ${candidate.reason}`)].join("\n");
-}
-export function buildOverlayBlockerNextActions(options) {
-    return [buildInspectOverlayStateAction(options.sessionName), ...options.diagnostic.candidates.map((candidate, index) => ({ id: `try-overlay-blocker-candidate-${index + 1}`, params: { args: withOptionalSessionArgs(options.sessionName, candidate.args) }, reason: candidate.reason, safety: "Only click this if the candidate is clearly a close/dismiss control for an overlay that blocks the intended workflow.", tool: "agent_browser" }))];
-}
-export function collectSnapshotOverlayBlockerDiagnostic(data) {
-    const candidates = getOverlayBlockerCandidates(data);
-    const snapshot = extractRefSnapshotFromData(data);
-    if (candidates.length === 0 || !snapshot)
-        return undefined;
-    return { candidates, snapshot, summary: "Snapshot contains dialog/modal context plus likely close or dismiss controls; treat covered controls as potentially obstructed until the overlay state is resolved." };
-}
-export async function collectOverlayBlockerDiagnostic(options) {
-    if (options.command !== "click" || !isRecord(options.data) || typeof options.data.clicked !== "string")
-        return undefined;
-    if (!options.data.clicked.startsWith("@") && !options.data.clicked.startsWith("ref="))
-        return undefined;
-    const priorUrl = normalizeComparableUrl(options.priorTarget?.url);
-    const currentUrl = normalizeComparableUrl(options.navigationSummary?.url);
-    if (!priorUrl || !currentUrl || currentUrl !== priorUrl)
-        return undefined;
-    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-    const diagnostic = collectSnapshotOverlayBlockerDiagnostic(snapshotData);
-    if (!diagnostic)
-        return undefined;
-    return { ...diagnostic, summary: `Click completed but the page stayed on ${currentUrl}; a fresh snapshot contains likely overlay close/dismiss controls.` };
-}
-const SELECTOR_TEXT_VISIBILITY_CANDIDATE_LIMIT = 8;
-function buildVisibleTextProbeScript(selector) {
-    return `(() => {\n  const selector = ${JSON.stringify(selector)};\n  const isVisible = (element) => {\n    const style = window.getComputedStyle(element);\n    if (!style || style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse' || Number(style.opacity) === 0) return false;\n    return Array.from(element.getClientRects()).some((rect) => rect.width > 0 && rect.height > 0);\n  };\n  let matches = [];\n  try {\n    matches = Array.from(document.querySelectorAll(selector));\n  } catch (error) {\n    return JSON.stringify({ selector, error: error instanceof Error ? error.message : String(error) });\n  }\n  const visible = matches.filter(isVisible);\n  const trim = (value) => typeof value === 'string' ? value.trim().replace(/\\s+/g, ' ').slice(0, 200) : undefined;\n  const describeCandidate = (element) => {\n    const index = matches.indexOf(element);\n    const role = element.getAttribute('role');\n    const candidate = { index, tagName: element.tagName.toLowerCase(), textPreview: trim(element.textContent) };\n    if (role) candidate.role = role;\n    return candidate;\n  };\n  const visibleCandidates = visible.slice(0, ${SELECTOR_TEXT_VISIBILITY_CANDIDATE_LIMIT}).map(describeCandidate);\n  return JSON.stringify({ selector, matchCount: matches.length, visibleCount: visible.length, firstMatchVisible: matches[0] ? isVisible(matches[0]) : undefined, firstTextPreview: trim(matches[0]?.textContent), firstVisibleTextPreview: trim(visible[0]?.textContent), visibleCandidates });\n})()`;
-}
-function parseSelectorTextVisibilityCandidates(value) {
-    if (!Array.isArray(value))
-        return undefined;
-    const candidates = value.flatMap((entry) => {
-        if (!isRecord(entry) || typeof entry.index !== "number" || typeof entry.tagName !== "string")
-            return [];
-        const role = typeof entry.role === "string" && entry.role.length > 0 ? entry.role : undefined;
-        const textPreview = typeof entry.textPreview === "string" && entry.textPreview.length > 0 ? redactSensitiveText(entry.textPreview) : undefined;
-        return [{ index: entry.index, tagName: entry.tagName, ...(role ? { role } : {}), ...(textPreview ? { textPreview } : {}) }];
-    });
-    return candidates.length > 0 ? candidates : undefined;
-}
-function parseSelectorTextVisibilityProbe(data, selector) {
-    const result = extractStringResultField(data, "result");
-    if (!result)
+    const recordCommand = getRecordStartLikeCommand(options.command, options.commandTokens);
+    if (recordCommand === undefined) {
         return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(result);
     }
-    catch {
+    if (await executableExistsOnPath("ffmpeg")) {
         return undefined;
     }
-    if (!isRecord(parsed) || typeof parsed.error === "string")
-        return undefined;
-    const matchCount = typeof parsed.matchCount === "number" ? parsed.matchCount : undefined;
-    const visibleCount = typeof parsed.visibleCount === "number" ? parsed.visibleCount : undefined;
-    if (matchCount === undefined || visibleCount === undefined)
-        return undefined;
     return {
-        firstMatchVisible: typeof parsed.firstMatchVisible === "boolean" ? parsed.firstMatchVisible : undefined,
-        firstVisibleTextPreview: typeof parsed.firstVisibleTextPreview === "string" && parsed.firstVisibleTextPreview.length > 0 ? redactSensitiveText(parsed.firstVisibleTextPreview) : undefined,
-        matchCount,
-        selector,
-        visibleCandidates: parseSelectorTextVisibilityCandidates(parsed.visibleCandidates),
-        visibleCount,
+        command: recordCommand,
+        dependency: "ffmpeg",
+        message: `${recordCommand} reported a pending recording, but ffmpeg is not on PATH. Its output is unverified; install ffmpeg before starting a new recording.`,
+        reason: "ffmpeg-missing-for-recording",
+        recommendations: [
+            "Install ffmpeg before recording; on macOS with Homebrew, brew install ffmpeg or brew install ffmpeg-full.",
+            "Stop this recording, check the result, and start a new recording after ensuring Pi can find ffmpeg on PATH.",
+        ],
     };
 }
-function selectorMayExposeSensitiveLiteral(selector) {
-    return redactSensitiveText(selector) !== selector || /\[[^\]]*[~|^$*]?=\s*(?:"[^"]*"|'[^']*'|[^\]\s]+)\s*(?:[is]\s*)?\]/.test(selector);
-}
-async function collectSelectorTextVisibilityDiagnosticForSelector(options) {
-    const { selector } = options;
-    if (!selector || /^@e\d+$/.test(selector) || /^#[A-Za-z_][\w-]*$/.test(selector) || selectorMayExposeSensitiveLiteral(selector))
-        return undefined;
-    const probe = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildVisibleTextProbeScript(selector) });
-    const parsed = parseSelectorTextVisibilityProbe(probe, selector);
-    if (!parsed || parsed.matchCount <= 1 && parsed.firstMatchVisible !== false)
-        return undefined;
-    if (parsed.visibleCount === 0)
+export function formatRecordingDependencyWarningText(warning) {
+    if (!warning) {
         return undefined;
-    const visibleMatchNoun = `visible match${parsed.visibleCount === 1 ? "" : "es"}`;
-    const visibleMatchVerb = parsed.visibleCount === 1 ? "exists" : "exist";
-    const summary = parsed.firstMatchVisible === false
-        ? `Selector ${JSON.stringify(selector)} matched ${parsed.matchCount} elements; the first match is hidden while ${parsed.visibleCount} ${visibleMatchNoun} ${visibleMatchVerb}.`
-        : `Selector ${JSON.stringify(selector)} matched ${parsed.matchCount} elements; get text reads the first upstream match, which may not be the intended visible tab/panel.`;
-    return { ...parsed, summary };
-}
-function getBatchGetTextSelectors(data) {
-    if (!Array.isArray(data))
-        return [];
-    return data.flatMap((item) => {
-        if (!isRecord(item) || item.success === false)
-            return [];
-        const [command, subcommand, selector] = extractBatchResultCommand(item);
-        return command === "get" && subcommand === "text" && selector ? [selector] : [];
-    });
-}
-function getSuccessfulGetTextSelectors(options) {
-    return options.commandInfo.command === "get" && options.commandInfo.subcommand === "text"
-        ? [options.commandTokens[2]].filter((selector) => typeof selector === "string" && selector.length > 0)
-        : options.commandInfo.command === "batch" ? getBatchGetTextSelectors(options.data) : [];
-}
-export async function collectSelectorTextVisibilityDiagnostics(options) {
-    const selectors = getSuccessfulGetTextSelectors(options);
-    const diagnostics = [];
-    for (const selector of selectors) {
-        const diagnostic = await collectSelectorTextVisibilityDiagnosticForSelector({ cwd: options.cwd, namespace: options.namespace, selector, sessionName: options.sessionName, signal: options.signal });
-        if (diagnostic)
-            diagnostics.push(diagnostic);
     }
-    return diagnostics.sort((left, right) => Number(right.firstMatchVisible === false) - Number(left.firstMatchVisible === false));
-}
-export function formatSelectorTextVisibilityText(diagnostics) {
-    if (diagnostics.length === 0)
-        return undefined;
-    return diagnostics.flatMap((diagnostic, index) => {
-        const actionId = index === 0 ? "inspect-visible-text-candidates" : `inspect-visible-text-candidates-${index + 1}`;
-        const lines = [`Selector text visibility warning: ${diagnostic.summary}`];
-        if (diagnostic.firstVisibleTextPreview)
-            lines.push(`First visible text preview: ${JSON.stringify(diagnostic.firstVisibleTextPreview)}`);
-        if (diagnostic.visibleCandidates && diagnostic.visibleCandidates.length > 0) {
-            lines.push(`Visible candidates (${diagnostic.visibleCandidates.length} shown, querySelectorAll index):`);
-            for (const candidate of diagnostic.visibleCandidates) {
-                const rolePart = candidate.role ? ` role=${candidate.role}` : "";
-                const previewPart = candidate.textPreview ? `: ${JSON.stringify(candidate.textPreview)}` : "";
-                lines.push(`- [${candidate.index}] ${candidate.tagName}${rolePart}${previewPart}`);
-            }
-        }
-        lines.push(`Next action: use details.nextActions ${actionId} before trusting this selector text.`);
-        return lines;
-    }).join("\n");
-}
-export function buildSelectorTextVisibilityNextActions(options) {
-    return options.diagnostics.map((diagnostic, index) => ({ id: index === 0 ? "inspect-visible-text-candidates" : `inspect-visible-text-candidates-${index + 1}`, params: { args: withOptionalSessionArgs(options.sessionName, ["eval", "--stdin"]), stdin: buildVisibleTextProbeScript(diagnostic.selector) }, reason: "Inspect selector match count and visible text before trusting get text on tabbed or hidden DOM content.", safety: "Read-only DOM inspection; use a more specific visible selector or current @ref before acting on hidden-tab text.", tool: "agent_browser" }));
-}
-function normalizeSelectorForScopeHeuristic(selector) {
-    return selector.trim().replace(/\s+/g, " ").toLowerCase();
-}
-function isBroadGetTextSelector(selector) {
-    if (!selector || /^@e\d+$/.test(selector) || selectorMayExposeSensitiveLiteral(selector))
-        return false;
-    const normalized = normalizeSelectorForScopeHeuristic(selector);
-    return normalized === "body" || normalized === "html" || normalized === ":root" || normalized === "*" || normalized === "main" || normalized === "div" || normalized === "section" || normalized === "article" || /^\[role=(?:"application"|'application'|application)\]$/i.test(normalized);
-}
-function getElectronTextScopeContext(options) {
-    const record = findElectronLaunchRecordForSession(options.sessionName, options.electronLaunchRecords, options.namespace);
-    if (!record)
-        return undefined;
-    const url = options.currentTarget?.url ?? options.priorTarget?.url;
-    return { launchId: record.launchId, sessionName: record.sessionName ?? options.sessionName, url };
-}
-export function getSourceLookupElectronContext(options) {
-    const record = findElectronLaunchRecordForSession(options.sessionName, options.electronLaunchRecords, options.namespace);
-    if (!record)
-        return undefined;
-    const url = options.currentTarget?.url ?? options.priorTarget?.url;
-    return { appName: record.appName, appPath: record.appPath, executablePath: record.executablePath, launchId: record.launchId, sessionName: record.sessionName ?? options.sessionName, url };
-}
-export function buildSourceLookupElectronNextActions(sourceLookup) {
-    if (sourceLookup?.status !== "no-candidates" || !sourceLookup.electronContext)
-        return [];
-    const actions = [];
-    const { launchId, sessionName } = sourceLookup.electronContext;
-    if (sessionName)
-        actions.push({ id: "snapshot-electron-session", params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) }, reason: "Refresh interactive refs in the attached Electron session before retrying source lookup with a narrower target.", safety: "Read-only snapshot; no app mutation.", tool: "agent_browser" });
-    if (launchId)
-        actions.push({ id: "probe-electron-launch", params: { action: "probe", launchId }, reason: "Collect bounded wrapper/session context for the packaged Electron launch after sourceLookup found no candidates.", safety: "Read-only probe of title, URL, focus, tabs, and compact snapshot metadata.", tool: "agent_browser_electron" });
-    if (sessionName)
-        actions.push({ id: "list-electron-tabs", params: { args: withOptionalSessionArgs(sessionName, ["tab", "list"]) }, reason: "Check current Electron tabs/targets before choosing a narrower selector or @ref.", safety: "Read-only tab listing.", tool: "agent_browser" });
-    return actions;
-}
-export function collectElectronBroadGetTextScopeDiagnostics(options) {
-    const electronContext = getElectronTextScopeContext(options);
-    if (!electronContext)
-        return [];
-    return getSuccessfulGetTextSelectors(options).filter(isBroadGetTextSelector).map((selector) => ({ electronContext, selector, summary: `Broad Electron get text selector warning: selector ${JSON.stringify(selector)} may read the entire app shell; prefer snapshot -i and a current @ref or a narrower panel selector.` }));
-}
-export function formatElectronBroadGetTextScopeText(diagnostics) {
-    return diagnostics.length > 0 ? diagnostics.map((diagnostic) => diagnostic.summary).join("\n") : undefined;
-}
-export function buildElectronBroadGetTextScopeNextActions(options) {
-    return options.diagnostics.map((diagnostic, index) => ({ id: index === 0 ? "snapshot-for-electron-text-scope" : `snapshot-for-electron-text-scope-${index + 1}`, params: { args: withOptionalSessionArgs(options.sessionName, ["snapshot", "-i"]) }, reason: `Refresh Electron refs before trusting broad get text selector ${JSON.stringify(diagnostic.selector)}.`, safety: "Read-only snapshot; prefer a current @ref or narrower selector before extracting app-shell text.", tool: "agent_browser" }));
-}
+    return [
+        "Recording dependency warning: ffmpeg not found on PATH.",
+        `Reason: ${warning.message}`,
+        ...warning.recommendations.map((recommendation) => `- ${recommendation}`),
+    ].join("\n");
+}
+export { formatOverlayBlockerText, buildOverlayBlockerNextActions, collectSnapshotOverlayBlockerDiagnostic, collectOverlayBlockerDiagnostic, } from "./overlay-diagnostics.js";
+export { collectSelectorTextVisibilityDiagnostics, formatSelectorTextVisibilityText, buildSelectorTextVisibilityNextActions, } from "./text-visibility-diagnostics.js";
+export { getSourceLookupElectronContext, buildSourceLookupElectronNextActions, collectElectronBroadGetTextScopeDiagnostics, formatElectronBroadGetTextScopeText, buildElectronBroadGetTextScopeNextActions, } from "./electron-text-diagnostics.js";
 function looksLikeFunctionEvalStdin(stdin) {
     const trimmed = stdin?.trim();
-    if (!trimmed)
+    if (trimmed === undefined || trimmed === "") {
         return false;
-    return /^(?:async\s+)?function\b/.test(trimmed) || /^(?:async\s*)?\([^)]*\)\s*=>/.test(trimmed) || /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed);
+    }
+    return (/^(?:async\s+)?function\b/.test(trimmed) ||
+        /^(?:async\s*)?\([^)]*\)\s*=>/.test(trimmed) ||
+        /^(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(trimmed));
 }
 function isPlainEmptyObject(value) {
-    if (!isRecord(value) || Array.isArray(value))
+    if (!isRecord(value) || Array.isArray(value)) {
         return false;
+    }
     const prototype = Object.getPrototypeOf(value);
     return (prototype === Object.prototype || prototype === null) && Object.keys(value).length === 0;
 }
 export function getEvalStdinHint(options) {
-    if (options.command !== "eval" || !looksLikeFunctionEvalStdin(options.stdin) || !isRecord(options.data))
-        return undefined;
+    if (options.command !== "eval" ||
+        !looksLikeFunctionEvalStdin(options.stdin) ||
+        !isRecord(options.data)) {
+        return;
+    }
     const result = options.data.result;
-    if (!isPlainEmptyObject(result))
-        return undefined;
-    return { reason: "eval --stdin received a function-shaped snippet and the upstream JSON result was an empty object, which often means the function itself was returned or serialized instead of invoked.", suggestion: "Pass a plain expression such as `({ title: document.title })`, or invoke the function explicitly, for example `(() => ({ title: document.title }))()`." };
+    if (!isPlainEmptyObject(result)) {
+        return;
+    }
+    return {
+        reason: "eval --stdin received a function-shaped snippet and the upstream JSON result was an empty object, which often means the function itself was returned or serialized instead of invoked.",
+        suggestion: "Pass a plain expression such as `({ title: document.title })`, or invoke the function explicitly, for example `(() => ({ title: document.title }))()`.",
+    };
 }
 export function formatEvalStdinHintText(hint) {
     return hint ? `Eval stdin hint: ${hint.reason} ${hint.suggestion}` : undefined;
 }
+function localEvalPageUrl(options) {
+    const pageUrl = options.pageUrl?.trim() ??
+        options.navigationSummary?.url?.trim() ??
+        extractNavigationSummaryFromData(options.data)?.url;
+    return pageUrl !== undefined && pageUrl !== "" && /^file:/i.test(pageUrl) ? pageUrl : undefined;
+}
 export function getEvalResultWarning(options) {
-    if (options.command !== "eval" || !options.stdin?.trim() || !isRecord(options.data) || options.data.result !== null)
-        return undefined;
-    const pageUrl = options.pageUrl?.trim() ?? options.navigationSummary?.url?.trim() ?? extractNavigationSummaryFromData(options.data)?.url;
-    if (!pageUrl || !/^file:/i.test(pageUrl))
-        return undefined;
-    const trimmed = options.stdin.trim();
-    if (/^(?:null|undefined)$/i.test(trimmed))
-        return undefined;
+    const trimmed = options.stdin?.trim();
+    if (options.command !== "eval" ||
+        trimmed === undefined ||
+        trimmed === "" ||
+        !isRecord(options.data) ||
+        options.data.result !== null ||
+        /^(?:null|undefined)$/i.test(trimmed) ||
+        localEvalPageUrl(options) === undefined) {
+        return;
+    }
     return {
         reason: "eval --stdin returned null on a file:// page; upstream may not expose full DOM semantics for local fixtures.",
         suggestion: "Treat this as inconclusive verification. Use snapshot -i, get text on current @refs, screenshot evidence, or a reachable http(s) fixture before concluding DOM state.",
@@ -489,22 +164,21 @@ export function getEvalResultWarning(options) {
 export function formatEvalResultWarningText(warning) {
     return warning ? `Eval result warning: ${warning.reason} ${warning.suggestion}` : undefined;
 }
-export async function getArtifactCleanupGuidance(options) {
-    if (!options.succeeded || !isCloseCommand(options.command) || !options.manifest)
-        return undefined;
-    const explicitEntries = options.manifest.entries.filter((entry) => entry.storageScope === "explicit-path");
-    if (explicitEntries.length === 0)
-        return undefined;
+async function collectExistingExplicitArtifactPaths(entries, cwd) {
     const explicitArtifactPaths = [];
     const seenPaths = new Set();
-    for (const entry of explicitEntries) {
-        if (explicitArtifactPaths.length >= 10)
+    for (const entry of entries) {
+        if (explicitArtifactPaths.length >= 10) {
             break;
+        }
         const displayPath = entry.path;
-        if (seenPaths.has(displayPath))
+        if (seenPaths.has(displayPath)) {
             continue;
-        const absolutePath = entry.absolutePath ?? (isAbsolute(entry.path) ? entry.path : resolve(options.cwd, entry.path));
+        }
+        const absolutePath = entry.absolutePath ?? (isAbsolute(entry.path) ? entry.path : resolve(cwd, entry.path));
         try {
+            // The first ten existing distinct display paths are selected in manifest order.
+            // oxlint-disable-next-line no-await-in-loop
             await stat(absolutePath);
         }
         catch {
@@ -513,357 +187,54 @@ export async function getArtifactCleanupGuidance(options) {
         seenPaths.add(displayPath);
         explicitArtifactPaths.push(displayPath);
     }
-    if (explicitArtifactPaths.length === 0)
-        return undefined;
-    return { explicitArtifactPaths, note: "Closing the browser session does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; clean existing paths with host file tools when no longer needed.", owner: "host-file-tools", summary: formatSessionArtifactRetentionSummary(options.manifest) };
+    return explicitArtifactPaths;
 }
-export function formatArtifactCleanupGuidanceText(guidance) {
-    if (!guidance || guidance.explicitArtifactPaths.length === 0)
-        return undefined;
-    const explicitCount = guidance.explicitArtifactPaths.length;
-    return `Artifact lifecycle: ${explicitCount} explicit artifact${explicitCount === 1 ? "" : "s"} remain${explicitCount === 1 ? "s" : ""}; expand or inspect details.artifactCleanup.explicitArtifactPaths for paths. Browser close does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; use host file tools for cleanup.`;
-}
-async function collectManagedSessionCommandData(options) {
-    try {
-        return { data: await runSessionCommandData({ ...options, pinNamespace: true }) };
-    }
-    catch (error) {
-        return { error: error instanceof Error ? error.message : String(error) };
-    }
-}
-async function collectElectronManagedSessionUrl(options) {
-    const urlResult = await collectManagedSessionCommandData({
-        args: ["get", "url"],
-        cwd: options.cwd,
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: options.signal,
-        timeoutMs: options.timeoutMs,
-    });
-    const url = boundElectronProbeString(extractStringResultField(urlResult.data, "result") ?? extractStringResultField(urlResult.data, "url"), 300);
-    return urlResult.error ? { error: urlResult.error } : { url };
-}
-export async function collectElectronManagedSessionTarget(options) {
-    if (!options.sessionName)
-        return undefined;
-    const urlResult = await collectManagedSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
-    const url = boundElectronProbeString(extractStringResultField(urlResult.data, "result") ?? extractStringResultField(urlResult.data, "url"), 300);
-    if (urlResult.error || !url)
-        return { error: urlResult.error ?? "get url returned no active page URL.", sessionName: options.sessionName };
-    const titleResult = await collectManagedSessionCommandData({ args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
-    const title = boundElectronProbeString(extractStringResultField(titleResult.data, "result") ?? extractStringResultField(titleResult.data, "title"), 160);
-    return { sessionName: options.sessionName, title, url, ...(titleResult.error ? { error: titleResult.error } : {}) };
-}
-export async function collectQaAttachedTarget(options) {
-    if (!options.sessionName)
-        return undefined;
-    if (options.currentTarget?.title || options.currentTarget?.url)
-        return { sessionName: options.sessionName, title: options.currentTarget.title, url: options.currentTarget.url };
-    return collectElectronManagedSessionTarget({ cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-}
-export function formatQaAttachedTargetText(target) {
-    if (!target)
+export async function getArtifactCleanupGuidance(options) {
+    if (!options.succeeded || !isCloseCommand(options.command) || !options.manifest) {
         return undefined;
-    return ["QA attached target:", target.sessionName, target.title, target.url].filter((part) => typeof part === "string" && part.length > 0).join(" — ");
-}
-function buildQaAttachedRecoveryNextActions(sessionName) {
-    const sessionArgs = (args) => withOptionalSessionArgs(sessionName, args);
-    return [
-        buildNextToolAction({
-            args: sessionArgs(["tab", "list"]),
-            id: "list-tabs-before-qa-attached",
-            reason: "Inspect the connected session tabs before retrying qa.attached.",
-            safety: "Read-only tab listing for the attached session.",
-        }),
-        buildNextToolAction({
-            args: sessionArgs(["snapshot", "-i"]),
-            id: "snapshot-before-qa-attached",
-            reason: "Capture interactive refs on the active page before retrying qa.attached.",
-            safety: "Read-only snapshot; confirms a renderable page is selected.",
-        }),
-    ];
-}
-export async function validateQaAttachedPrecondition(options) {
-    if (!options.sessionName) {
-        return {
-            error: "qa.attached requires an active attached session with a resolvable session name.",
-            nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
-        };
-    }
-    const urlProbe = await collectElectronManagedSessionUrl({ cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-    if (urlProbe.error) {
-        return {
-            error: `qa.attached could not read the attached session URL: ${urlProbe.error}. Run tab list or snapshot -i before retrying qa.attached.`,
-            nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
-        };
     }
-    const url = urlProbe.url?.trim();
-    if (!url) {
-        return {
-            error: "qa.attached requires an attached session with a readable page URL. Run tab list, select a stable tab, then snapshot -i before retrying.",
-            nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
-        };
-    }
-    return undefined;
-}
-function getTopLevelFillInvocation(commandTokens) {
-    if (commandTokens[0] !== "fill" || commandTokens.length < 3)
-        return undefined;
-    const selector = commandTokens[1];
-    const expected = commandTokens.slice(2).join(" ");
-    const refId = selector?.match(/^@?(e\d+)$/)?.[1];
-    return selector && expected.length > 0 ? { expected, ...(refId ? { refId } : {}), selector } : undefined;
-}
-function shouldVerifyContenteditableFill(fill, refSnapshot) {
-    if (!fill?.refId)
-        return false;
-    const ref = refSnapshot?.refs?.[fill.refId];
-    if (!ref)
-        return false;
-    return ref.isContentEditable === true && (ref.role === "generic" || ref.role === "unknown" || ref.role === "textbox");
-}
-export function buildFillVerificationNextActions(diagnostic, sessionName) {
-    return [
-        { id: "inspect-after-fill-verification", params: { args: withOptionalSessionArgs(sessionName, ["snapshot", "-i"]) }, reason: "Refresh the UI after a fill that reported success but did not appear to update the target.", safety: "Read-only snapshot; use current refs before retrying.", tool: "agent_browser" },
-        { id: "verify-filled-value", params: { args: withOptionalSessionArgs(sessionName, ["get", diagnostic.method, diagnostic.selector]) }, reason: `Check the target ${diagnostic.method} directly before submitting or creating files.`, safety: "Read-only check; selector may still be stale if the UI rerendered.", tool: "agent_browser" },
-    ];
-}
-function extractFillVerificationValue(data) {
-    if (typeof data === "string")
-        return data;
-    if (!isRecord(data))
-        return undefined;
-    if (typeof data.value === "string")
-        return data.value;
-    if (typeof data.result === "string")
-        return data.result;
-    return undefined;
-}
-export async function collectFillVerificationDiagnostic(options) {
-    const fill = getTopLevelFillInvocation(options.commandTokens);
-    if (!fill || !options.sessionName)
-        return undefined;
-    const contenteditable = shouldVerifyContenteditableFill(fill, options.refSnapshot);
-    if (!contenteditable && !options.forceValueVerification)
+    const explicitEntries = options.manifest.entries.filter((entry) => entry.storageScope === "explicit-path");
+    if (explicitEntries.length === 0) {
         return undefined;
-    const method = contenteditable ? "text" : "value";
-    let valueData;
-    try {
-        valueData = await runSessionCommandData({ args: ["get", method, fill.selector], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, timeoutMs: ELECTRON_FILL_VERIFICATION_TIMEOUT_MS });
     }
-    catch {
+    const explicitArtifactPaths = await collectExistingExplicitArtifactPaths(explicitEntries, options.cwd);
+    if (explicitArtifactPaths.length === 0) {
         return undefined;
     }
-    const actual = extractFillVerificationValue(valueData);
-    if (actual === undefined || actual === fill.expected)
-        return undefined;
-    const reason = contenteditable ? "contenteditable-fill-mismatch" : "value-fill-mismatch";
-    const actualPreview = actual.length > 0 ? `"${boundElectronProbeString(actual, 80)}"` : `an empty ${method}`;
-    const diagnostic = { actual: actual.length > 0 ? boundElectronProbeString(actual, 160) : "", expected: boundElectronProbeString(fill.expected, 160) ?? fill.expected, method, nextActionIds: [], reason, selector: fill.selector, status: "mismatch", summary: `Fill verification warning: fill ${fill.selector} reported success, but get ${method} returned ${actualPreview}.` };
-    diagnostic.nextActionIds = buildFillVerificationNextActions(diagnostic, options.sessionName).map((action) => action.id);
-    return diagnostic;
+    return {
+        explicitArtifactPaths,
+        note: "Closing the browser session does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; clean existing paths with host file tools when no longer needed.",
+        owner: "host-file-tools",
+        summary: formatSessionArtifactRetentionSummary(options.manifest),
+    };
 }
-export function formatFillVerificationText(diagnostic) {
-    if (!diagnostic)
+export function formatArtifactCleanupGuidanceText(guidance) {
+    if (!guidance || guidance.explicitArtifactPaths.length === 0) {
         return undefined;
-    const actual = diagnostic.actual !== undefined ? `actual "${diagnostic.actual}"` : `actual ${diagnostic.method} unavailable`;
-    const recovery = diagnostic.reason === "contenteditable-fill-mismatch"
-        ? "Contenteditable fill may append or prepend instead of replacing. Re-run snapshot -i, then prefer focus/click plus keyboard shortcut selection or direct keyboard insertion only after verifying the editor state."
-        : "Re-run snapshot -i, then prefer click/focus plus keyboard type for custom quick-input controls before submitting.";
-    return `${diagnostic.summary}\nExpected: "${diagnostic.expected}"; ${actual}.\nNext: ${recovery}`;
+    }
+    const explicitCount = guidance.explicitArtifactPaths.length;
+    return `Artifact lifecycle: ${explicitCount} explicit artifact${explicitCount === 1 ? "" : "s"} remain${explicitCount === 1 ? "s" : ""}; expand or inspect details.artifactCleanup.explicitArtifactPaths for paths. Browser close does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; use host file tools for cleanup.`;
 }
+export { collectElectronManagedSessionTarget, collectQaAttachedTarget, formatQaAttachedTargetText, validateQaAttachedPrecondition, collectElectronHandoff, } from "./electron-observation.js";
+export { collectFillVerificationDiagnostic, buildFillVerificationNextActions, formatFillVerificationText, } from "./fill-diagnostics.js";
 export async function collectVisibleRefFallbackDiagnostic(options) {
-    if (!options.sessionName)
-        return undefined;
-    const target = getVisibleRefFallbackTarget({ commandTokens: options.commandTokens, compiledSemanticAction: options.compiledSemanticAction });
-    if (!target)
+    if (options.sessionName === undefined || options.sessionName === "") {
         return undefined;
-    const snapshotData = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-    return buildVisibleRefFallbackDiagnosticFromSnapshot({ snapshotData, target });
-}
-export async function collectElectronHandoff(options) {
-    if (options.handoff === "connect")
-        return { handoff: "connect" };
-    if (options.signal?.aborted)
-        throw new Error("Electron handoff was aborted.");
-    const urlData = await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, throwOnFailure: true });
-    if (options.signal?.aborted)
-        throw new Error("Electron handoff was aborted.");
-    const url = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
-    if (!url)
-        throw new Error("Electron handoff get url returned no active page URL.");
-    const tabs = await runSessionCommandData({ args: ["tab", "list"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, throwOnFailure: true });
-    if (options.signal?.aborted)
-        throw new Error("Electron handoff was aborted.");
-    if (options.handoff === "tabs")
-        return { handoff: "tabs", tabs };
-    let snapshot = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, throwOnFailure: true });
-    let refSnapshot = extractRefSnapshotFromData(snapshot);
-    let snapshotRetryCount = 0;
-    while ((!refSnapshot || refSnapshot.refIds.length === 0) && snapshotRetryCount < 2) {
-        if (options.signal?.aborted)
-            throw new Error("Electron handoff was aborted.");
-        snapshotRetryCount += 1;
-        await sleepMs(250);
-        if (options.signal?.aborted)
-            throw new Error("Electron handoff was aborted.");
-        snapshot = await runSessionCommandData({ args: ["snapshot", "-i"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, throwOnFailure: true });
-        refSnapshot = extractRefSnapshotFromData(snapshot);
-    }
-    return { handoff: "snapshot", refSnapshot, snapshot, ...(snapshotRetryCount > 0 ? { snapshotRetryCount } : {}), tabs };
-}
-function getTimeoutProgressSteps(compiledJob, commandTokens, stdin) {
-    if (compiledJob)
-        return compiledJob.steps.map((step, index) => ({ args: step.args, generatedFrom: step.generatedFrom, index: index + 1 }));
-    return getUpstreamEffectiveBatchSteps(commandTokens, stdin).map((args, index) => ({ args, index: index + 1 }));
-}
-function getLastPositionalToken(args, startIndex = 1) {
-    for (let index = args.length - 1; index >= startIndex; index -= 1) {
-        const token = args[index];
-        if (token && !token.startsWith("-"))
-            return token;
-    }
-    return undefined;
-}
-function getTimeoutStepArtifactPath(commandTokens) {
-    return ["screenshot", "pdf", "download", "wait"].includes(commandTokens[0]) ? getExplicitArtifactDestination(commandTokens) : undefined;
-}
-async function statTimeoutArtifactPath(absolutePath) {
-    for (let attempt = 0; attempt < 3; attempt += 1) {
-        try {
-            const stats = await stat(absolutePath);
-            return { exists: true, sizeBytes: stats.size };
-        }
-        catch {
-            if (attempt < 2)
-                await sleepMs(25);
-        }
     }
-    return { exists: false };
-}
-async function collectTimeoutArtifactEvidence(cwd, steps) {
-    const evidence = [];
-    for (const step of steps) {
-        const path = getTimeoutStepArtifactPath(step.args);
-        if (!path)
-            continue;
-        const absolutePath = isAbsolute(path) ? path : resolve(cwd, path);
-        const artifact = await statTimeoutArtifactPath(absolutePath);
-        evidence.push(artifact.exists
-            ? { absolutePath, exists: true, path, sizeBytes: artifact.sizeBytes, state: "verified", stepIndex: step.index }
-            : { absolutePath, exists: false, path, state: "missing", stepIndex: step.index });
-    }
-    return evidence;
-}
-function getPlannedCurrentPageUrl(steps) {
-    for (let index = steps.length - 1; index >= 0; index -= 1) {
-        const args = steps[index]?.args ?? [];
-        if (isOpenNavigationCommand(args[0]) || args[0] === "pushstate")
-            return getLastPositionalToken(args);
-    }
-    return undefined;
-}
-const TIMEOUT_RETRYABLE_COMMANDS = new Set([
-    "console",
-    "diff",
-    "errors",
-    "get",
-    "goto",
-    "navigate",
-    "network",
-    "open",
-    "pdf",
-    "pushstate",
-    "screenshot",
-    "snapshot",
-    "tab",
-    "vitals",
-    "wait",
-]);
-function getTimeoutStepRetry(step) {
-    const command = step.args[0];
-    return command && TIMEOUT_RETRYABLE_COMMANDS.has(command) ? { args: ["batch"], stdin: JSON.stringify([step.args]) } : undefined;
-}
-export async function collectTimeoutPartialProgress(options) {
-    if ((options.commandTokens[0] === "session" && options.commandTokens[1] === "info") || isBrowserIndependentRead(options.commandTokens, options.stdin))
-        return undefined;
-    const rawSteps = getTimeoutProgressSteps(options.compiledJob, options.commandTokens, options.stdin);
-    const artifacts = await collectTimeoutArtifactEvidence(options.operationCwd ?? options.cwd, rawSteps);
-    const urlData = await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName });
-    const recoveredUrl = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
-    const titleData = recoveredUrl
-        ? await runSessionCommandData({ args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName })
-        : undefined;
-    const title = extractStringResultField(titleData, "result") ?? extractStringResultField(titleData, "title");
-    const plannedUrl = recoveredUrl ? undefined : getPlannedCurrentPageUrl(rawSteps);
-    const url = recoveredUrl ?? plannedUrl;
-    const currentPageSource = recoveredUrl ? "live" : plannedUrl ? "planned" : title ? "live" : undefined;
-    // A matching URL or existing file is current state, not an execution receipt.
-    const steps = rawSteps.map(step => ({ ...step, status: "unknown", reason: "Upstream did not report this step's outcome before timeout." }));
-    const singleStep = steps.length === 1 ? steps[0] : undefined;
-    const retry = singleStep ? getTimeoutStepRetry(singleStep) : undefined;
-    const retryStep = singleStep && retry ? { ...singleStep, retry } : undefined;
-    if (rawSteps.length === 0 && artifacts.length === 0 && !url && !title)
+    const target = getVisibleRefFallbackTarget({
+        commandTokens: options.commandTokens,
+        compiledSemanticAction: options.compiledSemanticAction,
+    });
+    if (!target) {
         return undefined;
-    const foundArtifacts = artifacts.filter((artifact) => artifact.exists).length;
-    const pageStateSummary = recoveredUrl || title ? " and current page state" : plannedUrl ? " and planned page URL" : "";
-    return { artifacts, currentPage: url || title ? { source: currentPageSource, title, url } : undefined, liveUrlRecovered: recoveredUrl !== undefined, retryStep, steps: steps.length > 0 ? steps : undefined, summary: `Timed out before upstream returned final results; ${steps.length} planned step outcome${steps.length === 1 ? " is" : "s are"} unknown. Found ${foundArtifacts}/${artifacts.length} declared artifact path${artifacts.length === 1 ? "" : "s"}${pageStateSummary}; these observations do not prove step execution.` };
-}
-function redactSensitivePathSegmentsForDiagnostic(path) {
-    return path.split(/([/\\]+)/).map((segment) => segment === "/" || segment === "\\" || /^[/\\]+$/.test(segment) ? segment : redactSensitiveText(segment) !== segment || /(?:secret|token|password|passwd|credential|auth|api[-_]?key|bearer)/i.test(segment) ? "[REDACTED]" : segment).join("");
-}
-function sanitizeCurrentPageUrlForTimeoutDiagnostic(url) {
-    try {
-        const parsedUrl = new URL(url);
-        parsedUrl.pathname = parsedUrl.pathname.split("/").map((segment) => redactSensitivePathSegmentsForDiagnostic(segment)).join("/");
-        for (const [key, value] of parsedUrl.searchParams.entries()) {
-            if (redactSensitiveText(key) !== key || redactSensitiveText(value) !== value || /(?:secret|token|password|passwd|credential|auth|api[-_]?key|bearer)/i.test(`${key} ${value}`))
-                parsedUrl.searchParams.set(key, "[REDACTED]");
-        }
-        if (parsedUrl.hash)
-            parsedUrl.hash = redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(parsedUrl.hash));
-        return redactSensitiveText(parsedUrl.toString());
     }
-    catch {
-        return redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(url));
-    }
-}
-export function redactTimeoutPartialProgress(progress) {
-    const redact = (value) => {
-        if (typeof value === "string")
-            return /^https?:\/\//i.test(value) ? sanitizeCurrentPageUrlForTimeoutDiagnostic(value) : redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(value));
-        if (Array.isArray(value))
-            return value.map(redact);
-        if (isRecord(value))
-            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item)]));
-        return value;
-    };
-    return redact(progress);
-}
-export function formatTimeoutPartialProgressText(progress, pageTargetUnknown = false) {
-    const lines = [`Timeout partial progress: ${progress.summary}`];
-    const currentPageTitle = progress.currentPage?.title ? redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(progress.currentPage.title)) : undefined;
-    const currentPageUrl = progress.currentPage?.url ? sanitizeCurrentPageUrlForTimeoutDiagnostic(progress.currentPage.url) : undefined;
-    if (currentPageTitle || currentPageUrl)
-        lines.push(`Current page: ${[currentPageTitle, currentPageUrl].filter(Boolean).join(" — ")}`);
-    if (progress.steps && progress.steps.length > 0) {
-        const shownSteps = progress.steps.slice(0, 6);
-        lines.push("Planned steps:");
-        for (const step of shownSteps) {
-            const commandText = redactSensitivePathSegmentsForDiagnostic(redactInvocationArgs(step.args).join(" "));
-            const generatedFrom = step.generatedFrom ? `, generated from ${step.generatedFrom}` : "";
-            lines.push(`- Step ${step.index} [${step.status}${generatedFrom}]: ${commandText}${step.reason ? ` — ${redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(step.reason))}` : ""}`);
-        }
-        if (progress.steps.length > shownSteps.length)
-            lines.push(`- ... ${progress.steps.length - shownSteps.length} more step${progress.steps.length - shownSteps.length === 1 ? "" : "s"} omitted`);
-    }
-    if (progress.retryStep?.retry?.args) {
-        const payload = JSON.stringify({ ...progress.retryStep.retry, stdin: JSON.stringify([redactInvocationArgs(progress.retryStep.args)]) });
-        lines.push(pageTargetUnknown
-            ? `Retry candidate for step ${progress.retryStep.index}: ${payload}. Verify the current URL before running it.`
-            : `Retry candidate for step ${progress.retryStep.index} (outcome unknown): ${payload}`);
-    }
-    for (const artifact of progress.artifacts)
-        lines.push(`Artifact from step ${artifact.stepIndex}: ${redactSensitivePathSegmentsForDiagnostic(artifact.path)} (${artifact.exists ? `exists${typeof artifact.sizeBytes === "number" ? `, ${artifact.sizeBytes} bytes` : ""}` : "missing"})`);
-    return lines.join("\n");
+    const snapshotData = await runSessionCommandData({
+        args: ["snapshot", "-i"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
+    return buildVisibleRefFallbackDiagnosticFromSnapshot({ snapshotData, target });
 }
+export { collectTimeoutPartialProgress, formatTimeoutPartialProgressText, } from "./timeout-diagnostics.js";