pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/webmcp-observation.js

@@ -4,22 +4,29 @@ const observation = new AsyncLocalStorage();
 export function getNativeWebMcpCatalog(data) {
     if (Array.isArray(data)) {
         for (let index = data.length - 1; index >= 0; index -= 1) {
-            const catalog = getNativeWebMcpCatalog(isRecord(data[index]) ? data[index].result : undefined);
-            if (catalog)
+            const row = data[index];
+            const catalog = getNativeWebMcpCatalog(isRecord(row) ? row.result : undefined);
+            if (catalog) {
                 return catalog;
+            }
         }
     }
-    if (!isRecord(data) || !isRecord(data.webmcp))
+    if (!isRecord(data) || !isRecord(data.webmcp)) {
         return undefined;
-    return Array.isArray(data.webmcp.tools) || data.webmcp.status === "unavailable" ? data.webmcp : undefined;
+    }
+    return Array.isArray(data.webmcp.tools) || data.webmcp.status === "unavailable"
+        ? data.webmcp
+        : undefined;
 }
 export function observeNativeWebMcp(data) {
     const current = observation.getStore();
-    if (!current)
+    if (!current) {
         return;
+    }
     const catalog = getNativeWebMcpCatalog(data);
-    if (catalog)
+    if (catalog) {
         current.catalog = catalog;
+    }
 }
 /** Native discovery is edge-triggered; helper reads must not swallow its updates. */
 export async function collectNativeWebMcp(run) {

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

@@ -3,42 +3,46 @@ 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.
+import { isRecord } from "./parsing.js";
+function environmentValues(env, name) {
+    return Object.entries(env)
+        .filter(([key, value]) => key.toUpperCase() === name && value !== undefined)
+        .map(([, value]) => value);
+}
+function hasStockEnvironment(env) {
+    const paths = environmentValues(env, "PATH");
+    const extensions = environmentValues(env, "PATHEXT");
+    return (paths.length === 1 &&
+        paths.at(0) !== undefined &&
+        paths.at(0) !== "" &&
+        extensions.length === 1 &&
+        extensions.at(0) === process.env.PATHEXT &&
+        environmentValues(env, "NODEFAULTCURRENTDIRECTORYINEXEPATH").length === 0);
+}
+function hasNativeCommandShell() {
+    const { comspec, SystemRoot } = process.env;
+    if (comspec === undefined ||
+        comspec.length === 0 ||
+        !isAbsolute(comspec) ||
+        SystemRoot === undefined ||
+        SystemRoot.length === 0) {
+        return false;
+    }
     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;
+        const shell = statSync(comspec, { bigint: true });
+        const native = statSync(join(SystemRoot, "System32", "cmd.exe"), { bigint: true });
+        return shell.dev === native.dev && shell.ino === native.ino;
     }
     catch {
-        return undefined;
+        return false;
     }
+}
+function selectLauncher(cwd, env) {
     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.
+        // which 2 has no cwd option; synchronous resolution matches cross-spawn's child cwd.
         process.chdir(cwd);
-        selected = which.sync("agent-browser", { path: env[pathKey({ env })], nothrow: true });
+        return which.sync("agent-browser", { path: env[pathKey({ env })], nothrow: true });
     }
     catch {
         return undefined;
@@ -46,21 +50,25 @@ export function resolveWindowsStockLauncher(cwd, env) {
     finally {
         process.chdir(previousCwd);
     }
-    // cross-spawn's second (extensionless) lookup cannot select this CMD shim.
-    if (!selected || !selected.toLowerCase().endsWith(".cmd"))
-        return undefined;
+}
+function stockLauncherBinary(absoluteShim) {
     try {
-        // which can return a relative PATH result; interpret it in the child cwd.
-        const absoluteShim = resolve(cwd, selected);
-        if (statSync(absoluteShim).size > 512)
+        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))
+        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"]))
+        if (!isRecord(manifest) || manifest.name !== "agent-browser" || !isRecord(manifest.bin)) {
+            return undefined;
+        }
+        const entrypoint = manifest.bin["agent-browser"];
+        if (entrypoint !== "bin/agent-browser.js" && entrypoint !== "./bin/agent-browser.js") {
             return undefined;
+        }
         const binary = join(packageRoot, "bin", "agent-browser-win32-x64.exe");
         return statSync(binary).isFile() ? binary : undefined;
     }
@@ -68,3 +76,21 @@ export function resolveWindowsStockLauncher(cwd, env) {
         return undefined;
     }
 }
+/** 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 stay on cross-spawn.
+ */
+export function resolveWindowsStockLauncher(cwd, env) {
+    if (process.platform !== "win32" ||
+        !isMainThread ||
+        !hasStockEnvironment(env) ||
+        !hasNativeCommandShell()) {
+        return undefined;
+    }
+    const selected = selectLauncher(cwd, env);
+    // cross-spawn's extensionless lookup cannot select this CMD shim.
+    if (selected === undefined || selected === null || !selected.toLowerCase().endsWith(".cmd")) {
+        return undefined;
+    }
+    return stockLauncherBinary(resolve(cwd, selected));
+}

package/dist/extensions/agent-browser/script-worker.js

@@ -2,8 +2,9 @@ import { randomBytes } from "node:crypto";
 import { createContext, runInContext, Script } from "node:vm";
 function parseLimit(value, label) {
     const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
         throw new Error(`Invalid ${label}.`);
+    }
     return parsed;
 }
 const maxMessageBytes = parseLimit(process.argv[2], "script IPC message limit");
