pi-agent-browser-native 0.2.77 → 0.3.0

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

@@ -5,8 +5,11 @@ import { OPEN_RESULT_TAB_CORRECTION_FLAGS } from "../../launch-scoped-flags.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { getAllowedDomainsViolation, parseAllowedDomainsPolicyFromArgs } from "../../navigation-policy.js";
 import { getManagedSessionResultingPageState, getObservedBrowserPageValidationError, managedSessionCommandRequiresLivePageVerification } from "../../managed-session-state-policy.js";
-import { analyzeNetworkSourceLookupResults, analyzeQaPresetResults, analyzeQaPresetTimeout, analyzeSourceLookupResults, buildQaCompactPassText, extractQaPageContext, redactNetworkSourceLookupAnalysis, } from "../../input-modes.js";
-import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics, buildToolPresentation, getAgentBrowserErrorText, parseAgentBrowserEnvelope, } from "../../results.js";
+import { analyzeNetworkSourceLookupResults, analyzeSourceLookupResults, redactNetworkSourceLookupAnalysis } from "../../input-modes/lookups.js";
+import { analyzeQaPresetResults, analyzeQaPresetTimeout, buildQaCompactPassText, extractQaPageContext } from "../../input-modes/job.js";
+import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics } from "../../results/network-routes.js";
+import { buildToolPresentation } from "../../results/presentation.js";
+import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { getClipboardWritePayloadCandidates, redactClipboardPermissionEcho, redactClipboardPermissionErrorValue } from "../../results/presentation/errors.js";
 import { shouldCaptureSemanticActionNavigationSummary } from "../../results/presentation/semantic-action.js";
 import { commandExplicitlyTargetsAboutBlank, deriveSessionTabTarget, extractLatestRefSnapshotStateFromBatchResults, extractRefSnapshotFromData, extractSessionTabTargetFromBatchResults, extractSessionTabTargetFromCommandData, isAboutBlankSessionTabTarget, normalizeSessionTabTarget, } from "../../session-page-state.js";
