pi-agent-browser-native 0.9.2 → 0.9.4

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,10 +33,11 @@ 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
-- 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
+- inject `--json` only when no caller output mode is selected; explicit `--json false` retains opaque redacted native text and process outcomes without interpreting page text as trusted receipts or a session target. Optional booleans follow upstream last-wins semantics; structured helpers stay strict JSON. Nonzero exits with stderr retain the native error ahead of parse diagnostics, while zero-exit malformed machine output remains a strict failure. Empty stdin batch rows pass validation and native execution skips them without rewriting caller input. 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 internally generated QA/source batch plans, rejecting other command/stdin combinations before launch; Electron manages its own input
 - support optional top-level `outputPath` for successful browser results and failed/pending/recovered recording receipts. Recording exports retain success/error, original attempt, native data, artifacts and recovery provenance; they do not treat a written receipt as a successful video. Other successful results write `details.data` (or model-facing text when no structured data exists) to a caller-requested local file and reporting `details.outputFile`, without changing upstream argv semantics or overwriting a browser artifact when both destinations resolve to the same file. If presentation compacted direct data, a batch result row, or a whole batch, apply the relevant command-specific redactor before spilling and rehydrate each full pre-compaction value only from its matching live wrapper-manifest spill; fail without writing compact metadata when any required spill is unavailable or untrusted
@@ -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
 
@@ -136,11 +142,12 @@ The optional `pi-change-working-dir` event protocol supplies one invocation exec
 
 ### Default
 
-An explicit native `session` default (user/project JSON or `AGENT_BROWSER_SESSION`) selects a caller-owned browser across Pi sessions. Per-call session/namespace flags win. `lib/orchestration/native-session-defaults.ts` reads session/namespace and contributing launch defaults from native config paths and uses sessionless native `--config <path> --json session` to validate each contributing file and resolve its session. Native config continues to own launch/profile/storage settings; the adapter does not duplicate its schema. Explicit config and per-call idle settings are scoped to helpers through `lib/process-environment.ts`. No startup probe, persistent config cache, or new lifecycle service is added.
+An explicit native `session` default (user/project JSON or `AGENT_BROWSER_SESSION`) selects a caller-owned browser across Pi sessions. Per-call session/namespace flags win. `lib/orchestration/native-session-defaults.ts` reads session/namespace and contributing launch defaults from native config paths and uses sessionless native `--config <path> --json session` to validate each contributing file and resolve its session. Native config continues to own launch/profile/storage settings; the adapter does not duplicate its schema. Explicit config, per-call idle settings, `--action-policy`, `--confirm-actions`, `--debug` and `--no-auto-dialog` are scoped to helpers through `lib/process-environment.ts`. Boolean selections also supply CLI operands to helpers lacking an explicit selection, because native ORs environment/config booleans and only CLI `false` overrides true defaults. Explicit debug false removes the debug environment variable because native daemon logging tests its presence; no-auto-dialog false retains native `0`. Caller argv stays intact and the environment scope ends with the call. The effective confirmation setting is retained in existing `SessionPageState` and canonical page events, resolved inside the identity queue before daemon inspection and helpers. First launch and new explicit `--confirm-actions` / `--config` selections use native argv → environment → config precedence; bare follow-ups retain selected strings, including explicit `""`, over ambient environment/discovered-config edits. Native unset is not retained and continues native default resolution; no config freezing or ambient-change detector is needed. Successful session/namespace close and successfully closed managed replacements clear it. Cleanup scopes every probe and close to the old identity's setting; failed close retains its page/policy continuity. Off-branch live owners keep their selected strings in the same page state until cleanup; an ordered post-close relaunch retains the new daemon's setting. Resume and branch restore use the same reducer. Native still owns policy changes and pending confirmations; there is no policy hot-reload, pending-command store, persistent config cache, or new lifecycle service. Electron launch and host probes retain the same selected confirmation setting. Begin records preserve interrupted intent; a definite no-dispatch/native CLI parse/config/local-inspection rejection restores the previous setting only when no earlier browser helper could have established the request. Other policy flags remain call-scoped.
 
 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
