pi-agent-browser-native 0.2.77 → 0.5.0

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Resolve and secure the filesystem identity used by automatic managed-session restore.
- * Responsibilities: Bind restore keys to one Git checkout generation, validate trusted HOME ancestry, and prepare owner-only upstream state directories.
- * Scope: Filesystem policy only; argv/session ownership and snapshot retention live in sibling modules.
- */
 import { createHash, randomUUID } from "node:crypto";
 import { linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -10,6 +5,7 @@ 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_NAME_PREFIX = "piab-r2-";
+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;
@@ -20,7 +16,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;
@@ -37,11 +33,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 {
@@ -61,7 +59,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;
@@ -143,12 +141,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;
@@ -162,13 +163,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 };
 }
@@ -180,8 +181,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);
@@ -197,22 +198,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);
         }
@@ -236,16 +250,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/navigation-policy.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Keep wrapper-side navigation policy parsing and evaluation small and explicit.
- * Responsibilities: Parse allowed-domain argv values and detect final-page host escapes.
- * Scope: Wrapper diagnostics only; upstream remains responsible for browser-time enforcement.
- */
 function normalizeDomainEntry(value) {
     let candidate = value.trim().toLowerCase();
     if (!candidate)

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

@@ -1,14 +1,14 @@
 import { stat } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
-import { boundElectronProbeString } from "../../electron/text.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";
@@ -22,8 +22,14 @@ 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))
+    if (isFileUrl(url) || isAboutBlankUrl(url))
         return { url };
+    // 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.priorTarget?.title && normalizeComparableUrl(options.priorTarget.url) === normalizeComparableUrl(url)) {
+        return { title: options.priorTarget.title, url };
+    }
     const title = extractStringResultField(await runSessionCommandData({ args: ["get", "title"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }), "title");
     return { title, url };
 }
@@ -390,14 +396,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 +475,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 +498,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 {
@@ -718,24 +725,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) {