pi-agent-browser-native 0.6.6 → 0.6.8

package/dist/extensions/agent-browser/index.js

@@ -5,7 +5,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./lib/batch-lifecycle.js";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactSensitiveText, isPlainTextInspectionArgs, } from "./lib/runtime.js";
+import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractUpstreamCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, redactSensitiveText, isPlainTextInspectionArgs, } from "./lib/runtime.js";
 import { extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
 import { parseArgvDescriptor } from "./lib/argv-descriptor.js";
 import { needsManagedSession } from "./lib/command-policy.js";
@@ -680,7 +680,7 @@ function shouldSerializeBrowserCommand(options) {
         return true;
     if (options.explicitSessionName === options.managedSessionName)
         return true;
-    if (options.ownedManagedSessions.has(getSessionContextKey(options.explicitSessionName, options.explicitNamespace) ?? options.explicitSessionName))
+    if (options.ownedManagedSessions.has(getSessionContextKey(options.explicitSessionName, options.namespace) ?? options.explicitSessionName))
         return true;
     return getActiveElectronRecords(options.ownedElectronLaunchRecords).some((record) => record.sessionName === options.explicitSessionName);
 }
@@ -844,7 +844,7 @@ export default function agentBrowserExtension(pi) {
     let artifactManifest;
     let activeRecordingReservations = new Map();
     let recordingSessionTombstones = new Map();
-    let recordingSessionTombstonesToPersist = new Map();
+    let recordingReservationsDirty = false;
     let attachedSessionKeys = new Set();
     let networkRoutesBySession = new Map();
     let electronLaunchRecords = new Map();
@@ -861,23 +861,64 @@ export default function agentBrowserExtension(pi) {
     let branchRestoreGeneration = 0;
     let branchStateGeneration = 0;
     const validatedUpstreamPathKeys = new Set();
+    const recordingPersistenceWarning = "Recording persistence warning: recording protection could not be saved to the Pi journal. Restart protection is not yet durable; keep recording destinations untouched until exact stop or close. The next browser operation retries journal persistence; cleanup remains available.";
+    const flushRecordingReservations = () => {
+        if (!recordingReservationsDirty)
+            return;
+        try {
+            // Pi updates branch memory before writing. One failed append can hide an earlier
+            // durable reservation after reopen, so republish all current state, not just the failed row.
+            for (const reservation of recordingSessionTombstones.values())
+                appendRecordingReservationTransition(pi, { reservation, state: "closed" });
+            for (const reservation of activeRecordingReservations.values())
+                appendRecordingReservationTransition(pi, { reservation, state: "active" });
+            recordingReservationsDirty = false;
+        }
+        catch { }
+    };
+    const warnRecordingPersistence = (result) => {
+        if (!recordingReservationsDirty)
+            return result;
+        const content = [...result.content];
+        const first = content[0];
+        let json;
+        if (first?.type === "text") {
+            try {
+                json = JSON.parse(first.text);
+            }
+            catch { }
+        }
+        if (isRecord(json) && typeof json.success === "boolean") {
+            content[0] = { type: "text", text: JSON.stringify({ ...json, warnings: [...(Array.isArray(json.warnings) ? json.warnings : []), recordingPersistenceWarning] }, null, 2) };
+        }
+        else if (first?.type === "text")
+            content[0] = { ...first, text: `${first.text}\n\n${recordingPersistenceWarning}` };
+        else
+            content.push({ type: "text", text: recordingPersistenceWarning });
+        return { ...result, content, details: { ...(isRecord(result.details) ? result.details : {}), recordingPersistenceWarning } };
+    };
+    const notifyRecordingPersistence = (ctx) => {
+        if (!recordingReservationsDirty)
+            return;
+        if (ctx.hasUI)
+            ctx.ui.notify(recordingPersistenceWarning, "warning");
+        else
+            console.warn(recordingPersistenceWarning);
+    };
     const appendRecordingTransitions = (transitions) => {
         for (const transition of transitions) {
             const key = getAgentBrowserSessionIdentityKey(transition.reservation.sessionName, transition.reservation.namespace);
-            if (transition.state === "active") {
+            if (transition.state === "active")
                 recordingSessionTombstones.delete(key);
-                recordingSessionTombstonesToPersist.delete(key);
-            }
-            else {
+            else
                 recordingSessionTombstones.set(key, transition.reservation);
-            }
+            if (recordingReservationsDirty)
+                continue;
             try {
                 appendRecordingReservationTransition(pi, transition);
-                recordingSessionTombstonesToPersist.delete(key);
             }
             catch {
-                if (transition.state === "closed")
-                    recordingSessionTombstonesToPersist.set(key, transition.reservation);
+                recordingReservationsDirty = true;
             }
         }
     };
@@ -885,19 +926,28 @@ export default function agentBrowserExtension(pi) {
         if (result.isError !== true)
             return result;
         const details = isRecord(result.details) ? result.details : {};
-        const nextActions = Array.isArray(details.nextActions) ? [...details.nextActions] : [];
-        if (nextActions.some((action) => action.id === "stop-pending-recording"))
+        const cleanupOnly = details.managedSessionCleanupOnlyReason === "restore-disabled-daemon-without-provenance";
+        const nextActions = (Array.isArray(details.nextActions) ? details.nextActions : [])
+            .filter((action) => !cleanupOnly || action.id !== "stop-pending-recording");
+        const actionId = cleanupOnly ? "close-pending-recording" : "stop-pending-recording";
+        if (nextActions.some((action) => action.id === actionId))
             return result;
         const stopActions = applyNamespaceToNextActions(applySessionToNextActions([
             buildNextToolAction({
-                args: ["record", "stop"],
-                id: "stop-pending-recording",
-                reason: "Stop the active recording so the requested video can be finalized and verified on disk.",
-                safety: "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
+                args: cleanupOnly ? ["close"] : ["record", "stop"],
+                id: actionId,
+                reason: cleanupOnly
+                    ? "Close this exact session to abandon the recording; its live daemon lacks current-instance provenance."
+                    : "Stop the active recording so the requested video can be finalized and verified on disk.",
+                safety: cleanupOnly
+                    ? "Close does not verify the WebM. The recording is abandoned/unverified, even if close leaves a file on disk."
+                    : "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
             }),
-        ], reservation.sessionName), reservation.namespace);
+        ], reservation.sessionName), cleanupOnly ? reservation.namespace ?? "" : reservation.namespace);
         appendUniqueAgentBrowserNextActions(nextActions, stopActions);
-        const cleanupNotice = "An active recording remains open. Use the exact stop-pending-recording payload in details.nextActions before leaving this session.";
+        const cleanupNotice = cleanupOnly
+            ? "This recording cannot be stopped through the unproven daemon. Use the exact close-pending-recording payload in details.nextActions; any WebM left by close is abandoned/unverified."
+            : "An active recording remains open. Use the exact stop-pending-recording payload in details.nextActions before leaving this session.";
         let noticeAppended = false;
         const content = result.content.map((item) => {
             if (noticeAppended || item.type !== "text")
@@ -917,18 +967,7 @@ export default function agentBrowserExtension(pi) {
         if (!reservation && artifactManifest === previousManifest)
             return;
         const terminalReservation = reservation ?? { absolutePath: "", cwd: managedSessionCwd, namespace, path: "", sessionName };
-        const terminalKey = getAgentBrowserSessionIdentityKey(sessionName, namespace);
-        recordingSessionTombstones.set(terminalKey, terminalReservation);
-        try {
-            appendRecordingReservationTransition(pi, {
-                reservation: terminalReservation,
-                state: "closed",
-            });
-            recordingSessionTombstonesToPersist.delete(terminalKey);
-        }
-        catch {
-            recordingSessionTombstonesToPersist.set(terminalKey, terminalReservation);
-        }
+        appendRecordingTransitions([{ reservation: terminalReservation, state: "closed" }]);
     };
     const syncRecordingReservationsFromResult = (result) => {
         const handledClosedSessionKeys = new Set();
@@ -1107,20 +1146,25 @@ export default function agentBrowserExtension(pi) {
         traceOwners = new Map();
         artifactManifest = restoreArtifactManifestFromBranch(branch);
         const restoredRecordingState = restoreRecordingReservationStateFromBranch(branch);
-        for (const [key, reservation] of recordingSessionTombstones) {
-            if (restoredRecordingState.terminal.has(key))
-                recordingSessionTombstonesToPersist.delete(key);
-            else
-                recordingSessionTombstonesToPersist.set(key, reservation);
+        for (const key of recordingSessionTombstones.keys()) {
+            if (!restoredRecordingState.terminal.has(key))
+                recordingReservationsDirty = true;
         }
         for (const [key, reservation] of restoredRecordingState.terminal) {
             if (!activeRecordingReservations.has(key))
                 recordingSessionTombstones.set(key, reservation);
         }
-        for (const key of recordingSessionTombstones.keys())
+        for (const [key, reservation] of recordingSessionTombstones) {
             restoredRecordingState.active.delete(key);
-        for (const [key, reservation] of activeRecordingReservations)
+            if (artifactManifest)
+                artifactManifest = retirePendingRecordingManifestEntries(artifactManifest, reservation.sessionName, reservation.namespace);
+        }
+        for (const [key, reservation] of activeRecordingReservations) {
+            const restored = restoredRecordingState.active.get(key);
+            if (restored?.absolutePath !== reservation.absolutePath || restored.cwd !== reservation.cwd)
+                recordingReservationsDirty = true;
             restoredRecordingState.active.set(key, reservation);
+        }
         activeRecordingReservations = restoredRecordingState.active;
         attachedSessionKeys = restoreAttachedSessionKeysFromBranch(branch);
         networkRoutesBySession = new Map();
@@ -1214,7 +1258,11 @@ export default function agentBrowserExtension(pi) {
             cwd: ctx.cwd,
             includeProjectConfig: shouldIncludeProjectConfig(ctx),
         }));
-        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => recoverScriptSessionLeasesWithinQueue(ctx)));
+        await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
+            await recoverScriptSessionLeasesWithinQueue(ctx);
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
+        }));
     });
     pi.on("session_tree", async (_event, ctx) => {
         for (const controller of activeScriptControllers)
@@ -1223,6 +1271,8 @@ export default function agentBrowserExtension(pi) {
         await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(async () => {
             restoreBranchBackedState(ctx, { resetRuntimeOwnership: false });
             await recoverScriptSessionLeasesWithinQueue(ctx);
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
         }));
     });
     pi.on("session_shutdown", async (event, ctx) => {
@@ -1263,30 +1313,21 @@ export default function agentBrowserExtension(pi) {
             else {
                 await closeOwnedManagedSessionsExcept(ownedManagedSessions, managedSessionRestoreState, managedSessionActive ? managedSessionName : undefined, implicitSessionCloseTimeoutMs, attachedSessionKeys, managedSessionActive ? managedSessionNamespace : undefined, (owner) => retireRecordingSession(owner.sessionName, owner.namespace));
             }
+            flushRecordingReservations();
+            notifyRecordingPersistence(ctx);
         }));
         managedSessionActive = false;
         managedSessionCompatibilityWorkaround = undefined;
         managedSessionHeadedAutosaveDisabled = false;
         managedSessionHeadedAutosaveInterval = undefined;
         managedSessionNamespace = undefined;