@@ -151,7 +158,7 @@ Browser-independent calls to an already-owned session reuse its idle timeout, na
 
 An explicit native `session info` call is the preflight: daemon activity/PID is separate from `runtime.browser` liveness, Chrome PID, exact profile, tabs and launched/attached ownership. Pi adds its own cleanup ownership from existing ownership records. Unknown native fields stay unknown; the wrapper does not infer the browser from daemon/config state or add a host process scan. Native `runtime.recording.current` / `last` receipts and protocol capabilities remain visible. Full fields require companion native support; receipts retained by the native daemon are not durable after it exits.
 
-`lib/read-confirmation.ts` recognizes only native structured control responses for actual explicit URL reads. Ordered pending/cleared `readConfirmation` markers live in the existing `SessionPageState` and tool-result transcript, including resume/branch replay. They preserve actual session/default routing even for legacy prompts. Only native `capabilities.readRequiresConfirmation: true`, which promises exact ID validation, allows matching confirm/deny to skip page helpers and managed replacement. Explicit caller identities win, DOM/unknown-origin confirmations keep their prior checks, and response content cannot manufacture provenance. There is no separate confirmation store or wrapper authorization system.
+`lib/read-confirmation.ts` recognizes strict native control envelopes with actual command provenance. Ordered pending/cleared `readConfirmation` markers in the existing `SessionPageState` and transcript preserve exact ID, canonical identity and compact originating command/native action across resume and branch replay; they never store argv or command blobs. For originating `tab new` commands, the same decoder and presentation validator also recognize paired `after_confirmation: ["open", <original URL>]` / nonempty `guidance` transport metadata, using the existing navigation operand reader and retaining strict control keys. It preserves conditional, redacted prose without persisting or executing continuation arguments; page/eval/HTTP data never acquires that provenance. Exact matching guarded decisions suppress only page/pinning helpers that could overwrite the native pending slot. For native batch this applies only when its first effective row is that matching decision, using native raw-argv-over-stdin selection; remaining page/ref checks stay intact. Completed browser-backed decisions still reconcile page/ref state, report inner failures and retire confirmed close normally; native ID validation is not implied. Explicit URL-read provenance remains separate: only `capabilities.readRequiresConfirmation: true` grants browser independence with native ID matching. Legacy URL reads keep normal checks; unrelated or forged/page-shaped observations gain no exemption. A per-call helper observer updates this same marker and stops later same-identity page helpers after a new pending control. Cold reopen exposes that helper decision without dispatching the original getter or replaying open. Confirmed full snapshots feed the existing ordered ref fold, while pending captures cannot replace completed refs. The existing cleared marker records one-use freshness only for a final successful complete confirmed capture; the next same-identity call consumes it in live state and replay. The semantic visible-ref resolver uses the same eligible capture for role click/check/fill and unique role/label select, preserving editable evidence and action payloads. This avoids gated semantic/freshness-snapshot retry loops without bypassing target, membership, invalidation or native generation checks. Pending snapshots use the common confirmation renderer rather than the empty-snapshot formatter. Required live URL verification replaces the call's remembered target before semantic resolution and direct-ref preflight, dropping old title/target identity when the complete URL changes. The existing stale-ref guard compares the complete approved URL, including fragments, only on one-use confirmed-capture calls; ordinary ref/tab URL comparisons remain fragment-insensitive. Caller-owned, attached and wrapper-owned managed sessions therefore reject refs from a different approved route without requiring resume, restore pinning or another gated snapshot. DOM-only renames on the same page after that sample are not resampled on this one use; ordinary checks resume afterward. Attachment replay honors realized compact close commands, including confirmed closes. There is no second confirmation store or wrapper authorization system. Click-dispatch probes keep their ordinary diagnostic window but self-clean their page listeners and marker after the per-call process timeout plus the existing two-second cleanup grace. Normal cleanup cancels that timer; expiry never needs a browser helper that could overwrite the pending slot.
 
 ### Native observation state
 
