pi-agent-browser-native 0.6.15 → 0.6.16

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.6.16 - 2026-09-21
+
+### Qualification
+
+- The owner waived Windows qualification for this rollout on 2026-09-21; Windows failures remain visible and nonblocking, not passed. Linux/macOS, Node floors, official/fork consumer checks and all three final reviewer approvals remain required before merge, release or activation.
+- Track unresolved Windows policy-lock and restored Electron cleanup failures in [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191). The unchanged Electron repeat passed once without a product patch; its original cause remains unknown. Earlier passing focused Windows controls are bounded evidence, not full-suite qualification. Failed private Windows candidates are not integrated.
+
+### Fixed
+
+- Validate explicit Windows socket directories using native directory semantics instead of requiring POSIX ownership metadata.
+- Start the config CLI correctly on Windows and encoded or symlinked paths using Node's native entrypoint identity, while keeping module imports silent.
+- Redact bearer credentials followed by Windows path separators in diagnostic text.
+- Await Windows process-tree termination before returning from browser timeouts or cancellation.
+- Preserve literal newlines through agent-browser's recognized global npm Windows CMD launcher by invoking that installation's native executable directly; custom and unrecognized launchers retain their existing behavior.
+- Allow ten seconds for native Windows process-identity queries, including PowerShell startup, while preserving the identity format and five-second POSIX budget.
+- Await tracked Electron process exit before removing its profile and reporting cleanup complete.
+- Inspect native Windows process command lines when verifying ownership of restored Electron launches.
+- Recognize native Windows absolute checkout paths when checking for duplicate extension sources.
+- Recheck released managed-session policy claims after PID inspection so a completed owner does not leave a stale busy result.
+- Refresh transient choosing tickets so a later managed-session contender cannot block its predecessor after publishing its ticket.
+- Retry native Windows open-file rename conflicts during owned policy-claim cleanup, with token revalidation and a fresh one-second retry window even after long browser shutdowns.
+
 ## 0.6.15 - 2026-09-18
 
 ### Fixed

package/README.md

@@ -4,6 +4,14 @@ A Pi extension that lets coding agents drive real browser sessions with a native
 
 It is for Pi users who want agents to browse sites, inspect pages, click through flows, capture screenshots, use persistent profiles, and handle authenticated web apps without spending context on `agent-browser` CLI ceremony.
 