-        for (const reservation of recordingSessionTombstonesToPersist.values()) {
-            try {
-                appendRecordingReservationTransition(pi, { reservation, state: "closed" });
-            }
-            catch { }
-        }
-        for (const reservation of activeRecordingReservations.values()) {
-            try {
-                appendRecordingReservationTransition(pi, { reservation, state: "active" });
-            }
-            catch { }
-        }
         sessionPageState.reset();
         traceOwners = new Map();
         artifactManifest = undefined;
-        activeRecordingReservations = new Map();
-        recordingSessionTombstones = new Map();
-        recordingSessionTombstonesToPersist = new Map();
+        if (!recordingReservationsDirty) {
+            activeRecordingReservations = new Map();
+            recordingSessionTombstones = new Map();
+        }
         attachedSessionKeys = new Set();
         networkRoutesBySession = new Map();
         electronLaunchRecords = new Map();
@@ -1365,8 +1406,9 @@ export default function agentBrowserExtension(pi) {
             }
             const applyUnserializedOutputPath = async (result, preserveTextContent = false) => {
                 if (!outputPath || result.isError === true || (isRecord(result.details) && result.details.resultCategory === "failure"))
-                    return result;
+                    return warnRecordingPersistence(result);
                 return artifactExecutionQueue.run(async () => {
+                    flushRecordingReservations();
                     const reservationError = getArtifactPreflightValidationError({
                         activeRecordingReservations: activeRecordingReservations.values(),
                         args: [],
@@ -1374,9 +1416,9 @@ export default function agentBrowserExtension(pi) {
                         outputPath,
                     });
                     if (reservationError) {
-                        return buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError });
+                        return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
                     }
-                    return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent, result });
+                    return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent, result: warnRecordingPersistence(result) });
                 });
             };
             const versionCheckCommand = extractUpstreamCommandTokens(resolvedInput.toolArgs)[0];