@@ -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.
@@ -183,7 +192,7 @@ Practical policy:
 - redact snapshot spill payloads before writing them, clean up process-private temp spill artifacts on shutdown, and keep persisted-session spill files in a private session-scoped artifact directory for `details.fullOutputPath` after reload/resume, with a 32 MiB per-session budget by default; `PI_AGENT_BROWSER_SESSION_ARTIFACT_MAX_BYTES=0` skips persistent-spill enumeration and eviction without changing temporary spill cleanup
 - keep explicit screenshots, downloads, PDFs, traces, HAR captures, and recordings written to caller-chosen paths on disk after a successful upstream close command (`close`, `quit`, or `exit`); before artifact-producing commands run, create missing parent directories for requested host paths, while native download always owns the click and download, including loopback links, generated Blob exports, and redirects; never substitute an anchor-href fetch. When the internal recent artifact view has entries, successful close commands also surface `details.artifactCleanup` and a compact `Artifact lifecycle` note pointing to structured explicit paths so operators remove files with normal host tools—the native tool does not delete arbitrary user paths (`extensions/agent-browser/lib/orchestration/browser-run/diagnostics.ts`, `getArtifactCleanupGuidance`); contract in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), checklist `RQ-0079` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 - reconstruct the current branch-visible extension-managed session, every transcript-proven still-active wrapper-owned managed identity, page-scoped refs, journal-ordered artifact-row changes, unbounded active-recording reservation events, and Electron launch records from the active transcript branch on `session_start` and `session_tree` so later default and explicit off-current calls keep following owned browsers after resume/reload or branch switching; restore also honors successful explicit `--session <wrapper-owned> close` rows, terminal nested-batch close outcomes even when aggregate artifact verification failed, and `electron.cleanup` managed-session steps so closed wrapper-owned sessions are not resurrected; a nested close invalidates the pre-close page target so a lifecycle-proven relaunch at `about:blank` is not treated as stale focus drift; explicit lifecycle evidence that a later diagnostic did not launch a browser preserves the terminal close, while any later row—including a failed row—whose lifecycle reports a browser launch keeps active/attached provenance; failed-step presentation persists only that bounded launch boolean so transcript replay reaches the same decision, missing lifecycle evidence remains conservatively active even on the first managed call, successful closes clear wrapper trace/profiler ownership before ordered later successful rows can rebuild it, namespace-scoped `close --all` clears all matching managed/attached/page/ref/route/trace/recording ownership, and recording starts after close are rejected before spawn