@@ -11,7 +12,8 @@ const maxCumulativeBytes = parseLimit(process.argv[3], "script IPC cumulative li
 let cumulativeBytes = 0;
 let inputBuffer = Buffer.alloc(0);
 let started = false;
-const sandbox = Object.create(null);
+const sandbox = {};
+Object.setPrototypeOf(sandbox, null);
 const context = createContext(sandbox, {
     codeGeneration: { strings: false, wasm: false },
     name: "agent-browser-script",
@@ -19,11 +21,13 @@ const context = createContext(sandbox, {
 const bridgeKey = `__piab_send_${randomBytes(16).toString("hex")}`;
 const stateName = `__piab_state_${randomBytes(16).toString("hex")}`;
 const hostSend = (json) => {
-    if (typeof json !== "string")
+    if (typeof json !== "string") {
         return false;
+    }
     const bytes = Buffer.byteLength(json, "utf8") + 1;
-    if (bytes > maxMessageBytes || cumulativeBytes + bytes > maxCumulativeBytes)
+    if (bytes > maxMessageBytes || cumulativeBytes + bytes > maxCumulativeBytes) {
         return false;
+    }
     cumulativeBytes += bytes;
     try {
         process.stdout.write(`${json}\n`);
@@ -36,10 +40,16 @@ const hostSend = (json) => {
 Object.setPrototypeOf(hostSend, null);
 Object.freeze(hostSend);
 sandbox[bridgeKey] = hostSend;
-runInContext("const " + stateName + " = (() => {\n" +
+runInContext("const " +
+    stateName +
+    " = (() => {\n" +
     "  'use strict';\n" +
-    "  const send = globalThis[" + JSON.stringify(bridgeKey) + "];\n" +
-    "  delete globalThis[" + JSON.stringify(bridgeKey) + "];\n" +
+    "  const send = globalThis[" +
+    JSON.stringify(bridgeKey) +
+    "];\n" +
+    "  delete globalThis[" +
+    JSON.stringify(bridgeKey) +
+    "];\n" +
     "  for (const name of ['console','process','require','Buffer','fetch','WebSocket','setTimeout','setInterval','setImmediate','queueMicrotask','clearTimeout','clearInterval','clearImmediate']) Object.defineProperty(globalThis, name, { value: undefined, writable: false, configurable: false });\n" +
     "  const NativePromise = Promise;\n" +
     "  const promiseThen = Promise.prototype.then;\n" +
@@ -47,7 +57,9 @@ runInContext("const " + stateName + " = (() => {\n" +
     "  const pending = new Map();\n" +
     "  let nextId = 0;\n" +
     "  const encode = (value) => { const json = JSON.stringify(value); if (typeof json !== 'string') throw new TypeError('Value must be JSON-serializable.'); return json; };\n" +
-    "  const sendValue = (value) => { const json = encode(value); if (json.length + 1 > " + maxMessageBytes + " || send(json) !== true) throw new RangeError('Script IPC limit exceeded.'); };\n" +
+    "  const sendValue = (value) => { const json = encode(value); if (json.length + 1 > " +
+    String(maxMessageBytes) +
+    " || send(json) !== true) throw new RangeError('Script IPC limit exceeded.'); };\n" +
     "  const browser = function browser(params) {\n" +
     "    return new NativePromise((resolve, reject) => {\n" +
     "      const id = ++nextId;\n" +
@@ -91,18 +103,67 @@ runInContext("const " + stateName + " = (() => {\n" +
     "  });\n" +
     "})();", context, { timeout: 1_000 });
 const deliver = runInContext(`${stateName}.deliver`, context, { timeout: 1_000 });
+if (typeof deliver !== "function") {
+    throw new Error("Script response bridge was not initialized.");
+}
 function fail(name, message) {
     hostSend(JSON.stringify({ type: "complete", error: { name, message } }));
 }
 function describeError(error, fallback) {
-    if (!error || typeof error !== "object")
+    if (error === null || typeof error !== "object") {
         return { message: fallback, name: "Error" };
-    const candidate = error;
+    }
+    const message = "message" in error ? error.message : undefined;
+    const name = "name" in error ? error.name : undefined;
     return {
-        message: typeof candidate.message === "string" ? candidate.message.replace(/[\r\n]+/g, " ").slice(0, 400) : fallback,
-        name: typeof candidate.name === "string" ? candidate.name.slice(0, 80) : "Error",
+        message: typeof message === "string" ? message.replace(/[\r\n]+/g, " ").slice(0, 400) : fallback,
+        name: typeof name === "string" ? name.slice(0, 80) : "Error",
     };
 }
+function startScript(message) {
+    if (message === null ||
+        typeof message !== "object" ||
+        !("type" in message) ||
+        message.type !== "start" ||
+        !("code" in message) ||
+        typeof message.code !== "string") {
+        fail("Error", "Invalid script start message.");
+        return;
+    }
+    started = true;
+    try {
+        const source = `'use strict';\n${stateName}.run(async function () {\n'use strict';\n${message.code}\n});`;
+        const script = new Script(source, {
+            filename: "agent-browser-script.js",
+            importModuleDynamically() {
+                process.exit(70);
+            },
+        });
+        script.runInContext(context);
+    }
+    catch (error) {
+        const described = describeError(error, "Script compilation failed.");
+        fail(described.name, described.message);
+    }
+}
+function deliverBrowserResponse(message, line) {
+    if (message === null ||
+        typeof message !== "object" ||
+        !("type" in message) ||
+        message.type !== "response") {
+        fail("Error", "Invalid parent IPC response.");
+        return;
+    }
+    try {
+        if (typeof deliver !== "function") {
+            throw new Error("Script response bridge is unavailable.");
+        }
+        Reflect.apply(deliver, undefined, [line]);
+    }
+    catch {
+        fail("Error", "Invalid browser response envelope.");
+    }
+}
 function handleLine(line) {
     const bytes = Buffer.byteLength(line, "utf8") + 1;
     if (bytes > maxMessageBytes || cumulativeBytes + bytes > maxCumulativeBytes) {
@@ -119,37 +180,10 @@ function handleLine(line) {
         return;
     }
     if (!started) {
-        if (!message || typeof message !== "object" || message.type !== "start" || typeof message.code !== "string") {
-            fail("Error", "Invalid script start message.");
-            return;
-        }
-        started = true;
-        try {
-            const source = `'use strict';\n${stateName}.run(async function () {\n'use strict';\n${message.code}\n});`;
-            const script = new Script(source, {
-                filename: "agent-browser-script.js",
-                importModuleDynamically() {
-                    process.exit(70);
-                },
-            });
-            script.runInContext(context, { timeout: undefined });
-        }
-        catch (error) {
-            const described = describeError(error, "Script compilation failed.");
-            fail(described.name, described.message);
-        }
+        startScript(message);
         return;
     }
-    if (!message || typeof message !== "object" || message.type !== "response") {
-        fail("Error", "Invalid parent IPC response.");
-        return;
-    }
-    try {
-        deliver(line);
-    }
-    catch {
-        fail("Error", "Invalid browser response envelope.");
-    }
+    deliverBrowserResponse(message, line);
 }
 process.stdin.on("data", (rawChunk) => {
     const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
@@ -161,12 +195,15 @@ process.stdin.on("data", (rawChunk) => {
     }
     for (;;) {
         const newline = inputBuffer.indexOf(10);
-        if (newline < 0)
+        if (newline < 0) {
             break;
+        }
         const line = inputBuffer.subarray(0, newline).toString("utf8");
         inputBuffer = inputBuffer.subarray(newline + 1);
         handleLine(line);
     }
 });
-process.stdin.on("error", () => undefined);
+process.stdin.on("error", () => {
+    // Parent transport teardown is handled by the parent's worker lifecycle owner.
+});
 hostSend(JSON.stringify({ type: "ready" }));

package/dist/scripts/agent-browser-target.mjs

@@ -11,11 +11,13 @@ function stableVersionParts(version) {
 export function isSupportedAgentBrowserVersion(version) {
     const actual = stableVersionParts(version);
     const minimum = stableVersionParts(MINIMUM_AGENT_BROWSER_VERSION);
-    if (!actual || !minimum)
+    if (!actual || !minimum) {
         return false;
+    }
     for (let index = 0; index < minimum.length; index += 1) {
-        if (actual[index] !== minimum[index])
+        if (actual[index] !== minimum[index]) {
             return actual[index] > minimum[index];
+        }
     }
     return true;
 }

package/docs/ARCHITECTURE.md

@@ -1,6 +1,7 @@
 # Architecture
 
 Related docs:
+
 - [`../README.md`](../README.md)
 - [`../AGENTS.md`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/AGENTS.md) (maintainer workflows, including upstream capability baseline)
 - [`REQUIREMENTS.md`](REQUIREMENTS.md)
@@ -13,6 +14,8 @@ Build this as a **thin `pi` extension/package** that exposes native commands and
 
 The package install path is the primary product path. Local checkout development should use explicit CLI loading for isolated smoke tests and configured-source plain `pi` runs for lifecycle validation, while package-manifest behavior and packaged contents matter more.
 
+Runtime graphs that use Pi host APIs are statically imported through Pi's extension loader, which supplies the host-peer mapping. Native ESM lazy imports must not bypass that mapping: a runtime-only global package does not install its optional Pi peers. The browser runner and observation/image publication retain Pi's native image primitives without a package-owned resolver or bundled host.
+
 ## Chosen shape
 
 ### Compact tools and native discovery
@@ -30,6 +33,7 @@ The collector's dynamic `isManaged()` decides ownership. Managed Pi delivers ful
 ### Direct subprocess execution
 
 The extension should:
+
 - resolve `agent-browser` from `PATH`
 - 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
@@ -42,7 +46,7 @@ The extension should:
 
 ### Persistent browser code
 
-`lib/input-modes/script.ts` and compiled `script-worker.js` retain the fresh permissioned Node child/VM and JSON-lines bridge. The internal filenames are not a public `script` input. `index.ts` selects the ordinary browser identity in the parent, holds its shared execution lock for the whole cell, serializes inner requests through the same executor, and reaps the child on completion, timeout, abort, branch change, or shutdown. The browser survives cell completion according to existing ownership. Native auth, profiles, state, connect, batch, and local commands retain ordinary parent-side configuration/environment; only changing the fixed session/namespace and namespace-wide close are excluded from an inner call.
+`lib/input-modes/script.ts` and compiled `script-worker.js` retain the fresh permissioned Node child/VM and JSON-lines bridge. The internal filenames are not a public `script` input. `orchestration/extension-code.ts` selects the ordinary browser identity in the parent, holds its shared execution lock for the whole cell, serializes inner requests through the same executor, and reaps the child on completion, timeout, abort, branch change, or shutdown. The browser survives cell completion according to existing ownership. Native auth, profiles, state, connect, batch, and local commands retain ordinary parent-side configuration/environment; only changing the fixed session/namespace and namespace-wide close are excluded from an inner call.
 
 The child has an empty environment, Node permission mode without host capability allowlists, a 64 MiB heap ceiling, and a VM with string/WebAssembly code generation disabled. Null-prototype `browser`, `emit`, and `emitImage` functions use JSON-only IPC; parent promises/objects/functions are not exposed. There are no imports or host filesystem/network/process/timer APIs. Node's VM alone is not a security boundary. The retained child isolation is distinct from the selected browser's persistent authentication and native capabilities; no QuickJS, broker, second driver, or provider payload injection is involved.
 
@@ -73,6 +77,7 @@ Artifact directory preparation has one filesystem-error boundary inside the exis
 The primary UX is the agent calling the tool directly.
 
 That means:
+
 - no command-heavy slash-command interface
 - no manual user orchestration as the main workflow
 - any future slash commands should be minimal and secondary
@@ -119,6 +124,7 @@ Local checkout validation has two intentional modes:
 The repo should not add a repo-local `.pi/extensions/` autoload shim as the documented checkout path.
 
 Why:
+
 - avoids duplicate `agent_browser` registrations when the package is also installed globally
 - keeps the product contract centered on the package manifest instead of repo-local autoload wiring
 - keeps reload and exact-session relaunch validation tied to Pi's configured-source lifecycle instead of an explicit-extension quick-test path, while `session_tree` state changes stay covered by focused extension harness tests
@@ -128,7 +134,7 @@ The published package should exclude agent-only and internal planning materials
 
 ## Host execution hook
 
-The default extension factory optionally accepts `{ beforeExecute }`. `index.ts` awaits this host callback after input resolution and before ordinary dispatch, forwarding the original outer Pi tool-call ID through inner code calls and supplying each dispatch's signal. Configured hosts use Pi's native sequential tool scheduling; inner code calls retain the existing serial queue. No separate controller, persistence store, retry policy, or timeout is introduced. Ordinary installation, internal helper probes, cleanup, batch-row execution, and web search are unchanged. See [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#host-execution-hook) for cancellation and error behavior; `test/agent-browser.pi-pipeline.test.ts` exercises the registered factory through real Pi with a fake upstream executable.
+The default extension factory optionally accepts `{ beforeExecute }`. `orchestration/extension-command-admission.ts` awaits this host callback after input resolution and before ordinary dispatch, forwarding the original outer Pi tool-call ID through inner code calls and supplying each dispatch's signal. Configured hosts use Pi's native sequential tool scheduling; inner code calls retain the existing serial queue. No separate controller, persistence store, retry policy, or timeout is introduced. Ordinary installation, internal helper probes, cleanup, batch-row execution, and web search are unchanged. See [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#host-execution-hook) for cancellation and error behavior; `test/agent-browser.pi-pipeline.test.ts` exercises the registered factory through real Pi with a fake upstream executable.
 
 ## Session model
 
@@ -141,6 +147,7 @@ An explicit native `session` default (user/project JSON or `AGENT_BROWSER_SESSIO
 When no native session, attachment, or explicit fresh launch is selected, `sessionMode: "auto"` uses `pi-root-<sha256(root Pi ID)[0:24]>` through the existing caller-owned named-session path. Descendants receive `PI_SUBAGENT_ROOT_SESSION_ID` from pi-subagents; root processes use `ctx.sessionManager.getSessionId()`. No cwd, human fork ancestry, run registry, or process-global assignment participates. The same name is the default native restore key. Existing native daemon inspection runs inside the existing identity queue: inactive roots receive bootstrap defaults, while active roots retain native launch settings and their current restore key. Scoped subprocess environment keeps helper settings consistent; no launch-settings journal is added. Root-name explicit follow-ups retain those defaults; unrelated explicit names do not. Global/override package `browser.defaultProfile` with `policy: "always"` supplies native Chrome profile names only, plus the configured executable, only when the effective engine is Chrome. Paths and project-only profile settings stay advisory. Native config/environment and explicit launch settings win. The communal source is copied by native Chrome launch, never by the wrapper, and each root's restore writes remain separate. Native JSON restore omits IndexedDB, service workers, and page-memory credentials; application-level restart verification is required. Parent and child quit leave the root browser alive; shared execution locks coordinate updated cooperating processes without a broker. An active older/fresh managed session keeps its existing lifecycle. A configured session has the same precedence over `fresh` as a literal `--session`; code follows the selected ordinary browser lifecycle; Electron launch retains its owned lifecycle. Electron launch suppresses the native session environment default only while allocating its generated session; ordinary browser follow-ups still honor the configured native default, so use the returned Electron session explicitly.
 
 Why:
+
 - works out of the box
 - gives continuity across calls
 - avoids forcing the agent to invent session names for basic browsing
@@ -168,6 +175,7 @@ The tool should also expose a first-class `sessionMode: "fresh"` escape hatch so
 ### Ownership
 
 Ownership rule:
+
 - automatic root sessions use native caller-owned lifecycle; group members coordinate and close them explicitly
 - older implicit auto-generated sessions are extension-managed convenience sessions
 - unnamed `sessionMode: "fresh"` launches rotate that extension-managed session to a new upstream browser
@@ -175,6 +183,7 @@ Ownership rule:
 - extension-managed sessions should be reusable during an active `pi` session and across `/reload`, exact-session relaunch, `/resume`, and Pi branch-tree transitions, while still being cleaned up predictably
 
 Practical policy:
+
 - preserve the current branch-visible extension-managed session across `/reload`, exact-session relaunch, `/resume`, and Pi 1.0.0+ `session_tree` branch transitions so persisted sessions can keep following the live browser after lifecycle changes
 - close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone
 - after branch restore, use the existing locked daemon inspection to distinguish a confirmed inactive wrapper-owned daemon from a live, unknown, or unavailable one. For compatible automatic managed restore only, keep the pending reopen in ordered session page state and persist it as `sessionTabReopenPending`. Non-page calls such as `tab list` can start a daemon without fulfilling it; explicit HTTP reads leave the managed browser and pending reopen untouched, including across branch/reload replay. Before the first current-page operation (`get url`, history commands and relative `pushstate` included), reopen the complete recorded URL with native `open`, invalidate old refs with the existing `page-transition` state, and verify the actual tab. Explicit URL reads and all-read batches skip managed ownership changes and browser helpers entirely; native owns their HTTP fetch and validation. Native `open` resets frame scope. Consume the obligation on that attempt or an executed explicit context/navigation/close command, not an unreached batch row; a failed open does not permit repeated navigation of a now-live browser. After the reopen CLI starts, cancellation returns a structured `aborted` result through the ordinary result path with the exact namespace/session, consumed marker and ref invalidation; it does not throw away replay state or run later browser helpers. Cancellation before the CLI starts does not consume the pending reopen. Internal URLs retain their fragments while tab/ref comparisons remain fragment-insensitive and presentation keeps normal redaction. Older transcripts cannot recover a fragment they did not record. Caller-owned/attached browsers and restore-disabled sessions do not take this path; live wrong-tab recovery still only selects an existing target. Reopening reloads the URL, not unsaved forms, JavaScript memory, or history. There is no second restore store or lifecycle lock.
@@ -188,6 +197,7 @@ Practical policy:
 - record successful `connect`, `--cdp`, enabled `--auto-connect`, environment-configured CDP/auto-connect, and wrapper Electron attachment identities in branch-visible state. First-use and later content-bearing calls live-check `get url` because attached targets can drift outside Pi. Caller config, file access, launch arguments, and environment pass through unchanged; only wrapper-injected compatibility launch arguments are omitted on active attachments. A terminal successful close removes the marker; a close followed by a later step whose lifecycle reports a browser launch preserves it, while a non-launching diagnostic such as `stream status` leaves the close terminal
 - when a successful close targets the current extension-managed session, including an explicit `--session <current> close` or an `electron.cleanup` managed-session step, clear page/ref state, mark that session inactive, untrack cleanup ownership, and rotate the next default auto call to a fresh wrapper-generated session name rather than reusing the closed name
 - on non-quit shutdown such as `/reload`, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership, but preserve the current branch-visible active managed session and Electron launch plus that launch's isolated `userDataDir` so reload continuity still works from the active transcript branch. First reuse of a restored Electron attachment checks the recorded namespace/session, live PID/profile presence, and exact browser WebSocket identity against current CDP metadata, then uses upstream `get cdp-url` to verify that the named daemon still targets that browser or one of its current pages. The metadata probe cannot commit daemon provenance merely by spawning; only a matching result permits the existing policy to record it. Ordinary calls, status, and probe share this path under the existing lock. Generic restore-disabled sessions, mismatched connections, quit, and off-branch cleanup are unchanged
+- require a nonempty, non-whitespace `Browser`/`browser` string in `/json/version` for Electron CDP readiness and debug-port liveness; other version metadata is optional. Before signaling a live restored Electron PID without a tracked child handle, require the process start identity recorded at launch to match the live process (the same `process-identity.ts` PID-reuse proof used for execution claims and temp-root ownership); a missing, unreadable, or mismatched identity retains the process/profile
 - expose still-owned off-branch Electron launch records to `electron.status { launchId }`, `electron.status { all: true }`, `electron.probe { launchId }`, and `electron.cleanup`, while leaving default `electron.probe` scoped to the current managed session
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds; `managedSessionOutcome.replacedSessionClosed` records whether that cleanup succeeded, and a failed close keeps the older identity wrapper-owned across transcript resume for explicit follow-up or cleanup
 - expose `details.browserWindow` and one visible login handoff only when a successful first/fresh local wrapper-managed headed result, including `batch`, is not an attachment and has upstream `lifecycle.effectiveLaunch.browserLaunched: true` and a `created`/`replaced` managed-session outcome. Keep `visibility: "unverified"`: this is launch evidence, never a claim about the user's OS desktop
@@ -196,12 +206,12 @@ Practical policy:
 - once the wrapper observes tab-drift risk for a session (profile restore correction, overlapping stale opens, or restored session state), later active-tab commands verify the intended tab under the existing session queue before semantic/ref helpers and user commands. Targets retain native CDP `targetId` across transcript replay; exact identity distinguishes duplicate URL/title tabs, while older targets without an ID keep URL-based matching. A cold managed reopen replaces the old ID. Native selection runs only when the intended tab is not already active, because upstream selection clears refs and frame scope even on same-tab reselection. Missing targets, failed selection, and post-selection target mismatches fail before user commands. Caller argv/stdin and native `--pin-tab` / `--no-pin-tab` preferences remain unchanged. Local commands, live `get url`, explicit HTTP `read <url>` (including its flags), URL `a11y`/`vitals`/`web-vitals`, `diff url`, `window new`, URL-bearing recording commands, and explicit tab/navigation/`connect`/`state load` recovery do not require the old target; history back/forward/reload, `pushstate`, and page-content operations still do. The same classifier scans effective batch rows past non-page prefixes until a page dependency or explicit context change, without rewriting user rows or changing bail behavior. For `window new` and `diff url`, observe the resulting URL instead of retaining the old target or treating the requested second URL as redirect evidence. Fold only reached native batch rows when available, discard targets before failed navigation/context transitions and live-verify the final page, discard observations and refs from before window/diff transitions, and let later successful snapshots rebuild refs even when another batch row fails. Retain an observed blank destination after either command instead of recovering the old page; if no final target is observed, use the existing unknown-target state. Caller batch arguments, stdin and bail behavior stay unchanged. Successful batches containing navigation-observable actions use the same final live page/identity observation as direct actions, so same-address popup tabs replace the pre-batch target before later pinning. Terminal batch closes do not trigger a page probe, and pending WebMCP targets remain unknown. Routine same-session commands avoid `tab list` preflights
 - for sessions with observed tab-drift risk, after a successful command on a known tab target, the wrapper may best-effort restore that same target again if restored/background tabs steal focus after the command returns; routine same-session commands skip focus correction, while observed pages without a returned native ID use `tab list` to establish current identity rather than inheriting an earlier tab's ID
 - after successful tab creation, selection, or close, including dispatched native batch rows, read the now-active URL and fresh non-blank title—even when two tabs share a URL—before updating per-session page state; retain the deliberate blank target instead of treating it as accidental drift
-- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore its once-stored ancestral definition when reloading, resuming, or moving to a different Pi session-tree branch, retain full membership and accessible metadata from that capture for wrapper-side diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; older supported natives can swap the page before their already-active check, so failed starts count; the warning and persisted summary explicitly describe conservative ref invalidation, not an observed page change), a `record restart` with a URL operand, `window new`, `diff url`, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection), including reached batch transitions and failed batch `open` rows whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); tab recovery (which leaves user argv/stdin and continue-on-error control flow unchanged), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated from `extensions/agent-browser/index.ts` after each tool result
+- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore its once-stored ancestral definition when reloading, resuming, or moving to a different Pi session-tree branch, retain full membership and accessible metadata from that capture for wrapper-side diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; older supported natives can swap the page before their already-active check, so failed starts count; the warning and persisted summary explicitly describe conservative ref invalidation, not an observed page change), a `record restart` with a URL operand, `window new`, `diff url`, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection), including reached batch transitions and failed batch `open` rows whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; the latch scan covers the whole plan, including rows after its first snapshot even when no earlier refs exist, so a non-form click between snapshot and ref getter still requires another snapshot. Batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); tab recovery (which leaves user argv/stdin and continue-on-error control flow unchanged), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated by `orchestration/extension-observation.ts` after each tool result
 - native 0.37 owns first-document setup inheritance for new tabs; the wrapper does not copy headers, user agents or other browser setup itself. The page-summary formatter displays native positive WebMCP availability while retaining raw details; it adds no discovery probe
 - when a direct or batched WebMCP call returns `status: "pending"`, or `result` / `cancel` fails while that target is unknown, keep its tab target unknown and discard same-call snapshot evidence instead of treating an immediate post-dispatch URL probe as stable; `webmcp result` / `cancel`, `get url`, and explicit navigation remain available while unknown; replace the generic blocked snapshot action with `verify-page-target-after-pending-webmcp` (`get url`), and let a completed `batch --bail` use that verification before `snapshot -i` to re-establish both target and refs
 - for top-level non-Electron direct `click` commands with an eligible target, install a bounded in-page target-specific event probe before upstream runs; if upstream reports success but no trusted pointer/mouse/click event reached the resolved target, fail the tool and report `details.clickDispatch` with explicit retry/inspect next actions (the wrapper does not replay clicks in-page). The probe covers `xpath=` targets and current `@e…` / `ref=` refs whose latest stored `refSnapshot.refs` role is `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`; it requires a unique role/name in the saved snapshot and the live candidates instead of taking a fresh pre-click snapshot that could recycle upstream refs. Ref and XPath candidates must additionally prove identity through a per-probe temporary DOM attribute read back by native `get attr <original-selector> <marker>`. Missing or mismatched identity, including XPath/frame scope mismatches, cleans up the probe and lets native click run without dispatch verification; candidate naming heuristics alone are never proof. Duplicate-name refs pass through without a probe: their old ordinal is not target identity. The probe is intentionally skipped when the effective native confirmation list guards `evaluate`, avoiding an optional-eval approval loop without bypassing native click policy. Dynamic action-policy files stay native-owned. It is also skipped for CSS selector clicks, unresolved `find … click` locators, and `batch`/`qa` click steps
 - skip unrelated tools and harmless Bash inspections before building prompt policy. Seed the latest raw user message on start/tree, update it on user `message_end`, and re-read its current content before parsing policy so native content replacement cannot leave stale intent. Capture that policy at queued admission without a whole-branch scan on every event. Derive narrow prompt guards only for concrete evidence invariants: explicitly requested screenshot/recording output paths block browser close until the artifact manifest verifies those paths, while bare inbound attachment paths remain inputs. The wrapper intentionally does not infer broad business/user intent from prompt text such as order/payment/post boundaries; agents must follow those instructions themselves. The artifact guard is bounded preflight policy (`details.promptGuard`, `failureCategory: "policy-blocked"`), not a reusable browser recipe layer
-- keep the existing page/selector scroll API; explicit CSS-container movement uses `Element.scrollBy` with `behavior: "instant"` before measuring offsets so smooth-scroll CSS cannot cause a premature no-movement failure
+- keep the existing page/selector scroll API; shims intercept only complete recognized shapes (`scroll to end|top` with exactly three tokens, or CSS-container scroll with three/four), passing surplus operands through to native execution without dropping them. Explicit CSS-container movement uses `Element.scrollBy` with `behavior: "instant"` before measuring offsets so smooth-scroll CSS cannot cause a premature no-movement failure
 - reject direct and effective batch `scrollintoview text=...` / `scrollinto text=...` before dispatch because current upstream can falsely report success without movement, while leaving help forms untouched; return only native recovery (`find text ... hover` or fresh snapshot/ref), leaving CSS, XPath, and current-ref behavior upstream-owned
 - after successful `get text` on a qualifying non-ref CSS selector, optionally issue one read-only `eval --stdin` probe per selector when multiple DOM matches or a hidden first match with visible peers could misread tabbed or off-screen content; simple id selectors and sensitive-looking literals skip this probe. Merge `details.selectorTextVisibility` / `selectorTextVisibilityAll`, visible warning lines, and `inspect-visible-text-candidates*` next actions as documented in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) and `RQ-0074` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 - caller-owned sessions honor native `AGENT_BROWSER_SOCKET_DIR` unless `PI_AGENT_BROWSER_SOCKET_DIR` overrides it, with the same socket integrity checks. For other local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit; require the selected path to be absolute, owned by the current uid, mode `0700`, under checked ancestry, and free of symlink, foreign-owner, or special planted entries; reject pre-existing unsafe modes instead of repairing them, then recheck before spawn. The actual filesystem root `/` is supplied by the trusted operating environment: a directory without group/other write bits is accepted regardless of its reported owner, which can be unmapped in a Linux user namespace. Existing root-owned sticky-directory acceptance is unchanged. This boundary does not protect against whoever controls the root filesystem. Every non-root ancestor still needs trusted ownership and permissions, including the destination ancestry of root-owned aliases; a matching overflow UID is not trusted. Android/Termux uses `/data/data/<package>/piab`, treats the owner-only app-data directory as the trust anchor, permits the app's matching private uid/gid ancestry, compacts generated managed identities to one 80-bit digest so ordinary namespace plus fresh-session paths remain within the limit, and places policy-lock coordination under `os.tmpdir()` because Android `/tmp` is shell-owned and inaccessible
@@ -217,7 +227,7 @@ Native close/save and explicit URL reopen remain the persistence path, not a liv
 
 ### 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.
+`native-session-defaults.ts` reads launch-argument/engine fields through its existing native-validated config discovery. Local Chrome composes `--no-startup-window` with caller CLI arguments only when native environment/config does not supply local launch defaults. Otherwise it leaves startup arguments entirely native-owned so browser, local auth, and helper calls do not alternate launch configurations. Callers wanting a single headed window with native launch defaults include `--no-startup-window` in their own `args`. 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 scoped arguments after managed restore-policy checks, composing the existing compatibility user agent without overriding caller Chrome arguments. Ordinary active calls do not receive new wrapper bootstrap settings. Native still owns CLI → environment → config precedence and hash-change restarts. This adds no browser launcher, profile mutation, tab cleanup, binary distribution, or persistent launch-settings state.
 
 Input resolution replaces URL-less `open` with native `get url` before planning, retaining requested argv separately. Effective raw/stdin batch rows use the existing native argument parser and raw-over-stdin precedence; only changed rows are rewritten. Native URL reads provide lazy launch and real lifecycle/URL output without navigating an existing page. Explicit navigation and help/version input are unchanged.
 
@@ -252,6 +262,7 @@ When a managed implicit or fresh `--session` plan reaches process execution, `de
 ## Preferring the native tool
 
 Keep the handling simple:
+
 - prefer the native tool through extension guidance and tool-call guards
 - do not rely on package skill overrides as the primary solution
 
@@ -268,7 +279,7 @@ Upstream restore-state persistence remains upstream-owned. The wrapper passes an
 - clear missing-binary errors
 - filtered `network requests --current-page` / `--current-origin` / `--current-url` preparation results use the same `redactPresentationData` credential redactor as ordinary diagnostics before populating `details.data` or writing `outputPath`
 - compact result summaries, including presentation-time redaction: stateful browser-context commands (`auth`, `cookies`, `storage`, `dialog`, `frame`, `state`) use field-aware value redaction and compact formatters, while other structured upstream JSON (for example `network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, and `chat`) is passed through `redactPresentationData` in `extensions/agent-browser/lib/results/presentation.ts` so model-facing `details.data` and batch roll-ups stay compact and do not echo bearer tokens, proxy passwords, or similar fields verbatim; `redactInvocationArgs` in `extensions/agent-browser/lib/runtime.ts` masks trailing values for sensitive global flags such as `--body`, `--headers`, `--password`, and `--proxy`, preserves positional rules for `cookies set` and `storage local|session set` while distinguishing native `--curl` file-import operands from inline cookie values (including failed batch diagnostics), and nested `batch` steps use the same argv and error-body scrubbing before echoing commands or errors. Shared URL redaction covers SAMLRequest/SAMLResponse/RelayState and auth-context-only state/nonce at model/persisted-artifact boundaries while retaining exact internal page-target URLs; snapshot spills are redacted before disk writes
-- bounded machine-readable outcome metadata on tool `details` (`resultCategory`, `successCategory`, `failureCategory`, optional `nextActions`, optional `pageChangeSummary` with observed-vs-dispatched evidence and per-step summaries on `batch`, optional `artifactVerification` with the same shape on each successful `batchSteps[]` row) so agents can branch without parsing prose; enums, classifier precedence, and generic follow-up payloads are implemented under `extensions/agent-browser/lib/results/` in focused modules (`contracts.ts` for shared types, `categories.ts` for `classifyAgentBrowserSuccessCategory` / `classifyAgentBrowserFailureCategory` / `buildAgentBrowserResultCategoryDetails`, `action-recommendations.ts` for `buildAgentBrowserNextActions`, `next-actions.ts` for the `AgentBrowserNextAction` shape and merge helpers, `recovery-actions.ts` for recovery id registries and `buildRecoveryNextActions`, `network.ts` for `classifyNetworkRequestFailure` / `summarizeNetworkFailures`, and related helpers). Per-session tab target, `refSnapshot` alignment, invalidation, and tab pinning observations flow through `extensions/agent-browser/lib/session-page-state.ts` from `extensions/agent-browser/index.ts`. Compact page-change summaries and artifact verification rollups are built in `extensions/agent-browser/lib/results/presentation.ts` (`buildPageChangeSummary`, `buildArtifactVerificationSummary`), and the human contract lives in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). Final public results return native `isError` after all wrapper reclassifications, without a `tool_result` repair hook. Prose retains the visible category notice; explicit parseable JSON stays unchanged. `lib/native-output.ts` and `finalizeAgentBrowserFailure` in `lib/pi-tool-rendering.ts` keep structured observations, transcript status and TUI affordances aligned (transcript semantics in the same contract doc)
+- bounded machine-readable outcome metadata on tool `details` (`resultCategory`, `successCategory`, `failureCategory`, optional `nextActions`, optional `pageChangeSummary` with observed-vs-dispatched evidence and per-step summaries on `batch`, optional `artifactVerification` with the same shape on each successful `batchSteps[]` row) so agents can branch without parsing prose; enums, classifier precedence, and generic follow-up payloads are implemented under `extensions/agent-browser/lib/results/` in focused modules (`contracts.ts` for shared types, `categories.ts` for `classifyAgentBrowserSuccessCategory` / `classifyAgentBrowserFailureCategory` / `buildAgentBrowserResultCategoryDetails`, `action-recommendations.ts` for `buildAgentBrowserNextActions`, `action-contracts.ts` for the `AgentBrowserNextAction` shape and `next-actions.ts` for merge helpers, `recovery-actions.ts` for recovery id registries and `buildRecoveryNextActions`, `network.ts` for `classifyNetworkRequestFailure` / `summarizeNetworkFailures`, and related helpers). Per-session tab target, `refSnapshot` alignment, invalidation, and tab pinning observations flow through `extensions/agent-browser/lib/session-page-state.ts` through `orchestration/extension-observation.ts` and branch restore. Compact page-change summaries and artifact verification rollups are built in `results/presentation/navigation.ts` and `artifact-verification.ts` (`buildPageChangeSummary`, `buildArtifactVerificationSummary`), and the human contract lives in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). Final public results return native `isError` after all wrapper reclassifications, without a `tool_result` repair hook. Prose retains the visible category notice; explicit parseable JSON stays unchanged. `lib/native-output.ts` and `finalizeAgentBrowserFailure` in `lib/pi-tool-rendering.ts` keep structured observations, transcript status and TUI affordances aligned (transcript semantics in the same contract doc)
 - inline screenshots/images for the plain `screenshot` command; other image-like saves (for example `diff screenshot`) still appear in `details.artifacts` and summaries but are not auto-inlined as Pi image attachments (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details))
 - lightweight session convenience
 - docs, including a repo-readable command reference that mirrors the blocked direct-binary help path closely enough for normal agent work
@@ -296,6 +307,7 @@ This mirrors the playbook contract pattern described in [`TOOL_CONTRACT.md`](TOO
 ## Not the right design
 
 Avoid:
+
 - duplicating native CLI semantics in bespoke tools
 - compatibility layers for old `agent-browser` versions
 - deep embedded SDK-style integration
@@ -322,6 +334,7 @@ Avoid:
 ## Summary
 
 The architecture should stay:
+
 - thin
 - aligned to the recommended upstream release and stable support floor
 - close to upstream