pi-agent-browser-native 0.3.0 → 0.6.5

package/dist/extensions/agent-browser/lib/managed-session-storage.js

@@ -3,8 +3,12 @@ import { linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, parse, resolve, win32 } from "node:path";
 import { canonicalizeAgentBrowserNamespace } from "./argv-grammar.js";
-export { isManagedSessionRestoreKey } from "./managed-session-capabilities.js";
+const MANAGED_SESSION_RESTORE_KEY_PATTERN = /^piab-r2-[a-f\d]{32}$/i;
 const MANAGED_SESSION_NAME_PREFIX = "piab-r2-";
+export function isManagedSessionRestoreKey(value) {
+    return typeof value === "string" && MANAGED_SESSION_RESTORE_KEY_PATTERN.test(value);
+}
+const MANAGED_SESSION_FRESH_SUFFIX_PATTERN = /-fresh-[a-f\d]{10}$/i;
 const MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH = 32;
 const PROJECT_GENERATION_MARKER_NAME = "pi-agent-browser-project-generation-v1.json";
 const PROJECT_GENERATION_MARKER_MAX_BYTES = 1_024;
@@ -15,7 +19,7 @@ function isAbsoluteHome(path, platform) {
 function currentUid() {
     return typeof process.getuid === "function" ? process.getuid() : undefined;
 }
-function isTrustedPosixDirectory(path, requireCurrentOwner) {
+function isTrustedPosixDirectory(path, requireCurrentOwner, platform = process.platform) {
     const uid = currentUid();
     if (uid === undefined)
         return false;
@@ -32,11 +36,13 @@ function isTrustedPosixDirectory(path, requireCurrentOwner) {
         }
         if (entry.isSymbolicLink() || !entry.isDirectory())
             return false;
-        if (entry.uid !== 0 && entry.uid !== uid)
+        const androidSystemAncestor = platform === "android" && (cursor === "/data" || cursor === "/data/data") && entry.uid === 1000 && (entry.mode & 0o002) === 0;
+        const androidAppDirectory = platform === "android" && entry.uid === uid && entry.gid === uid && (entry.mode & 0o002) === 0;
+        if (!androidSystemAncestor && entry.uid !== 0 && entry.uid !== uid)
             return false;
         const writableByOthers = (entry.mode & 0o022) !== 0;
         const rootOwnedStickyDirectory = entry.uid === 0 && (entry.mode & 0o1000) !== 0;
-        if (writableByOthers && !rootOwnedStickyDirectory)
+        if (writableByOthers && !rootOwnedStickyDirectory && !androidSystemAncestor && !androidAppDirectory)
             return false;
     }
     try {
@@ -56,7 +62,7 @@ export function resolveManagedSessionRestoreHome(parentEnv, platform = process.p
         return candidate;
     try {
         const canonical = realpathSync(candidate);
-        return isTrustedPosixDirectory(canonical, true) ? canonical : undefined;
+        return isTrustedPosixDirectory(canonical, true, platform) ? canonical : undefined;
     }
     catch {
         return undefined;
@@ -138,12 +144,15 @@ function readProjectGenerationMarker(path, platform) {
         return undefined;
     }
 }
-function getDirectoryFilesystemIdentity(path) {
+function getDirectoryFilesystemIdentity(path, platform) {
     try {
         const entry = statSync(path, { bigint: true });
-        return entry.isDirectory() && entry.dev > 0n && entry.ino > 0n && entry.birthtimeNs > 0n
-            ? `${entry.dev}:${entry.ino}:${entry.birthtimeNs}`
-            : undefined;
+        if (!entry.isDirectory() || entry.dev <= 0n || entry.ino <= 0n)
+            return undefined;
+        // ponytail: Android reports mutable ctime as birthtime; use statx birthtime/inode generation when Node exposes either reliably.
+        return platform === "android"
+            ? `${entry.dev}:${entry.ino}`
+            : entry.birthtimeNs > 0n ? `${entry.dev}:${entry.ino}:${entry.birthtimeNs}` : undefined;
     }
     catch {
         return undefined;
@@ -157,13 +166,13 @@ function resolveManagedSessionRestoreProjectCheckout(cwd, platform) {
     catch {
         return undefined;
     }
-    if (platform !== "win32" && !isTrustedPosixDirectory(canonicalCwd, false))
+    if (platform !== "win32" && !isTrustedPosixDirectory(canonicalCwd, false, platform))
         return undefined;
     const checkout = resolveGitCheckout(canonicalCwd, platform);
     if (!checkout)
         return undefined;
-    if (platform !== "win32" && (!isTrustedPosixDirectory(checkout.worktreeDirectory, true)
-        || !isTrustedPosixDirectory(checkout.gitDirectory, true)))
+    if (platform !== "win32" && (!isTrustedPosixDirectory(checkout.worktreeDirectory, true, platform)
+        || !isTrustedPosixDirectory(checkout.gitDirectory, true, platform)))
         return undefined;
     return { canonicalCwd, ...checkout };
 }
@@ -175,8 +184,8 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
     if (!checkout)
         return undefined;
     const { canonicalCwd } = checkout;
-    const gitFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.gitDirectory);
-    const worktreeFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.worktreeDirectory);
+    const gitFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.gitDirectory, platform);
+    const worktreeFilesystemIdentity = getDirectoryFilesystemIdentity(checkout.worktreeDirectory, platform);
     if (!gitFilesystemIdentity || !worktreeFilesystemIdentity)
         return undefined;
     const markerPath = join(checkout.gitDirectory, PROJECT_GENERATION_MARKER_NAME);
@@ -192,22 +201,35 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
     projectGenerationCache.delete(canonicalCwd);
     try {
         if (!marker) {
-            const candidatePath = `${markerPath}.candidate-${process.pid}-${randomUUID()}`;
-            try {
-                writeFileSync(candidatePath, JSON.stringify({ id: randomUUID(), version: 1 }), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            const content = JSON.stringify({ id: randomUUID(), version: 1 });
+            if (platform === "android") {
+                // ponytail: Android denies hard links in app storage; use renameat2(RENAME_NOREPLACE) if Node exposes it.
                 try {
-                    linkSync(candidatePath, markerPath);
+                    writeFileSync(markerPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
                 }
                 catch (error) {
                     if (error.code !== "EEXIST")
                         return undefined;
                 }
             }
-            finally {
+            else {
+                const candidatePath = `${markerPath}.candidate-${process.pid}-${randomUUID()}`;
                 try {
-                    unlinkSync(candidatePath);
+                    writeFileSync(candidatePath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    try {
+                        linkSync(candidatePath, markerPath);
+                    }
+                    catch (error) {
+                        if (error.code !== "EEXIST")
+                            return undefined;
+                    }
+                }
+                finally {
+                    try {
+                        unlinkSync(candidatePath);
+                    }
+                    catch { }
                 }
-                catch { }
             }
             marker = readProjectGenerationMarker(markerPath, platform);
         }
@@ -231,16 +253,23 @@ function resolveProjectGenerationIdentity(cwd, platform = process.platform) {
 export function hasManagedSessionRestoreProjectIdentity(cwd) {
     return resolveProjectGenerationIdentity(cwd) !== undefined;
 }
-/** Stable for one checkout generation; deliberately changes when a path is replaced by another checkout. */
-export function createManagedSessionRestoreKey(cwd) {
+/** Keep fresh rotations from one Pi transcript in one private upstream restore pool. */
+export function getManagedSessionRestoreScope(sessionName) {
+    return sessionName.replace(MANAGED_SESSION_FRESH_SUFFIX_PATTERN, "");
+}
+/** Stable for one Pi transcript and checkout generation; isolated from other concurrent transcripts. */
+export function createManagedSessionRestoreKey(cwd, restoreScope = "", platform = process.platform) {
     let canonicalCwd = resolve(cwd);
     try {
         canonicalCwd = realpathSync(canonicalCwd);
     }
     catch { }
-    const identity = resolveProjectGenerationIdentity(canonicalCwd);
+    const identity = resolveProjectGenerationIdentity(canonicalCwd, platform);
     const material = identity ?? `unavailable:${canonicalCwd}`;
-    const digest = createHash("sha256").update(`restore-v2:${material}`).digest("hex").slice(0, MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH);
+    const digest = createHash("sha256")
+        .update(`restore-v3:${material}:scope:${restoreScope}`)
+        .digest("hex")
+        .slice(0, MANAGED_SESSION_RESTORE_KEY_HASH_LENGTH);
     return `${MANAGED_SESSION_NAME_PREFIX}${digest}`;
 }
 function hasValidEncryptionKey(parentEnv) {

package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js

@@ -1,3 +1,4 @@
+const BATCH_STDIN_EXAMPLE = ' Example: { "args": ["batch"], "stdin": "[[\\"get\\",\\"title\\"],[\\"get\\",\\"url\\"]]" }';
 // Mirror upstream commands::shell_words_split so policy inspection sees the same argv.
 export function parseBatchCommandArgument(command) {
     const tokens = [];
@@ -36,20 +37,20 @@ export function parseBatchCommandArgument(command) {
 function validateUserBatchStep(step, index) {
     if (!Array.isArray(step)) {
         return {
-            error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.`,
+            error: `agent_browser batch stdin step ${index} must be a non-empty array of string command tokens.${BATCH_STDIN_EXAMPLE}`,
             ok: false,
         };
     }
     if (step.length === 0) {
         return {
-            error: `agent_browser batch stdin step ${index} must not be empty.`,
+            error: `agent_browser batch stdin step ${index} must not be empty.${BATCH_STDIN_EXAMPLE}`,
             ok: false,
         };
     }
     const invalidTokenIndex = step.findIndex((token) => typeof token !== "string");
     if (invalidTokenIndex !== -1) {
         return {
-            error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.`,
+            error: `agent_browser batch stdin step ${index} token ${invalidTokenIndex} must be a string.${BATCH_STDIN_EXAMPLE}`,
             ok: false,
         };
     }
@@ -62,13 +63,13 @@ export function parseBatchStdinJsonArray(stdin) {
     try {
         const parsed = JSON.parse(stdin);
         if (!Array.isArray(parsed)) {
-            return { error: "agent_browser batch stdin must be a JSON array of command steps." };
+            return { error: `agent_browser batch stdin must be a JSON array of command steps.${BATCH_STDIN_EXAMPLE}` };
         }
         return { steps: parsed };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}` };
+        return { error: `agent_browser batch stdin could not be parsed as JSON: ${message}.${BATCH_STDIN_EXAMPLE}` };
     }
 }
 export function parseUserBatchStdin(stdin) {
@@ -86,6 +87,26 @@ export function parseUserBatchStdin(stdin) {
     }
     return { steps };
 }
+/**
+ * The batch steps upstream will actually execute: run_batch uses raw batch
+ * arguments exclusively when any exist and reads stdin only otherwise.
+ * Upstream filters only the exact `--bail` token, so an equals form such as
+ * `--bail=true` stays a raw command (an unknown-command row) and keeps stdin
+ * ignored.
+ */
+export function getUpstreamEffectiveBatchSteps(commandTokens, stdin) {
+    if (commandTokens[0] !== "batch")
+        return [];
+    const argumentSteps = commandTokens.slice(1).flatMap((command) => {
+        if (command === "--bail")
+            return [];
+        const step = parseBatchCommandArgument(command).step;
+        return step ? [step] : [];
+    });
+    if (argumentSteps.length > 0)
+        return argumentSteps;
+    return parseUserBatchStdin(stdin).steps ?? [];
+}
 export function parseValidBatchStepEntries(stdin) {
     const parsed = parseBatchStdinJsonArray(stdin);
     if (parsed.error || parsed.steps === undefined)

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

@@ -1,46 +1,126 @@
-import { extname, isAbsolute } from "node:path";
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS } from "../../argv-grammar.js";
+import { lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { foldAgentBrowserFilesystemIdentity } from "../../argv-grammar.js";
+import { parseWaitCommandTokens } from "../../argv-descriptor.js";
 const SCREENSHOT_BOOLEAN_FLAGS = new Set(["--annotate", "--full", "-f"]);
 const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
-const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
-function isImagePathToken(token) {
-    const extension = extname(token).toLowerCase();
-    return SCREENSHOT_IMAGE_EXTENSIONS.has(extension);
+const SCREENSHOT_IMAGE_EXTENSIONS = [".jpeg", ".jpg", ".png", ".webp"];
+function isSingleScreenshotPathToken(token) {
+    const explicitlyRelative = token.startsWith("./") || token.startsWith("../");
+    if (token.startsWith("#") || token.startsWith("@") || (token.startsWith(".") && !explicitlyRelative && !token.includes("/")))
+        return false;
+    return explicitlyRelative || token.includes("/") || SCREENSHOT_IMAGE_EXTENSIONS.some((extension) => token.endsWith(extension));
+}
+function getScreenshotPositionalIndices(commandTokens) {
+    if (commandTokens[0] !== "screenshot")
+        return [];
+    const positionalIndices = [];
+    for (let index = 1; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        if (SCREENSHOT_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (SCREENSHOT_BOOLEAN_FLAGS.has(token))
+            continue;
+        positionalIndices.push(index);
+    }
+    return positionalIndices;
 }
 export function getScreenshotPathTokenIndex(commandTokens) {
-    if (commandTokens[0] !== "screenshot") {
+    const positionalIndices = getScreenshotPositionalIndices(commandTokens);
+    if (positionalIndices.length === 0)
         return undefined;
+    const candidateIndex = positionalIndices.length >= 2 ? positionalIndices[1] : positionalIndices[0];
+    const candidate = commandTokens[candidateIndex];
+    if (positionalIndices.length >= 2 || isSingleScreenshotPathToken(candidate)) {
+        return candidateIndex;
     }
-    const positionalIndices = [];
-    for (let index = 1; index < commandTokens.length; index += 1) {
+    return undefined;
+}
+const DIFF_SCREENSHOT_VALUE_FLAGS = new Set(["-b", "--baseline", "-o", "--output", "-s", "--selector", "-t", "--threshold"]);
+function getDiffScreenshotOutputPath(commandTokens) {
+    let outputPath;
+    for (let index = 2; index < commandTokens.length; index += 1) {
         const token = commandTokens[index];
-        if (token === "--") {
-            for (let positionalIndex = index + 1; positionalIndex < commandTokens.length; positionalIndex += 1) {
-                positionalIndices.push(positionalIndex);
+        if (!DIFF_SCREENSHOT_VALUE_FLAGS.has(token))
+            continue;
+        const value = commandTokens[index + 1];
+        if (value === undefined)
+            return undefined;
+        if (token === "-o" || token === "--output")
+            outputPath = value;
+        index += 1;
+    }
+    return outputPath;
+}
+function foldArtifactPath(path, platform) {
+    return foldAgentBrowserFilesystemIdentity(path, platform);
+}
+function canonicalizeArtifactPath(absolutePath, platform, seenSymlinks) {
+    let cursor = absolutePath;
+    const suffix = [];
+    while (true) {
+        try {
+            const canonicalPath = join(realpathSync.native(cursor), ...suffix);
+            try {
+                const stats = statSync(canonicalPath, { bigint: true });
+                if (stats.ino > 0n)
+                    return `inode:${stats.dev}:${stats.ino}`;
+            }
+            catch {
+                // The destination does not exist yet; canonical ancestry still catches aliases.
             }
-            break;
+            return foldArtifactPath(canonicalPath, platform);
         }
-        if (token.startsWith("-")) {
-            const normalizedToken = token.split("=", 1)[0] ?? token;
-            if ((SCREENSHOT_VALUE_FLAGS.has(normalizedToken) || VALUE_FLAGS.has(normalizedToken)) && !token.includes("=")) {
-                index += 1;
-                continue;
+        catch {
+            let symlinkTarget;
+            try {
+                if (lstatSync(cursor).isSymbolicLink())
+                    symlinkTarget = resolve(dirname(cursor), readlinkSync(cursor));
             }
-            if (SCREENSHOT_BOOLEAN_FLAGS.has(normalizedToken) || GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken)) {
-                if (["true", "false"].includes(commandTokens[index + 1] ?? ""))
-                    index += 1;
-                continue;
+            catch { }
+            if (symlinkTarget) {
+                if (seenSymlinks.has(cursor))
+                    throw new Error(`Artifact destination contains a symlink loop: ${absolutePath}`);
+                if (seenSymlinks.size >= 32)
+                    throw new Error(`Artifact destination has too many symlink hops: ${absolutePath}`);
+                seenSymlinks.add(cursor);
+                return canonicalizeArtifactPath(join(symlinkTarget, ...suffix), platform, seenSymlinks);
             }
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                return foldArtifactPath(absolutePath, platform);
+            suffix.unshift(basename(cursor));
+            cursor = parent;
         }
-        positionalIndices.push(index);
     }
-    if (positionalIndices.length === 0) {
-        return undefined;
-    }
-    const candidateIndex = positionalIndices[positionalIndices.length - 1];
-    const candidate = commandTokens[candidateIndex];
-    if (positionalIndices.length >= 2 || isImagePathToken(candidate) || isAbsolute(candidate) || candidate.startsWith("./") || candidate.startsWith("../")) {
-        return candidateIndex;
+}
+export function canonicalizeExplicitArtifactDestination(cwd, destination, platform = process.platform) {
+    return canonicalizeArtifactPath(resolve(cwd, destination), platform, new Set());
+}
+export function getExplicitArtifactDestination(commandTokens) {
+    const command = commandTokens[0];
+    const subcommand = commandTokens[1];
+    if (command === "screenshot") {
+        const index = getScreenshotPathTokenIndex(commandTokens);
+        return index === undefined ? undefined : commandTokens[index];
     }
+    if (command === "download")
+        return commandTokens[2];
+    if (command === "pdf")
+        return commandTokens[1];
+    if (command === "wait")
+        return parseWaitCommandTokens(commandTokens).downloadPath;
+    if (command === "state" && subcommand === "save")
+        return commandTokens[2];
+    if (command === "diff" && subcommand === "screenshot")
+        return getDiffScreenshotOutputPath(commandTokens);
+    if (command === "network" && subcommand === "har" && commandTokens[2] === "stop")
+        return commandTokens[3];
+    if ((command === "trace" || command === "profiler") && subcommand === "stop")
+        return commandTokens[2];
+    if (command === "record" && (subcommand === "start" || subcommand === "restart"))
+        return commandTokens[2];
     return undefined;
 }

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

@@ -245,6 +245,7 @@ export async function collectClickDispatchDiagnostic(options) {
     const result = getEvalResultRecord(data);
     if (!result)
         return undefined;
+    options.probe.cleaned = true;
     const status = typeof result.status === "string" ? result.status : undefined;
     if (status !== "no-native-event-observed")
         return undefined;
@@ -264,7 +265,7 @@ export async function collectClickDispatchDiagnostic(options) {
     };
 }
 export async function cleanupClickDispatchProbe(options) {
-    if (!options.probe || !options.sessionName)
+    if (!options.probe || options.probe.cleaned || !options.sessionName)
         return;
     await runSessionCommandData({
         args: ["eval", "--stdin"],

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

@@ -3,14 +3,12 @@ import { isAbsolute, resolve } from "node:path";
 import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
 import { boundElectronProbeString } from "../../electron/cdp.js";
 import { executableExistsOnPath } from "../../executable-path.js";
-import { isHttpOrHttpsUrl } from "../../input-modes/job.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
 import { buildNextToolAction, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { buildVisibleRefFallbackDiagnosticFromSnapshot, getVisibleRefFallbackTarget } from "../../results/selector-recovery.js";
-import { extractRefSnapshotFromData, normalizeComparableUrl } from "../../session-page-state.js";
-import { redactInvocationArgs, redactSensitiveText } from "../../runtime.js";
+import { extractRefSnapshotFromData, isAboutBlankUrl, normalizeComparableUrl } from "../../session-page-state.js";
+import { extractUpstreamCommandTokens, parseWaitCommandTokens, redactInvocationArgs, redactSensitiveText } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
-import { getManagedSessionStateAccessValidationError, isFileUrl } from "../../managed-session-state-policy.js";
 import { extractBatchResultCommand, extractNavigationSummaryFromData, extractStringResultField, findElectronLaunchRecordForSession, runSessionCommandData, } from "./session-state.js";
 import { parseValidBatchStepEntries } from "../batch-stdin.js";
 import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
@@ -22,10 +20,17 @@ 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))
         return undefined;
-    if (isFileUrl(url))
-        return { url };
+    const urlChanged = options.priorTarget?.url ? normalizeComparableUrl(options.priorTarget.url) !== normalizeComparableUrl(url) : undefined;
+    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 title = extractStringResultField(await runSessionCommandData({ args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }), "title");
-    return { title, url };
+    return { title, url, ...(urlChanged !== undefined ? { urlChanged } : {}) };
 }
 function extractScrollPositionSnapshot(data) {
     const result = isRecord(data) && isRecord(data.result) ? data.result : data;
@@ -83,6 +88,21 @@ function sameScrollPositionSnapshot(left, right) {
         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;
@@ -390,14 +410,14 @@ function isBroadGetTextSelector(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);
+    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);
+    const record = findElectronLaunchRecordForSession(options.sessionName, options.electronLaunchRecords, options.namespace);
     if (!record)
         return undefined;
     const url = options.currentTarget?.url ?? options.priorTarget?.url;
@@ -469,9 +489,11 @@ 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 || options.manifest.entries.length === 0)
+    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;
     const explicitArtifactPaths = [];
     const seenPaths = new Set();
     for (const entry of explicitEntries) {
@@ -490,16 +512,15 @@ 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) };
 }
 export function formatArtifactCleanupGuidanceText(guidance) {
-    if (!guidance)
+    if (!guidance || guidance.explicitArtifactPaths.length === 0)
         return undefined;
     const explicitCount = guidance.explicitArtifactPaths.length;
-    const explicitSummary = explicitCount === 0
-        ? "No existing explicit artifact paths were found in the recent manifest."
-        : `${explicitCount} explicit artifact${explicitCount === 1 ? "" : "s"} remain${explicitCount === 1 ? "s" : ""}; expand or inspect details.artifactCleanup.explicitArtifactPaths for paths.`;
-    return `Artifact lifecycle: ${explicitSummary} Browser close does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; use host file tools for cleanup.`;
+    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 {
@@ -524,14 +545,11 @@ async function collectElectronManagedSessionUrl(options) {
 export async function collectElectronManagedSessionTarget(options) {
     if (!options.sessionName)
         return undefined;
-    const urlResult = await collectManagedSessionCommandData({ allowManagedSessionTarget: options.allowManagedSessionTarget, args: ["get", "url"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    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 fileAccessError = getManagedSessionStateAccessValidationError({ args: ["get", "title"], currentPageUrl: url, cwd: options.cwd });
-    if (fileAccessError)
-        return { error: fileAccessError, sessionName: options.sessionName, url };
-    const titleResult = await collectManagedSessionCommandData({ allowManagedSessionTarget: options.allowManagedSessionTarget, args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, timeoutMs: options.timeoutMs });
+    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 } : {}) };
 }
@@ -559,7 +577,7 @@ export function buildQaAttachedRecoveryNextActions(sessionName) {
         buildNextToolAction({
             args: sessionArgs(["snapshot", "-i"]),
             id: "snapshot-before-qa-attached",
-            reason: "Capture interactive refs on the active http(s) page before retrying qa.attached.",
+            reason: "Capture interactive refs on the active page before retrying qa.attached.",
             safety: "Read-only snapshot; confirms a renderable page is selected.",
         }),
     ];
@@ -581,13 +599,7 @@ export async function validateQaAttachedPrecondition(options) {
     const url = urlProbe.url?.trim();
     if (!url) {
         return {
-            error: "qa.attached requires an attached session with a readable http(s) page URL. Run tab list, select a stable tab, then snapshot -i before retrying.",
-            nextActions: buildQaAttachedRecoveryNextActions(options.sessionName),
-        };
-    }
-    if (!isHttpOrHttpsUrl(url)) {
-        return {
-            error: `qa.attached requires an http(s) page URL; the current attached URL is "${url}". Use tab list and snapshot -i to recover a web surface before retrying.`,
+            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),
         };
     }
@@ -679,9 +691,6 @@ export async function collectElectronHandoff(options) {
     const url = extractStringResultField(urlData, "result") ?? extractStringResultField(urlData, "url");
     if (!url)
         throw new Error("Electron handoff get url returned no active page URL.");
-    const fileAccessError = getManagedSessionStateAccessValidationError({ args: ["snapshot", "-i"], currentPageUrl: url, cwd: options.cwd });
-    if (fileAccessError)
-        return { error: fileAccessError, failureCategory: "validation-error", handoff: options.handoff };
     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.");
@@ -718,24 +727,18 @@ function getLastPositionalToken(args, startIndex = 1) {
     return undefined;
 }
 function getTimeoutStepArtifactPath(args) {
-    const [command] = args;
+    const commandArgs = extractUpstreamCommandTokens(args);
+    const [command] = commandArgs;
     if (command === "screenshot") {
-        const index = getScreenshotPathTokenIndex(args);
-        return index === undefined ? undefined : args[index];
+        const index = getScreenshotPathTokenIndex(commandArgs);
+        return index === undefined ? undefined : commandArgs[index];
     }
     if (command === "pdf")
-        return getLastPositionalToken(args);
+        return getLastPositionalToken(commandArgs);
     if (command === "download")
-        return getLastPositionalToken(args, 2);
-    if (command === "wait") {
-        const inlineDownload = args.find((token) => token.startsWith("--download="));
-        if (inlineDownload)
-            return inlineDownload.slice("--download=".length) || undefined;
-        const downloadIndex = args.indexOf("--download");
-        const downloadPath = downloadIndex >= 0 ? args[downloadIndex + 1] : undefined;
-        if (downloadPath && !downloadPath.startsWith("-"))
-            return downloadPath;
-    }
+        return getLastPositionalToken(commandArgs, 2);
+    if (command === "wait")
+        return parseWaitCommandTokens(commandArgs).downloadPath;
     return undefined;
 }
 async function statTimeoutArtifactPath(absolutePath) {
@@ -874,7 +877,7 @@ export async function collectTimeoutPartialProgress(options) {
     const artifacts = await collectTimeoutArtifactEvidence(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 && !isFileUrl(recoveredUrl)
+    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");
@@ -909,7 +912,7 @@ function sanitizeCurrentPageUrlForTimeoutDiagnostic(url) {
         return redactSensitivePathSegmentsForDiagnostic(redactSensitiveText(url));
     }
 }
-export function formatTimeoutPartialProgressText(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;
@@ -927,7 +930,10 @@ export function formatTimeoutPartialProgressText(progress) {
             lines.push(`- ... ${progress.steps.length - shownSteps.length} more step${progress.steps.length - shownSteps.length === 1 ? "" : "s"} omitted`);
     }
     if (progress.retryStep?.retry?.args) {
-        lines.push(`Retry failed step: ${JSON.stringify({ args: redactInvocationArgs(progress.retryStep.retry.args) })}`);
+        const payload = JSON.stringify({ args: redactInvocationArgs(progress.retryStep.retry.args) });
+        lines.push(pageTargetUnknown
+            ? `Retry candidate for step ${progress.retryStep.index}: ${payload}. Verify the current URL before running it.`
+            : `Retry failed step: ${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"})`);