pi-agent-browser-native 0.5.0 → 0.6.6

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

@@ -50,9 +50,6 @@ function getPolicyLockDigest(sessionName, namespace) {
 export function getManagedSessionPolicyLockPath(sessionName, namespace) {
     return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${getPolicyLockDigest(sessionName, namespace)}.lock-v3`);
 }
-export function getLegacyManagedSessionPolicyLockPath(sessionName, namespace) {
-    return join(getCoordinationDirectory(), `.pi-agent-browser-policy-${getPolicyLockDigest(sessionName, namespace)}.lock-v2`);
-}
 function parseOwner(content) {
     if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
         return undefined;
@@ -69,22 +66,6 @@ function parseOwner(content) {
         return undefined;
     }
 }
-function parseLegacyBridgeOwner(content) {
-    if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
-        return undefined;
-    try {
-        const parsed = JSON.parse(content);
-        return (parsed.version === 2 || parsed.version === 3)
-            && Number.isSafeInteger(parsed.pid) && (parsed.pid ?? 0) > 0
-            && typeof parsed.startIdentity === "string" && parsed.startIdentity.length > 0
-            && typeof parsed.token === "string" && parsed.token.length > 0
-            ? parsed
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 function parseTicket(content, token) {
     if (Buffer.byteLength(content) > POLICY_LOCK_MAX_BYTES)
         return undefined;
@@ -139,26 +120,6 @@ async function readClaim(path) {
         return undefined;
     }
 }
-async function readLegacyBridgeOwner(path) {
-    try {
-        const directory = await lstat(path);
-        const ownerPath = join(path, LOCK_OWNER_FILE);
-        const ownerEntry = await lstat(ownerPath);
-        if (!directory.isDirectory() || directory.isSymbolicLink() || !ownerEntry.isFile() || ownerEntry.isSymbolicLink())
-            return undefined;
-        if (ownerEntry.size > POLICY_LOCK_MAX_BYTES)
-            return undefined;
-        if (process.platform !== "win32") {
-            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
-            if (uid === undefined || directory.uid !== uid || ownerEntry.uid !== uid || (directory.mode & 0o077) !== 0 || (ownerEntry.mode & 0o177) !== 0)
-                return undefined;
-        }
-        return parseLegacyBridgeOwner(await readFile(ownerPath, "utf8"));
-    }
-    catch {
-        return undefined;
-    }
-}
 async function readClaims(basePath) {
     const directory = dirname(basePath);
     const prefix = `${basename(basePath)}.claim-`;
@@ -225,28 +186,6 @@ async function removeClaimOwnedBy(path, token) {
     await rm(movedPath, { force: true, recursive: true });
     return true;
 }
-async function removeLegacyBridgeOwnedBy(path, token) {
-    const current = await readLegacyBridgeOwner(path);
-    if (current?.version !== 3 || current.token !== token)
-        return false;
-    const movedPath = join(dirname(path), `.pi-agent-browser-policy-bridge-remove-${token}-${randomUUID()}`);
-    try {
-        await rename(path, movedPath);
-    }
-    catch (error) {
-        return error.code === "ENOENT";
-    }
-    const moved = await readLegacyBridgeOwner(movedPath);
-    if (moved?.version !== 3 || moved.token !== token) {
-        try {
-            await rename(movedPath, path);
-        }
-        catch { }
-        return false;
-    }
-    await rm(movedPath, { force: true, recursive: true });
-    return true;
-}
 async function cleanDeadPolicyArtifacts(directory) {
     let names;
     try {
@@ -256,72 +195,13 @@ async function cleanDeadPolicyArtifacts(directory) {
         return;
     }
     for (const name of names.filter((candidate) => candidate.startsWith(".pi-agent-browser-policy-remove-")
-        || candidate.startsWith(".pi-agent-browser-policy-bridge-remove-")
-        || candidate.includes(".lock-v2.bridge-candidate-")
-        || candidate.includes(".lock-v2.candidate-")
         || candidate.includes(".lock-v3.candidate-"))) {
         const path = join(directory, name);
-        const owner = await readLegacyBridgeOwner(path);
-        if (owner && await ownerAlive(owner) === false)
+        const claim = await readClaim(path);
+        if (claim && await ownerAlive(claim.owner) === false)
             await rm(path, { force: true, recursive: true }).catch(() => undefined);
     }
 }
-async function hasLegacyV2Contender(path) {
-    try {
-        const prefix = `${basename(path)}.candidate-`;
-        return (await readdir(dirname(path))).some((name) => name.startsWith(prefix));
-    }
-    catch {
-        return undefined;
-    }
-}
-async function acquireLegacyPolicyBridge(options) {
-    const path = getLegacyManagedSessionPolicyLockPath(options.sessionName, options.namespace);
-    const candidatePath = `${path}.bridge-candidate-${options.owner.token}`;
-    try {
-        await mkdir(candidatePath, { mode: 0o700 });
-        await writeFile(join(candidatePath, LOCK_OWNER_FILE), JSON.stringify(options.owner), { encoding: "utf8", flag: "wx", mode: 0o600 });
-        while (!options.signal?.aborted) {
-            const legacyContender = await hasLegacyV2Contender(path);
-            if (legacyContender === undefined)
-                return undefined;
-            if (legacyContender) {
-                if (Date.now() >= options.deadline)
-                    return undefined;
-                await waitForRetry(options.signal);
-                continue;
-            }
-            try {
-                await rename(candidatePath, path);
-                const installed = await readLegacyBridgeOwner(path);
-                return installed?.version === 3 && installed.token === options.owner.token
-                    ? { release: async () => { await removeLegacyBridgeOwnedBy(path, options.owner.token); } }
-                    : undefined;
-            }
-            catch (error) {
-                if (!["EACCES", "EEXIST", "ENOTEMPTY", "EPERM"].includes(error.code ?? ""))
-                    return undefined;
-            }
-            const observed = await readLegacyBridgeOwner(path);
-            if (!observed)
-                return undefined;
-            if (observed.version === 3 && await ownerAlive(observed) === false) {
-                if (await removeLegacyBridgeOwnedBy(path, observed.token))
-                    continue;
-            }
-            if (Date.now() >= options.deadline)
-                return undefined;
-            await waitForRetry(options.signal);
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-    finally {
-        await rm(candidatePath, { force: true, recursive: true }).catch(() => undefined);
-    }
-}
 function claimPrecedes(left, right) {
     if (left.ticket === null)
         return true;
@@ -358,7 +238,6 @@ export async function acquireManagedSessionPolicyLock(options) {
     const candidatePath = `${basePath}.candidate-${token}`;
     const claimPath = `${basePath}.claim-${token}`;
     let claimPublished = false;
-    let legacyBridge;
     let lockAcquired = false;
     try {
         await mkdir(candidatePath, { mode: 0o700 });
@@ -397,20 +276,8 @@ export async function acquireManagedSessionPolicyLock(options) {
             }
             if (!blocked) {
                 await cleanDeadPolicyArtifacts(directory);
-                legacyBridge = await acquireLegacyPolicyBridge({
-                    deadline,
-                    owner,
-                    signal: options.signal,
-                    sessionName: options.sessionName,
-                    namespace: options.namespace,
-                });
-                if (!legacyBridge)
-                    return undefined;
                 lockAcquired = true;
-                return { release: async () => {
-                        await legacyBridge?.release();
-                        await removeClaimOwnedBy(claimPath, token);
-                    } };
+                return { release: async () => { await removeClaimOwnedBy(claimPath, token); } };
             }
             if (Date.now() >= deadline)
                 return undefined;
@@ -423,8 +290,6 @@ export async function acquireManagedSessionPolicyLock(options) {
     }
     finally {
         await rm(candidatePath, { force: true, recursive: true }).catch(() => undefined);
-        if (!lockAcquired)
-            await legacyBridge?.release();
         if (claimPublished && !lockAcquired)
             await removeClaimOwnedBy(claimPath, token);
     }

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

@@ -1,23 +1,17 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { chmodSync, lstatSync, readFileSync, unlinkSync } from "node:fs";
 import { extractUpstreamCommandTokens, parseCommandInfo } from "./argv-descriptor.js";
 import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, extractRequestedRestoreKey, getAgentBrowserSessionIdentityKey, isUpstreamEnvFlagEnabled, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
 import { hasLaunchScopedFlagToken, MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS, MANAGED_RESTORE_INCOMPATIBLE_ENVS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS, } from "./launch-scoped-flags.js";
 import { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 import { parseUserBatchStdin } from "./orchestration/batch-stdin.js";
 import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
-import { writeSecureTempFile } from "./temp.js";
 export { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope } from "./managed-session-storage.js";
 export { pruneOwnedManagedSessionRestoreSnapshots } from "./managed-session-snapshots.js";
 const AGENT_BROWSER_CONFIG_ENV = "AGENT_BROWSER_CONFIG";
 const AGENT_BROWSER_RESTORE_ENV = "AGENT_BROWSER_RESTORE";
 const MANAGED_SESSION_RESTORE_ENV = "PI_AGENT_BROWSER_MANAGED_SESSION_RESTORE";
 export const MANAGED_SESSION_NAME_PREFIX = "piab-";
-const MANAGED_SESSION_RESTORE_EMPTY_CONFIG_CONTENT = "{}\n";
-const MANAGED_SESSION_RESTORE_EMPTY_CONFIG_NAME = ".pi-agent-browser-managed-restore-config-v1.json";
 const MANAGED_SESSION_RESTORE_SPAWN_PINNED_ENVS = new Set([AGENT_BROWSER_CONFIG_ENV, AGENT_BROWSER_RESTORE_ENV, "AGENT_BROWSER_NAMESPACE"]);
-let managedSessionRestoreEmptyConfigPath;
-let managedSessionRestoreEmptyConfigPromise;
 function isDisabledEnvFlag(value) {
     if (value === undefined)
         return false;
@@ -108,7 +102,7 @@ function closesBrowserSession(args) {
 export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserProcessEnvironment(), args = []) {
     return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
 }
-/** Explicit config overrides disable restore; passive files are ignored because every browser-backed subprocess pins a protected empty config. */
+/** Caller-selected upstream config disables the wrapper's automatic restore injection without blocking that config. */
 export function agentBrowserConfigBlocksManagedRestore(_cwd, parentEnv = getAgentBrowserProcessEnvironment(), args = [], platform = process.platform) {
     return !resolveManagedSessionRestoreHome(parentEnv, platform) || agentBrowserExplicitConfigIsPresent(parentEnv, args);
 }
@@ -203,80 +197,6 @@ export function getOwnedManagedSessionCompatibilityEnv(options) {
         ...(ownedContext.headedManagedAutosaveInterval !== undefined && !explicitIntervalMatches ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: ownedContext.headedManagedAutosaveInterval } : {}),
     };
 }
-export function shouldOmitOwnedManagedSessionRestoreEnv(options) {
-    return resolveManagedSessionRestorePolicy(options).owned && closesBrowserSession(options.args);
-}
-export function canonicalizeOwnedManagedSessionCloseArgs(options, force = false) {
-    const policy = resolveManagedSessionRestorePolicy(options);
-    if (!policy.owned || !closesBrowserSession(options.args))
-        return options.args;
-    const sessionName = policy.ownedContext?.sessionName ?? policy.sessionName;
-    if (!sessionName)
-        return options.args;
-    const namespace = canonicalizeAgentBrowserNamespace(policy.ownedContext?.namespace ?? policy.namespace) ?? "";
-    const command = options.args.at(-1);
-    const prefix = options.args.slice(0, -1);
-    const safePrefixes = [
-        ["--session", sessionName],
-        ["--json", "--session", sessionName],
-        ["--namespace", namespace, "--session", sessionName],
-        ["--json", "--namespace", namespace, "--session", sessionName],
-    ];
-    if (!force && command && ["close", "exit", "quit"].includes(command)
-        && safePrefixes.some((candidate) => candidate.length === prefix.length && candidate.every((token, index) => token === prefix[index]))) {
-        return options.args;
-    }
-    return ["--json", "--namespace", namespace, "--session", sessionName, "close"];
-}
-export function cleanupManagedSessionRestoreConfig() {
-    if (managedSessionRestoreEmptyConfigPath) {
-        try {
-            unlinkSync(managedSessionRestoreEmptyConfigPath);
-        }
-        catch { }
-    }
-    managedSessionRestoreEmptyConfigPath = undefined;
-    managedSessionRestoreEmptyConfigPromise = undefined;
-}
-async function ensureManagedSessionRestoreEmptyConfig(platform) {
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            managedSessionRestoreEmptyConfigPromise ??= writeSecureTempFile({
-                content: MANAGED_SESSION_RESTORE_EMPTY_CONFIG_CONTENT,
-                prefix: MANAGED_SESSION_RESTORE_EMPTY_CONFIG_NAME.replace(/\.json$/, ""),
-                suffix: ".json",
-            }).then((path) => {
-                if (platform !== "win32")
-                    chmodSync(path, 0o400);
-                managedSessionRestoreEmptyConfigPath = path;
-                return path;
-            });
-            const path = await managedSessionRestoreEmptyConfigPromise;
-            let entry = lstatSync(path);
-            if (entry.isSymbolicLink() || !entry.isFile())
-                throw new Error("Managed restore config is not a regular file.");
-            if (platform !== "win32" && (entry.mode & 0o777) !== 0o400) {
-                chmodSync(path, 0o400);
-                entry = lstatSync(path);
-            }
-            if (entry.isSymbolicLink() || !entry.isFile() || (platform !== "win32" && (entry.mode & 0o777) !== 0o400))
-                throw new Error("Managed restore config permissions are unsafe.");
-            if (readFileSync(path, "utf8") !== MANAGED_SESSION_RESTORE_EMPTY_CONFIG_CONTENT)
-                throw new Error("Managed restore config content changed.");
-            return path;
-        }
-        catch {
-            cleanupManagedSessionRestoreConfig();
-        }
-    }
-    return undefined;
-}
-export async function getManagedSessionRestoreConfigEnv(restoreEnv, pinForOwnedClose = false) {
-    if (restoreEnv[AGENT_BROWSER_RESTORE_ENV] === undefined && !pinForOwnedClose)
-        return {};
-    const path = await ensureManagedSessionRestoreEmptyConfig(process.platform);
-    return path ? { [AGENT_BROWSER_CONFIG_ENV]: path } : undefined;
-}
 export function getManagedSessionRestoreProtectedEnv(options, restoreEnv) {
     const { ownedContext } = resolveManagedSessionRestorePolicy(options);
     if (restoreEnv[AGENT_BROWSER_RESTORE_ENV] === undefined)

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

@@ -3,8 +3,11 @@ 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";

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, 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,16 +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) || isAboutBlankUrl(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.priorTarget?.title && normalizeComparableUrl(options.priorTarget.url) === normalizeComparableUrl(url)) {
-        return { title: options.priorTarget.title, url };
+    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;
@@ -89,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;
@@ -531,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 } : {}) };
 }
@@ -566,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.",
         }),
     ];
@@ -588,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),
         };
     }
@@ -686,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.");
@@ -875,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");
@@ -910,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;
@@ -928,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"})`);

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

@@ -3,9 +3,10 @@ import { getCompiledSemanticActionCommandIndex, getCompiledSemanticActionSession
 import { redactNetworkSourceLookupSurface } from "../../input-modes/lookups.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
+import { extractAgentBrowserLifecycle } from "../../results/presentation/common.js";
 import { formatSessionArtifactRetentionSummary } from "../../results/artifact-manifest.js";
 import { alignPageChangeSummaryNextActionIds, appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, isStandaloneSnapshotNextAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
-import { buildConnectedSessionNextActions, buildNoActivePageNextActions, buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
+import { buildConnectedSessionNextActions, buildNoActivePageNextActions, buildPendingWebMcpNextActions, buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions, } from "../../results/recovery-next-actions.js";
 import { buildRichInputRecoveryDiagnostic, buildRichInputRecoveryNextActions, buildVisibleRefFallbackNextActions, formatRichInputRecoveryText, formatVisibleRefFallbackText, sanitizeVisibleRefFallbackDiagnostic, } from "../../results/selector-recovery.js";
 import { buildNoActivePageRefSnapshotInvalidation, isNoActivePageSnapshotFailure, } from "../../session-page-state.js";
 import { extractExplicitSessionName } from "../../argv-grammar.js";
@@ -208,6 +209,18 @@ function buildTimeoutPartialProgressNextActions(options) {
     const retryArgs = options.timeoutPartialProgress?.retryStep?.retry?.args;
     const stepIndex = options.timeoutPartialProgress?.retryStep?.index;
     const freshSessionAbandoned = options.sessionMode === "fresh" && options.timeoutPartialProgress?.liveUrlRecovered !== true;
+    if (options.currentSessionTabTargetUnknown && !freshSessionAbandoned && options.executionPlan.sessionName) {
+        return [{
+                id: "verify-page-target-after-timeout",
+                params: {
+                    args: withOptionalSessionArgs(options.executionPlan.sessionName, ["batch", "--bail"]),
+                    stdin: JSON.stringify([["get", "url"], ["snapshot", "-i"]]),
+                },
+                reason: `Verify the current URL, then inspect the page after timeout${stepIndex === undefined ? "" : ` before resuming from incomplete step ${stepIndex}`}.`,
+                safety: "Fail-fast read-only recovery: snapshot runs only after get url succeeds, satisfying the wrapper page-target guard without trusting the planned URL.",
+                tool: "agent_browser",
+            }];
+    }
     if (retryArgs) {
         return [{
                 id: "retry-timeout-step",
@@ -267,6 +280,10 @@ function buildResultNextActions(options) {
     const appendUnique = (actions) => {
         appendUniqueAgentBrowserNextActions(nextActions, actions);
     };
+    if (options.unsettledWebMcpMutation && options.currentSessionTabTargetUnknown) {
+        nextActions = nextActions.filter((action) => !isStandaloneSnapshotNextAction(action));
+        appendUnique(buildPendingWebMcpNextActions(options.executionPlan.sessionName));
+    }
     if (options.categoryDetails.resultCategory === "success" && options.executionPlan.commandInfo.command === "connect" && !options.electronLaunchRecord)
         appendUnique(buildConnectedSessionNextActions(options.executionPlan.sessionName));
     if (options.noActivePageSnapshotFailure)
@@ -320,6 +337,8 @@ function buildResultNextActions(options) {
     if (options.managedSessionOutcome)
         appendUnique(buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
     if (options.categoryDetails.failureCategory === "timeout" && options.processResult.timedOut) {
+        if (options.currentSessionTabTargetUnknown)
+            nextActions = nextActions.filter((action) => !isStandaloneSnapshotNextAction(action));
         appendUnique(buildTimeoutPartialProgressNextActions(options));
         appendUnique(buildDialogTimeoutNextActions({ command: options.executionPlan.commandInfo.command, sessionName: options.executionPlan.sessionName }));
     }
@@ -329,19 +348,45 @@ function buildResultNextActions(options) {
         append(buildAgentBrowserNextActions({ electron: { launchId: options.electronLaunchRecord.launchId, sessionName: options.electronLaunchRecord.sessionName, status: options.electronLaunchRecord.cleanupState }, failureCategory: options.categoryDetails.failureCategory, resultCategory: options.categoryDetails.resultCategory, successCategory: options.categoryDetails.successCategory }));
     return nextActions.length > 0 ? nextActions : undefined;
 }
-function formatFailureNextActionsText(options, nextActions) {
-    if (options.categoryDetails.resultCategory !== "failure" || !nextActions || nextActions.length === 0)
+export function formatAgentBrowserNextActionsText(nextActions) {
+    if (!nextActions || nextActions.length === 0)
         return undefined;
     const lines = nextActions.slice(0, 6).map((action) => {
         const params = action.params
-            ? { ...action.params, ...(action.params.stdin === undefined ? {} : { stdin: "[omitted; use details.nextActions]" }) }
+            ? { ...action.params, ...(action.params.stdin !== undefined && action.params.stdin.length > 500 ? { stdin: "[omitted; use details.nextActions]" } : {}) }
             : undefined;
         const payload = action.artifactPath ? { artifactPath: action.artifactPath } : params;
-        return `- ${action.id}${payload ? ` ${JSON.stringify(payload)}` : ""}: ${action.reason}`;
+        return `- ${action.id}${payload ? ` ${redactSensitiveText(JSON.stringify(payload))}` : ""}: ${redactSensitiveText(action.reason)}`;
     });
-    return ["Next actions:", ...lines, "Use the exact redacted payloads in details.nextActions when available."].join("\n");
+    return ["Next actions:", ...lines, "The same redacted payloads are available in details.nextActions."].join("\n");
+}
+function formatFailureNextActionsText(options, nextActions) {
+    return options.categoryDetails.resultCategory === "failure" ? formatAgentBrowserNextActionsText(nextActions) : undefined;
+}
+function getReadSource(options) {
+    return options.executionPlan.commandInfo.command === "read" && isRecord(options.presentationEnvelope?.data) && typeof options.presentationEnvelope.data.source === "string"
+        ? options.presentationEnvelope.data.source
+        : undefined;
+}
+function formatReadExecutionText(options, lifecycle) {
+    const source = getReadSource(options);
+    if (!source)
+        return undefined;
+    return `Read execution: source ${source}; CLI started: ${options.processResult.agentBrowserStarted ? "yes" : "no"}; managed browser lifecycle active: ${lifecycle?.effectiveLaunch.browserLaunched === true ? "yes" : "no"}; managed session outcome: ${options.managedSessionOutcome?.status ?? "not managed"}.`;
+}
+function buildBrowserWindowStatus(options, lifecycle) {
+    if (!options.headedLaunch || options.preserveAttachedBrowserSession || options.providerLaunch || !options.succeeded || lifecycle?.effectiveLaunch.browserLaunched !== true || !options.executionPlan.managedSessionName || !options.managedSessionOutcome || !["created", "replaced"].includes(options.managedSessionOutcome.status))
+        return undefined;
+    return { mode: "headed", ownership: "wrapper-managed", sessionName: options.executionPlan.managedSessionName, visibility: "unverified" };
+}
+function formatBrowserWindowText(browserWindow) {
+    if (!browserWindow)
+        return undefined;
+    return "Headed browser handoff: wrapper-managed headed window requested; desktop visibility unverified. If login is needed, ask the user to confirm they can see the window and finish signing in there, then continue with sessionMode auto.";
 }
 function buildAgentBrowserResultDetails(options, nextActions) {
+    const lifecycle = extractAgentBrowserLifecycle(options.presentationEnvelope?.data);
+    const browserWindow = buildBrowserWindowStatus(options, lifecycle);
     const publicVisibleRefFallbackDiagnostic = options.visibleRefFallbackDiagnostic ? sanitizeVisibleRefFallbackDiagnostic(options.visibleRefFallbackDiagnostic) : undefined;
     const rawPageChangeSummary = (options.scrollNoopDiagnostic || options.comboboxFocusDiagnostic) && options.presentation.pageChangeSummary ? { ...options.presentation.pageChangeSummary, nextActionIds: nextActions?.map((action) => action.id) } : options.presentation.pageChangeSummary;
     const pageChangeSummary = alignPageChangeSummaryNextActionIds(rawPageChangeSummary, nextActions);
@@ -370,6 +415,9 @@ function buildAgentBrowserResultDetails(options, nextActions) {
         electron: options.electronLaunchRecord ? { action: "launch", cleanup: options.electronFailedConnectCleanup, handoff: options.electronHandoff, identifiers: buildElectronIdentifiers(options.electronLaunchRecord), launch: options.electronLaunchRecord, profileIsolation: options.electronProfileIsolationDetails, status: options.succeeded ? "succeeded" : "failed", targets: options.electronLaunch?.targets, version: options.electronLaunch?.version } : undefined,
         ...options.categoryDetails,
         agentBrowserStarted: options.processResult.agentBrowserStarted,
+        browserWindow,
+        lifecycle,
+        readSource: getReadSource(options),
         aboutBlankSessionMismatch: options.aboutBlankSessionMismatch,
         electronPostCommandHealth: options.electronPostCommandHealth,
         electronRefFreshness: options.electronRefFreshnessDiagnostic,
@@ -429,6 +477,8 @@ function buildAgentBrowserResultDetails(options, nextActions) {
 }
 export function buildFinalAgentBrowserToolResult(options) {
     const nextActions = applyNamespaceToNextActions(buildResultNextActions(options), options.executionPlan.namespace);
+    const lifecycle = extractAgentBrowserLifecycle(options.presentationEnvelope?.data);
+    const browserWindow = buildBrowserWindowStatus(options, lifecycle);
     const details = buildAgentBrowserResultDetails(options, nextActions);
     const visibleRefFallbackText = formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic);
     const richInputRecoveryText = formatRichInputRecoveryText(options.richInputRecoveryDiagnostic);
@@ -445,10 +495,12 @@ export function buildFinalAgentBrowserToolResult(options) {
     const evalStdinHintText = formatEvalStdinHintText(options.evalStdinHint);
     const evalResultWarningText = formatEvalResultWarningText(options.evalResultWarning);
     const artifactCleanupText = formatArtifactCleanupGuidanceText(options.artifactCleanup);
-    const timeoutPartialProgressText = options.timeoutPartialProgress ? formatTimeoutPartialProgressText(options.timeoutPartialProgress) : undefined;
+    const timeoutPartialProgressText = options.timeoutPartialProgress ? formatTimeoutPartialProgressText(options.timeoutPartialProgress, options.currentSessionTabTargetUnknown === true && !(options.sessionMode === "fresh" && options.timeoutPartialProgress.liveUrlRecovered !== true)) : undefined;
     const managedSessionOutcomeText = formatManagedSessionOutcomeText(options.managedSessionOutcome);
+    const readExecutionText = formatReadExecutionText(options, lifecycle);
+    const browserWindowText = formatBrowserWindowText(browserWindow);
     const failureNextActionsText = formatFailureNextActionsText(options, nextActions);
-    const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, clickDispatchText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, evalResultWarningText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText, failureNextActionsText].filter((item) => item !== undefined).join("\n\n");
+    const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, clickDispatchText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, evalResultWarningText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText, readExecutionText, browserWindowText, failureNextActionsText].filter((item) => item !== undefined).join("\n\n");
     const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, options.exactSensitiveValues));
     const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!options.userRequestedJson || options.plainTextInspection);
     let content = shouldAppendDiagnosticText && options.redactedContent[0]?.type === "text" ? [{ ...options.redactedContent[0], text: `${options.redactedContent[0].text}\n\n${appendedDiagnosticText}` }, ...options.redactedContent.slice(1)] : options.redactedContent;

package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js

@@ -20,7 +20,6 @@ function getHeadedManagedAutosaveEnv(interval) {
 }
 export async function inspectManagedSessionDaemon(options) {
     const processResult = await runAgentBrowserProcess({
-        allowManagedSessionTarget: options.allowManagedSessionTarget,
         args: ["--json", "--namespace", options.namespace ?? "", "--session", options.sessionName, "session", "info"],
         cwd: options.cwd,
         env: getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
@@ -63,12 +62,11 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
         return signal?.aborted
             ? {}
             : {
-                error: "Managed-session policy coordination is unavailable or busy. Retry after the current operation finishes, repair the private policy-lock directory, and on POSIX verify that /bin/ps or /usr/bin/ps is available.",
+                error: "Managed-session policy coordination is unavailable or busy. Retry after the current operation finishes, repair the private policy-lock directory, and on POSIX verify that /bin/ps, /usr/bin/ps, or ps through PATH is available.",
             };
     }
     try {
         const daemon = await inspectManagedSessionDaemon({
-            allowManagedSessionTarget: true,
             cwd: context.cwd,
             headedManagedAutosaveInterval: context.headedManagedAutosaveInterval,
             namespace: context.namespace,
@@ -133,7 +131,6 @@ export async function closeManagedSession(options) {
     }
     try {
         const daemon = await inspectManagedSessionDaemon({
-            allowManagedSessionTarget: true,
             cwd: options.cwd,
             headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
             namespace: options.namespace,