@@ -1459,7 +1501,10 @@ export default function agentBrowserExtension(pi) {
                     signal?.removeEventListener("abort", abortScript);
                     if (leased) {
                         try {
-                            cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd)));
+                            cleanupError = await artifactExecutionQueue.run(() => managedSessionExecutionQueue.run(() => {
+                                flushRecordingReservations();
+                                return closeScriptSessionLeaseWithinQueue(sessionName, ctx.cwd);
+                            }));
                         }
                         catch {
                             cleanupError = "The isolated script session cleanup operation failed.";
@@ -1563,6 +1608,7 @@ export default function agentBrowserExtension(pi) {
                 : runElectronHostInput();
             const electronHostResult = compiledElectron?.action === "cleanup"
                 ? await artifactExecutionQueue.run(async () => {
+                    flushRecordingReservations();
                     const reservationError = outputPath ? getArtifactPreflightValidationError({
                         activeRecordingReservations: activeRecordingReservations.values(),
                         args: [],
@@ -1570,31 +1616,31 @@ export default function agentBrowserExtension(pi) {
                         outputPath,
                     }) : undefined;
                     if (reservationError) {
-                        return buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError });
+                        return warnRecordingPersistence(buildValidationFailureResult({ attemptedKind: resolvedInput.kind, kind: "invalid", redactedArgs: resolvedInput.redactedArgs, status: "invalid", toolArgs: resolvedInput.toolArgs, toolStdin: resolvedInput.toolStdin, validationError: reservationError }));
                     }
                     const result = await runSerializedElectronHostInput();
-                    return result ? applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result }) : result;
+                    return result ? applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, result: warnRecordingPersistence(result) }) : result;
                 })
                 : await runSerializedElectronHostInput();
             if (electronHostResult) {
                 return compiledElectron?.action === "cleanup" ? electronHostResult : applyUnserializedOutputPath(electronHostResult);
             }
             const explicitSessionName = extractExplicitSessionName(toolArgs);