+## Pi release qualification
+
+Development host dependencies are pinned to official Pi **0.86.1**, with wildcard runtime peers. `npm run check:compat` checks the installed candidate SDK/CLI identity, typechecks, runs the existing offline tests (including the native Pi pipeline with a controlled provider and fake browser), and tests a packed runtime-only installation through both the SDK and the actual bundled RPC CLI. The fork lane additionally requires the native idle checkpoint hook. It does not substitute a fork SDK while leaving official types or child CLI installed.
+
+Run in an empty HOME with a **short** TMPDIR outside your real home. Long temporary paths can exceed macOS's 103-byte Unix socket limit; keep the fixture's socket safety checks intact. Real-browser/checkpoint controls, live upstream help sampling, lifecycle dogfood, and platform qualification remain the separate gates documented below. A Pi-only compatibility run uses no live browser profiles, credentials, or agent-browser fork, and does not certify those external integrations.
+
+For the 0.6.16 compatibility rollout, the owner explicitly waived Windows qualification on 2026-09-21. Windows diagnostics and failures remain visible but nonblocking; this is **not** a Windows full-suite pass. Linux/macOS, declared Node floors, official/fork host and consumer-artifact checks remain required. Known Windows failures and follow-up are tracked in [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191); see the [current support evidence](docs/SUPPORT_MATRIX.md#current-0616-rollout).
+
 ## Source-of-truth map
 
 Start here for install and common usage. For deeper work, use the active docs by purpose:
@@ -639,6 +647,10 @@ Policy-required URL reads keep the two-call read → confirm/deny flow. Returned
 
 Full live identity, browser-independent native reads/confirmations and detailed recording receipts require the companion upstream fixes; the current recommended release does not yet supply all of them. Older supported versions remain accepted with unavailable evidence marked unknown. The extension does not upgrade or restart your installed browser to obtain these fields.
 
+### Native working-session checkpoints
+
+On Pi hosts with `session_checkpoint`, an unused or cleanly closed browser integration can qualify for sleep. Live browsers, attachments, scripts, unfinished recordings/cleanup leases, and dirty recording persistence keep compute alive. Pi core owns native journal flush/repair and strict restore; an ongoing journal I/O failure rejects checkpoint acquisition. Checkpointing never closes browsers or changes cleanup ownership. Native save-on-close and per-root restore remain the persistence path; page JavaScript, unsaved forms, and live recordings are not serialized. See [checkpoint boundaries](docs/ARCHITECTURE.md#native-checkpoint-boundary).
+
 ### Profile selection
 
 The wrapper does not clone profiles or hide what upstream Chrome/Chromium profile or executable you chose. Passing `--profile` or `--executable-path` is an explicit upstream `agent-browser` choice. Visible page content from real profiles is model-visible and may persist in transcripts or saved artifacts; redaction protects credential-like cookie/storage/auth values, not ordinary page text you asked the browser to read. Redactions use `[REDACTED]` (URL-encoded in parsed URLs); ordinary technical phrases such as `bearer token` stay intact. URL redaction includes `code`, `authorization_session_id`, and auth-context `state` / `nonce` across visible text, details, spills, and `outputPath` exports. URLs needing no redaction keep their original spelling.

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

@@ -9,11 +9,12 @@ import { buildExecutionPlan, canUseHeadlessCompatibilityUserAgent, createEphemer
 import { deleteIdentityKeysInNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
 import { parseArgvDescriptor } from "./lib/argv-descriptor.js";
 import { needsManagedSession } from "./lib/command-policy.js";
-import { ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
+import { ManagedSessionRestoreState, resolveOwnedManagedSessionContext, withOwnedManagedSessionContext } from "./lib/managed-session-restore.js";
 import { isRecord } from "./lib/parsing.js";
 import { runAgentBrowserProcess } from "./lib/process.js";
 import { getAgentBrowserProcessEnvironment, withIsolatedAgentBrowserEnvironment } from "./lib/process-environment.js";
 import { withNativeSessionDefaults } from "./lib/orchestration/native-session-defaults.js";
+import { closeManagedSession, inspectManagedSessionDaemon } from "./lib/orchestration/browser-run/managed-session-daemon-policy.js";
 import { MINIMUM_AGENT_BROWSER_VERSION, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, getAgentBrowserVersionValidationError, parseAgentBrowserVersionOutput, } from "./lib/upstream-version.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseAllCommand, isCloseCommand } from "./lib/command-taxonomy.js";
@@ -21,9 +22,8 @@ import { hasLaunchScopedFlagToken } from "./lib/launch-scoped-flags.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
 import { AGENT_BROWSER_PARAMS } from "./lib/input-modes/params.js";
 import { AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS, AGENT_BROWSER_SCRIPT_NAMESPACE, createAgentBrowserScriptSessionName, isAgentBrowserScriptSessionName, runAgentBrowserScript, } from "./lib/input-modes/script.js";
-import { closeManagedSession, getSessionContextKey, runAgentBrowserTool } from "./lib/orchestration/browser-run/index.js";
 import { canonicalizeExplicitArtifactDestination, getExplicitArtifactDestination, getRecordContactSheetDestination } from "./lib/orchestration/browser-run/artifact-paths.js";
-import { findElectronLaunchRecordForSession, getActiveElectronRecords } from "./lib/orchestration/browser-run/session-state.js";
+import { findElectronLaunchRecordForSession, getActiveElectronRecords, getSessionContextKey } from "./lib/orchestration/browser-run/session-state.js";
 import { parseBatchCommandArgument, parseUserBatchStdin } from "./lib/orchestration/batch-stdin.js";
 import { ELECTRON_POST_COMMAND_STATUS_SETTLE_MS, ELECTRON_PROFILE_ISOLATION_DETAILS, cleanupActiveElectronHostLaunches, handleElectronHostInput, restoreElectronLaunchRecordsFromBranch, } from "./lib/orchestration/electron-host/index.js";
 import { buildValidationFailureResult, resolveAgentBrowserInput } from "./lib/orchestration/input-plan.js";
@@ -571,7 +571,7 @@ function collectBranchManagedResourceEvents(branch) {
             const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
-        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh" || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
+        if (succeeded && !isCloseCommand(command) && sessionName && ((!explicitSessionName && (usedImplicitSession || sessionMode === "fresh")) || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
             setBranchManagedSessionActive(events, sessionName, namespace, eventRank);
         }
         if (succeeded && isCloseCommand(command)) {
@@ -1243,6 +1243,78 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
             notifyRecordingPersistence(ctx);
         }));
     });
+    // Additive native checkpoint event; the package's 0.84 validation types predate it.
+    // Pi owns awaited tools/events (including their execution queues). Only script
+    // children and retained browser/recording resources need extension-side checks.
+    const checkpointPi = pi;
+    checkpointPi.on("session_checkpoint", async (event, ctx) => {
+        const blocked = (reason) => ({ sleepReady: false, reason });
+        if (activeScriptControllers.size || activeScriptExecutions.size)
+            return blocked("Browser script execution or cleanup is pending");
+        flushRecordingReservations();
+        if (recordingReservationsDirty)
+            return blocked("Browser recording journal persistence is dirty");
+        if (activeRecordingReservations.size)
+            return blocked("Browser recording is pending; finish it explicitly before sleep");
+        const entries = ctx.sessionManager.getEntries();
+        if ([...getScriptSessionLeasesFromBranch(entries).values()].some(lease => lease.cleanup !== "closed")
+            || [...ownedManagedSessions.values()].some(owner => isAgentBrowserScriptSessionName(owner.sessionName))) {
+            return blocked("Browser script cleanup lease is unresolved");
+        }
+        if (getActiveElectronRecords(ownedElectronLaunchRecords).length || getActiveElectronRecords(electronLaunchRecords).length
+            || [...electronChildProcesses.values()].some(child => child.exitCode === null && child.signalCode === null)) {
+            return blocked("Electron launch is still active");
+        }
+        if (attachedSessionKeys.size || restoreAttachedSessionKeysFromBranch(entries).size)
+            return blocked("Attached browser state is caller-owned and not checkpointed");
+        if (traceOwners.size || [...networkRoutesBySession.values()].some(routes => routes.length))
+            return blocked("Browser trace or network routes are still active");
+        // Include off-branch and caller-owned/root identities, without acquiring
+        // cleanup ownership. Transcript page/ref details do not serialize a browser.
+        const historicalResources = collectBranchManagedResourceEvents(entries);
+        const sessions = new Map(ownedManagedSessions);
+        if (managedSessionActive)
+            trackOwnedManagedSession(sessions, managedSessionName, managedSessionCwd, { namespace: managedSessionNamespace });
+        for (const entry of entries) {
+            if (entry.type !== "message" || entry.message.role !== "toolResult" || entry.message.toolName !== "agent_browser")
+                continue;
+            const details = isRecord(entry.message.details) ? entry.message.details : undefined;
+            // Helpers can launch before a main-process failure. Conversely, native
+            // launch flags on sessionless reads can open the unnamed default browser.
+            const sessionName = typeof details?.sessionName === "string" ? details.sessionName
+                : details?.agentBrowserStarted === true ? "default" : undefined;
+            if (!sessionName)
+                continue;
+            const namespace = typeof details?.namespace === "string" ? details.namespace : undefined;
+            const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+            if (!sessions.has(key))
+                trackOwnedManagedSession(sessions, sessionName, ctx.cwd, { namespace });
+        }
+        for (const [key, owner] of sessions) {
+            event.signal.throwIfAborted();
+            // An abnormal restart can leave a wrapper-created browser only off-branch.
+            // Reuse native ownership events for inspection, never cleanup ownership.
+            // A later close can refer to the same identity in a different socket root.
+            const historicalIdentity = historicalResources.managedSessionActiveIdentities.get(key);
+            const historicallyOwned = historicalIdentity && isRestorableManagedSessionName(historicalIdentity.sessionName, managedSessionBaseName);
+            const context = resolveOwnedManagedSessionContext({
+                ...owner,
+                currentManagedSessionName: managedSessionActive ? managedSessionName : undefined,
+                currentManagedSessionNamespace: managedSessionNamespace,
+                recordedOwnedSession: ownedManagedSessions.get(key) ?? (historicallyOwned ? { ...historicalIdentity, cwd: ctx.cwd } : undefined),
+                restoreState: managedSessionRestoreState,
+            });
+            // Owned routing must not mask an explicit caller's same-name ambient daemon.
+            for (const inspectionContext of context ? [{ ...context, reuseOnly: true }, undefined] : [undefined]) {
+                const daemon = await withOwnedManagedSessionContext(inspectionContext, () => inspectManagedSessionDaemon({ ...owner, signal: event.signal, timeoutMs: 2_000 }));
+                if (daemon.status !== "inactive")
+                    return blocked("Browser daemon is live or unverified; finish browser work explicitly before sleep");
+            }
+        }
+        // No detached writer remains to pause/resume. Native ingress stays held;
+        // checkpoint never closes a browser or changes ordinary shutdown ownership.
+        return { sleepReady: true };
+    });
     pi.on("session_shutdown", async (event, ctx) => {
         for (const controller of activeScriptControllers)
             controller.abort();
@@ -1623,6 +1695,9 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
                     ? getSessionContextKey(explicitSessionName, callerOwnedSessionNamespace) ?? explicitSessionName
                     : undefined;
                 const runBrowserCommand = async (daemonInactive) => {
+                    // Load execution-only preparation/output code inside the existing session queue,
+                    // before capturing state. Registration, rendering, and restore stay synchronous/eager.
+                    const { runAgentBrowserTool } = await import("./lib/orchestration/browser-run/index.js");
                     flushRecordingReservations();
                     const branchRestoreGenerationAtStart = branchRestoreGeneration;
                     const generationAtStart = branchStateGeneration;

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

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { lstat, rm } from "node:fs/promises";
+import { win32 } from "node:path";
 import { promisify } from "node:util";
 import { fetchCdpJson, parseCdpTargets, parseCdpVersion } from "./cdp.js";
 import { ELECTRON_PROFILE_DIR_PREFIX } from "./launch.js";
@@ -53,21 +54,35 @@ export async function inspectElectronLaunchStatus(record, signal) {
         version: cdp.version,
     };
 }
+function hasProcessExited(child, pid) {
+    // A Windows PID probe can report ESRCH during termination, before the
+    // tracked process has exited and released its executable/resources.
+    return child ? child.exitCode !== null || child.signalCode !== null : isPidAlive(pid) === false;
+}
 async function waitForProcessExit(child, pid, deadlineMs) {
     while (Date.now() <= deadlineMs) {
-        if (child && (child.exitCode !== null || child.signalCode !== null))
-            return true;
-        if (isPidAlive(pid) === false)
+        if (hasProcessExited(child, pid))
             return true;
         await sleep(ELECTRON_CLEANUP_POLL_INTERVAL_MS);
     }
-    return isPidAlive(pid) === false;
+    return hasProcessExited(child, pid);
 }
 async function readPidCommandLine(pid) {
     if (!pid || !Number.isSafeInteger(pid) || pid <= 0)
         return undefined;
     try {
-        const { stdout } = await execFileAsync("ps", ["-ww", "-p", String(pid), "-o", "command="], {
+        // Win32_Process.CommandLine is the native ownership evidence; process
+        // start time (used by daemon-policy locks) cannot prove profile ownership.
+        const systemRoot = process.env.SystemRoot;
+        const windowsRoot = systemRoot && win32.isAbsolute(systemRoot) ? systemRoot : "C:\\Windows";
+        const file = process.platform === "win32"
+            ? win32.join(windowsRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+            : "ps";
+        const args = process.platform === "win32"
+            ? ["-NoProfile", "-NonInteractive", "-Command",
+                `[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new(); $p = [wmi]"Win32_Process.Handle='${pid}'"; [Console]::WriteLine($p.CommandLine)`]
+            : ["-ww", "-p", String(pid), "-o", "command="];
+        const { stdout } = await execFileAsync(file, args, {
             timeout: RESTORED_PROCESS_COMMAND_TIMEOUT_MS,
         });
         return stdout.trim() || undefined;
@@ -117,7 +132,7 @@ function signalRestoredLaunchProcess(record, signal) {
 async function cleanupProcess(record, child, deadlineMs) {
     if (!record.pid)
         return { resource: "process", state: "skipped" };
-    if (isPidAlive(record.pid) === false)
+    if (hasProcessExited(child, record.pid))
         return { resource: "process", state: "already-gone" };
     if (!child) {
         const verificationError = await getRestoredProcessVerificationError(record);

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

@@ -164,16 +164,29 @@ async function ownerAlive(owner) {
     const current = await readProcessStartIdentity(owner.pid);
     return current === undefined ? undefined : processStartIdentitiesMatch(owner.startIdentity, current);
 }
-async function removeClaimOwnedBy(path, token) {
-    const current = await readClaim(path);
-    if (current?.owner.token !== token)
-        return false;
+async function removeClaimOwnedBy(path, token, deadline = 0) {
     const movedPath = join(dirname(path), `.pi-agent-browser-policy-remove-${token}-${randomUUID()}`);
-    try {
-        await rename(path, movedPath);
-    }
-    catch (error) {
-        return error.code === "ENOENT";
+    while (true) {
+        const current = await readClaim(path);
+        if (current?.owner.token !== token)
+            return false;
+        try {
+            await rename(path, movedPath);
+            break;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT")
+                return true;
+            // Windows may refuse a directory move while a contender reads its
+            // metadata. Revalidate before retrying. Owned-claim cleanup gets
+            // its own bounded window, independent of the acquisition wait.
+            if (process.platform !== "win32" || code !== "EPERM" || Date.now() >= deadline)
+                return false;
+            await waitForRetry();
+            if (Date.now() >= deadline)
+                return false;
+        }
     }
     const moved = await readClaim(movedPath);
     if (moved?.owner.token !== token) {
@@ -209,6 +222,12 @@ function claimPrecedes(left, right) {
         return false;
     return left.ticket < right.ticket || (left.ticket === right.ticket && left.owner.token < right.owner.token);
 }
+async function hasPublishedLaterTicket(claim, ownClaim) {
+    if (claim.ticket !== null)
+        return false;
+    const current = await readClaim(claim.path);
+    return current?.owner.token === claim.owner.token && !claimPrecedes(current, ownClaim);
+}
 function waitForRetry(signal) {
     return new Promise((resolve) => {
         if (signal?.aborted)
@@ -266,18 +285,35 @@ export async function acquireManagedSessionPolicyLock(options) {
             for (const claim of claims) {
                 if (claim.owner.token === token || !claimPrecedes(claim, ownClaim))
                     continue;
+                // Choosing is transient: a later published ticket must not make
+                // its predecessor wait on it using an earlier null snapshot.
+                if (await hasPublishedLaterTicket(claim, ownClaim))
+                    continue;
                 const alive = await ownerAlive(claim.owner);
                 if (alive === false) {
                     await removeClaimOwnedBy(claim.path, claim.owner.token);
                     continue;
                 }
+                // A native identity query can outlive the owner's entire critical
+                // section. Its result (including unknown after exit) does not make
+                // an already released immutable claim a current blocker.
+                try {
+                    await lstat(claim.path);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        continue;
+                }
+                // Publication can also complete during the native identity query.
+                if (await hasPublishedLaterTicket(claim, ownClaim))
+                    continue;
                 blocked = true;
                 break;
             }
             if (!blocked) {
                 await cleanDeadPolicyArtifacts(directory);
                 lockAcquired = true;
-                return { release: async () => { await removeClaimOwnedBy(claimPath, token); } };
+                return { release: async () => { await removeClaimOwnedBy(claimPath, token, Date.now() + POLICY_LOCK_WAIT_MS); } };
             }
             if (Date.now() >= deadline)
                 return undefined;
@@ -291,6 +327,6 @@ export async function acquireManagedSessionPolicyLock(options) {
     finally {
         await rm(candidatePath, { force: true, recursive: true }).catch(() => undefined);
         if (claimPublished && !lockAcquired)
-            await removeClaimOwnedBy(claimPath, token);
+            await removeClaimOwnedBy(claimPath, token, Date.now() + POLICY_LOCK_WAIT_MS);
     }
 }

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

@@ -1,7 +1,8 @@
 import { execFile } from "node:child_process";
 import { dirname, join, win32 } from "node:path";
 const WINDOWS_PROCESS_START_IDENTITY_PREFIX = "win32-powershell-ticks-v1:";
-const PROCESS_START_IDENTITY_TIMEOUT_MS = 5_000;
+// Native Windows PowerShell startup can exhaust the former five-second probe budget.
+const PROCESS_START_IDENTITY_TIMEOUT_MS = process.platform === "win32" ? 10_000 : 5_000;
 const DEFAULT_WINDOWS_SYSTEM_ROOT = "C:\\Windows";
 export function buildProcessStartIdentityCommand(pid, platform = process.platform) {
     if (!Number.isSafeInteger(pid) || pid <= 0)

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

@@ -11,6 +11,7 @@ import { getPageTargetValidationError, } from "./page-target-validation.js";
 import { getImplicitSessionIdleTimeoutMs } from "./runtime.js";
 import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
+import { resolveWindowsStockLauncher } from "./windows-stock-launcher.js";
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
 const MAX_BUFFERED_STDERR_CHARS = 32_000;
 const MAX_BUFFERED_STDOUT_TAIL_CHARS = 32_000;
@@ -52,11 +53,17 @@ export function prepareAgentBrowserSpawnArgs(args, wrapperCompatibilityUserAgent
     normalized[occurrence.index + 1] = customArgs;
     return normalized;
 }
-function terminateSpawnedChild(child, signal) {
+async function terminateSpawnedChild(child, signal) {
     if (processPlatform === "win32" && child.pid) {
-        const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
-        killer.on("error", () => undefined);
-        killer.unref();
+        // Keep the shell alive until taskkill has traversed its descendants, and
+        // observe the killer before allowing the browser call to finish.
+        const killed = await new Promise((resolve) => {
+            const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+            killer.once("error", () => resolve(false));
+            killer.once("close", (code) => resolve(code === 0));
+        });
+        if (killed)
+            return;
     }
     child.kill(signal);
 }
@@ -224,9 +231,29 @@ async function socketDirEntriesAreOwned(socketDir, uid, visited = { count: 0 })
     }
     return true;
 }
-export async function getAgentBrowserSocketDirValidationError(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+export async function getAgentBrowserSocketDirValidationError(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined, platform = processPlatform) {
     if (!isAbsolute(socketDir))
         return "the path is not absolute";
+    // Windows uses native ACLs and named pipes, not POSIX uid/mode metadata.
+    // Still require a real directory; never accept a file or a redirected root.
+    if (platform === "win32") {
+        try {
+            try {
+                await mkdir(socketDir);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            const metadata = await lstat(socketDir);
+            if (metadata.isSymbolicLink())
+                return "the directory is a symlink";
+            return metadata.isDirectory() ? undefined : "the path is not a directory";
+        }
+        catch (error) {
+            return `the directory could not be inspected (${error.code ?? "unknown error"})`;
+        }
+    }
     if (typeof uid !== "number")
         return "POSIX ownership metadata is unavailable";
     try {
@@ -378,6 +405,8 @@ export async function runAgentBrowserProcess(options) {
         }
         effectiveEnv = { ...effectiveEnv, [AGENT_BROWSER_SOCKET_DIR_ENV]: requestedSocketDir };
     }
+    const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
+    const stockLauncher = resolveWindowsStockLauncher(cwd, childEnv);
     if (signal?.aborted) {
         return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
     }
@@ -395,6 +424,7 @@ export async function runAgentBrowserProcess(options) {
         let stdoutSpillPending = false;
         let pendingStdoutWrite = Promise.resolve();
         let stdoutSpillError;
+        let pendingTermination;
         let killTimer;
         let timeoutTimer;
         let abortListener;
@@ -444,15 +474,16 @@ export async function runAgentBrowserProcess(options) {
             if (settled)
                 return;
             settled = true;
+            removeAbortListener();
+            if (killTimer) {
+                clearTimeout(killTimer);
+            }
+            if (timeoutTimer) {
+                clearTimeout(timeoutTimer);
+            }
+            completionWatcher?.clear();
             void pendingStdoutWrite.finally(async () => {
-                removeAbortListener();
-                if (killTimer) {
-                    clearTimeout(killTimer);
-                }
-                if (timeoutTimer) {
-                    clearTimeout(timeoutTimer);
-                }
-                completionWatcher?.clear();
+                await pendingTermination;
                 if (stdoutSpillHandle) {
                     await stdoutSpillHandle.close().catch(() => undefined);
                 }
@@ -478,14 +509,13 @@ export async function runAgentBrowserProcess(options) {
                 });
             });
         };
-        const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
         const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, options.browserIndependentReadConfirmation);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });
             return;
         }
-        const spawnBrowser = processPlatform === "win32" ? crossSpawn : spawn;
-        const child = spawnBrowser("agent-browser", prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession, chromeStartupArgsContext.getStore()), {
+        const spawnBrowser = processPlatform === "win32" && !stockLauncher ? crossSpawn : spawn;
+        const child = spawnBrowser(stockLauncher ?? "agent-browser", prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession, chromeStartupArgsContext.getStore()), {
             cwd,
             env: childEnv,
             stdio: ["pipe", "pipe", "pipe"],
@@ -505,10 +535,16 @@ export async function runAgentBrowserProcess(options) {
             else {
                 timedOut = true;
             }
-            terminateSpawnedChild(child, "SIGTERM");
-            killTimer = setTimeout(() => {
-                terminateSpawnedChild(child, "SIGKILL");
-            }, 2_000);
+            if (pendingTermination)
+                return;
+            pendingTermination = terminateSpawnedChild(child, "SIGTERM");
+            // Windows taskkill already forces the entire tree. A concurrent direct
+            // kill would remove its root before traversal finishes.
+            if (processPlatform !== "win32") {
+                killTimer = setTimeout(() => {
+                    pendingTermination = terminateSpawnedChild(child, "SIGKILL");
+                }, 2_000);
+            }
         };
         const recordStdinError = (error) => {
             const stdinError = error instanceof Error ? error : new Error(String(error));

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

@@ -251,7 +251,7 @@ function redactBearerCredentials(text) {
             return match;
         return formatRedactedCredential(label, credential, trailing);
     })
-        .replace(/\b(Bearer)\s+([^\s"',)\[\]]+)([),.]?)/gi, (match, label, credential, trailing) => {
+        .replace(/\b(Bearer)\s+([^\s\\"',)\[\]]+)([),.]?)/gi, (match, label, credential, trailing) => {
         // Without a credential field/header, require a bearer-token shape, not prose, HTML or a URL.
         const token = credential.slice(0, credential.length - credentialTrailingPunctuation(credential).length);
         if (!/^[A-Za-z0-9._~+/-]+=*$/.test(token) || !/[0-9._~+/=-]/.test(token))

package/dist/extensions/agent-browser/lib/windows-stock-launcher.js

@@ -0,0 +1,70 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { isMainThread } from "node:worker_threads";
+import pathKey from "path-key";
+import which from "which";
+/** Bypass only upstream's optimized npm CMD shim: cmd.exe loses literal CR/LF.
+ * Keep which/path-key aligned with cross-spawn's public dependency versions.
+ * Unknown/custom launchers (including other npm layouts) stay on cross-spawn.
+ */
+export function resolveWindowsStockLauncher(cwd, env) {
+    if (process.platform !== "win32" || !isMainThread)
+        return undefined;
+    // which reads parent PATHEXT; cmd.exe reads the child's. Node also handles
+    // duplicate case-insensitive environment keys differently from path-key.
+    // In those ambiguous cases, keep the original transport and its selection.
+    const values = (name) => Object.entries(env)
+        .filter(([key, value]) => key.toUpperCase() === name && value !== undefined).map(([, value]) => value);
+    const paths = values("PATH"), extensions = values("PATHEXT");
+    if (paths.length !== 1 || !paths[0] || extensions.length !== 1 || extensions[0] !== process.env.PATHEXT
+        || values("NODEFAULTCURRENTDIRECTORYINEXEPATH").length)
+        return undefined;
+    // A custom COMSPEC can implement different command selection/semantics.
+    // Compare filesystem identity, not short/long Windows path spellings.
+    try {
+        if (!process.env.comspec || !isAbsolute(process.env.comspec) || !process.env.SystemRoot)
+            return undefined;
+        const shell = statSync(process.env.comspec, { bigint: true });
+        const native = statSync(join(process.env.SystemRoot, "System32", "cmd.exe"), { bigint: true });
+        if (shell.dev !== native.dev || shell.ino !== native.ino)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const previousCwd = process.cwd();
+    let selected;
+    try {
+        // which 2 has no cwd option. Like cross-spawn, change cwd only during
+        // synchronous resolution, restoring it before any caller can await.
+        process.chdir(cwd);
+        selected = which.sync("agent-browser", { path: env[pathKey({ env })], nothrow: true });
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        process.chdir(previousCwd);
+    }
+    // cross-spawn's second (extensionless) lookup cannot select this CMD shim.
+    if (!selected || !selected.toLowerCase().endsWith(".cmd"))
+        return undefined;
+    try {
+        // which can return a relative PATH result; interpret it in the child cwd.
+        const absoluteShim = resolve(cwd, selected);
+        if (statSync(absoluteShim).size > 512)
+            return undefined;
+        const text = readFileSync(absoluteShim, "utf8");
+        if (!/^@ECHO off\r?\n"%~dp0node_modules\\agent-browser\\bin\\agent-browser-win32-x64\.exe" %\*(?:\r?\n)?(?![\s\S])/.test(text))
+            return undefined;
+        const packageRoot = join(dirname(absoluteShim), "node_modules", "agent-browser");
+        const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        if (manifest.name !== "agent-browser" || !["bin/agent-browser.js", "./bin/agent-browser.js"].includes(manifest.bin?.["agent-browser"]))
+            return undefined;
+        const binary = join(packageRoot, "bin", "agent-browser-win32-x64.exe");
+        return statSync(binary).isFile() ? binary : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/docs/ARCHITECTURE.md

@@ -36,7 +36,8 @@ Why:
 
 The extension should:
 - resolve `agent-browser` from `PATH`
-- invoke it with native Node `spawn` on POSIX and `cross-spawn` on Windows. The latter handles Windows `PATH`/`PATHEXT`, `.cmd` shims and argument escaping without PowerShell or wrapper-owned command reordering. Caller commands and helper probes retain empty operands, literal doublequotes, command/subcommand adjacency and explicit default `--namespace ""`; the selected shim still owns upstream architecture selection. Keep piped stdin/stdout/stderr and terminate the full Windows shell/agent-browser process tree with `taskkill /T /F` on timeout or abort before falling back to the direct child signal. Missing commands use the spawner's `ENOENT`, not a parsed shell-error string
+- invoke it with native Node `spawn` on POSIX and `cross-spawn` on Windows. For the recognized global npm CMD template, public `which`/`path-key` resolution selects the same launcher and Node invokes its exact adjacent native executable directly, preserving literal CR/LF. Recognition requires the stock template, package identity and executable; custom launchers, other layouts, ambiguous search environments and worker-thread calls retain `cross-spawn`. No later installation is substituted. Custom or unrecognized batch files can still truncate literal newlines. Caller commands and helper probes retain empty operands, literal doublequotes, command/subcommand adjacency and explicit default `--namespace ""`. Keep piped stdin/stdout/stderr and await full Windows process-tree termination with `taskkill /T /F` on timeout or abort before falling back to the direct child signal. Missing commands use the spawner's `ENOENT`
+- bound native process-identity queries at ten seconds on Windows, including PowerShell startup, and five seconds on POSIX. These probes preserve PID/start-time comparison and fail closed when identity is unavailable; their budget is separate from lock contention and browser command watchdogs
 - inject `--json`; caller-requested JSON also uses the existing `buildJsonVisibleContent` envelope for early snapshot/network filters, scroll results, and preparation failures, retaining metadata in `details` and keeping output-file notices out of visible JSON. Help/version stays native text
 - complete each upstream invocation when the direct `agent-browser` child exits even if Node delays `"close"`: piped stdio can stay referenced by longer-lived descendant processes, so `runAgentBrowserProcess` watches `exit` and `close` together, leaves stdio intact during a short post-`exit` grace so normal `close` can still win, destroys streams only when the post-`exit` fallback fires, and prefers `close` codes then wrapper timeout (`124`) over signal-shaped `exit` codes (`watchSpawnedChildCompletion` / `resolveSpawnedChildExitCode` in `extensions/agent-browser/lib/process.ts`) so the tool cannot hang after the CLI process has already terminated
 - support optional stdin only for `eval --stdin`, `batch`, `auth save --password-stdin`, and wrapper-generated `batch` stdin from top-level `job`, `qa`, `sourceLookup`, or `networkSourceLookup`, rejecting other command/stdin combinations before launch; top-level `electron` never accepts caller `stdin` (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#electron))
@@ -214,6 +215,16 @@ Practical policy:
 
 This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should own its lifecycle without breaking reload, resume, or branch-tree semantics. If the caller explicitly chose the upstream session model, the extension should stay out of the way.
 
+### Native checkpoint boundary
+
+The additive native `session_checkpoint` hook qualifies only the no-active-resource path. Pi already awaits tools, commands and lifecycle callbacks, including their returned execution queues. The hook checks the existing script controllers/completion promises, recording reservations and dirty retry state, cleanup leases, Electron records/children, attachments, trace owners and routes. It adds no work queue or state journal, and never invokes shutdown, stops recording, or closes a browser during capture.
+
+Known native identities come from existing ownership and all native tool-result entries, including off-branch caller-owned/root sessions and the unnamed native default (launch flags can open it even for an explicit URL read). Read-only `session info` must prove each daemon inactive; active, missing-binary and unknown results remain blockers. These probes reuse the existing owned-session context for runtime-owned identities and transcript-proven wrapper-created identities, including off-branch browsers after an abnormal restart, so an ambient `AGENT_BROWSER_SOCKET_DIR` cannot redirect their inspection. Historical routing uses the existing managed-resource events and namespace/session identity, not a name pattern alone, and does not acquire cleanup ownership. For owned or historically owned targets, inspection also checks native ambient routing: the same namespace/name can identify different daemons in different socket roots. A later transcript close does not suppress the historical route's read-only probe, since it may have closed only the ambient caller. Explicit caller choices (even the exact historical name with `sessionMode: "fresh"`), unrelated namespaces and root identities retain native ambient routing. An unused extension needs no browser executable or profile scan. Independent hosts/group members must still coordinate their own writers and resources; a Pi receipt is not a cross-process browser lock.
+
+Recording retries still republish existing reservation transitions and retain a blocker while that extension state is dirty. Native journal persistence is Pi-owned: after extension barriers, core flushes accepted entries before returning a checkpoint; ongoing I/O failures reject acquisition. Repair filesystem permissions and retry capture after ordinary browser close/cleanup. The extension does not scan, compare or repair Pi's journal. Native strict restore rejects a journal/artifact mismatch, and native materialization supports a not-yet-created journal.
+
+With no detached work left, native ingress provides the hold and release; there is no extension observer to suspend. Normal ownership-aware shutdown remains unchanged. Native close/save followed by explicit URL reopen can restore synthetic cookies/localStorage/sessionStorage with the same `pi-root-*` identity on fresh filesystem inodes. This does not qualify live DOM/JS, forms, history, IndexedDB, or the separate inode-scoped `piab-r2-*` managed restore key for cold filesystem relocation. See [native qualification](RELEASE.md#native-checkpoint-qualification).
+
 ### Launch flags
 
 `native-session-defaults.ts` reads launch-argument/engine fields through its existing native-validated config discovery. Local Chrome composes `--no-startup-window` with the highest-priority caller arguments. Root bootstrap retains its existing helper scope; owned/fresh preparation reuses daemon-policy inspection, while explicit local callers use the same session-info probe. `process.ts` applies the scoped arguments after managed restore-policy checks, composing the existing compatibility user agent without overriding caller Chrome arguments. Configured environment/file arguments remain consistent across helpers; ordinary active calls do not receive a new launch configuration. This adds no browser launcher, profile mutation, tab cleanup, binary distribution, or persistent launch-settings state. Older custom-argument browsers can undergo native's normal hash-change restart on first use of the new default.

package/docs/ELECTRON.md

@@ -184,7 +184,9 @@ Output appears under `details.electron.probe`: `title`, `url`, `focusedElement`,
 
 ### `electron.cleanup` — wrapper-owned only
 
-Closes the tracked managed session, stops only the wrapper-tracked process, verifies that the debug port no longer serves `/json/version`, and removes the wrapper-created `userDataDir`. Cleanup partial failures fail the tool result with `failureCategory: "cleanup-failed"` and the `retry-electron-cleanup` next action references the same `launchId` so retries are bounded.
+Closes the tracked managed session, stops only the wrapper-tracked process, verifies that the debug port no longer serves `/json/version`, and removes the wrapper-created `userDataDir`. Cleanup waits for actual exit when it has a tracked child handle. For a live restored PID without that handle, it first checks the native process command line for the recorded profile: `Win32_Process.CommandLine` through Windows PowerShell on Windows, or `ps` on POSIX. If inspection fails or the profile does not match, cleanup leaves the process and profile intact.
+
+Cleanup partial failures fail the tool result with `failureCategory: "cleanup-failed"` and the `retry-electron-cleanup` next action references the same `launchId` so retries are bounded.
 
 ```json
 { "electron": { "action": "cleanup", "launchId": "electron-…" } }
@@ -313,7 +315,7 @@ Policy mismatches fail with `failureCategory: "policy-blocked"` and `details.ele
 
 Failed startup diagnostics include `outputCaptured`, `stdoutTail` / `stderrTail`, and `stdoutTruncated` / `stderrTruncated`. Each tail reads at most the last **4096 source bytes** before UTF-8 decoding and normal credential redaction, and appears in both visible failure text and structured details. Empty output is reported explicitly; `stdoutError` / `stderrError` report capture-read or close errors without replacing the original startup reason, exit status, or cleanup warning.
 
-The app writes to mode-0600 `stdout.log` and `stderr.log` inside its isolated profile. These are regular files, not pipes to Pi, so retained apps can keep writing after reload or host exit. Logs follow profile preservation and removal; **the read limit is not a lifetime disk limit**. If failed-startup process cleanup cannot finish, the profile and logs are protected from general temp cleanup. Any failure to persist that protection appears alongside the original `failure.cleanupError`; in-memory protection remains. Use the reported PID and profile path to resolve that failed cleanup before removing files.
+The app writes to mode-0600 `stdout.log` and `stderr.log` inside its isolated profile. Regular-file capture lets a retained app keep writing independently of Pi's output streams. POSIX launches are detached and can outlive the host; Windows launches remain host-owned and stop when the host exits. Preserved logs survive either outcome. Logs follow profile preservation and removal; **the read limit is not a lifetime disk limit**. If failed-startup process cleanup cannot finish, the profile and logs are protected from general temp cleanup. Any failure to persist that protection appears alongside the original `failure.cleanupError`; in-memory protection remains. Use the reported PID and profile path to resolve that failed cleanup before removing files.
 
 Single-instance Electron behavior is a common cause of `timeout` and `upstream-error`. Many Electron apps enforce a single running instance and silently drop a second invocation's `--remote-debugging-port` flag. If the app is already running without a debug port, quit it first or use the manual host-launch path against the existing instance instead.
 

package/docs/RELEASE.md

@@ -17,6 +17,14 @@ Related docs:
 
 Provide one concrete maintainer workflow for validating repo state, package contents, and install guidance before publishing `pi-agent-browser-native`.
 
+## Current 0.6.16 rollout waiver
+
+The owner's 2026-09-21 **“waive windows”** instruction makes Windows qualification nonblocking for this rollout, even with available runners, and supersedes older mandatory-Windows/no-waiver wording below and in platform guidance. Preserve failed diagnostics; do not claim a Windows full-suite pass or continue Windows repair experiments. Known policy-lock/restored Electron failures and bounded repeat results are tracked in [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191) and the [current support matrix](SUPPORT_MATRIX.md#current-0616-rollout).
+
+Linux/macOS, declared Node floors, official/fork host and consumer-artifact checks, and Native checkpoint Linux remain required. All three final reviewers (reviewer-gpt, reviewer-ponytail, reviewer-claude) must approve before merge, release or activation. This waiver changes neither runtime nor the composed `release`/`prepublishOnly` scripts: record individually satisfied gates and the explicit Windows waiver, never label the full composition passed.
+
+Docs/workflow-only changes may reuse prior live/platform evidence when the complete compiled runtime, runtime dependencies and relevant tests are unchanged. Changed published files require a new retained tarball checked by `verify-package.mjs --smoke-pi`, including runtime-only SDK and actual CLI loading. Publish those exact checked bytes without repacking.
+
 ## Pre-release checks
 
 From the repository root:
@@ -47,7 +55,7 @@ npm run verify -- pre-pr
 3. `npm run verify -- package-pi`, which first validates package contents via `npm pack --json --dry-run` and then smoke-loads the packed package in Pi isolation
 4. `npm run smoke:platform:doctor` and the full Crabbox matrix from [`platform-smoke.md`](platform-smoke.md): macOS SSH, Ubuntu local-container, and native Windows Parallels targets running fast target-local `platform-build` plus `browser-dogfood-smoke`
 
-The 0.6.15 release uses the documented [local macOS and hosted native-Windows alternatives](platform-smoke.md#alternate-native-transports) instead of SSH and Parallels. Run and inspect those target-local suites separately alongside the remaining release checks. The default composed gate is unchanged; alternate evidence must not be labeled a passing Crabbox matrix.
+When using the documented, maintainer-approved [local macOS and hosted native-Windows alternatives](platform-smoke.md#alternate-native-transports), run and inspect those target-local suites separately alongside the remaining release checks. The default composed gate is unchanged; alternate evidence must not be labeled a passing Crabbox matrix.
 
 `npm publish` runs npm’s `prepublishOnly` script from `package.json`, which executes the same `npm run verify -- release` gate and then `npm pack --dry-run`. That concatenated gate is everything in the default `npm run verify` step (generated playbook drift, clean `dist/` build, TypeScript, the unit/fake suite, generated command-reference blocks, and live upstream command-reference sampling against the targeted `agent-browser` on `PATH`), the configured-source lifecycle harness, the packaged Pi smoke in `package-pi`, and the release-blocking Crabbox platform matrix. Using `npm publish --ignore-scripts` skips that contract intentionally.
 
@@ -282,6 +290,32 @@ This suite requires the installed stable `agent-browser --version` to meet the m
 
 The default unit suite also runs `agentBrowserExtension passes through core command coverage fallback matrix` in [`test/agent-browser.extension-passthrough-validation.test.ts`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/test/agent-browser.extension-passthrough-validation.test.ts): a fake upstream records argv so explicit `--session connector connect 9222`, plus `download` with a selector and path, `get url`, `snapshot --compact`, and `tab new` / `tab t1` / `tab close` on implicit managed sessions, still prove `--json` and session ordering without a browser. A second fake-upstream matrix in that file (`agentBrowserExtension passes through non-core network debug diff stream dashboard and chat families`) pins representative `network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, and `chat` JSON shapes plus redacted `details.data` and argv echoes without a browser. A third matrix (`agentBrowserExtension passes through provider and specialized skill workflows`) asserts provider `open` argv shapes still receive `--json` plus implicit `--session` while read-only `skills get …` stays stateless (no managed session fields) and provider credential env vars are forwarded into the fake upstream log. Extend those matrices when adding passthrough coverage that should stay out of the slow real-upstream loop.
 
+### Native checkpoint qualification
+
+`test/agent-browser.checkpoint-native.test.mjs` is an opt-in, model-free test for a Pi SDK exposing `acquireCheckpoint` with native failed-journal repair/flush (qualified against core `c401cada69172dfd683e6d569b2cd9e5a45b4fcd`). It loads the compiled extension through native resource discovery, dispatches real tools through an awaited native command, and records real results with SessionManager. It checks idle/release/reload, live root and managed browsers (including a stable ambient socket override without a Pi override), off-branch state, detached and native-owned scripts, recording, failed journal appends/cleanup leases, routes, trace, caller-owned CDP attachment, and native checkpoint selection/entries plus root restore after replacing checkout/state directories with fresh inodes. No provider or fake readiness classifier is used.
+
+Run as a non-root user in an isolated environment with stock `agent-browser`, Chrome for Testing and ffmpeg. Clear inherited credentials/configuration; do not use a personal browser. The test creates its own HOME/socket directory, copies only the supplied browser binary directory, serves a loopback synthetic page, explicitly closes its sessions, and removes its fixtures. `PI_CHECKPOINT_TEST_BROWSER_DIR` must name a binary installation directory such as `.../.agent-browser/browsers/chrome-<version>`, never a browser profile.
+
+```bash
+npm run build
+PI_CHECKPOINT_TEST_REQUIRED=1 \
+PI_CHECKPOINT_TEST_SDK=/path/to/native/pi-coding-agent/dist/index.js \
+PI_CHECKPOINT_TEST_BROWSER_DIR=/path/to/browsers/chrome-<version> \
+node --test test/agent-browser.checkpoint-native.test.mjs
+```
+
+`PI_CHECKPOINT_TEST_EXTENSION` can select a separate baseline checkout. With `PI_CHECKPOINT_TEST_BASELINE_RESTORE=1`, only its existing root-restore path runs and every receipt must retain the old shutdown blocker; this is not positive sleep qualification. The SDK selector is test-only; it does not change package peers or activate an extension. This gate is separate from the default 0.84 unit fixtures and release/platform/model-based gates. Qualification is for ordinary native save-on-close and explicit URL reopen, not a live browser snapshot. Journal fault injection checks that ongoing native I/O errors reject acquisition and preserve prior bytes/accepted entries. Permission repair must recover through core capture without repeating the failed append; recording retry and cleanup leases remain extension-owned. The test also checks exact repaired entries/selection in a separate-process strict cold restore and rejection of a mismatched artifact. After explicit close it observes native daemon exit before asserting idle readiness; an acknowledgement alone is not proof of inactivity. The abnormal-restart regression kills only its exact SDK fixture PID after ordinary branch navigation, then reopens the real journal in a fresh SDK process. It verifies that the off-branch wrapper-created daemon blocks capture without acquiring cleanup ownership, and that explicit managed-looking names and a nonowned namespace retain ambient routing. Same-namespace/same-name controls check distinct live daemons in owned and ambient socket roots, continued blocking after closing only the caller, ambient-only blocking after closing the historical daemon, and positive readiness after both are explicitly closed. All browser ownership evidence comes from executed native tools, never injected ownership records.
+
+#### Required Linux PR gate
+
+[`.github/workflows/native-checkpoint.yml`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/.github/workflows/native-checkpoint.yml) runs **Native checkpoint Linux** on every PR to `main`, pushes to `main`, and manual dispatch. Require this check in branch protection before merging checkpoint changes (repository settings are separate from the workflow). It does not replace release/manual-publication gates or full Linux personal-workspace sleep/resume qualification.
+
+The CI-only recipe in [`scripts/ci-native-checkpoint.sh`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/ci-native-checkpoint.sh) builds the public fork target selected by `host-targets.json` in the workflow's pinned `fitchmultz/.github` automation revision, using the fork's lockfile and documented `npm ci --ignore-scripts`, `hydrate:model-data`, `build:offline` sequence. It uses explicit Node **26.9.0**, the extension's unchanged lockfile, stock **agent-browser 0.38.1**, a fresh stock Chrome-for-Testing download, and Ubuntu ffmpeg. No browser fork, personal profile, credentials, or model calls are involved.
+
+Sources live under a private `/tmp` root, outside HOME ancestry. Setup and tests use `env -i`; verification runs non-root in a loopback-only network namespace after downloads finish. Shared compatibility checks select independent official/fork graphs for types, tests and consumer installation. This workflow additionally runs the locked official graph on Node 26 before network isolation, then generated-document checks and live command-reference sampling inside the loopback namespace. The separate native gate requires **13 passed, zero failed/cancelled/skipped/todo** in its TAP output. `PI_CHECKPOINT_TEST_REQUIRED=1` turns a missing SDK into a failure and rejects root/baseline-only runs; missing browser parameters, binaries, or checkpoint APIs fail normally. Without the flag or SDK, direct local invocation remains opt-in and skips.
+
+CI uploads raw setup/build/provenance logs, Node 26 and document verification output, and native TAP (including receipts), even on failure. Chrome is downloaded through the pinned stock installer, not separately version-pinned; the actual browser version is logged. These checks prove synthetic native behavior on that runner and sourcehost, not real-site authentication, Electron-app behavior, managed-key cold portability, or complete personal qualification. Passing this gate does not replace code review or full personal-workspace acceptance.
+
 ### Native Linux socket-root regression
 
 `test/agent-browser.socket-namespace.test.ts` is opt-in (`PI_AGENT_BROWSER_SOCKET_NAMESPACE=1`). Run it with the installed `tsx` test runner inside a disposable bubblewrap user/mount namespace: a read-only mode-`0755` `/` whose owner is unmapped, and a current-user-owned mode-`0700` tmpfs at `/tmp`. Use a cleared environment with only the required executable PATH, private HOME and the opt-in variable. The test verifies those identities, exchanges data over a real Unix socket, dispatches native `agent-browser --version` through the shared subprocess wrapper, and inspects a disposable managed session with automatic restore enabled. It does not launch a browser or call a model.

package/docs/SUPPORT_MATRIX.md

@@ -77,7 +77,7 @@ Browser evidence (RQ-0152) is covered by `test/agent-browser.browser-evidence.te
 
 Contributor fixes #133/#152 remove unused prompt suffix entries without changing runtime guidance and diagnose bare `--no-sandbox` only in the command slot or navigation option positions. Native `--args` values and literal operands remain intact; batch checks use raw effective rows without treating row-local `--args` as a launch setting. `test/agent-browser.chromium-args.test.ts` covers pre-dispatch rejection, literal/flag-value controls, inspection, raw/stdin batch precedence and dispatcher outcomes. Existing prompt/grammar checks remain; source checks do not replace native-product gates.
 
-Electron diagnostics (RQ-0096, #128) keep list timeout rejection truthful, label explicit-ID cleaned records as historical without changing active selection or actions, and measure the tracked profile path with native `lstat` (`present` / ENOENT-only `absent` / `unknown`). Existing Electron discovery/lifecycle tests cover current liveness independently of cleanup history, native path errors and dangling symlinks, transcript replay, and unchanged cleanup ownership. Failed-startup diagnostics include redacted last-4096-byte stdout/stderr tails in visible text and structured details, using private profile-local regular files. Regression tests cover exact tails, empty output, capture/spawn errors and closed native file handles; a real spawned fixture with injected kill denial proves profile/log preservation through temp cleanup and host exit, including persistence failure reporting. The shared daemon policy verifies a restored Electron attachment's live browser endpoint and named upstream `get cdp-url` before ordinary calls, status, or probe reuse; `test/agent-browser.extension-ref-guards.test.ts` covers successful reuse and repeated rejection of replaced app, connection, and namespace identities without weakening generic restore-disabled rules. These checks do not replace native-app, Pi lifecycle, package, or live-site gates.
+Electron diagnostics (RQ-0096, #128) keep list timeout rejection truthful, label explicit-ID cleaned records as historical without changing active selection or actions, and measure the tracked profile path with native `lstat` (`present` / ENOENT-only `absent` / `unknown`). Existing Electron discovery/lifecycle tests cover current liveness independently of cleanup history, native path errors and dangling symlinks, transcript replay, and unchanged cleanup ownership. Failed-startup diagnostics include redacted last-4096-byte stdout/stderr tails in visible text and structured details, using private profile-local regular files. Regression tests cover exact tails, empty output, capture/spawn errors and closed native file handles; a real spawned fixture with injected kill denial proves live output through temp cleanup, retained logs through native host-exit behavior, and persistence failure reporting. Tracked-child cleanup regressions require actual exit before profile removal and immediate executable deletion. Restored-PID cleanup uses native process command-line evidence on Windows and POSIX; real-process regressions verify matching profiles with spaces/Unicode, refusal of unrelated or mismatched profiles, and shutdown after transcript restoration. The shared daemon policy verifies a restored Electron attachment's live browser endpoint and named upstream `get cdp-url` before ordinary calls, status, or probe reuse; `test/agent-browser.extension-ref-guards.test.ts` covers successful reuse and repeated rejection of replaced app, connection, and namespace identities without weakening generic restore-disabled rules. These checks do not replace native-app, Pi lifecycle, package, or live-site gates.
 
 Artifact diagnostics (#124/#127) use a shared pre-dispatch mkdir-error boundary, preserve raw batch argv/precedence, recommend absolute raw artifact paths, recognize image headers rather than filename MIME guesses, retain known requested/reported paths, and warn once about conservative ref invalidation after dispatched recording starts and URL-bearing restarts, on success or failure, without claiming an observed page change. `test/agent-browser.artifact-diagnostics.test.ts` covers registered filesystem failures, real image bytes and misleading suffixes, the inline bound, native macOS path aliases, recording/ref continuity and unreached-row negatives; `test/agent-browser.presentation-artifacts-batch.test.ts` retains artifact/persistence coverage. These source regressions do not qualify daemon-cwd differences or affected-filesystem timestamp behavior (#118), or replace native/Pi/package/live-site gates.
 
@@ -97,6 +97,16 @@ Shared native defaults are covered by `test/agent-browser.shared-defaults.test.t
 
 Browser correctness regressions cover credential-bearing filtered network details/exports, native generated-Blob downloads with actual saved bytes, accessible-name click target identity and abstention, smooth CSS-container movement, and parseable early-result JSON. Native fixture coverage complements deterministic dispatch/cleanup and output-shape checks; release qualification remains separate.
 
+## Current 0.6.16 rollout
+
+On 2026-09-21 the owner explicitly instructed **“waive windows”** for this rollout, superseding older required-Windows/no-waiver guidance even where runners are available. Windows diagnostics remain visible but nonblocking; do not interpret a successful compatibility aggregate as a Windows pass. Follow-up: [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191).
+
+At runtime source `3a9adf490883149e7f79ee070d1900877e17b891`, PR compatibility passed seven of eight lanes, including official Windows with its full consumer contract; fork Windows failed one restored Electron cleanup case. The private combined Windows run had two policy-lock failures (1,162 passed, 37 skipped, zero cancelled out of 1,201). One unchanged Electron repeat passed without a product patch; the original cause is unknown. Historical focused Windows passes below retain only their stated scope, not full Windows qualification.
+
+Fresh precommit evidence for that runtime passed real Pi checkout/live-site and supported disposable Electron smoke, configured-source lifecycle, packaged runtime-only SDK/CLI loading, real-upstream checks, native macOS and the canonical named Ubuntu target (Debian 12). Local macOS is the documented alternate, not an SSH pass. Docs/workflow-only delivery may reuse this runtime evidence only after all 104 rebuilt runtime files match the checked artifact; changed published docs require a newly checked retained tarball. No additional paid/live gate is implied by an otherwise byte-identical runtime.
+
+Linux/macOS, declared Node floors, official/fork host identities, required consumer artifacts and Native checkpoint Linux remain required. Required current-head CI and all three final reviewer approvals precede merge/release/activation. The unchanged composed `release`/`prepublishOnly` command still includes Windows and is not reported as passed under this waiver; see [release guidance](RELEASE.md#current-0616-rollout-waiver).
+
 ## Verification evidence
 
 **0.38.1 PR evidence (2026-09-17, local macOS):** the full unit/fake suite passed 1,146 tests with 27 opt-in skips; the final review fixes then passed typecheck and 64 affected tests. Generated docs, live command-reference sampling, and the 132-file packaged Pi smoke passed. The real-upstream contract and 75 native batch/fidelity checks passed, as did all eight deterministic dogfood flows. Interactive compiled-checkout Pi smoke covered example.com and react.dev, delta/ref follow-ups, conditional screenshots, and a recording batch whose persisted result had two verified artifacts and no pending artifacts. Separate native probes confirmed helper-consumed WebMCP catalog updates remain visible. These checks do not qualify release-only platform/lifecycle gates; the hosted native-Windows result is recorded on the PR.
@@ -107,7 +117,7 @@ Re-run the gates below before each release. Dated outcomes in this table are his
 | --- | --- | --- |
 | Default local gate | `npm run verify` checks generated playbook drift, clean-builds generated `dist/`, runs `tsc --noEmit`, unit/fake tests, generated command-reference blocks, and live command-reference sampling. | **Earlier 0.36.0:** pass on 2026-09-01; 779 tests passed, two opt-in real-upstream tests skipped, and build/typecheck/docs/live command-reference gates passed. |
 | Pre-PR local gate | `npm run verify -- pre-pr` composes the default gate with package-content verification. Use before larger local handoffs or PR-ready claims when lifecycle/platform/live dogfood cost is not warranted. | **Earlier 0.36.0 / package 0.6.2:** pass on 2026-09-01; 779 tests passed, two opt-in tests skipped, and the 127-file tarball verified. |
-| Windows argument transport (#102/#131/#141) | `node --import tsx --test test/agent-browser.windows-argv.test.ts` exercises the actual host subprocess with independent expected argv, empty fill/launch/namespace values, literal quotes, Unicode/spaces, stdin, child-`PATH` custom shims and missing-command/nonzero-exit truth. It also runs in the default and `platform-target` gates. Windows uses `cross-spawn`; POSIX keeps native Node `spawn`. | The old PowerShell Legacy path dropped empty operands and split ordinary doublequoted fill text; the quoted-empty-only proposal fixed the former but left the latter broken. Native macOS and Ubuntu validate the unchanged POSIX subprocess path. Native Windows/`cmd.exe` and affected-host managed open → snapshot → close retests remain unrun under the task-specific waiver; neither Linux PowerShell diagnostics nor dependency tests are reported as native Windows proof. |
+| Windows argument transport (#102/#131/#141) | `test/agent-browser.windows-argv.test.ts` exercises actual host argv, empty values, quotes, Unicode/spaces, stdin, custom shims and failure outcomes. `test/agent-browser.windows-stock-launcher.test.ts` covers the recognized global npm CMD template's direct-native path, command selection, fallback, literal LF/CRLF and cancellation. Custom or unrecognized batch launchers retain their existing newline limitation. POSIX keeps Node `spawn`. | Native Windows focused qualification on 2026-09-21 passed all seven stock-launcher controls, all 29 Chromium cases and 33 process/argv cases (two existing platform skips). Actual upstream Rust received all 12 expected operands; the original CMD path lost all four newline-bearing operands. These focused results do not replace full-suite, managed-browser, package or release gates. |
 | Real upstream contract | `npm run verify -- real-upstream` runs the localhost fixture matrix against a real stable `agent-browser` at or above the configured floor. | **Earlier recommended 0.36.0:** pass on 2026-09-01 (2/2 tests), including WebMCP and `--no-webmcp`; the 0.35.0 floor last passed on 2026-08-26 (2/2 tests). |
 | Packaged Pi smoke | `npm run verify -- package-pi` validates package contents, installs the extracted tarball's runtime dependencies without lifecycle scripts or host peers, loads the packaged `agent_browser` tool without requiring optional Brave config, and executes fake-upstream `--version`. | **Earlier package 0.6.2 / Pi 0.84.4:** pass on 2026-09-01; the 127-file tarball loaded exactly one packaged `agent_browser` and executed `--version`. |
 | Startup profile | `npm run verify -- startup-profile --samples <n>` clean-builds generated `dist/`, records direct package entrypoint import/factory timing in fresh Node processes, and writes `.artifacts/startup-profile/latest.json`. It must not launch Pi, tmux, mise, npm, browsers, or `agent-browser`; full Pi TUI ready-prompt profiling is intentionally excluded after it proved too invasive for routine verification. Run this opt-in evidence when package layout, the compiled entrypoint, top-level imports, schema registration, or prompt/config startup logic changes. | **Earlier compiled 0.6.2 entrypoint:** pass on 2026-09-01 with three samples; median 104.9 ms and max 114.5 ms, below the 250 ms budget. |

package/docs/TOOL_CONTRACT.md

@@ -820,6 +820,8 @@ For `script`, the top-level category describes the whole orchestration and clean
 
 These categories are intentionally bounded and stable so agents can branch on them instead of parsing prose. They do not replace raw diagnostics: `details.error`, `details.stderr`, `details.parseError`, `details.validationError`, and visible content still preserve the specific upstream or wrapper message after normal redaction.
 
+`details.exitCode` preserves the native child close code when available, so it is not a portable timeout indicator: a Windows process stopped with `taskkill` can report `1`. The wrapper uses `124` for its timeout when no native close code is available. Use `failureCategory`, `timedOut`, and `aborted` to distinguish these outcomes.
+
 For argv-supplied `--allowed-domains`, the wrapper treats domain containment as launch-scoped. Upstream owns request, worker, popup, and WebRTC containment plus incompatible-mode rejection; the wrapper passes the setting and upstream result through unchanged.
 
 Real Pi custom tools only mark a tool result failed when the tool throws during `execute`; returned `isError` fields are not authoritative. The extension therefore also registers a `tool_result` handler that treats any `agent_browser` result with `details.resultCategory: "failure"` as a real Pi tool error. For normal prose output, it appends `Result category: failure; failureCategory: …; Pi tool isError: true.` to model-visible text. For caller-requested `--json` output, it only patches `isError` and preserves visible parseable JSON content unchanged. The TUI renderer also repeats that category line at the top of failed rendered results so collapsed failed rows keep the outcome visible. The hook treats `--json` as requested when echoed `details.args` or the original tool `input.args` includes that flag; it skips appending the prose notice when any non-empty text content item is parseable JSON, even if other text items are not parseable. Invalid or non-JSON text still gets the visible prose notice. Implementation: `buildAgentBrowserToolResultPatch` in `extensions/agent-browser/lib/pi-tool-rendering.ts`; `extensions/agent-browser/index.ts` registers the handler. This keeps Pi transcript semantics aligned with the machine-readable result contract, including wrapper-side reclassifications such as `qa-failure` after an upstream-successful batch and `artifact-missing` after an upstream-successful artifact command whose requested file is absent.

package/docs/platform-smoke.md

@@ -2,7 +2,9 @@
 
 `pi-agent-browser-native` uses a Crabbox-backed local platform smoke gate to prove the package on macOS, Ubuntu Linux, and native Windows before release.
 
-This is a release-blocking gate. Missing setup is not a skipped pass. When a maintainer approves an [alternate native transport](#alternate-native-transports), it must prove the same target-local suites; missing upstream `agent-browser` or browser dependencies still blocks that target.
+**Current 0.6.16 rollout exception:** the owner explicitly waived Windows qualification on 2026-09-21, including available runners. Windows failures remain visible but nonblocking, not passed; no further Windows repair experiments are part of this rollout. Linux/macOS and all other required checks remain required. See [release waiver and artifact requirements](RELEASE.md#current-0616-rollout-waiver) and [follow-up #191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191). The commands below are unchanged and a waived Windows result does not make the full composition a passing matrix.
+
+Outside that rollout exception, this is a release-blocking gate. Missing setup is not a skipped pass. When a maintainer approves an [alternate native transport](#alternate-native-transports), it must prove the same target-local suites; missing upstream `agent-browser` or browser dependencies still blocks that target.
 
 ## Required release gate
 
@@ -34,11 +36,11 @@ npm run verify -- platform-smoke run --target ubuntu --suite platform-build
 | --- | --- | --- | --- |
 | `macos` | `ssh` static localhost | POSIX shell on macOS | Required |
 | `ubuntu` | `local-container` | POSIX shell in a Docker-compatible local container | Required |
-| `windows-native` | `parallels` | native Windows PowerShell over OpenSSH | Required |
+| `windows-native` | `parallels` | native Windows PowerShell over OpenSSH | Nonblocking for the owner-waived 0.6.16 rollout; otherwise required |
 
 ## Alternate native transports
 
-For the 0.6.15 release, local macOS execution replaces localhost SSH, and the [Native Windows workflow](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/.github/workflows/windows-native.yml) runs the existing Windows suites on a GitHub-hosted Windows runner. These are native platform checks, not Crabbox SSH or Parallels passes. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
+With maintainer approval, local macOS execution can replace localhost SSH, and the [Native Windows workflow](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/.github/workflows/windows-native.yml) runs the existing Windows suites on a GitHub-hosted Windows runner. Record these as native platform checks, separately from Crabbox SSH or Parallels results. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
 
 On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', 24)` and `buildBrowserDogfoodCommand('macos', '0.38.1', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles. No Remote Login or host security change is required.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.6.15",
+  "version": "0.6.16",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -65,11 +65,12 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.0",
-    "@earendil-works/pi-coding-agent": "0.84.0",
-    "@earendil-works/pi-tui": "0.84.0",
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "^25.9.3",
+    "@types/which": "2.0.2",
     "tsx": "^4.21.0",
     "typebox": "^1.1.38",
     "typescript": "^6.0.3"
@@ -90,8 +91,9 @@
     "smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
     "smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",
     "smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native",
+    "check:compat": "node scripts/compat-host.mjs && npm run typecheck && npm test && node scripts/verify-package.mjs --smoke-pi",
     "typecheck": "node ./scripts/project.mjs verify typecheck",
-    "test": "node ./scripts/build.mjs && tsx --test --test-concurrency=1 test/**/*.test.ts",
+    "test": "node ./scripts/build.mjs && tsx --test --test-reporter=tap --test-concurrency=1 test/**/*.test.ts",
     "verify": "node ./scripts/project.mjs verify",
     "prepublishOnly": "npm run verify -- release && npm pack --dry-run",
     "build": "node ./scripts/build.mjs",
@@ -114,6 +116,8 @@
     }
   },
   "dependencies": {
-    "cross-spawn": "7.0.6"
+    "cross-spawn": "7.0.6",
+    "path-key": "3.1.1",
+    "which": "2.0.2"
   }
 }

package/scripts/config.mjs

@@ -363,7 +363,7 @@ export async function main(argv = process.argv.slice(2)) {
 	throw new UsageError(`Unknown command: ${command}`);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.main) {
 	main().catch((error) => {
 		if (error instanceof UsageError) {
 			console.error(error.message);

package/scripts/doctor.mjs

@@ -11,7 +11,7 @@ import { execFile as execFileCallback } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
@@ -155,7 +155,7 @@ function expandUserPath(path) {
 }
 
 function isPathLikeSource(source) {
-	return source.startsWith("/") || source.startsWith("./") || source.startsWith("../") || source.startsWith("~");
+	return isAbsolute(source) || source.startsWith("./") || source.startsWith("../") || source.startsWith("~");
 }
 
 function sourceLooksLikeThisPackage(source, cwd, sourceBaseDir = cwd) {