-- keep active recording destination reservations separate from the bounded metadata-only artifact manifest. The same journal retains native recording IDs and start windows; native receipts, including failures, flow through existing artifact metadata and verification. A stop timeout/no-recording result gets one two-second native `session info` query matching namespace/session, ID/path or effective batch start window. Recovery needs terminal native encoder success plus a matching verified file; filesystem presence alone is insufficient, old same-path receipts cannot verify a new take, and freshness starts at capture rather than status-query time. Original attempts and unrelated batch failures remain visible. No second ledger, recorder, sidecar or runtime ffprobe is added. The process-wide map is keyed by canonical namespace/session identity, rebuilt from append-only branch events, and retained for still-live process-owned recordings across branch switches. Shutdown/reload appends both terminal tombstones and still-live reservations onto the current branch so restart cannot resurrect a cross-branch close or lose a live-daemon reservation. One artifact lifecycle/output queue makes global destination preflight and reservation updates atomic across otherwise-concurrent caller-owned session queues. Every successful direct, ordered nested-batch, managed replacement, code, Electron, or shutdown close retires its exact identity at that lifecycle point; only the newest pending recording path remains authoritative across current transition replay (including same-timestamp restart rows), and recording starts after a nested close are rejected because upstream can falsely report success. Existing and dangling symlink ancestry, hardlink inode identity, full Unicode/platform case folding, and same-call `outputPath` comparison prevent alias reuse. One shared command-token projection mirrors upstream's full-argv global cleanup before artifact, recording, and presentation parsing; wait-download detection removes only the first timeout pair, follows upstream long/short mode precedence, and accepts both `--download` and `-d` wherever download mode wins; screenshot destinations use upstream's exact-flag, selector-prefix, case-sensitive extension, slash-path, and second-positional rules, while retaining the wrapper's intentional slash-bearing hidden-workspace path normalization. Recording path/URL consumers share a command-local reader that skips complete numeric `--fps` pairs, cursor/contact-sheet switches, and contact-sheet threshold values without rewriting argv or treating them as outer globals; native owns rate, format and extra-argument validation. Current recording transitions are replayed directly; artifact manifests are not treated as reservation events
+- keep active recording destination reservations separate from the bounded metadata-only artifact manifest. The same journal retains native recording IDs and start windows; native receipts, including failures, flow through existing artifact metadata and verification. A restart without a terminal previous-take receipt retires the prior pending artifact only when native acknowledges `restarted: true`; rejected or pending restarts retain its reservation and stop action. A stop timeout/no-recording result gets one two-second native `session info` query matching namespace/session, ID/path or effective batch start window. Recovery needs terminal native encoder success plus a matching verified file; filesystem presence alone is insufficient, old same-path receipts cannot verify a new take, and freshness starts at capture rather than status-query time. Original attempts and unrelated batch failures remain visible. No second ledger, recorder, sidecar or runtime ffprobe is added. The process-wide map is keyed by canonical namespace/session identity, rebuilt from append-only branch events, and retained for still-live process-owned recordings across branch switches. Shutdown/reload appends both terminal tombstones and still-live reservations onto the current branch so restart cannot resurrect a cross-branch close or lose a live-daemon reservation. One artifact lifecycle/output queue makes global destination preflight and reservation updates atomic across otherwise-concurrent caller-owned session queues. Every successful direct, ordered nested-batch, managed replacement, code, Electron, or shutdown close retires its exact identity at that lifecycle point; only the newest pending recording path remains authoritative across current transition replay (including same-timestamp restart rows), and recording starts after a nested close are rejected because upstream can falsely report success. Existing and dangling symlink ancestry, hardlink inode identity, full Unicode/platform case folding, and same-call `outputPath` comparison prevent alias reuse. One shared command-token projection mirrors upstream's full-argv global cleanup before artifact, recording, and presentation parsing; wait-download detection removes only the first timeout pair, follows upstream long/short mode precedence, and accepts both `--download` and `-d` wherever download mode wins; screenshot destinations use upstream's exact-flag, selector-prefix, case-sensitive extension, slash-path, and second-positional rules, while retaining the wrapper's intentional slash-bearing hidden-workspace path normalization. Recording path/URL consumers share a command-local reader that skips complete numeric `--fps` pairs, cursor/contact-sheet switches, and contact-sheet threshold values without rewriting argv or treating them as outer globals; native owns rate, format and extra-argument validation. Current recording transitions are replayed directly; artifact manifests are not treated as reservation events
 - keep process-owned cleanup registries for extension-managed sessions and wrapper-launched Electron records separate from the current branch-visible view; `session_tree` restore and wrapper-owned browser commands are serialized with managed-session work, while caller-owned explicit-session commands use local queues and shared execution locks keyed to actual socket context and effective canonical namespace/session across prepare helpers (explicit namespace argv overrides inherited `AGENT_BROWSER_NAMESPACE`, including an explicit empty default) and main execution. macOS and Windows additionally normalize and case-fold namespace and session components to match case-insensitive daemon identity. Different caller-owned identities remain concurrent, except namespace-scoped `close --all` drains and exclusively barriers managed plus matching caller-owned work before clearing global namespace state; nested helpers never re-enter the outer queue, policy/route/artifact deltas merge across unrelated managed-state commits, and a separate branch-restore generation guard prevents stale completions from overwriting newer branch-visible state; artifact-row changes use the existing artifact queue and journal order so replay retains concurrently completed entries. Branch switches still must not drop resources the current Pi process owns and must keep fresh-session allocation monotonic
 - 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
@@ -196,10 +205,10 @@ 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; 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 for CSS selector clicks, unresolved `find … click` locators, and `batch`/`qa` click steps
+- 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
 - 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
@@ -217,7 +226,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 +261,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 +278,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 +306,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 +333,7 @@ Avoid:
 ## Summary
 
 The architecture should stay:
+
 - thin
 - aligned to the recommended upstream release and stable support floor
 - close to upstream

package/docs/CODE_QUALITY.md