-            const explicitNamespace = extractExplicitNamespace(toolArgs);
+            const callerOwnedSessionNamespace = explicitSessionName
+                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
+                : undefined;
             const serializeBrowserCommand = shouldSerializeBrowserCommand({
-                explicitNamespace,
+                namespace: callerOwnedSessionNamespace,
                 explicitSessionName,
                 managedSessionName,
                 ownedElectronLaunchRecords,
                 ownedManagedSessions,
             });
-            const callerOwnedSessionNamespace = explicitSessionName
-                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
-                : undefined;
             const callerOwnedSessionQueueKey = !serializeBrowserCommand && explicitSessionName
                 ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
                 : undefined;
             const runBrowserCommand = async () => {
+                flushRecordingReservations();
                 const branchRestoreGenerationAtStart = branchRestoreGeneration;
                 const generationAtStart = branchStateGeneration;
                 const sessionPageStateUpdate = sessionPageState.beginUpdate();
@@ -1620,6 +1666,14 @@ export default function agentBrowserExtension(pi) {
                     sessionPageState,
                     traceOwners,
                 };
+                const selectedPlan = buildExecutionPlan(toolArgs, {
+                    freshSessionName: createFreshSessionName(browserRunState.managedSessionBaseName, browserRunState.ephemeralSessionSeed, browserRunState.freshSessionOrdinal + 1),
+                    managedSessionActive: browserRunState.managedSessionActive,
+                    managedSessionCompatibilityWorkaround: browserRunState.managedSessionCompatibilityWorkaround,
+                    managedSessionName: browserRunState.managedSessionName,
+                    managedSessionNamespace: browserRunState.managedSessionNamespace,
+                    sessionMode: compiledElectron?.action === "launch" ? "fresh" : params.sessionMode ?? "auto",
+                });
                 const initialArtifactManifest = browserRunState.artifactManifest;
                 const initialNetworkRoutesBySession = browserRunState.networkRoutesBySession;
                 const attachedSessionRequested = isAttachedBrowserInvocation(toolArgs)
@@ -1628,7 +1682,8 @@ export default function agentBrowserExtension(pi) {
                     && (params.sessionMode === "fresh" || (resolvedInput.kind === "electron" && resolvedInput.compiledElectron.action === "launch"));
                 const reusableSessionKey = allocatesFreshManagedSession
                     ? undefined
-                    : callerOwnedSessionQueueKey ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
+                    : getSessionContextKey(selectedPlan.sessionName, selectedPlan.namespace)
+                        ?? getSessionContextKey(browserRunState.managedSessionName, browserRunState.managedSessionNamespace);
                 const attachedSessionKnown = reusableSessionKey !== undefined && attachedSessionKeys.has(reusableSessionKey);
                 let result = await runAgentBrowserTool({
                     ctx,
@@ -1654,7 +1709,7 @@ export default function agentBrowserExtension(pi) {
                     : extractExplicitSessionName(toolArgs);
                 const resultNamespace = typeof resultDetails?.namespace === "string"
                     ? resultDetails.namespace
-                    : resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+                    : selectedPlan.namespace;
                 if (branchRestoreStillCurrent) {
                     const resultBatchCloseLifecycle = getSuccessfulBatchCloseLifecycle(resultDetails?.batchSteps);
                     const resultSessionKey = getSessionContextKey(resultSessionName, resultNamespace) ?? resultSessionName;
@@ -1732,21 +1787,28 @@ export default function agentBrowserExtension(pi) {
                     mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
                         branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
                         touchedLaunchIds: !result.isError
-                            ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, explicitSessionName ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE) : browserRunState.managedSessionNamespace)
+                            ? getTouchedElectronLaunchIds(explicitSessionName ?? browserRunState.managedSessionName, electronLaunchRecords, resultNamespace)
                             : undefined,
                     });
                     if (serializeBrowserCommand)
                         branchStateGeneration += 1;
                 }
-                return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result });
+                return applyAgentBrowserOutputPath({ cwd: ctx.cwd, outputPath, preserveTextContent: Array.isArray(params.args) && params.args.includes("--json"), result: warnRecordingPersistence(result) });
             };
             const closesAllSessions = commandClosesAllSessions(toolArgs, resolvedInput.toolStdin);
