pi-agent-browser-native 0.9.2 → 0.9.4

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

@@ -0,0 +1,167 @@
+import { rm } from "node:fs/promises";
+import { acquireManagedSessionPolicyLock, } from "../../managed-session-policy-lock.js";
+import { pruneOwnedManagedSessionRestoreSnapshots, } from "../../managed-session-restore.js";
+import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
+import { isRecord } from "../../parsing.js";
+import { withAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { runAgentBrowserProcess } from "../../process.js";
+import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
+import { detectConfirmationRequired } from "../../results/confirmation.js";
+import { stringifyUnknown } from "../../results/text.js";
+import { redactInvocationArgs } from "../../runtime-redaction.js";
+import { getHeadedManagedAutosaveEnv, inspectManagedSessionDaemon, } from "./managed-session-daemon-inspection.js";
+function getCloseArgs(options) {
+    return [
+        ...(options.namespace !== undefined ? ["--namespace", options.namespace] : []),
+        "--session",
+        options.sessionName,
+        "close",
+    ];
+}
+async function inspectCloseRestoreKey(options, signal) {
+    const daemon = await inspectManagedSessionDaemon({
+        cwd: options.cwd,
+        headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
+        namespace: options.namespace,
+        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
+        sessionName: options.sessionName,
+        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);
+    return !options.restoreState.isDisabled(options.sessionName, options.namespace) &&
+        isManagedSessionRestoreKey(daemonRestoreKey)
+        ? daemonRestoreKey
+        : null;
+}
+function confirmedClosedData(processResult, envelope) {
+    return !processResult.aborted &&
+        !processResult.spawnError &&
+        processResult.exitCode === 0 &&
+        envelope?.success === true &&
+        isRecord(envelope.data) &&
+        envelope.data.closed === true
+        ? envelope.data
+        : undefined;
+}
+async function finishManagedClose(options, processResult, ownedRestoreKey) {
+    const parsed = await parseAgentBrowserEnvelope({
+        stdout: processResult.stdout,
+        stdoutPath: processResult.stdoutSpillPath,
+    });
+    const closedData = confirmedClosedData(processResult, parsed.envelope);
+    if (closedData) {
+        options.restoreState.clear(options.sessionName, options.namespace);
+        pruneOwnedManagedSessionRestoreSnapshots({
+            cwd: options.cwd,
+            namespace: options.namespace,
+            restoreKey: ownedRestoreKey,
+            statePath: typeof closedData.statePath === "string" ? closedData.statePath : undefined,
+        });
+    }
+    const pending = detectConfirmationRequired(parsed.envelope?.data);
+    if (pending) {
+        return `Native close requires confirmation (${pending.id}); the session remains wrapper-owned.`;
+    }
+    return getAgentBrowserErrorText({
+        aborted: processResult.aborted,
+        command: "close",
+        effectiveArgs: redactInvocationArgs(getCloseArgs(options)),
+        envelope: parsed.envelope,
+        exitCode: processResult.exitCode,
+        parseError: parsed.parseError,
+        plainTextInspection: false,
+        spawnError: processResult.spawnError,
+        stderr: processResult.stderr,
+        timedOut: processResult.timedOut,
+        timeoutMs: processResult.timeoutMs,
+    });
+}
+async function closeUnderPolicy(options, lifecycle) {
+    lifecycle.enterPhase("daemon inspection");
+    const ownedRestoreKey = await inspectCloseRestoreKey(options, lifecycle.signal);
+    lifecycle.enterPhase("native close");
+    const processResult = await runAgentBrowserProcess({
+        args: getCloseArgs(options),
+        cwd: options.cwd,
+        env: {
+            AGENT_BROWSER_JSON: "1",
+            ...getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
+        },
+        managedSessionRestoreState: options.restoreState,
+        ownedManagedSession: true,
+        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
+        signal: lifecycle.signal,
+    });
+    lifecycle.clearTimer();
+    try {
+        return await finishManagedClose(options, processResult, ownedRestoreKey);
+    }
+    finally {
+        if (processResult.stdoutSpillPath !== undefined && processResult.stdoutSpillPath !== "") {
+            await rm(processResult.stdoutSpillPath, { force: true }).catch(() => {
+                // A spill removal failure must not replace the native close result.
+            });
+        }
+    }
+}
+async function closeWithDeadline(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);
+    const lifecycle = {
+        signal: controller.signal,
+        enterPhase: (nextPhase) => {
+            phase = nextPhase;
+            phaseStartedAt = Date.now();
+        },
+        clearTimer: () => {
+            clearTimeout(timer);
+        },
+    };
+    let policyLock;
+    try {
+        policyLock =
+            options.policyLock ??
+                (await acquireManagedSessionPolicyLock({
+                    namespace: options.namespace,
+                    sessionName: options.sessionName,
+                    signal: controller.signal,
+                    timeoutMs: Math.min(options.timeoutMs, 1_000),
+                }));
+        if (!policyLock) {
+            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 {
+            const closeError = await closeUnderPolicy(options, lifecycle);
+            // The deadline callback can update timeoutError while any close phase is suspended.
+            return timeoutError ?? closeError;
+        }
+        catch (error) {
+            return timeoutError ?? (error instanceof Error ? error.message : stringifyUnknown(error));
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        if (options.policyLock === undefined && policyLock) {
+            await policyLock.release();
+        }
+    }
+}
+export function closeManagedSession(options) {
+    return withAgentBrowserProcessEnvironment({
+        AGENT_BROWSER_CONFIRM_ACTIONS: options.confirmActions,
+        ...(options.socketDir !== undefined && options.socketDir !== ""
+            ? { PI_AGENT_BROWSER_SOCKET_DIR: options.socketDir }
+            : {}),
+    }, () => closeWithDeadline(options));
+}

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

@@ -0,0 +1,108 @@
+import { rm } from "node:fs/promises";
+import { isRecord } from "../../parsing.js";
+import { resolveExplicitAutosaveInterval } from "../../managed-session-restore.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { readProcessStartIdentity } from "../../process-identity.js";
+import { runAgentBrowserProcess } from "../../process.js";
+import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
+const MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS = 35_000;
+const RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR = 'AGENT_BROWSER_AUTOSAVE_INTERVAL_MS cannot change a running wrapper-owned headed session\'s launch-time periodic autosave interval. Close that session first, then retry with sessionMode: "fresh" so the new daemon starts with the requested interval.';
+export function getRunningHeadedAutosavePolicyChangeError(recordedInterval, closeCommand = false) {
+    const explicitInterval = resolveExplicitAutosaveInterval(getAgentBrowserProcessEnvironment().AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
+    return recordedInterval !== undefined &&
+        !closeCommand &&
+        explicitInterval !== undefined &&
+        explicitInterval !== recordedInterval
+        ? RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR
+        : undefined;
+}
+export function getHeadedManagedAutosaveEnv(interval) {
+    return interval !== undefined ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: interval } : undefined;
+}
+async function readDaemonGeneration(runtime, options) {
+    if (options.includeGeneration !== true ||
+        typeof runtime.backgroundPid !== "number" ||
+        !Number.isSafeInteger(runtime.backgroundPid) ||
+        runtime.backgroundPid <= 0 ||
+        typeof runtime.socketDir !== "string" ||
+        runtime.browserLaunched === false) {
+        return undefined;
+    }
+    const start = await readProcessStartIdentity(runtime.backgroundPid, process.platform, {
+        signal: options.signal,
+        deadline: Date.now() + (options.timeoutMs ?? 5_000),
+    });
+    return start !== undefined && start !== ""
+        ? JSON.stringify({
+            pid: runtime.backgroundPid,
+            start,
+            socketDir: runtime.socketDir,
+        })
+        : undefined;
+}
+async function parseDaemonInspection(data, options) {
+    if (!isRecord(data) || typeof data.active !== "boolean") {
+        return { status: "unknown" };
+    }
+    if (!data.active) {
+        return { status: "inactive" };
+    }
+    if (!isRecord(data.runtime)) {
+        return { status: "unknown" };
+    }
+    const generation = await readDaemonGeneration(data.runtime, options);
+    if (typeof data.runtime.restoreKey === "string" && data.runtime.restoreKey.length > 0) {
+        return { restoreKey: data.runtime.restoreKey, status: "active", generation };
+    }
+    return data.runtime.restoreKey === null
+        ? { restoreKey: null, status: "active", generation }
+        : { status: "unknown" };
+}
+function daemonProcessFailure(processResult) {
+    if (processResult.spawnError &&
+        "code" in processResult.spawnError &&
+        processResult.spawnError.code === "ENOENT") {
+        return { status: "missing-binary" };
+    }
+    return processResult.aborted || processResult.spawnError || processResult.exitCode !== 0
+        ? { status: "unknown" }
+        : undefined;
+}
+async function readDaemonInfo(processResult) {
+    const parsed = await parseAgentBrowserEnvelope({
+        stdout: processResult.stdout,
+        stdoutPath: processResult.stdoutSpillPath,
+    });
+    return (parsed.parseError ?? "") !== "" || parsed.envelope?.success === false
+        ? undefined
+        : parsed.envelope?.data;
+}
+export async function inspectManagedSessionDaemon(options) {
+    const processResult = await runAgentBrowserProcess({
+        args: [
+            "--json",
+            "--namespace",
+            options.namespace ?? "",
+            "--session",
+            options.sessionName,
+            "session",
+            "info",
+        ],
+        cwd: options.cwd,
+        env: getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
+        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
+        signal: options.signal,
+        timeoutMs: options.timeoutMs ?? MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS,
+    });
+    try {
+        const failure = daemonProcessFailure(processResult);
+        return failure ?? (await parseDaemonInspection(await readDaemonInfo(processResult), options));
+    }
+    finally {
+        if (processResult.stdoutSpillPath !== undefined && processResult.stdoutSpillPath !== "") {
+            await rm(processResult.stdoutSpillPath, { force: true }).catch(() => {
+                // Spill cleanup is best-effort and must not change the daemon inspection result.
+            });
+        }
+    }
+}

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

@@ -1,93 +1,147 @@
-import { rm } from "node:fs/promises";
 import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
 import { inspectElectronLaunchStatus } from "../../electron/cleanup.js";
-import { acquireManagedSessionPolicyLock } from "../../managed-session-policy-lock.js";
-import { pruneOwnedManagedSessionRestoreSnapshots, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
-import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
+import { acquireManagedSessionPolicyLock, } from "../../managed-session-policy-lock.js";
+import { withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { isRecord } from "../../parsing.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";
+import { withAttachedBrowserSessionContext } from "../../process.js";
 import { runSessionCommandData } from "./session-state.js";
-const MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS = 35_000;
-const RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR = "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS cannot change a running wrapper-owned headed session's launch-time periodic autosave interval. Close that session first, then retry with sessionMode: \"fresh\" so the new daemon starts with the requested interval.";
-export function getRunningHeadedAutosavePolicyChangeError(recordedInterval, closeCommand = false) {
-    const explicitInterval = resolveExplicitAutosaveInterval(getAgentBrowserProcessEnvironment().AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
-    return recordedInterval !== undefined && !closeCommand && explicitInterval !== undefined && explicitInterval !== recordedInterval
-        ? RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR
-        : undefined;
+import { getHeadedManagedAutosaveEnv, inspectManagedSessionDaemon, } from "./managed-session-daemon-inspection.js";
+export { closeManagedSession } from "./managed-session-close.js";
+export { getRunningHeadedAutosavePolicyChangeError, inspectManagedSessionDaemon, } from "./managed-session-daemon-inspection.js";
+function hasElectronAttachmentIdentity(record) {
+    return (record.webSocketDebuggerUrl !== undefined &&
+        record.webSocketDebuggerUrl !== "" &&
+        record.sessionName !== undefined &&
+        record.sessionName !== "");
 }
-function getHeadedManagedAutosaveEnv(interval) {
-    return interval !== undefined ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: interval } : undefined;
-}
-export async function inspectManagedSessionDaemon(options) {
-    const processResult = await runAgentBrowserProcess({
-        args: ["--json", "--namespace", options.namespace ?? "", "--session", options.sessionName, "session", "info"],
-        cwd: options.cwd,
-        env: getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
-        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
-        signal: options.signal,
-        timeoutMs: options.timeoutMs ?? MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS,
-    });
-    try {
-        if (processResult.spawnError?.code === "ENOENT")
-            return { status: "missing-binary" };
-        if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0)
-            return { status: "unknown" };
-        const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
-        const data = parsed.parseError || parsed.envelope?.success === false ? undefined : parsed.envelope?.data;
-        if (!isRecord(data) || typeof data.active !== "boolean")
-            return { status: "unknown" };
-        if (!data.active)
-            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", generation };
-        return data.runtime.restoreKey === null ? { restoreKey: null, status: "active", generation } : { status: "unknown" };
+function restoredAttachmentTarget(context, record) {
+    const cwd = context.cwd;
+    if (cwd === undefined || cwd === "" || !record || !hasElectronAttachmentIdentity(record)) {
+        return undefined;
     }
-    finally {
-        if (processResult.stdoutSpillPath)
-            await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+    if (record.cleanupState === "cleaned" ||
+        getAgentBrowserSessionIdentityKey(record.sessionName ?? "", record.namespace) !==
+            getAgentBrowserSessionIdentityKey(context.sessionName, context.namespace)) {
+        return undefined;
     }
+    return { cwd, record };
 }
-async function verifyRestoredElectronAttachment(context, record, signal, timeoutMs) {
-    const cwd = context.cwd;
-    if (!cwd || !record?.webSocketDebuggerUrl || !record.sessionName || record.cleanupState === "cleaned"
-        || getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace) !== getAgentBrowserSessionIdentityKey(context.sessionName, context.namespace))
+function attachmentStatusMatches(record, status) {
+    return (status.pidAlive === true &&
+        status.userDataDirState === "present" &&
+        status.version?.webSocketDebuggerUrl === record.webSocketDebuggerUrl);
+}
+function attachmentConnectionMatches(connection, record, status) {
+    return (isRecord(connection) &&
+        typeof connection.cdpUrl === "string" &&
+        (connection.cdpUrl === record.webSocketDebuggerUrl ||
+            status.targets.some((target) => target.webSocketDebuggerUrl === connection.cdpUrl)));
+}
+async function verifyRestoredElectronAttachment(options) {
+    const { context, signal } = options;
+    const attachment = restoredAttachmentTarget(context, options.electronLaunchRecord);
+    if (!attachment) {
         return false;
-    const status = await inspectElectronLaunchStatus(record, signal);
-    if (signal?.aborted || status.pidAlive !== true || status.userDataDirState !== "present"
-        || status.version?.webSocketDebuggerUrl !== record.webSocketDebuggerUrl)
+    }
+    const status = await inspectElectronLaunchStatus(attachment.record, signal);
+    if (signal?.aborted === true || !attachmentStatusMatches(attachment.record, status)) {
         return false;
+    }
     // This metadata probe must not grant daemon provenance just by spawning.
     const connection = await withAttachedBrowserSessionContext(true, () => withOwnedManagedSessionContext(undefined, () => runSessionCommandData({
-        args: ["get", "cdp-url"], cwd, env: getHeadedManagedAutosaveEnv(context.headedManagedAutosaveInterval), namespace: context.namespace, pinNamespace: true,
-        sessionName: context.sessionName, signal, timeoutMs,
+        args: ["get", "cdp-url"],
+        cwd: attachment.cwd,
+        env: getHeadedManagedAutosaveEnv(context.headedManagedAutosaveInterval),
+        namespace: context.namespace,
+        pinNamespace: true,
+        sessionName: context.sessionName,
+        signal,
+        timeoutMs: options.electronVerificationTimeoutMs,
     })));
-    return !signal?.aborted && isRecord(connection) && typeof connection.cdpUrl === "string"
-        && (connection.cdpUrl === record.webSocketDebuggerUrl || status.targets.some((target) => target.webSocketDebuggerUrl === connection.cdpUrl));
+    return (
+    // The abort callback can change this signal during the awaited CDP read; static narrowing does not model it.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
+    !(signal?.aborted ?? false) &&
+        attachmentConnectionMatches(connection, attachment.record, status));
+}
+function reconcileDaemonReceipt(context, daemon, receipt) {
+    if (daemon.status === "inactive") {
+        context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
+    }
+    if (daemon.status !== "active" ||
+        receipt === undefined ||
+        context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace)) {
+        return;
+    }
+    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);
+    }
+}
+function daemonPolicyMismatch(daemon, restoreDisabledPolicyNeedsProvenance, hasKnownDaemonRestoreKey) {
+    return {
+        cleanupOnlyReason: daemon.status === "active" &&
+            restoreDisabledPolicyNeedsProvenance &&
+            !hasKnownDaemonRestoreKey
+            ? "restore-disabled-daemon-without-provenance"
+            : undefined,
+        daemonStatus: daemon.status,
+        error: [
+            "This wrapper-owned session's live daemon does not match the requested managed-restore policy.",
+            'Close that session first, retry with sessionMode: "fresh", or use a distinct explicit --session.',
+        ].join(" "),
+    };
+}
+async function validateReusableDaemonPolicy(options, daemon) {
+    const { context } = options;
+    const stickyDisabled = context.restoreState.isDisabled(context.sessionName, context.namespace);
+    let hasKnownDaemonRestoreKey = context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace);
+    const knownDaemonRestoreKey = context.restoreState.getDaemonRestoreKey(context.sessionName, context.namespace);
+    const requestedDaemonRestoreKey = context.restoreDecision === "enabled" && stickyDisabled
+        ? (knownDaemonRestoreKey ?? null)
+        : context.expectedDaemonRestoreKey;
+    if (daemon.status === "unknown") {
+        return {
+            error: 'The wrapper could not verify this managed session\'s live daemon restore policy. Retry, close that session, or use sessionMode: "fresh".',
+        };
+    }
+    const restoreDisabledPolicyNeedsProvenance = stickyDisabled || context.restoreDecision !== "enabled";
+    if (daemon.status === "active" &&
+        restoreDisabledPolicyNeedsProvenance &&
+        !hasKnownDaemonRestoreKey &&
+        daemon.restoreKey === requestedDaemonRestoreKey) {
+        hasKnownDaemonRestoreKey = await verifyRestoredElectronAttachment(options);
+    }
+    return finishReusableDaemonPolicy(context, daemon, {
+        restoreDisabledPolicyNeedsProvenance,
+        requestedDaemonRestoreKey,
+    }, hasKnownDaemonRestoreKey);
+}
+function finishReusableDaemonPolicy(context, daemon, policy, hasKnownDaemonRestoreKey) {
+    const activePolicyMatches = daemon.status === "active" &&
+        (!policy.restoreDisabledPolicyNeedsProvenance || hasKnownDaemonRestoreKey) &&
+        daemon.restoreKey === policy.requestedDaemonRestoreKey;
+    if (activePolicyMatches) {
+        context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
+    }
+    return !["inactive", "missing-binary"].includes(daemon.status) && !activePolicyMatches
+        ? daemonPolicyMismatch(daemon, policy.restoreDisabledPolicyNeedsProvenance, hasKnownDaemonRestoreKey)
+        : { daemonStatus: daemon.status };
 }
 export async function acquireOwnedManagedSessionDaemonPolicy(options) {
     const { context, signal } = options;
-    if (!context.cwd)
+    if (context.cwd === undefined || context.cwd === "") {
         return { error: "Managed-session policy validation requires the wrapper-owned session cwd." };
+    }
     const lock = await acquireManagedSessionPolicyLock({
         namespace: context.namespace,
         sessionName: context.sessionName,
         signal,
     });
     if (!lock) {
-        return signal?.aborted
+        return signal?.aborted === true
             ? {}
             : {
                 error: "Managed-session policy coordination is unavailable or busy. Retry after the current operation finishes, repair the private policy-lock directory, and on POSIX verify that /bin/ps, /usr/bin/ps, or ps through PATH is available.",
@@ -97,150 +151,24 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
         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),
+            includeGeneration: receipt !== undefined &&
+                !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace),
             headedManagedAutosaveInterval: context.headedManagedAutosaveInterval,
             namespace: context.namespace,
             sessionName: context.sessionName,
             signal,
         });
-        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);
-        }
+        reconcileDaemonReceipt(context, daemon, receipt);
         if (options.mode === "close") {
-            if (daemon.status === "active")
+            if (daemon.status === "active") {
                 context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
+            }
             return { daemonStatus: daemon.status, lock };
         }
-        const stickyDisabled = context.restoreState.isDisabled(context.sessionName, context.namespace);
-        let hasKnownDaemonRestoreKey = context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace);
-        const knownDaemonRestoreKey = context.restoreState.getDaemonRestoreKey(context.sessionName, context.namespace);
-        const requestedDaemonRestoreKey = context.restoreDecision === "enabled" && stickyDisabled
-            ? knownDaemonRestoreKey ?? null
-            : context.expectedDaemonRestoreKey;
-        if (daemon.status === "unknown") {
-            return {
-                error: "The wrapper could not verify this managed session's live daemon restore policy. Retry, close that session, or use sessionMode: \"fresh\".",
-                lock,
-            };
-        }
-        const restoreDisabledPolicyNeedsProvenance = stickyDisabled || context.restoreDecision !== "enabled";
-        if (daemon.status === "active" && restoreDisabledPolicyNeedsProvenance && !hasKnownDaemonRestoreKey && daemon.restoreKey === requestedDaemonRestoreKey) {
-            hasKnownDaemonRestoreKey = await verifyRestoredElectronAttachment(context, options.electronLaunchRecord, signal, options.electronVerificationTimeoutMs);
-        }
-        const activePolicyMatches = daemon.status === "active"
-            && (!restoreDisabledPolicyNeedsProvenance || hasKnownDaemonRestoreKey)
-            && daemon.restoreKey === requestedDaemonRestoreKey;
-        if (activePolicyMatches)
-            context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
-        return !["inactive", "missing-binary"].includes(daemon.status) && !activePolicyMatches
-            ? {
-                cleanupOnlyReason: daemon.status === "active" && restoreDisabledPolicyNeedsProvenance && !hasKnownDaemonRestoreKey
-                    ? "restore-disabled-daemon-without-provenance"
-                    : undefined,
-                daemonStatus: daemon.status,
-                error: [
-                    "This wrapper-owned session's live daemon does not match the requested managed-restore policy.",
-                    "Close that session first, retry with sessionMode: \"fresh\", or use a distinct explicit --session.",
-                ].join(" "),
-                lock,
-            }
-            : { daemonStatus: daemon.status, lock };
+        return { ...(await validateReusableDaemonPolicy(options, daemon)), lock };
     }
     catch (error) {
         await lock.release();
         throw error;
     }
 }
-export async function closeManagedSession(options) {
-    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,
-            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,
-                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,
-            });
-            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,
-            });
-        }
-        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();
-        }
-    });
-}