@@ -0,0 +1,242 @@
+# Code quality
+
+Oxlint owns maintained-code linting, Oxfmt owns supported formatting, and TypeScript,
+tests, builds, and generated-document checks remain independent gates. Use the pinned
+Node runtime and npm version in `package.json`, then `npm ci --ignore-scripts`.
+
+Correctness, long-term maintainability, and reliable enforcement are equal
+requirements. Keep production complexity, size, readonly, and safety checks even
+when satisfying them requires substantial restructuring. A maintainability finding
+does not need to identify a current runtime bug. Refactors must improve responsibility
+boundaries, explicit ownership, failure/cancellation flow, and localized changes—not
+just move lines, add forwarding layers, or pass a giant mutable context everywhere.
+Use already authorized exceptions when their conditions are demonstrated; further
+relaxations require concrete evidence and explicit approval.
+
+## Commands
+
+| Command                            | Purpose                                                                                                                                                                                                |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `npm run quality`                  | Canonical non-modifying acceptance: clean build, checker preparation, scope/suppression policy, lint, formatting, compiler checks, tests with real-tool probes, and generated-doc/upstream-help checks |
+| `npm run lint`                     | Policy checks followed by strict Oxlint over the complete maintained-code inventory                                                                                                                    |
+| `npm run lint:agent`               | Identical coverage with Oxlint agent diagnostics                                                                                                                                                       |
+| `npm run lint:fix`                 | Identical policy and coverage; apply ordinary safe Oxlint fixes                                                                                                                                        |
+| `npm run format`                   | Format supported maintained files using Oxfmt                                                                                                                                                          |
+| `npm run format:check`             | Check formatting without modifying files                                                                                                                                                               |
+| `npm run quality:policy`           | Validate language coverage and parsed suppression comments; emit the current exception inventory                                                                                                       |
+| `npm run quality:scope -- --write` | Regenerate the final exact unchecked-JavaScript override after an intentional scope/tool change                                                                                                        |
+| `npm run quality:probes`           | Run the focused `node:test` real-CLI regression suite                                                                                                                                                  |
+| `npm run quality:mutations`        | Require clean acceptance, then prove the real workflow rejects syntax, semantic, compiler, formatting, and allowance-isolation mutations in disposable copies                                          |
+
+Review fixes before committing; dangerous fixes and suggestion fixes are not part of
+`lint:fix`. Run formatting after reviewed lint fixes and rerun acceptance. Failures
+are never converted to success by these commands.
+
+## Language and role scope
+
+The root `.oxlintrc.json` enables type-aware rules and compiler diagnostics. The
+canonical `tsconfig.json` includes maintained extension TypeScript, TypeScript
+scripts, tests, and explicitly checked configuration-policy JavaScript; build configuration
+continues to own emitted extension files.
+
+`scripts/code-quality-policy.mjs` discovers maintained code and effective compiler
+projects using the installed TypeScript CLI. It reads inherited settings with
+`tsc --showConfig` and actual project/import membership with `tsc --listFilesOnly`.
+Oxc's parser identifies genuine leading `@ts-check` comments without mistaking
+strings or documentation for directives.
+
+| Source                            | Syntactic lint | Semantic lint | Compiler | Formatting/tests |
+| --------------------------------- | -------------- | ------------- | -------- | ---------------- |
+| TypeScript                        | Yes            | Yes           | Yes      | Yes              |
+| JS with effective `checkJs: true` | Yes            | Yes           | Yes      | Yes              |
+| JS with leading `@ts-check`       | Yes            | Yes           | Yes      | Yes              |
+| Other maintained JS               | Yes            | No            | No       | Yes              |
+
+Unchecked JavaScript is **not ignored**. The final root override lists its exact
+paths and disables only the installed metadata's type-dependent rules plus the
+TypeScript-only module-boundary annotation requirement. It is generated explicitly,
+not dynamically weakened during a lint run. The policy gate rejects drift in files,
+projects, checking directives, metadata, or root lint inventory. Checked files must
+be explicit compiler-project inputs: imported-only checked JS can otherwise fall
+through Oxlint's compiler project assignment. Imported unchecked JS remains available for resolution
+and its TypeScript consumers retain safety checks.
+
+There are no extra lint-only JavaScript semantic opt-ins. Test role and language
+scope are separate: unchecked JS tests keep ordinary lint and test checks without
+accidentally inheriting type-dependent test rules. Production limits are complexity
+10, depth 3, four parameters, 40 statements, 80 nonblank/noncomment function lines,
+and 500 nonblank/noncomment file lines. Tests and verified `test/helpers` use
+complexity 15, depth 4, six parameters, and no size/statement limits. Handwritten
+declarations retain type/API checks without structural metrics.
+
+## Responsibility and ownership changes
+
+The major decompositions preserve the tool surface and lifecycle contracts; they
+separate operations and owners rather than creating a new execution framework.
+
+| Before                                                                                                                                                                                 | After and change locality                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts` combined registration, prompt caching, command execution, branch replay, and browser/recording/Electron cleanup in one closure.                                             | The entrypoint composes registration. `extension-command-run.ts` makes preparation, durable admission, dispatch, reconciliation, and finish publication explicit. Prompt, artifacts, recording reservations, Electron resources, managed identities, page resources, branch generations, and in-flight code have distinct owners. `BrowserRuntime` is readonly composition, not an exempt mutable bag; leaf helpers receive operations, readonly views, or primitives. |
+| Browser preparation and output mixed input guards, observations, native lifecycle state, artifact handling, and presentation.                                                          | `prepare.ts` orders focused validation and preparation. `process-output.ts` exposes native observation, page observation, lifecycle commit, and publication, with owned stdout-spool cleanup in `finally`. Readonly phase results carry evidence; only the existing command, page, restore, probe, and presentation owners receive exact mutation allowances.                                                                                                          |
+| Presentation assembled diagnostics, artifact verification/images, notices, output compaction, and redaction together.                                                                  | `results/presentation.ts` retains the visible assembly order; diagnostic families and artifact verification, image handling, and compaction live at their respective boundaries. Mutable presentation identity is retained only at assembly operations; successful data still passes through redaction.                                                                                                                                                                |
+| `runtime.ts` combined argv planning, identity/replay, launch compatibility, timeout rules, and credential redaction. Storage conversion combined decoding, streaming, and publication. | Planning remains pre-spawn and filesystem-free, with focused planning/replay/redaction modules and preserved exports. Journal read/replay/projection and legacy conversion are separate responsibilities; conversion still verifies the unchanged source before exclusive separate-copy publication and releases only its owned resources.                                                                                                                             |
+
+Ordering, branch-generation guards, cancellation, append-failure behavior, native
+argument presence, and cleanup ownership remain independent behavioral contracts.
+The real-CLI probes also reject mutable additions to qualified owners and verify
+that ordinary runtime records and parameter-property writes remain checked.
+
+## Corrected checker and allowance integrity
+
+The locked baseline is Oxlint **1.87.0**, `oxlint-tsgolint` **7.0.2003**, Oxfmt
+**0.72.0**, TypeScript **7.0.2**, and `oxc-parser` **0.153.0**. Framework rules use
+`eslint-node-test` **1.0.1** through Oxlint's supported JS-plugin mechanism; ESLint
+is its required runtime API dependency, not another configured lint owner.
+
+The original backend has reproduced file-safe-call origin and readonly
+intersection/container defects. `scripts/prepare-quality-checker.mjs` builds the
+pinned backend revision `eb9339115edde6811ca94c3433adf69ea9852880` and compiler
+submodule `2bd066d87f5bafd315be9f40889d0a60b9e58e0b`, applies
+`patches/oxlint-tsgolint.patch`, and verifies the cached binary's fingerprint/hash.
+It selects Go **1.27.1**. A clean install needs Git, Go, and network access for this
+first build; no manual installed-package edits or install lifecycle hooks are needed.
+
+All semantic lint goes through `scripts/oxlint.mjs`, which forces the verified
+binary through upstream's `OXLINT_TSGOLINT_PATH`. CLI, probes, fixes, and the editor
+must use this same launcher. The checked-in VS Code setting `oxc.path.oxlint` points
+to `./scripts/oxlint.mjs`; the Oxc extension starts `.mjs` launchers with Node.
+Keep Node 24.21.0+ available to the editor. Oxc normally resolves `node` from its
+environment; an editor launched without that PATH can use its user-level
+`oxc.path.node` setting to select the supported executable. Oxc 1.63+ also supports
+`oxc.useExecPath: true` when the editor's bundled Node meets that floor. Do not
+enable it blindly on an editor with an older bundled runtime.
+For another editor, start the language server with `node scripts/oxlint.mjs --lsp`
+using its documented executable mechanism. Do not substitute an independently
+installed global Oxlint or the uncorrected raw backend. Root configuration is shared,
+including JS scope and the actual Node test rules.
+
+Oxlint 1.87's language server reports lint diagnostics but does not expose its CLI
+compiler-diagnostic pass. Keep the editor's native TypeScript/JavaScript validation
+enabled (the workspace settings do so), and retain `npm run typecheck` and the
+canonical CLI as independent compiler gates. A successful lint-server handshake
+does not establish compiler coverage. Oxlint 1.87 also does not merge unsaved
+cross-file editor overlays into a dependent file's semantic project. Save referenced
+files and reanalyze the dependent document; the canonical launcher diagnoses and
+clears cross-module ownership at that save/re-pull boundary. This is an upstream
+limitation shared by the unpatched backend, not a persistent native-checker cache.
+
+`allowForKnownSafePromises` stays empty. The only safe-call registration group is
+the declaration-qualified `node:test` package's `test`, `it`, `describe`, and `suite`.
+Ordinary floating work, local shadows, and unrelated exports/packages retain
+floating-Promise checking. The complete policy also requires owned native `t.test`
+subtests; do not assume a diagnostic came from `no-floating-promises` when it came
+from `node-test/no-unawaited-subtest`. `node-test/no-nested-tests` additionally rejects
+imported test registration inside a test body; use an owned `t.test` subtest instead.
+The repository uses direct imports, not custom registration reexports; requalify
+framework scope before adopting a different registration pattern. Suite callbacks
+receive an exemption only when their value uses establish exclusive native suite
+ownership. Borrowing a native callable or namespace type does not establish native
+value identity. Opaque module loading or native VM code execution withholds that
+claim for exported callbacks, including when module resolution supplies only a
+declaration or external-library target instead of maintained runtime code. The
+Require analysis uses a precise target only for an explicit relative file operand
+whose native resolved path equals the runtime operand; package conditions and
+extension substitution remain opaque. The checker does not interpret code strings
+or promise a runtime security boundary.
+
+Native readonly allowances are declaration-qualified, not shape/name-only. They
+accept the actual native contract, not mutable application additions or runtime
+freezing. Generic `Map`, `Record`, `Readonly`, and callable shapes are not blanket
+allowances. The correction checks native readonly map/set elements recursively
+while preserving mutable-container and mutable-nested-value counterexamples.
+Non-generic TS/JSDoc array aliases retain exact declared identity without introducing
+wrapper types. Built-in browser `URL` and Node's `node:url` `URL` have distinct
+origins; the filesystem `PathLike` contract requires the Node-qualified allowance.
+
+`test/code-quality.test.ts` exercises actual language/compiler scope, consumer
+resolution, test-role boundaries, framework diagnostics, declaration isolation,
+mutable intersections, suppression policy, and formatting idempotence. Probes
+check expected rule identities; setup/configuration/parser failures are not valid
+negative evidence. Keep minimal unsuppressed checker reproductions when upgrading
+the backend and retire the patch only after the same controls pass.
+
+## Semantic exceptions
+
+Native directives must be exact, single-rule `oxlint-disable-next-line` comments
+with a specific adjacent explanation. Supported semantic rules are:
+
+- `no-await-in-loop`: journals, dependency ordering, retries, backpressure, locks,
+  and ordered cleanup.
+- `no-control-regex`: intentionally escaped field/protocol control-character
+  validation.
+- `typescript/no-unnecessary-condition`: necessary live lifecycle checks whose
+  state can change during an awaited operation.
+- `typescript/prefer-readonly-parameter-types`: reproduced plain generic callback
+  false positives, never mutable callable properties.
+- `node-test/no-conditional-assertion`, **only in tests/test helpers**: exhaustive
+  variant validation or independently proven fail-closed narrowing.
+
+An explanation is not semantic proof. Review the actual ownership/ordering/guard
+contract and retain boundary tests, including interrupted and uninterrupted paths.
+Do not suppress floating-Promise protection to compensate for a matcher defect.
+Blanket disables, multi-rule disables, ESLint directives, `@ts-ignore`, and
+`@ts-nocheck` are forbidden. Described `@ts-expect-error` is accepted only in
+dedicated `*.test-d.ts` negative type tests with at least ten explanation characters.
+Unused native disables remain errors.
+
+The policy command prints current paths, locations, rules, and reasons for every
+comment exception. Exact configuration exceptions are reviewable in root config:
+
+`scripts/code-quality-boundaries.mjs` is the canonical inventory of exact local
+declaration and mutation boundaries, including their reasons. `quality:scope -- --write`
+generates their complete rule options immediately before the final JS override;
+overlapping boundaries retain all allowed declarations and the entire strict native
+baseline. Never hand-edit those generated overrides or turn generic maps/sets into
+blanket allowances. The inventory covers diagnostics collectors, next-action
+accumulators, replay fixtures, canonical runtime/resource owners, presentation
+assembly, and the browser-run reducer—not arbitrary input records or read-only views.
+
+Reviewed native-resource readonly exceptions remain single-site directives:
+`browser-journal-projection.ts` receives its native async cursor in `projectJson`;
+`browser-session-conversion-stream.ts` receives native async cursors in `writeBytes`
+and `inject`; `recording-reservations.ts` deliberately mutates its existing index
+only in `applyRecordingArtifactsToReservations` and `retireRecordingReservation`.
+These contracts do not exempt generic `AsyncIterable` or `Map` inputs elsewhere.
+
+The exact site-policy map in `code-quality-policy.mjs` additionally permits only
+the reviewed native `promisify` callback contracts, sanitized secret-error propagation,
+native cancellation reason identity, and the private numeric generation-token
+constructor. Their unused directives remain errors and their actual locations and
+reasons appear in the emitted inventory.
+
+| Scope                                                                                                                                                                                                                            | Exception                                               | Contract/verification                                                                           |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Tests and test-only helpers                                                                                                                                                                                                      | `no-useless-undefined.checkArguments: false`            | Preserve argument presence and negative input fixtures; other rule checks remain active         |
+| `test/agent-browser.tool-surface.test.ts`, `test/verify-package.test.ts`, `test/doctor.test.ts`                                                                                                                                  | Additionally `checkArrowFunctionBody: false`            | Preserve required undefined-returning fixture callbacks                                         |
+| `managed-session-policy-lock.ts`, `browser-execution-claims.ts`, `browser-execution-claim-storage.ts`, `temp-mutation-queue.ts`, `temp-artifact-budget.ts`, `temp-root-ownership.ts`, `temp-root.ts` under the extension library | `checkArrowFunctionBody: false` only                    | Required undefined-returning release/error callbacks; argument checking remains active          |
+| `test/agent-browser.batch-fidelity.test.ts`, `test/agent-browser.native-lifecycle.test.mjs`                                                                                                                                      | `no-await-in-loop: off`                                 | Cohesive inherently ordered native lifecycle suites; original behavior tests retained           |
+| `scripts/verify-recording-native.mjs`, `scripts/verify-agent-browser-dogfood.ts`                                                                                                                                                 | Exact test role, including `checkTypePredicates: false` | Actual nonpackaged assertion harnesses, not production helpers                                  |
+| `tool-surface.ts`, `web-search.ts`, `orchestration/extension-tool-boundary.ts`, `config-validation.js`, `redaction-fields.ts` under the extension library                                                                        | `max-params: 5`                                         | Fixed SDK/public config/regex replacement callback arity; other production limits remain active |
+
+## Formatting, generation, and CI
+
+Oxfmt preserves the repository's tabs, LF endings, semicolons, and existing import
+order. Optional sorting and JSDoc rewriting remain off. The package manager owns
+`package-lock.json`; compiled output and task artifact directories are excluded.
+Generator-owned documentation must converge with Oxfmt through its generator,
+not by hand-editing generated blocks or ignoring maintained documents.
+
+`.github/workflows/code-quality.yml` installs locked dependencies, the selected Go
+toolchain, and the separately installed command-reference upstream target. It runs
+the real acceptance and mutation controls without modifying maintained artifacts.
+The release workflow requires this job before publishing. Existing official/fork
+Pi qualification and lifecycle checks remain separate and are not replaced by
+quality acceptance.
+
+Classify findings accurately: scope/configuration reductions, checker-integrity
+fixes, genuine source improvements, fixture corrections, and production runtime
+bugs are different outcomes. Zero diagnostics is meaningful only with scope,
+suppression, allowance, typecheck, test, build, generation, and formatting gates
+all passing on the exact integrated revision. Major refactors also require review
+of their resulting responsibilities, ownership, API surface, asynchronous phases,
+and before/after change locality. Green checks do not substitute for that review.