-            const closeAllNamespace = closesAllSessions
-                ? resolveAgentBrowserNamespace(toolArgs, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE)
-                : undefined;
             const runWithinSessionQueue = () => {
                 if (closesAllSessions)
-                    return managedSessionExecutionQueue.run(() => callerOwnedSessionExecutionQueues.runExclusive(closeAllNamespace, runBrowserCommand));
+                    return managedSessionExecutionQueue.run(() => {
+                        const plan = buildExecutionPlan(toolArgs, {
+                            freshSessionName: createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal + 1),
+                            managedSessionActive,
+                            managedSessionCompatibilityWorkaround,
+                            managedSessionName,
+                            managedSessionNamespace,
+                            sessionMode: params.sessionMode ?? "auto",
+                        });
+                        return callerOwnedSessionExecutionQueues.runExclusive(plan.namespace, runBrowserCommand);
+                    });
                 if (serializeBrowserCommand)
                     return managedSessionExecutionQueue.run(runBrowserCommand);
                 return callerOwnedSessionQueueKey
@@ -1765,10 +1827,11 @@ export default function agentBrowserExtension(pi) {
                 });
                 if (!artifactValidationError)
                     return runWithinSessionQueue();
+                flushRecordingReservations();
                 return applyAgentBrowserOutputPath({
                     cwd: ctx.cwd,
                     outputPath,
-                    result: buildValidationFailureResult({
+                    result: warnRecordingPersistence(buildValidationFailureResult({
                         attemptedKind: resolvedInput.kind,
                         kind: "invalid",
                         redactedArgs: resolvedInput.redactedArgs,
@@ -1776,7 +1839,7 @@ export default function agentBrowserExtension(pi) {
                         toolArgs: resolvedInput.toolArgs,
                         toolStdin: resolvedInput.toolStdin,
                         validationError: artifactValidationError,
-                    }),
+                    })),
                 });
             });
         },

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -143,7 +143,6 @@ const COMMAND_CAPABILITIES = [
         command: "keyboard",
         eligibleForElectronHealthProbe: true,
         eligibleForPageChangeSummary: true,
-        guardsPageRefs: true,
         invalidatesBatchRefs: true,
         triggersPostMutationSnapshot: true,
     },