@@ -19,7 +22,7 @@ import { applyOpenResultTabCorrection, buildAboutBlankRecoveryHint, buildAboutBl
 import { collectClickDispatchDiagnostic } from "./click-dispatch.js";
 import { buildScrollNoopDiagnostic, collectComboboxFocusDiagnostic, collectElectronBroadGetTextScopeDiagnostics, collectElectronHandoff, collectFillVerificationDiagnostic, collectNavigationSummary, collectOverlayBlockerDiagnostic, collectQaAttachedTarget, collectSnapshotOverlayBlockerDiagnostic, collectRecordingDependencyWarning, collectScrollPositionSnapshot, collectSelectorTextVisibilityDiagnostics, collectTimeoutPartialProgress, sleepMs, formatQaAttachedTargetText, getArtifactCleanupGuidance, getEvalResultWarning, getEvalStdinHint, getSourceLookupElectronContext, } from "./diagnostics.js";
 import { repairScreenshotData } from "./prepare.js";
-import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
+import { getPersistentSessionArtifactStore } from "./session-state.js";
 import { buildFinalAgentBrowserToolResult, buildRedactedPresentationContent, buildWrapperRecoveryHint, prepareFinalResultRecoveryState, redactExactSensitiveValue, } from "./final-result.js";
 async function repairScreenshotArtifact(options) {
     const { cwd, envelope, request } = options;
@@ -105,6 +108,8 @@ export async function processBrowserOutput(input) {
     let freshSessionOrdinal = state.freshSessionOrdinal;
     let managedSessionActive = state.managedSessionActive;
     let managedSessionCompatibilityWorkaround = state.managedSessionCompatibilityWorkaround;
+    let managedSessionHeadedAutosaveDisabled = state.managedSessionHeadedAutosaveDisabled === true;
+    let managedSessionHeadedAutosaveInterval = state.managedSessionHeadedAutosaveInterval;
     let managedSessionCwd = state.managedSessionCwd;
     let managedSessionName = state.managedSessionName;
     let managedSessionNamespace = state.managedSessionNamespace;
@@ -327,6 +332,7 @@ export async function processBrowserOutput(input) {
         }
         const priorManagedSessionActive = managedSessionActive;
         const priorManagedSessionCwd = managedSessionCwd;
+        const priorManagedSessionHeadedAutosaveInterval = managedSessionHeadedAutosaveInterval;
         const priorManagedSessionName = managedSessionName;
         const priorManagedSessionNamespace = managedSessionNamespace;
         const commandClosesSession = isCloseCommand(prepared.executionPlan.commandInfo.command);
@@ -344,6 +350,7 @@ export async function processBrowserOutput(input) {
         const failedFreshDaemon = failedFreshSessionMayHaveStarted && prepared.executionPlan.sessionName
             ? await inspectManagedSessionDaemon({
                 cwd,
+                headedManagedAutosaveInterval: prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval,
                 namespace: prepared.executionPlan.namespace,
                 sessionName: prepared.executionPlan.sessionName,
                 timeoutMs: Math.min(implicitSessionCloseTimeoutMs, 2_000),
@@ -368,9 +375,13 @@ export async function processBrowserOutput(input) {
                 === getAgentBrowserSessionIdentityKey(managedSessionName, managedSessionNamespace);
         if (!managedSessionActive) {
             managedSessionCompatibilityWorkaround = undefined;
+            managedSessionHeadedAutosaveDisabled = false;
+            managedSessionHeadedAutosaveInterval = undefined;
         }
         else if (managedTransitionSucceeded && executionTargetsManagedSession) {
             managedSessionCompatibilityWorkaround = prepared.compatibilityWorkaround;
+            managedSessionHeadedAutosaveDisabled = prepared.ownedManagedSessionContext?.headedManagedAutosaveDisabled === true;
+            managedSessionHeadedAutosaveInterval = prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval;
         }
         if (commandClosesSession && succeeded && managedCloseSessionName === priorManagedSessionName && !managedSessionActive) {
             const daemonRestoreKey = state.managedSessionRestoreState.getDaemonRestoreKey(managedCloseSessionName, priorManagedSessionNamespace);
@@ -406,7 +417,16 @@ export async function processBrowserOutput(input) {
             networkRoutesBySession.delete(replacedSessionStateKey ?? replacedManagedSessionName);
             sessionPageState.clearSession(replacedSessionStateKey ?? replacedManagedSessionName);
             const replacedSessionKey = replacedSessionStateKey ?? replacedManagedSessionName;
-            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, namespace: priorManagedSessionNamespace, preserveAttachedBrowserSession: state.attachedSessionKeys.has(replacedSessionKey), restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+            const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, headedManagedAutosaveInterval: priorManagedSessionHeadedAutosaveInterval, namespace: priorManagedSessionNamespace, preserveAttachedBrowserSession: state.attachedSessionKeys.has(replacedSessionKey), restoreState: state.managedSessionRestoreState, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+            if (managedSessionOutcome) {
+                managedSessionOutcome = {
+                    ...managedSessionOutcome,
+                    replacedSessionClosed: !replacedCloseError,
+                    summary: replacedCloseError
+                        ? `${managedSessionOutcome.summary} Previous session ${replacedManagedSessionName} remains wrapper-owned because automatic close failed; retry an explicit close.`
+                        : managedSessionOutcome.summary,
+                };
+            }
             if (!replacedCloseError) {
                 state.attachedSessionKeys.delete(replacedSessionKey);
                 state.closedManagedSessionNames.add(replacedSessionKey);
@@ -434,7 +454,7 @@ export async function processBrowserOutput(input) {
                 if (electronHandoff.error) {
                     succeeded = false;
                     presentationEnvelope = { error: electronHandoff.error, success: false };
-                    const closeError = await closeManagedSession({ cwd, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, preserveAttachedBrowserSession: input.preserveAttachedBrowserSession, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+                    const closeError = await closeManagedSession({ cwd, headedManagedAutosaveInterval: prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval, namespace: prepared.executionPlan.namespace, policyLock: prepared.managedSessionPolicyLock, preserveAttachedBrowserSession: input.preserveAttachedBrowserSession, restoreState: state.managedSessionRestoreState, sessionName: electronSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronFailedConnectCleanup = await cleanupElectronLaunchResources({ child: prepared.electronLaunch.child, record: electronLaunchRecord, timeoutMs: implicitSessionCloseTimeoutMs });
                     electronLaunchRecord = electronFailedConnectCleanup.record;
                     if (electronFailedConnectCleanup.partial) {
@@ -588,8 +608,16 @@ export async function processBrowserOutput(input) {
         if (sessionStateKey)
             currentSessionTabTarget = authoritativePageState?.tabTarget;
         const currentSessionTabTargetUnknown = authoritativePageState?.tabTargetUnknown === true ? true : undefined;
-        const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, clickDispatchDiagnostic, commandTokens: prepared.commandTokens, comboboxFocusDiagnostic, compiledNetworkSourceLookup: prepared.compiledNetworkSourceLookup, compiledSemanticAction: prepared.compiledSemanticAction, compatibilityWorkaround: prepared.compatibilityWorkaround, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, currentSessionTabTargetUnknown, electronBroadGetTextScopeDiagnostics, electronFailedConnectCleanup, electronHandoff, electronLaunch: prepared.electronLaunch, electronLaunchRecord, electronLaunchRecords, electronPostCommandHealth, electronProfileIsolationDetails: input.electronProfileIsolationDetails, electronRefFreshnessDiagnostic, electronSessionMismatch, errorText, evalResultWarning, evalStdinHint, exactSensitiveValues: prepared.exactSensitiveValues, executionPlan: prepared.executionPlan, fillVerificationDiagnostic, inspectionText, managedSessionOutcome, managedSessionRestoreDisabled: state.managedSessionRestoreState.isDisabled(prepared.executionPlan.sessionName, prepared.executionPlan.namespace), navigationSummary, networkSourceLookup, noActivePageSnapshotFailure: finalRecoveryState.noActivePageSnapshotFailure, openResultTabCorrection, overlayBlockerDiagnostic, parseError, parseFailureOutput, parseSucceeded, plainTextInspection, presentation, presentationEnvelope, priorSessionTabTarget: prepared.priorSessionTabTarget, processResult, qaAttachedTarget, qaPreset, recordingDependencyWarning, redactedArgs: prepared.redactedArgs, redactedCompiledElectron: prepared.redactedCompiledElectron, redactedCompiledJob: prepared.redactedCompiledJob, redactedCompiledNetworkSourceLookup: prepared.redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset: prepared.redactedCompiledQaPreset, redactedCompiledSemanticAction: prepared.redactedCompiledSemanticAction, redactedCompiledSourceLookup: prepared.redactedCompiledSourceLookup, redactedContent, redactedProcessArgs: prepared.redactedProcessArgs, redactedRecoveryHint: prepared.redactedRecoveryHint, resultArtifactManifest, richInputRecoveryDiagnostic: finalRecoveryState.richInputRecoveryDiagnostic, scrollNoopDiagnostic, selectorTextVisibilityDiagnostics, sessionMode: prepared.sessionMode, sessionTabCorrection, sourceLookup, succeeded, timeoutPartialProgress, userRequestedJson: prepared.userRequestedJson, visibleRefFallbackDiagnostic: finalRecoveryState.visibleRefFallbackDiagnostic, visibleRefFallbackSessionName: finalRecoveryState.visibleRefFallbackSessionName });
-        const statePatch = { allowedDomainsBySession, artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCompatibilityWorkaround, managedSessionCwd, managedSessionName, managedSessionNamespace, networkRoutesBySession };
+        const resultRetainsPreparedManagedSession = !managedSessionOutcome || (managedSessionOutcome.activeAfter
+            && managedSessionOutcome.attemptedSessionName === managedSessionOutcome.currentSessionName);
+        const resultHeadedManagedAutosaveDisabled = prepared.ownedManagedSessionContext?.headedManagedAutosaveDisabled === true
+            && resultRetainsPreparedManagedSession
+            && !(commandClosesSession && succeeded);
+        const resultHeadedManagedAutosaveInterval = resultRetainsPreparedManagedSession && !(commandClosesSession && succeeded)
+            ? prepared.ownedManagedSessionContext?.headedManagedAutosaveInterval
+            : undefined;
+        const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, clickDispatchDiagnostic, commandTokens: prepared.commandTokens, comboboxFocusDiagnostic, compiledNetworkSourceLookup: prepared.compiledNetworkSourceLookup, compiledSemanticAction: prepared.compiledSemanticAction, compatibilityWorkaround: prepared.compatibilityWorkaround, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, currentSessionTabTargetUnknown, electronBroadGetTextScopeDiagnostics, electronFailedConnectCleanup, electronHandoff, electronLaunch: prepared.electronLaunch, electronLaunchRecord, electronLaunchRecords, electronPostCommandHealth, electronProfileIsolationDetails: input.electronProfileIsolationDetails, electronRefFreshnessDiagnostic, electronSessionMismatch, errorText, evalResultWarning, evalStdinHint, exactSensitiveValues: prepared.exactSensitiveValues, executionPlan: prepared.executionPlan, fillVerificationDiagnostic, inspectionText, managedSessionHeadedAutosaveDisabled: resultHeadedManagedAutosaveDisabled || undefined, managedSessionHeadedAutosaveInterval: resultHeadedManagedAutosaveInterval, managedSessionOutcome, managedSessionRestoreDisabled: state.managedSessionRestoreState.isDisabled(prepared.executionPlan.sessionName, prepared.executionPlan.namespace), navigationSummary, networkSourceLookup, noActivePageSnapshotFailure: finalRecoveryState.noActivePageSnapshotFailure, openResultTabCorrection, overlayBlockerDiagnostic, parseError, parseFailureOutput, parseSucceeded, plainTextInspection, presentation, presentationEnvelope, priorSessionTabTarget: prepared.priorSessionTabTarget, processResult, qaAttachedTarget, qaPreset, recordingDependencyWarning, redactedArgs: prepared.redactedArgs, redactedCompiledElectron: prepared.redactedCompiledElectron, redactedCompiledJob: prepared.redactedCompiledJob, redactedCompiledNetworkSourceLookup: prepared.redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset: prepared.redactedCompiledQaPreset, redactedCompiledSemanticAction: prepared.redactedCompiledSemanticAction, redactedCompiledSourceLookup: prepared.redactedCompiledSourceLookup, redactedContent, redactedProcessArgs: prepared.redactedProcessArgs, redactedRecoveryHint: prepared.redactedRecoveryHint, resultArtifactManifest, richInputRecoveryDiagnostic: finalRecoveryState.richInputRecoveryDiagnostic, scrollNoopDiagnostic, selectorTextVisibilityDiagnostics, sessionMode: prepared.sessionMode, sessionTabCorrection, sourceLookup, succeeded, timeoutPartialProgress, userRequestedJson: prepared.userRequestedJson, visibleRefFallbackDiagnostic: finalRecoveryState.visibleRefFallbackDiagnostic, visibleRefFallbackSessionName: finalRecoveryState.visibleRefFallbackSessionName });
+        const statePatch = { allowedDomainsBySession, artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCompatibilityWorkaround, managedSessionHeadedAutosaveDisabled, managedSessionHeadedAutosaveInterval, managedSessionCwd, managedSessionName, managedSessionNamespace, networkRoutesBySession };
         return { result, statePatch };
     }
     finally {

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

@@ -1,6 +1,7 @@
 import { rm } from "node:fs/promises";
 import { runAgentBrowserProcess } from "../../process.js";
-import { buildAgentBrowserNextActions, parseAgentBrowserEnvelope } from "../../results.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { buildNextToolAction, withOptionalNamespaceArgs, withOptionalSessionArgs } from "../../results/next-actions.js";
 import { getSessionPageStateKey, isAboutBlankUrl, normalizeComparableUrl, normalizeSessionTabTarget, targetsMatch, } from "../../session-page-state.js";
 import { isCloseCommand, isElectronPostCommandHealthCommand, isNavigationObservableCommandName, isRefGuardedCommand, isRefInvalidatingBatchCommand, isSessionTabPinningExcludedCommand, isSessionTabPostCommandCorrectionExcludedCommand, } from "../../command-taxonomy.js";
@@ -21,6 +22,10 @@ export function applyBrowserRunStatePatch(state, patch) {
         state.managedSessionActive = patch.managedSessionActive;
     if ("managedSessionCompatibilityWorkaround" in patch)
         state.managedSessionCompatibilityWorkaround = patch.managedSessionCompatibilityWorkaround;
+    if (patch.managedSessionHeadedAutosaveDisabled !== undefined)
+        state.managedSessionHeadedAutosaveDisabled = patch.managedSessionHeadedAutosaveDisabled;
+    if ("managedSessionHeadedAutosaveInterval" in patch)
+        state.managedSessionHeadedAutosaveInterval = patch.managedSessionHeadedAutosaveInterval;
     if (patch.managedSessionCwd !== undefined)
         state.managedSessionCwd = patch.managedSessionCwd;
     if (patch.managedSessionName !== undefined)
@@ -136,6 +141,12 @@ function formatManagedSessionOutcomeRecoveryGuidance(outcome) {
 export function formatManagedSessionOutcomeText(outcome) {
     if (!outcome)
         return undefined;
+    if (outcome.replacedSessionClosed === false) {
+        const cleanupWarning = "Cleanup warning: Automatic close of the previous wrapper-managed session failed, so it remains wrapper-owned. Use details.managedSessionOutcome for its exact identity and close it explicitly when safe.";
+        return outcome.succeeded
+            ? ["Managed session outcome: The fresh browser became current.", cleanupWarning].join("\n")
+            : [formatManagedSessionOutcomeHeadline(outcome), formatManagedSessionOutcomeRecoveryGuidance(outcome), cleanupWarning].join("\n");
+    }
     if (outcome.status === "closed" && outcome.succeeded) {
         return [
             "Managed session outcome: The current wrapper-managed browser session was closed.",
@@ -753,3 +764,8 @@ export function formatElectronRefFreshnessText(diagnostic) {
     return diagnostic?.summary;
 }
 export { extractBatchResultCommand };
+export function getPersistentSessionArtifactStore(ctx) {
+    const sessionDir = typeof ctx.sessionManager.getSessionDir === "function" ? ctx.sessionManager.getSessionDir() : undefined;
+    const sessionId = ctx.sessionManager.getSessionId();
+    return sessionDir && sessionId ? { sessionDir, sessionId } : undefined;
+}

package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js

@@ -1,22 +1,18 @@
-/**
- * Purpose: Own wrapper-side Electron host orchestration for agent_browser structured electron input.
- * Responsibilities: Discover Electron apps, inspect/probe/cleanup wrapper-tracked Electron launches, and build Pi-facing Electron host results.
- * Scope: Electron host actions that do not spawn the main upstream browser command; generic agent_browser execution stays in browser-run.
- */
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus } from "../../electron/cleanup.js";
 import { discoverElectronApps } from "../../electron/discovery.js";
-import { boundElectronProbeString } from "../../electron/text.js";
+import { boundElectronProbeString } from "../../electron/cdp.js";
 import { buildOwnedManagedSessionRestoreContext, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { getManagedSessionStateAccessValidationError } from "../../managed-session-state-policy.js";
 import { isRecord } from "../../parsing.js";
 import { withAttachedBrowserSessionContext } from "../../process.js";
-import { buildAgentBrowserNextActions, buildAgentBrowserResultCategoryDetails } from "../../results.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
 import { extractRefSnapshotFromData, getSessionPageStateKey, isAboutBlankUrl, normalizeSessionTabTarget } from "../../session-page-state.js";
 import { redactSensitiveText } from "../../runtime.js";
 import { collectElectronManagedSessionTarget } from "../browser-run/diagnostics.js";
 import { buildElectronHostFailureResult, formatElectronTargetLines, redactToolDetails } from "../browser-run/final-result.js";
-import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession } from "../browser-run/managed-session-daemon-policy.js";
+import { acquireOwnedManagedSessionDaemonPolicy, closeManagedSession, getRunningHeadedAutosavePolicyChangeError } from "../browser-run/managed-session-daemon-policy.js";
 import { buildElectronIdentifiers, buildElectronMismatchNextActions, buildElectronSessionMismatch, extractStringResultField, findElectronLaunchRecordForSession, formatElectronSessionMismatchText, getActiveElectronRecords, getLiveElectronRendererTargets, runSessionCommandData, } from "../browser-run/session-state.js";
 const ELECTRON_PROFILE_ISOLATION_NOTE = "Profile note: electron.launch starts an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app.";
 const ELECTRON_EXISTING_AUTH_GUIDANCE = "For already-authenticated desktop app content, do not stop here: if host tools are allowed and the app is not running, launch the normal app with --remote-debugging-port=<port>, verify the port, then run agent_browser connect <port>; if it is already running without a debug port, ask before relaunching it.";
@@ -398,9 +394,14 @@ function getElectronProbeSummary(probe) {
 class ElectronManagedSessionPolicyError extends Error {
 }
 async function withOwnedElectronManagedSessionPolicy(options, run) {
+    const autosavePolicyChangeError = getRunningHeadedAutosavePolicyChangeError(options.headedManagedAutosaveInterval);
+    if (autosavePolicyChangeError)
+        throw new ElectronManagedSessionPolicyError(autosavePolicyChangeError);
     const context = buildOwnedManagedSessionRestoreContext({
         args: ["--namespace", options.namespace ?? "", "--session", options.sessionName, ...options.args],
         cwd: options.cwd,
+        headedManagedAutosaveDisabled: options.headedManagedAutosaveDisabled,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
         managedSessionName: options.sessionName,
         namespace: options.namespace,
         restoreState: options.restoreState,
@@ -581,6 +582,8 @@ function buildElectronProbeResult(options) {
         },
         nextActions: nextActions.length > 0 ? nextActions : undefined,
         ...buildAgentBrowserResultCategoryDetails({ args: [], succeeded: true }),
+        managedSessionHeadedAutosaveDisabled: options.headedManagedAutosaveDisabled === true ? true : undefined,
+        managedSessionHeadedAutosaveInterval: options.headedManagedAutosaveInterval,
         namespace: options.namespace,
         refSnapshot: options.probe.refSnapshot,
         sessionName: options.probe.sessionName,
@@ -597,8 +600,10 @@ function buildElectronProbeResult(options) {
 export async function cleanupTrackedElectronHostLaunches(options) {
     const results = [];
     for (const record of options.records) {
+        const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+        const managedSessionOwner = sessionKey ? options.ownedManagedSessions.get(sessionKey) : undefined;
         const managedSessionCloseError = record.sessionName
-            ? await closeManagedSession({ cwd: options.cwd, preserveAttachedBrowserSession: options.attachedSessionKeys.has(getSessionPageStateKey(record.sessionName) ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
+            ? await closeManagedSession({ cwd: options.cwd, headedManagedAutosaveInterval: managedSessionOwner?.headedManagedAutosaveInterval, preserveAttachedBrowserSession: options.attachedSessionKeys.has(sessionKey ?? record.sessionName), restoreState: options.managedSessionRestoreState, sessionName: record.sessionName, timeoutMs: options.timeoutMs })
             : undefined;
         const managedSessionStep = record.sessionName
             ? managedSessionCloseError
@@ -647,7 +652,7 @@ export async function handleElectronHostInput(options) {
     return await withAttachedBrowserSessionContext(preserveAttachedBrowserSession, () => handleElectronHostInputInContext(options));
 }
 async function handleElectronHostInputInContext(options) {
-    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, redactedCompiledElectron, sessionPageState, signal, } = options;
+    const { attachedSessionKeys, compiledElectron, cwd, electronChildProcesses, electronLaunchRecords, implicitSessionCloseTimeoutMs, managedSessionActive, managedSessionName, managedSessionNamespace, managedSessionRestoreState, ownedManagedSessions, redactedCompiledElectron, sessionPageState, signal, } = options;
     if (compiledElectron?.action === "list") {
         try {
             const discovery = await discoverElectronApps({ maxResults: compiledElectron.maxResults, query: compiledElectron.query });
@@ -665,13 +670,18 @@ async function handleElectronHostInputInContext(options) {
         const statuses = await Promise.all(records.map((record) => inspectElectronLaunchStatus(record)));
         const managedSessions = await Promise.all(records
             .filter((record) => typeof record.sessionName === "string")
-            .map((record) => collectOwnedElectronManagedSessionTarget({
-            cwd,
-            restoreState: managedSessionRestoreState,
-            sessionName: record.sessionName,
-            signal,
-            timeoutMs: compiledElectron.timeoutMs,
-        })));
+            .map((record) => {
+            const sessionKey = getSessionPageStateKey(record.sessionName) ?? record.sessionName;
+            return collectOwnedElectronManagedSessionTarget({
+                cwd,
+                headedManagedAutosaveDisabled: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval: ownedManagedSessions.get(sessionKey)?.headedManagedAutosaveInterval,
+                restoreState: managedSessionRestoreState,
+                sessionName: record.sessionName,
+                signal,
+                timeoutMs: compiledElectron.timeoutMs,
+            });
+        }));
         const mismatches = managedSessions
             .map((managedSession) => {
             const record = records.find((candidate) => candidate.sessionName === managedSession.sessionName);
@@ -733,9 +743,14 @@ async function handleElectronHostInputInContext(options) {
             });
             if (fileAccessError)
                 throw new ElectronManagedSessionPolicyError(fileAccessError);
+            const managedSessionOwner = ownedManagedSessions.get(pageStateKey);
+            const headedManagedAutosaveDisabled = managedSessionOwner?.headedManagedAutosaveDisabled === true;
+            const headedManagedAutosaveInterval = managedSessionOwner?.headedManagedAutosaveInterval;
             const probe = await withOwnedElectronManagedSessionPolicy({
                 args: ["snapshot", "-i"],
                 cwd,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 namespace: probeNamespace,
                 restoreState: managedSessionRestoreState,
                 sessionName: probeSessionName,
@@ -779,6 +794,8 @@ async function handleElectronHostInputInContext(options) {
             }
             return buildElectronProbeResult({
                 compiledElectron: redactedCompiledElectron ?? compiledElectron,
+                headedManagedAutosaveDisabled,
+                headedManagedAutosaveInterval,
                 mismatch: sessionMismatch,
                 namespace: probeNamespace,
                 probe,
@@ -801,7 +818,7 @@ async function handleElectronHostInputInContext(options) {
         const selection = selectElectronRecords(compiledElectron, electronLaunchRecords);
         if (selection.error)
             return buildElectronHostFailureResult({ compiledElectron: redactedCompiledElectron ?? compiledElectron, errorText: selection.error, failureCategory: "validation-error" });
-        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
+        const cleanupResults = await cleanupTrackedElectronHostLaunches({ attachedSessionKeys, cwd, electronChildProcesses, electronLaunchRecords, managedSessionRestoreState, ownedManagedSessions, records: selection.records ?? [], timeoutMs: compiledElectron.timeoutMs ?? implicitSessionCloseTimeoutMs });
         return buildElectronCleanupResult(redactedCompiledElectron ?? compiledElectron, cleanupResults);
     }
     return undefined;

package/dist/extensions/agent-browser/lib/orchestration/input-plan.js

@@ -1,7 +1,10 @@
 import { parseArgvDescriptor } from "../argv-descriptor.js";
 import { validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
 import { buildAgentBrowserResultCategoryDetails } from "../results/categories.js";
-import { compileAgentBrowserElectron, compileAgentBrowserJob, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserQaPreset, compileAgentBrowserSemanticAction, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl, } from "../input-modes.js";
+import { compileAgentBrowserElectron } from "../input-modes/electron.js";
+import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "../input-modes/job.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, redactNetworkSourceLookupArgs, redactNetworkSourceLookupUrl } from "../input-modes/lookups.js";
+import { compileAgentBrowserSemanticAction } from "../input-modes/semantic-action.js";
 function redactCompiledElectron(compiled) {
     if (!compiled)
         return undefined;

package/dist/extensions/agent-browser/lib/orchestration/output-file.js

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, realpath, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { getAgentBrowserStoragePathValidationError } from "../managed-session-state-policy.js";
 import { isRecord } from "../parsing.js";
@@ -31,6 +31,33 @@ function appendOutputFileNotice(result, message) {
 export function getAgentBrowserOutputPathValidationError(outputPath, cwd) {
     return outputPath ? getAgentBrowserStoragePathValidationError(normalizeRequestedOutputPath(outputPath), cwd) : undefined;
 }
+function getArtifactPaths(result, cwd) {
+    const details = isRecord(result.details) ? result.details : undefined;
+    if (!details || !Array.isArray(details.artifacts))
+        return [];
+    return details.artifacts.flatMap((artifact) => {
+        if (!isRecord(artifact))
+            return [];
+        const path = typeof artifact.absolutePath === "string" ? artifact.absolutePath : typeof artifact.path === "string" ? artifact.path : undefined;
+        return path ? [isAbsolute(path) ? path : resolve(cwd, path)] : [];
+    });
+}
+async function pathsReferToSameFile(left, right) {
+    if (resolve(left) === resolve(right))
+        return true;
+    try {
+        if (await realpath(left) === await realpath(right))
+            return true;
+    }
+    catch { }
+    try {
+        const [leftStat, rightStat] = await Promise.all([stat(left), stat(right)]);
+        return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+    }
+    catch {
+        return false;
+    }
+}
 export async function applyAgentBrowserOutputPath(options) {
     if (!options.outputPath)
         return options.result;
@@ -47,6 +74,20 @@ export async function applyAgentBrowserOutputPath(options) {
     const requestedPath = normalizeRequestedOutputPath(options.outputPath);
     const absolutePath = isAbsolute(requestedPath) ? requestedPath : resolve(options.cwd, requestedPath);
     const payload = getOutputPayload(options.result);
+    for (const artifactPath of getArtifactPaths(options.result, options.cwd)) {
+        if (!await pathsReferToSameFile(absolutePath, artifactPath))
+            continue;
+        const message = "outputPath resolves to the same file as a browser artifact destination; choose a separate outputPath or omit it. The browser artifact was preserved.";
+        const outputFile = { absolutePath, error: message, path: requestedPath, source: payload.source, status: "failed" };
+        const details = isRecord(options.result.details) ? { ...options.result.details } : {};
+        delete details.successCategory;
+        return {
+            ...options.result,
+            content: appendOutputFileNotice(options.result, `Output file rejected: ${message}`),
+            details: { ...details, failureCategory: "validation-error", outputFile, resultCategory: "failure" },
+            isError: true,
+        };
+    }
     try {
         const serialized = serializeOutputPayload(payload.value);
         await mkdir(dirname(absolutePath), { recursive: true });

package/dist/extensions/agent-browser/lib/parsing.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Centralize low-level boundary parsing helpers shared by runtime planning, temp-artifact lifecycle, and result rendering.
- * Responsibilities: Identify non-null object records and normalize positive-integer string configuration values.
- * Scope: Tiny generic parsing predicates only; module-specific validation and error handling stay with their owning modules.
- * Usage: Imported by agent-browser wrapper modules that parse untyped JSON, persisted state, or environment variables.
- * Invariants/Assumptions: Arrays intentionally count as records to preserve existing object-boundary semantics, and positive integers must be safe base-10 integer strings greater than zero.
- */
 export function isRecord(value) {
     return typeof value === "object" && value !== null;
 }

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -1,5 +1,8 @@
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { compileAgentBrowserElectron, compileAgentBrowserJob, compileAgentBrowserNetworkSourceLookup, compileAgentBrowserQaPreset, compileAgentBrowserSemanticAction, compileAgentBrowserSourceLookup, } from "./input-modes.js";
+import { compileAgentBrowserElectron } from "./input-modes/electron.js";
+import { compileAgentBrowserJob, compileAgentBrowserQaPreset } from "./input-modes/job.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup } from "./input-modes/lookups.js";
+import { compileAgentBrowserSemanticAction } from "./input-modes/semantic-action.js";
 import { isRecord } from "./parsing.js";
 import { redactInvocationArgs } from "./runtime.js";
 const TUI_INVOCATION_PREVIEW_MAX_CHARS = 160;

package/dist/extensions/agent-browser/lib/playbook.js

@@ -1,11 +1,4 @@
 import { LAUNCH_SCOPED_FLAG_LABEL } from "./launch-scoped-flags.js";
-/**
- * Purpose: Provide the canonical agent_browser operating playbook shared by runtime prompt metadata and generated documentation fragments.
- * Responsibilities: Define stable guidance bullets, native tool-call examples, and wrapper-behavior notes without importing runtime/browser process code.
- * Scope: Agent-facing documentation and prompt-guidance text only; command execution and wrapper state behavior live in runtime modules.
- * Usage: Imported by the extension entrypoint for promptGuidelines and by the documentation drift-check script for generated Markdown blocks.
- * Invariants/Assumptions: The native pi tool receives args after the agent-browser binary, stdin is only for batch/eval --stdin/auth save --password-stdin, and wrapper behavior documented here must match implemented behavior.
- */
 export const PROJECT_RULE_PROMPT = "Project rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.";
 export const TOOL_PROMPT_GUIDELINES_PREFIX = [
     "Use agent_browser for real browser or live web content.",
@@ -21,7 +14,7 @@ export const QUICK_START_GUIDELINES = [
     `Common advanced calls: { args: ["batch", "--bail"], stdin: "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }, { job: { steps: [{ action: "open", url: "https://example.com" }, { action: "assertText", text: "Example Domain" }, { action: "screenshot", path: ".dogfood/example.png" }] } }, { qa: { url: "https://example.com", expectedText: "Example Domain", screenshotPath: ".dogfood/qa-example.png" } } (example.com smoke only; elsewhere match exact visible text from snapshot -i), { electron: { action: "list", query: "code" } }, { electron: { action: "launch", appName: "Visual Studio Code", handoff: "snapshot" } }, { electron: { action: "probe" } }, { qa: { attached: true, expectedText: "Explorer" } }, { args: ["eval", "--stdin"], stdin: "document.title", outputPath: "logs/page-title.json" }, { args: ["auth", "save", "name", "--password-stdin"], stdin: "<password from user-approved secret source>" }, { args: ["--profile", "Default", "open", "https://example.com/account"], sessionMode: "fresh" }, and { args: ["open", "--enable", "react-devtools", "https://example.com"], sessionMode: "fresh" }. For app pages with a native dropdown, job steps can include { action: "select", selector: "#flavor", value: "chocolate" } before the dependent assertion; for locator-friendly pages, job click/fill steps can use semantic locator fields such as { action: "fill", locator: "role", role: "searchbox", name: "Search", text: "agent browser" }; for human-paced input, job type steps can use { action: "type", selector: "#prompt", text: "hello", delayMs: 20, press: "Enter" }; delayed typing is capped at 200 characters per step, and generated per-character rows are compacted in visible batch prose while full rows remain in details.batchSteps.`,
     "Constrained job navigation is explicit only: click (and select/submit flows that may navigate) does not prove the next page loaded; add assertUrl and/or assertText after navigation-prone steps before screenshot or later interactions. Keep jobs short around navigation, click, and rerender boundaries on dynamic React/product apps; avoid a whole checkout in one job. If a long job times out and details.timeoutPartialProgress shows a mutating incomplete step, inspect current page state and continue with a shorter job or single action instead of blindly retrying the mutating step. Example: { job: { steps: [{ action: \"open\", url: \"https://shop.example/checkout\" }, { action: \"fill\", selector: \"#email\", text: \"user@example.com\" }, { action: \"click\", selector: \"#continue\" }, { action: \"assertUrl\", url: \"**/shipping\" }, { action: \"assertText\", text: \"Shipping address\" }, { action: \"screenshot\", path: \".dogfood/shipping.png\" }] } }. Top-level click may add pageChangeSummary hints, but job never auto-inserts post-click asserts.",
     "High-value command reference: click <selector> --new-tab opens link-like targets in a new tab; select <selector> <value...> changes native dropdown values; wrapper-handled scroll <dir> [px|percent] and scroll to end/top target document scrolling before upstream fallback, while scroll <selector> <dir> [px|percent] targets nested scrollers; download <selector> <path> saves a file triggered by a click; read [url] returns agent-readable text (explicit URLs prefer markdown without launching Chrome; omit the URL for rendered active-tab DOM); get title/url need no selector; get text/html/value/count <selector> and get attr <selector> <name> read elements/page state (use body for whole-page text/html); screenshot [selector] [path] captures a page or element image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree, react inspect <fiberId>, react renders start/stop, and react suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation; tap <selector> and swipe <direction> [distance] support iOS/provider touch flows.",
-    "For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata; record start rows are pending/openRecording until record stop writes the target. The wrapper creates parent directories for direct artifact paths and can save simple loopback HTTP(S) anchor downloads directly to the requested path before upstream download fallback. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. If close fails with details.promptGuard.reason=requested-artifacts-missing-before-close, save the exact required artifact path before closing. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step; if annotation labels crowd a dense page, use a scoped or non-annotated screenshot plus snapshot refs instead.",
+    "For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata; record start rows are pending/openRecording until record stop writes the target. The wrapper creates parent directories for direct artifact paths and can save simple loopback HTTP(S) anchor downloads directly to the requested path before upstream download fallback. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. If close fails with details.promptGuard.reason=requested-artifacts-missing-before-close, save the exact required artifact path before closing. A bare inbound image/video path is not a requested output artifact and does not block close. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step; if annotation labels crowd a dense page, use a scoped or non-annotated screenshot plus snapshot refs instead.",
     "When details.nextActions is present, prefer those exact native agent_browser follow-up payloads over prose guidance; they may include args, stdin, sessionMode, networkSourceLookup, safety notes, or artifactPath for saved files.",
 ];
 export const WEB_SEARCH_PROMPT_GUIDELINE = "Use agent_browser_web_search for quick live search/URL discovery; prefer it over public search-engine forms that can hit anti-bot/CAPTCHA-gated pages. Use agent_browser after you have a target URL; one query, one follow-up max; stop on HTTP 429.";
@@ -44,7 +37,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, sourceLookup candidates for local UI source hints, react renders start/stop, or react suspense; sourceLookup is experimental and reports confidence/evidence instead of guaranteed DOM-to-file mappings. For failed fetches and APIs, networkSourceLookup (experimental) correlates failed network requests with initiator metadata and bounded workspace URL literals—candidates only, not definitive blame. Use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.",
     "For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.",
     "For stateful browser context work, prefer purpose-specific page actions before dumping browser data: use auth save --password-stdin with the tool stdin field for credentials, auth list/show/delete/remove for local auth-profile maintenance, auth login when you need the browser to fill a saved profile, state save/load for portable test state, state list/show/rename and targeted `state clear <caller-owned-name>` for saved-state lifecycle cleanup (the native wrapper blocks broad clear/clean and managed targets), cookies get/set/clear and storage local|session only when the task needs those values, and expect cookie/storage/auth/state summaries to redact credential-like fields while allowing benign primitive storage values when useful for local QA.",
-    "Upstream restore sessions periodically autosave cookies and localStorage while the browser stays open, including page-driven background changes; AGENT_BROWSER_AUTOSAVE_INTERVAL_MS controls the interval (30000 by default; 0 disables periodic saves but keeps save-on-close), while the never value for --restore-save disables automatic saves for that restore session.",
+    "Upstream restore sessions periodically autosave cookies and localStorage while the browser stays open, including page-driven background changes; AGENT_BROWSER_AUTOSAVE_INTERVAL_MS controls the interval (30000 by default; 0 disables periodic saves but keeps save-on-close), while the never value for --restore-save disables automatic saves for that restore session. For wrapper-owned headed launches, the wrapper defaults the interval to 0 because upstream 0.33.2 collects multi-origin storage through visible temporary tabs, then records and reapplies the effective launch-time value to helpers and follow-ups so daemon configuration remains stable. Native close still saves, but direct window close can lose newer state because upstream exempts headed browsers from idle shutdown; set AGENT_BROWSER_AUTOSAVE_INTERVAL_MS before launch when periodic preservation matters, because changing it on a running wrapper-owned headed session requires close plus a fresh launch.",
     "For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.",
     "For non-core families, pass current upstream commands through the native tool directly: network requests, network route <url>, network har start/stop [path], diff snapshot, diff screenshot --baseline <file>, diff url <u1> <u2>, trace start, trace stop [path], profiler start, profiler stop [path], record start <path>, record stop, console/errors [--clear], highlight <selector>, inspect, clipboard read, clipboard write <text>, clipboard copy/paste, stream enable/disable/status, dashboard start/stop, device list for iOS simulator inventory, and chat <message>. For compact network requests output, prefer details.nextActions for request detail, route-mock diagnostics, actionable failed-request networkSourceLookup, filtering, clearing the aggregate buffer before repro, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done; stream enable already-enabled outcomes are treated as idempotent success with status/disable follow-ups.",
     "For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, run get url to verify the active target before page-content reads, inspect tab list, select the stable tab id such as tab t2, verify it again with get url, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.",
@@ -56,7 +49,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "For downloads, prefer download <selector> <path> when an element click should save a file; simple loopback anchor downloads are saved to the requested path when the wrapper can resolve an HTTP(S) href. Do not rely on click alone when you need the downloaded file on disk.",
     "On dashboards with nested scroll containers, verify scroll with a screenshot or fresh snapshot -i; if the viewport did not move, details.data.scrolled may be false/noMovement true and you should prefer scrollintoview <@ref> or target the actual scrollable region with scroll <selector> <dir> [px|percent]. For native selects, use select <selector> <value...> (or semanticAction/job select) instead of clicking option refs; for custom comboboxes, a click/semanticAction may only focus the field, so re-snapshot and fall back to type, press Enter/arrow keys, or visible option refs.",
     "When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
-    "When using eval --stdin for extraction, pass the JavaScript through the native tool stdin field, not as an extra args token after --stdin, and return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); use outputPath when the eval/get/snapshot data should be saved as a durable local file. If a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. The native wrapper blocks follow-up inspection, scripting, and interaction on file:// pages to protect authenticated local browser state; use a reachable HTTP(S) fixture instead. If get text on a broad CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.",
+    "When using eval --stdin for extraction, pass the JavaScript through the native tool stdin field, not as an extra args token after --stdin, and return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); use outputPath when the eval/get/snapshot data should be saved as a durable local file, but never reuse a screenshot, download, recording, or other browser artifact destination as outputPath. If a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. The native wrapper blocks follow-up inspection, scripting, and interaction on file:// pages to protect authenticated local browser state; use a reachable HTTP(S) fixture instead. If get text on a broad CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.",
     "When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.",
     "When commands save or spill files (screenshots, downloads, PDFs, traces, recordings, HAR, large snapshot spills), use the user's exact requested paths when given and treat paths as provisional until details.artifactVerification shows every row verified: branch on missingCount, pendingCount, unverifiedCount, per-entry state, and optional limitation before downstream file use or PASS/FAIL reporting.",
     "For evidence-only screenshots, QA captures, or other audit artifacts, save to an explicit path and branch on details.artifactVerification plus details.artifacts before reporting PASS/FAIL; do not require vision review of inline image attachments unless the user asked for visual inspection.",

package/dist/extensions/agent-browser/lib/process-identity.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Describe the native command used to read a process start identity for PID-reuse-safe ownership checks.
- * Responsibilities: Keep POSIX and native-Windows process identity probes aligned across policy locks and temp cleanup.
- * Scope: Command construction, output normalization, and cached async lookup for the current process.
- */
 import { execFile } from "node:child_process";
 import { win32 } from "node:path";
 const WINDOWS_PROCESS_START_IDENTITY_PREFIX = "win32-powershell-ticks-v1:";

package/dist/extensions/agent-browser/lib/process.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Execute the upstream agent-browser binary for the pi-agent-browser extension.
- * Responsibilities: Validate POSIX socket storage, spawn the agent-browser subprocess, forward parent environment variables plus wrapper overrides, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
- * Scope: Process execution only; argument planning, output formatting, and pi tool registration live elsewhere.
- * Usage: Called by the extension tool after argument validation and session planning are complete.
- * Invariants/Assumptions: The binary name is always `agent-browser`; Windows routes through PowerShell to invoke npm launchers with escaped argv; callers handle semantic success/error interpretation.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn } from "node:child_process";
 import { lstat, mkdir, readdir } from "node:fs/promises";