pi-agent-browser-native 0.8.2 → 0.9.0

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

@@ -1,5 +1,6 @@
 import { isRecord } from "../parsing.js";
 import { summarizeNetworkFailures } from "../results/network.js";
+import { truncateText } from "../results/text.js";
 import { getBatchResultItems, getCommandNameFromBatchItem } from "./shared.js";
 import { AGENT_BROWSER_QA_LOAD_STATES, } from "./types.js";
 function describeQaChecksRun(checks) {
@@ -61,15 +62,19 @@ export function buildQaCompactPassText(options) {
     return lines.join("\n");
 }
 export function buildQaCompactFailureText(options) {
-    const lines = [options.qaPreset.summary];
+    const lines = [options.causalError
+            ? truncateText(options.causalError.replace(/\s+/g, " ").trim(), 700)
+            : options.qaPreset.summary];
     const pageParts = [options.page?.title, options.page?.url].filter((part) => typeof part === "string" && part.length > 0);
     if (pageParts.length > 0)
         lines.push(`Page: ${pageParts.join(" — ")}`);
     if (options.qaPreset.failedChecks.length > 0)
         lines.push("Failed checks:", ...options.qaPreset.failedChecks.map((failure) => `- ${failure}`));
+    if (options.qaPreset.notRunChecks.length > 0)
+        lines.push("Not run:", ...options.qaPreset.notRunChecks.map((check) => `- ${check}`));
     if (options.qaPreset.warnings.length > 0)
         lines.push("Warnings:", ...options.qaPreset.warnings.map((warning) => `- ${warning}`));
-    lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
+    lines.push(`Execution: ${options.executedStepCount ?? "unknown"}/${options.plannedStepCount} batch steps`);
     lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
     return lines.join("\n");
 }
@@ -182,11 +187,45 @@ export function analyzeQaPresetTimeout(compiled) {
     const failedChecks = compiled.checks.expectedText.map((text) => `expected text was not verified before timeout: ${formatQaExpectedTextPreview(text)}`);
     return {
         failedChecks,
+        notRunChecks: [],
         passed: false,
         summary: `QA preset failed: ${failedChecks.join("; ")}.`,
         warnings: ["The wrapper timed out before expected-text evidence could be verified; inspect timeoutPartialProgress and retry with a narrower readiness condition if the page was still loading."],
     };
 }
+function describeNotRunQaChecks(compiled, executedStepCount) {
+    const checks = [];
+    let expectedTextIndex = 0;
+    for (const [index, step] of compiled.steps.entries()) {
+        let check;
+        if (step.action === "assertText") {
+            const expected = compiled.checks.expectedText[expectedTextIndex++];
+            if (expected)
+                check = `expected text: ${formatQaExpectedTextPreview(expected)}`;
+        }
+        else if (step.args[0] === "wait" && step.args[1] === "--load") {
+            check = `load state: ${step.args[2]}`;
+        }
+        else if (compiled.checks.expectedSelector && step.args[0] === "wait" && step.args[1] === compiled.checks.expectedSelector) {
+            check = `expected selector: ${formatQaExpectedTextPreview(compiled.checks.expectedSelector)}`;
+        }
+        else if (step.args[0] === "network" && !step.args.includes("--clear")) {
+            check = "network diagnostics";
+        }
+        else if (step.args[0] === "console" && !step.args.includes("--clear")) {
+            check = "console diagnostics";
+        }
+        else if (step.args[0] === "errors" && !step.args.includes("--clear") && step.generatedFrom !== "qa.errorBaselineAfterClear") {
+            check = "page error diagnostics";
+        }
+        else if (step.action === "screenshot") {
+            check = `screenshot: ${formatQaExpectedTextPreview(step.args[1] ?? "")}`;
+        }
+        if (index >= executedStepCount && check)
+            checks.push(check);
+    }
+    return checks;
+}
 export function analyzeQaPresetResults(data, compiled) {
     const items = getBatchResultItems(data);
     if (items.length === 0)
@@ -238,6 +277,8 @@ export function analyzeQaPresetResults(data, compiled) {
             const expected = compiled.checks.expectedText[expectedTextIndex++];
             if (!expected)
                 return;
+            if (!items[index])
+                return;
             const visibleTextPassed = qaVisibleTextWaitPassed(items[index], step);
             if (visibleTextPassed === true)
                 return;
@@ -246,10 +287,16 @@ export function analyzeQaPresetResults(data, compiled) {
                 failedChecks.push(`expected text not found: ${formatQaExpectedTextPreview(expected)}`);
         });
     }
+    const stoppedEarly = compiled && items.length < compiled.steps.length;
+    const failedFast = stoppedEarly && items.at(-1)?.success === false;
+    if (stoppedEarly && !failedFast)
+        failedChecks.push("QA execution could not be verified (incomplete batch results)");
     const uniqueFailures = [...new Set(failedChecks)];
     const uniqueWarnings = [...new Set(warnings)];
+    const notRunChecks = compiled && failedFast ? describeNotRunQaChecks(compiled, items.length) : [];
     return {
         failedChecks: uniqueFailures,
+        notRunChecks,
         passed: uniqueFailures.length === 0,
         summary: uniqueFailures.length === 0
             ? uniqueWarnings.length === 0 ? "QA preset passed." : `QA preset passed with warnings: ${uniqueWarnings.join("; ")}.`

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

@@ -79,41 +79,38 @@ export function createAgentBrowserQaParamsSchema(Type = JsonSchema, StringEnum =
 export function createAgentBrowserElectronParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     const common = { outputPath: outputProperties(Type).outputPath };
     const timeoutMs = Type.Optional(Type.Integer({ minimum: 1 }));
-    return Type.Unsafe(Type.Union([
-        Type.Object({
-            action: StringEnum(["list"]),
-            query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
-            maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, clamped to ${ELECTRON_DISCOVERY_MAX_RESULTS}.`, minimum: 1 })),
-            ...common,
-        }, { additionalProperties: false }),
-        Type.Object({
-            action: StringEnum(["launch"]),
-            appPath: Type.Optional(Type.String({ description: "macOS .app path.", minLength: 1 })),
-            appName: Type.Optional(Type.String({ description: "Name from agent_browser_electron list.", minLength: 1 })),
-            bundleId: Type.Optional(Type.String({ minLength: 1 })),
-            executablePath: Type.Optional(Type.String({ minLength: 1 })),
-            appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-            handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
-            targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
-            timeoutMs,
-            allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-            deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
-            ...common,
-        }, { additionalProperties: false }),
-        Type.Object({
-            action: StringEnum(["status", "cleanup"]),
-            launchId: Type.Optional(Type.String({ minLength: 1 })),
-            all: Type.Optional(Type.Literal(true)),
-            timeoutMs,
-            ...common,
-        }, { additionalProperties: false, not: { required: ["launchId", "all"] } }),
-        Type.Object({
-            action: StringEnum(["probe"]),
-            launchId: Type.Optional(Type.String({ minLength: 1 })),
-            timeoutMs,
-            ...common,
-        }, { additionalProperties: false }),
-    ]));
+    const list = {
+        query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
+        maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, clamped to ${ELECTRON_DISCOVERY_MAX_RESULTS}.`, minimum: 1 })),
+    };
+    const launch = {
+        appPath: Type.Optional(Type.String({ description: "macOS .app path.", minLength: 1 })),
+        appName: Type.Optional(Type.String({ description: "Name from agent_browser_electron list.", minLength: 1 })),
+        bundleId: Type.Optional(Type.String({ minLength: 1 })),
+        executablePath: Type.Optional(Type.String({ minLength: 1 })),
+        appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
+        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
+        timeoutMs,
+        allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    };
+    const probe = { launchId: Type.Optional(Type.String({ minLength: 1 })), timeoutMs };
+    const lifecycle = { ...probe, all: Type.Optional(Type.Literal(true)) };
+    // Strict providers need an object root; Pi needs root properties to normalize optional nulls.
+    // Each branch retains its original action-specific field boundary.
+    return Type.Unsafe(Type.Object({
+        action: StringEnum(["list", "launch", "status", "cleanup", "probe"]),
+        ...list, ...launch, ...lifecycle, ...common,
+    }, {
+        additionalProperties: false,
+        anyOf: [
+            Type.Object({ action: StringEnum(["list"]), ...list, ...common }, { additionalProperties: false }),
+            Type.Object({ action: StringEnum(["launch"]), ...launch, ...common }, { additionalProperties: false }),
+            Type.Object({ action: StringEnum(["status", "cleanup"]), ...lifecycle, ...common }, { additionalProperties: false, not: { required: ["launchId", "all"] } }),
+            Type.Object({ action: StringEnum(["probe"]), ...probe, ...common }, { additionalProperties: false }),
+        ],
+    }));
 }
 export function createAgentBrowserSourceParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Unsafe(Type.Object({

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

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomInt, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -11,6 +11,9 @@ const POLICY_LOCK_RETRY_MS = 10;
 const POLICY_LOCK_MAX_BYTES = 1_048_576; // One claim may cover an entire owned-browser cleanup set.
 const LOCK_OWNER_FILE = "owner.json";
 const LOCK_TICKET_FILE = "ticket.json";
+const STALE_CLAIM_MIN_AGE_MS = 30 * 60 * 1_000;
+const POLICY_GC_BATCH_SIZE = 8;
+let lastPolicyGcName;
 function getCoordinationDirectory(platform = process.platform) {
     if (platform !== "win32") {
         const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
@@ -175,6 +178,7 @@ function parseOwner(content) {
             && Number.isSafeInteger(parsed.pid) && (parsed.pid ?? 0) > 0
             && typeof parsed.startIdentity === "string" && parsed.startIdentity.length > 0
             && typeof parsed.token === "string" && parsed.token.length > 0
+            && !parsed.token.includes("/") && !parsed.token.includes("\\") && !parsed.token.includes("\0")
             ? parsed
             : undefined;
     }
@@ -323,14 +327,30 @@ async function cleanDeadPolicyArtifacts(directory, budget) {
     catch {
         return;
     }
-    for (const name of names.filter((candidate) => candidate.startsWith(".pi-agent-browser-policy-remove-")
-        || candidate.includes(".lock-v4.candidate-"))) {
+    // ponytail: list/sort all names; stream directories if enumeration becomes the bottleneck.
+    const candidates = names.filter((name) => name.startsWith(".pi-agent-browser-policy-remove-")
+        || /^\.pi-agent-browser-policy-[a-f0-9]{64}\.lock-v4\.(?:candidate|claim)-/.test(name)).sort();
+    if (candidates.length === 0)
+        return;
+    const start = lastPolicyGcName === undefined ? randomInt(candidates.length)
+        : Math.max(0, candidates.findIndex((name) => name > lastPolicyGcName));
+    const batch = Array.from({ length: Math.min(POLICY_GC_BATCH_SIZE, candidates.length) }, (_, offset) => candidates[(start + offset) % candidates.length]);
+    lastPolicyGcName = batch.at(-1);
+    for (const name of batch) {
         if (budget.signal?.aborted || Date.now() >= (budget.deadline ?? Infinity))
             return;
         const path = join(directory, name);
+        const published = name.includes(".lock-v4.claim-");
+        if (published) {
+            const entry = await lstat(path).catch(() => undefined);
+            if (!entry || entry.mtimeMs >= Date.now() - STALE_CLAIM_MIN_AGE_MS)
+                continue;
+        }
         const claim = await readClaim(path);
-        if (claim && await ownerAlive(claim.owner, budget) === false)
-            await rm(path, { force: true, recursive: true }).catch(() => undefined);
+        if (!claim || (published && !name.endsWith(`.claim-${claim.owner.token}`)))
+            continue;
+        if (await ownerAlive(claim.owner, budget) === false)
+            await removeClaimOwnedBy(path, claim.owner.token).catch(() => false);
     }
 }
 function claimPrecedes(left, right) {

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

@@ -4,6 +4,7 @@ import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExp
 import { hasLaunchScopedFlagToken, MANAGED_RESTORE_INCOMPATIBLE_BOOLEAN_ENVS, MANAGED_RESTORE_INCOMPATIBLE_ENVS, MANAGED_RESTORE_INCOMPATIBLE_FLAGS, } from "./launch-scoped-flags.js";
 import { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope, getManagedSessionRestoreProtectedStorageEnv, hasManagedSessionRestoreProjectIdentity, resolveManagedSessionRestoreHome, } from "./managed-session-storage.js";
 import { parseUserBatchStdin } from "./orchestration/batch-stdin.js";
+import { isRecord } from "./parsing.js";
 import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 export { createManagedSessionRestoreKey, ensureManagedSessionRestoreStorageIsSecure, getManagedSessionRestoreScope } from "./managed-session-storage.js";
 export { pruneOwnedManagedSessionRestoreSnapshots } from "./managed-session-snapshots.js";
@@ -39,10 +40,11 @@ export class ManagedSessionRestoreState {
             this.#disabled.add(getAgentBrowserSessionIdentityKey(sessionName, namespace));
     }
     getDaemonRestoreKey(sessionName, namespace) {
-        return typeof sessionName === "string" ? this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace)) : undefined;
+        return typeof sessionName === "string" ? this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace))?.restoreKey : undefined;
     }
     hasDaemonRestoreKey(sessionName, namespace) {
-        return typeof sessionName === "string" && this.#daemonRestoreKeys.has(getAgentBrowserSessionIdentityKey(sessionName, namespace));
+        return typeof sessionName === "string" && this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace))?.restored !== true
+            && this.#daemonRestoreKeys.has(getAgentBrowserSessionIdentityKey(sessionName, namespace));
     }
     forgetDaemonRestoreKey(sessionName, namespace) {
         if (sessionName)
@@ -51,9 +53,22 @@ export class ManagedSessionRestoreState {
     isDisabled(sessionName, namespace) {
         return typeof sessionName === "string" && this.#disabled.has(getAgentBrowserSessionIdentityKey(sessionName, namespace));
     }
-    recordDaemonRestoreKey(sessionName, namespace, restoreKey) {
-        if (sessionName)
-            this.#daemonRestoreKeys.set(getAgentBrowserSessionIdentityKey(sessionName, namespace), restoreKey);
+    recordDaemonRestoreKey(sessionName, namespace, restoreKey, generation) {
+        if (sessionName) {
+            const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+            const previous = this.#daemonRestoreKeys.get(key);
+            this.#daemonRestoreKeys.set(key, { restoreKey, generation: generation ?? (previous?.restoreKey === restoreKey ? previous.generation : undefined) });
+        }
+    }
+    getDaemonReceipt(sessionName, namespace) {
+        const receipt = sessionName ? this.#daemonRestoreKeys.get(getAgentBrowserSessionIdentityKey(sessionName, namespace)) : undefined;
+        return receipt?.generation ? { restoreKey: receipt.restoreKey, generation: receipt.generation } : undefined;
+    }
+    restoreDaemonReceipt(sessionName, namespace, receipt) {
+        if (isRecord(receipt) && typeof receipt.generation === "string" && receipt.generation.length > 0
+            && (receipt.restoreKey === null || typeof receipt.restoreKey === "string")) {
+            this.#daemonRestoreKeys.set(getAgentBrowserSessionIdentityKey(sessionName, namespace), { restoreKey: receipt.restoreKey, generation: receipt.generation, restored: true });
+        }
     }
     replace(identities = [], options = {}) {
         if (!options.preserveDaemonRestoreKeys)

package/dist/extensions/agent-browser/lib/native-output.js

@@ -0,0 +1,46 @@
+import { JsonSchema } from "./json-schema.js";
+import { isRecord } from "./parsing.js";
+import { finalizeAgentBrowserFailure } from "./pi-tool-rendering.js";
+import { isPlainTextInspectionArgs } from "./runtime.js";
+import { projectAgentBrowserObservation, OBSERVATION_INLINE_MAX_CHARS } from "./results/presentation/content.js";
+export const AGENT_BROWSER_NAMESPACE = {
+    name: "browser",
+    description: "Browser commands, bounded browser code, advanced UI checks, Electron, and optional web search.",
+    instructions: "Use agent_browser for native commands and batch --bail for fixed sequences. Use agent_browser_code for a fresh bounded JS cell with a persistent browser. Enable advanced direct tools with agent_browser_tools before calling them. Check success and nextActions; structured imageObservations are capture metadata, not inline images. Optional web search is available only when configured. Full browser instructions remain in the agent_browser prompt section.",
+};
+export const AGENT_BROWSER_OUTPUT_SCHEMA = JsonSchema.Object({
+    success: JsonSchema.Boolean(),
+    resultCategory: JsonSchema.Union([JsonSchema.Literal("success"), JsonSchema.Literal("failure")]),
+    data: JsonSchema.Optional(JsonSchema.Unsafe({})),
+    error: JsonSchema.Optional(JsonSchema.Unsafe({})),
+    summary: JsonSchema.Optional(JsonSchema.String()),
+    nextActions: JsonSchema.Optional(JsonSchema.Array(JsonSchema.Object({}))),
+}, { additionalProperties: true });
+/** Final public boundary, after execution, persistence, and any requested output export. */
+export async function finalizeAgentBrowserNativeResult(result, input) {
+    const finalized = finalizeAgentBrowserFailure(result, input);
+    // Native help/version stays plain text; the entrypoint intentionally skips observation rendering for it.
+    if (isRecord(input) && Array.isArray(input.args) && isPlainTextInspectionArgs(input.args))
+        return finalized;
+    const succeeded = finalized.isError !== true;
+    // The normal entrypoint supplies the exact bounded projection, including its complete spill.
+    if (isRecord(result.structuredContent) && result.structuredContent.success === succeeded)
+        return finalized;
+    const details = isRecord(result.details) ? result.details : {};
+    const observation = projectAgentBrowserObservation(details, succeeded);
+    if (JSON.stringify(observation).length > OBSERVATION_INLINE_MAX_CHARS) {
+        const { renderAgentBrowserObservation } = await import("./results/presentation/large-output.js");
+        const rendered = await renderAgentBrowserObservation({
+            content: finalized.content, details, succeeded,
+            json: isRecord(input) && ("code" in input || Array.isArray(input.args) && input.args.includes("--json")),
+            // The caller's exact visible output stays inline (for example formatted search results); only the structured field is bounded.
+            preserveContent: true,
+        });
+        const { artifactManifest, ...renderedResult } = rendered;
+        return finalizeAgentBrowserFailure({
+            ...finalized, ...renderedResult,
+            details: artifactManifest ? { ...details, artifactManifest } : details,
+        }, input);
+    }
+    return { ...finalized, structuredContent: JSON.parse(JSON.stringify(observation)) };
+}

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

@@ -5,7 +5,8 @@ import { acquireManagedSessionPolicyLock } from "../../managed-session-policy-lo
 import { pruneOwnedManagedSessionRestoreSnapshots, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
 import { isRecord } from "../../parsing.js";
-import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { readProcessStartIdentity } from "../../process-identity.js";
+import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment } from "../../process-environment.js";
 import { runAgentBrowserProcess, withAttachedBrowserSessionContext } from "../../process.js";
 import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
 import { redactInvocationArgs } from "../../runtime.js";
@@ -43,9 +44,16 @@ export async function inspectManagedSessionDaemon(options) {
             return { status: "inactive" };
         if (!isRecord(data.runtime))
             return { status: "unknown" };
+        let generation;
+        if (options.includeGeneration && Number.isSafeInteger(data.runtime.backgroundPid) && Number(data.runtime.backgroundPid) > 0
+            && typeof data.runtime.socketDir === "string" && data.runtime.browserLaunched !== false) {
+            const start = await readProcessStartIdentity(Number(data.runtime.backgroundPid), process.platform, { signal: options.signal, deadline: Date.now() + (options.timeoutMs ?? 5_000) });
+            if (start)
+                generation = JSON.stringify({ pid: data.runtime.backgroundPid, start, socketDir: data.runtime.socketDir });
+        }
         if (typeof data.runtime.restoreKey === "string" && data.runtime.restoreKey.length > 0)
-            return { restoreKey: data.runtime.restoreKey, status: "active" };
-        return data.runtime.restoreKey === null ? { restoreKey: null, status: "active" } : { status: "unknown" };
+            return { restoreKey: data.runtime.restoreKey, status: "active", generation };
+        return data.runtime.restoreKey === null ? { restoreKey: null, status: "active", generation } : { status: "unknown" };
     }
     finally {
         if (processResult.stdoutSpillPath)
@@ -86,8 +94,10 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
             };
     }
     try {
+        const receipt = context.restoreState.getDaemonReceipt(context.sessionName, context.namespace);
         const daemon = await inspectManagedSessionDaemon({
             cwd: context.cwd,
+            includeGeneration: receipt !== undefined && !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace),
             headedManagedAutosaveInterval: context.headedManagedAutosaveInterval,
             namespace: context.namespace,
             sessionName: context.sessionName,
@@ -95,6 +105,13 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
         });
         if (daemon.status === "inactive")
             context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
+        if (daemon.status === "active" && receipt && !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace)) {
+            if (daemon.generation === receipt.generation && daemon.restoreKey === receipt.restoreKey) {
+                context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey, daemon.generation);
+            }
+            else
+                context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
+        }
         if (options.mode === "close") {
             if (daemon.status === "active")
                 context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
@@ -141,87 +158,89 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
     }
 }
 export async function closeManagedSession(options) {
-    const controller = new AbortController();
-    let phase = "policy coordination";
-    let phaseStartedAt = Date.now();
-    let timeoutError;
-    const timer = setTimeout(() => {
-        timeoutError = `Managed-session cleanup timed out after ${options.timeoutMs} ms during ${phase} (${Date.now() - phaseStartedAt} ms in this phase).`;
-        controller.abort();
-    }, options.timeoutMs);
-    let stdoutSpillPath;
-    const closeArgs = [...(options.namespace !== undefined ? ["--namespace", options.namespace] : []), "--session", options.sessionName, "close"];
-    const policyLock = options.policyLock ?? await acquireManagedSessionPolicyLock({
-        namespace: options.namespace,
-        sessionName: options.sessionName,
-        signal: controller.signal,
-        timeoutMs: Math.min(options.timeoutMs, 1_000),
-    });
-    if (!policyLock) {
-        clearTimeout(timer);
-        return timeoutError ?? "Managed-session policy coordination is unavailable or busy; cleanup did not run. Retry after the current operation finishes or repair the private policy-lock directory.";
-    }
-    try {
-        phase = "daemon inspection";
-        phaseStartedAt = Date.now();
-        const daemon = await inspectManagedSessionDaemon({
-            cwd: options.cwd,
-            headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
+    return withAgentBrowserProcessEnvironment(options.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: options.socketDir } : {}, async () => {
+        const controller = new AbortController();
+        let phase = "policy coordination";
+        let phaseStartedAt = Date.now();
+        let timeoutError;
+        const timer = setTimeout(() => {
+            timeoutError = `Managed-session cleanup timed out after ${options.timeoutMs} ms during ${phase} (${Date.now() - phaseStartedAt} ms in this phase).`;
+            controller.abort();
+        }, options.timeoutMs);
+        let stdoutSpillPath;
+        const closeArgs = [...(options.namespace !== undefined ? ["--namespace", options.namespace] : []), "--session", options.sessionName, "close"];
+        const policyLock = options.policyLock ?? await acquireManagedSessionPolicyLock({
             namespace: options.namespace,
-            preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
             sessionName: options.sessionName,
             signal: controller.signal,
-            timeoutMs: Math.min(options.timeoutMs, 2_000),
-        });
-        if (daemon.status === "active")
-            options.restoreState.recordDaemonRestoreKey(options.sessionName, options.namespace, daemon.restoreKey);
-        const daemonRestoreKey = options.restoreState.getDaemonRestoreKey(options.sessionName, options.namespace);
-        const ownedRestoreKey = !options.restoreState.isDisabled(options.sessionName, options.namespace)
-            && isManagedSessionRestoreKey(daemonRestoreKey) ? daemonRestoreKey : null;
-        phase = "native close";
-        phaseStartedAt = Date.now();
-        const processResult = await runAgentBrowserProcess({
-            args: closeArgs,
-            cwd: options.cwd,
-            env: { AGENT_BROWSER_JSON: "1", ...getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval) },
-            managedSessionRestoreState: options.restoreState,
-            ownedManagedSession: true,
-            preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
-            signal: controller.signal,
+            timeoutMs: Math.min(options.timeoutMs, 1_000),
         });
-        clearTimeout(timer);
-        stdoutSpillPath = processResult.stdoutSpillPath;
-        if (!processResult.aborted && !processResult.spawnError && processResult.exitCode === 0) {
-            const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
-            const data = parsed.envelope?.success === true && isRecord(parsed.envelope.data) ? parsed.envelope.data : undefined;
-            options.restoreState.clear(options.sessionName, options.namespace);
-            pruneOwnedManagedSessionRestoreSnapshots({
+        if (!policyLock) {
+            clearTimeout(timer);
+            return timeoutError ?? "Managed-session policy coordination is unavailable or busy; cleanup did not run. Retry after the current operation finishes or repair the private policy-lock directory.";
+        }
+        try {
+            phase = "daemon inspection";
+            phaseStartedAt = Date.now();
+            const daemon = await inspectManagedSessionDaemon({
                 cwd: options.cwd,
+                headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
                 namespace: options.namespace,
-                restoreKey: ownedRestoreKey,
-                statePath: typeof data?.statePath === "string" ? data.statePath : undefined,
+                preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
+                sessionName: options.sessionName,
+                signal: controller.signal,
+                timeoutMs: Math.min(options.timeoutMs, 2_000),
+            });
+            if (daemon.status === "active")
+                options.restoreState.recordDaemonRestoreKey(options.sessionName, options.namespace, daemon.restoreKey);
+            const daemonRestoreKey = options.restoreState.getDaemonRestoreKey(options.sessionName, options.namespace);
+            const ownedRestoreKey = !options.restoreState.isDisabled(options.sessionName, options.namespace)
+                && isManagedSessionRestoreKey(daemonRestoreKey) ? daemonRestoreKey : null;
+            phase = "native close";
+            phaseStartedAt = Date.now();
+            const processResult = await runAgentBrowserProcess({
+                args: closeArgs,
+                cwd: options.cwd,
+                env: { AGENT_BROWSER_JSON: "1", ...getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval) },
+                managedSessionRestoreState: options.restoreState,
+                ownedManagedSession: true,
+                preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            stdoutSpillPath = processResult.stdoutSpillPath;
+            if (!processResult.aborted && !processResult.spawnError && processResult.exitCode === 0) {
+                const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
+                const data = parsed.envelope?.success === true && isRecord(parsed.envelope.data) ? parsed.envelope.data : undefined;
+                options.restoreState.clear(options.sessionName, options.namespace);
+                pruneOwnedManagedSessionRestoreSnapshots({
+                    cwd: options.cwd,
+                    namespace: options.namespace,
+                    restoreKey: ownedRestoreKey,
+                    statePath: typeof data?.statePath === "string" ? data.statePath : undefined,
+                });
+            }
+            return timeoutError ?? getAgentBrowserErrorText({
+                aborted: processResult.aborted,
+                command: "close",
+                effectiveArgs: redactInvocationArgs(closeArgs),
+                exitCode: processResult.exitCode,
+                plainTextInspection: false,
+                spawnError: processResult.spawnError,
+                stderr: processResult.stderr,
+                timedOut: processResult.timedOut,
+                timeoutMs: processResult.timeoutMs,
             });
         }
-        return timeoutError ?? getAgentBrowserErrorText({
-            aborted: processResult.aborted,
-            command: "close",
-            effectiveArgs: redactInvocationArgs(closeArgs),
-            exitCode: processResult.exitCode,
-            plainTextInspection: false,
-            spawnError: processResult.spawnError,
-            stderr: processResult.stderr,
-            timedOut: processResult.timedOut,
-            timeoutMs: processResult.timeoutMs,
-        });
-    }
-    catch (error) {
-        return timeoutError ?? (error instanceof Error ? error.message : String(error));
-    }
-    finally {
-        clearTimeout(timer);
-        if (stdoutSpillPath)
-            await rm(stdoutSpillPath, { force: true }).catch(() => undefined);
-        if (!options.policyLock)
-            await policyLock.release();
-    }
+        catch (error) {
+            return timeoutError ?? (error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            clearTimeout(timer);
+            if (stdoutSpillPath)
+                await rm(stdoutSpillPath, { force: true }).catch(() => undefined);
+            if (!options.policyLock)
+                await policyLock.release();
+        }
+    });
 }

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

@@ -392,6 +392,7 @@ export async function prepareBrowserRun(options) {
                 }) };
         }
         electronLaunch = launchResult.value;
+        electronLaunch.record.ownerSessionId = options.ctx.sessionManager.getSessionId();
         runtimeToolArgs = ["connect", electronLaunch.connectArg];
         runtimeToolStdin = undefined;
     }
@@ -570,7 +571,18 @@ export async function prepareBrowserRun(options) {
             const sessionTabPinningReason = priorSessionPageState.pinningReason;
             let priorRefSnapshotState = priorSessionPageState.refSnapshot;
             let priorRefSnapshotInvalidation = priorSessionPageState.refSnapshotInvalidation;
-            const coldManagedSession = !browserIndependent && (managedSessionDaemonInactive || priorSessionPageState.tabReopenPending === true)
+            let nativeGenerationChanged = false;
+            if (!browserIndependent && !isCloseCommand(executionPlan.commandInfo.command) && priorRefSnapshotState?.refIds.length && sessionStateKey && executionPlan.sessionName) {
+                const daemon = await inspectManagedSessionDaemon({ cwd, namespace: executionPlan.namespace, sessionName: executionPlan.sessionName, signal, includeGeneration: true, headedManagedAutosaveInterval: ownedManagedSession?.headedManagedAutosaveInterval ?? (ownedManagedSession?.headedManagedAutosaveDisabled ? "0" : undefined), timeoutMs: params.timeoutMs });
+                sessionPageState.bindSnapshotGeneration(sessionStateKey, daemon.status === "active" ? daemon.generation : undefined);
+                if (daemon.status !== "active" || daemon.generation === undefined || priorRefSnapshotState.generation !== daemon.generation) {
+                    nativeGenerationChanged = daemon.status === "active" && daemon.generation !== undefined && priorRefSnapshotState.generation !== undefined && priorRefSnapshotState.generation !== daemon.generation;
+                    priorRefSnapshotState = undefined;
+                    priorRefSnapshotInvalidation = buildPageTransitionRefSnapshotInvalidation("The native browser generation changed or could not be verified. Take a new complete snapshot before using refs, even when the URL is unchanged.");
+                    sessionPageState.applyRefSnapshotInvalidation({ invalidation: priorRefSnapshotInvalidation, sessionName: sessionStateKey, update: options.sessionPageStateUpdate });
+                }
+            }
+            const coldManagedSession = !browserIndependent && (managedSessionDaemonInactive || nativeGenerationChanged || priorSessionPageState.tabReopenPending === true)
                 && recordedOwnedSession !== undefined
                 && sessionTabPinningReason === "restore"
                 && ownedManagedSession?.restoreDecision === "enabled"
@@ -960,8 +972,17 @@ export async function prepareBrowserRun(options) {
                 signal,
                 usedImplicitSession: executionPlan.usedImplicitSession,
             });
-            if (snapshotFilter)
+            if (snapshotFilter) {
+                if (sessionStateKey && executionPlan.sessionName) {
+                    const daemon = await inspectManagedSessionDaemon({ cwd, namespace: executionPlan.namespace, sessionName: executionPlan.sessionName, signal, includeGeneration: true, headedManagedAutosaveInterval: ownedManagedSession?.headedManagedAutosaveInterval ?? (ownedManagedSession?.headedManagedAutosaveDisabled ? "0" : undefined), timeoutMs: params.timeoutMs });
+                    sessionPageState.bindSnapshotGeneration(sessionStateKey, daemon.status === "active" ? daemon.generation : undefined);
+                    if (ownedManagedSession && daemon.status === "active" && daemon.generation)
+                        state.managedSessionRestoreState.recordDaemonRestoreKey(executionPlan.sessionName, executionPlan.namespace, daemon.restoreKey, daemon.generation);
+                    if (isRecord(snapshotFilter.result.details))
+                        snapshotFilter.result.details.refSnapshot = sessionPageState.get(sessionStateKey).refSnapshot;
+                }
                 return { kind: "early-result", statePatch: { ...statePatch, artifactManifest: snapshotFilter.artifactManifest ?? statePatch.artifactManifest }, result: snapshotFilter.result };
+            }
             const networkRequestsPageFilter = await tryNetworkRequestsPageFilter({
                 commandTokens,
                 compatibilityWorkaround,