@@ -157,7 +156,6 @@ const COMMAND_CAPABILITIES = [
     {
         command: "mouse",
         eligibleForElectronHealthProbe: true,
-        guardsPageRefs: true,
         invalidatesBatchRefs: true,
     },
     {
@@ -181,7 +179,6 @@ const COMMAND_CAPABILITIES = [
         command: "press",
         eligibleForElectronHealthProbe: true,
         eligibleForPageChangeSummary: true,
-        guardsPageRefs: true,
         invalidatesBatchRefs: true,
         triggersPostMutationSnapshot: true,
     },
@@ -330,8 +327,11 @@ export function isRecordPageTransitionCommand(tokens) {
 export function isWebMcpPageMutationCommand(tokens) {
     return isWebMcpPageMutation(tokens[0], tokens[1]);
 }
+export function isWindowOrDiffPageTransitionCommand(command, subcommand) {
+    return (command === "window" && subcommand === "new") || (command === "diff" && subcommand === "url");
+}
 export function isRefInvalidatingBatchCommand(step) {
-    return hasCommandCapability(step[0], "invalidatesBatchRefs") || isRecordPageTransitionCommand(step) || isWebMcpPageMutationCommand(step);
+    return hasCommandCapability(step[0], "invalidatesBatchRefs") || isRecordPageTransitionCommand(step) || isWebMcpPageMutationCommand(step) || isWindowOrDiffPageTransitionCommand(step[0], step[1]);
 }
 export function isRefGuardedCommand(command) {
     return hasCommandCapability(command, "guardsPageRefs");
@@ -343,12 +343,13 @@ function isWebMcpPageMutation(command, subcommand) {
     return command === "webmcp" && WEBMCP_PAGE_MUTATION_SUBCOMMANDS.has(subcommand ?? "");
 }
 export function isNavigationObservableCommandName(command, subcommand) {
-    return hasCommandCapability(command, "navigationObservable") || isWebMcpPageMutation(command, subcommand);
+    return hasCommandCapability(command, "navigationObservable") || isWebMcpPageMutation(command, subcommand) || isWindowOrDiffPageTransitionCommand(command, subcommand);
 }
 export function isUnverifiedPageTransitionCommand(command, subcommand) {
     return ["back", "connect", "eval", "forward", "reload"].includes(command ?? "")
         || (command === "state" && subcommand === "load")
         || (command === "tab" && subcommand !== undefined && !["list", "new"].includes(subcommand))
+        || isWindowOrDiffPageTransitionCommand(command, subcommand)
         || isWebMcpPageMutation(command, subcommand);
 }
 export function isPageMutationCommand(command, subcommand) {

package/dist/extensions/agent-browser/lib/electron/cleanup.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { rm } from "node:fs/promises";
+import { lstat, rm } from "node:fs/promises";
 import { promisify } from "node:util";
 import { fetchCdpJson, parseCdpTargets, parseCdpVersion } from "./cdp.js";
 import { ELECTRON_PROFILE_DIR_PREFIX } from "./launch.js";
@@ -33,6 +33,14 @@ async function isPortAlive(port) {
 }
 export async function inspectElectronLaunchStatus(record) {
     const cdp = await isPortAlive(record.port);
+    let userDataDirState;
+    try {
+        await lstat(record.userDataDir);
+        userDataDirState = "present";
+    }
+    catch (error) {
+        userDataDirState = error.code === "ENOENT" ? "absent" : "unknown";
+    }
     return {
         cleanupState: record.cleanupState,
         launchId: record.launchId,
@@ -41,6 +49,7 @@ export async function inspectElectronLaunchStatus(record) {
         port: record.port,
         portAlive: cdp.version !== undefined,
         targets: cdp.targets,
+        userDataDirState,
         version: cdp.version,
     };
 }

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -11,7 +11,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
             maxLength: AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES,
         })),
         args: Type.Optional(Type.Array(Type.String(), {
-            description: "Raw agent-browser argv only: no binary, shell operators, or --json. Start with open → snapshot -i → act on current @refs; re-snapshot after page changes.",
+            description: "Raw agent-browser argv only: no binary, shell operators, or --json. Start with open → snapshot -i → act on current @refs; re-snapshot after page changes. Input: type <selector> <text>, or keyboard type <text> at current focus. Wait duration: wait <ms> (no --time). Artifacts: screenshot [selector] [path] [--full/-f]; record start <path> [url]; record restart <path> [url]; record stop. Paths are positional (no --path); use --full, not --full-page.",
             minItems: 1,
         })),
         semanticAction: Type.Optional(Type.Object({
@@ -21,10 +21,23 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
             values: Type.Optional(Type.Array(Type.String(), { description: "Select options; required for select by label.", minItems: 1 })),
             selector: Type.Optional(Type.String({ description: "Direct selector or @ref." })),
             text: Type.Optional(Type.String({ description: "Fill text." })),
-            role: Type.Optional(Type.String({ description: "Role locator; alternative to value." })),
+            role: Type.Optional(Type.String({ description: "Role for locator=role; select needs combobox or listbox." })),
             name: Type.Optional(Type.String({ description: "Accessible name." })),
             session: Type.Optional(Type.String({ description: "Upstream session name." })),
-        }, { additionalProperties: false, description: "Stable locator or direct-selector action." })),
+        }, {
+            additionalProperties: false,
+            // Pi normalizes optional nulls through properties, not union branches.
+            anyOf: [
+                Type.Object({
+                    action: StringEnum(["select"]),
+                    locator: Type.Optional(StringEnum(["role", "label"])),
+                }, { not: { required: ["text"] } }),
+                Type.Object({
+                    action: StringEnum(["check", "click", "fill"]),
+                }, { not: { required: ["values"] } }),
+            ],
+            description: "Stable locator or direct-selector action. values only with action=select.",
+        })),
         qa: Type.Optional(Type.Union([
             Type.Object({
                 attached: Type.Literal(true),
@@ -112,7 +125,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
                 locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator when selector is omitted." })),
                 role: Type.Optional(Type.String({ description: "Role locator." })),
                 name: Type.Optional(Type.String({ description: "Accessible name." })),
-                text: Type.Optional(Type.String({ description: "Fill text or assertText target." })),
+                text: Type.Optional(Type.String({ description: "Fill/type text; assertText uses only text, not selector/locator fields." })),
                 value: Type.Optional(Type.String({ description: "Select option or locator value." })),
                 values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
                 path: Type.Optional(Type.String({ description: "Download or screenshot path." })),
@@ -120,10 +133,10 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
                 press: Type.Optional(Type.String({ description: "Key to press after typing." })),
                 milliseconds: Type.Optional(Type.Number({ description: "Wait duration in milliseconds." })),
             }, { additionalProperties: false }), { minItems: 1 }),
-        }, { additionalProperties: false, description: "Constrained multi-step batch." })),
-        stdin: Type.Optional(Type.String({ description: "Raw stdin for batch, eval --stdin, or auth save --password-stdin; unavailable with structured modes and electron." })),
+        }, { additionalProperties: false, description: "Constrained multi-step batch. Clicks can stale later refs; split and re-snapshot before using them." })),
+        stdin: Type.Optional(Type.String({ description: "For batch, a JSON array of token arrays, e.g. [[\"get\",\"title\"]]. Raw text only for eval --stdin or auth save --password-stdin; unavailable with structured modes and electron." })),
         outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result-data path; keep it distinct from screenshot, download, recording, and other browser artifact destinations.", minLength: 1 })),
-        timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. Electron uses electron.timeoutMs.", minimum: 1 })),
+        timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. electron.list has no configurable timeout; other Electron actions use electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
             description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",
             default: DEFAULT_SESSION_MODE,

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -150,7 +150,6 @@ export const MANAGED_RESTORE_INCOMPATIBLE_ENVS = [
     "AGENT_BROWSER_PROFILE",
     "AGENT_BROWSER_STATE",
     "AGENT_BROWSER_CDP",
-    "AGENT_BROWSER_NAMESPACE",
     "AGENT_BROWSER_SESSION_NAME",
     "AGENT_BROWSER_PROVIDER",
     "AGENT_BROWSER_EXECUTABLE_PATH",