pi-agent-browser-native 0.9.5 → 0.9.7

package/docs/ARCHITECTURE.md

@@ -12,16 +12,30 @@ Related docs:
 
 Build this as a **thin `pi` extension/package** that exposes native commands and persistent-browser code while keeping upstream `agent-browser` as the source of truth.
 
+The recommended separately installed native is 0.41.0, with the stable 0.35.0 runtime floor unchanged. Native owns the newer download persistence, origin-scoped restore, project-config trust, and daemon `.config` cleanup; the wrapper adds no version-specific emulation. Native finite MCP calls remain outside the current integration: existing validation rejects non-help `mcp`, and inner identity, cross-session locking, secret presentation, and image delivery are unresolved. See the [capability guide](COMMAND_REFERENCE.md#upstream-0410-rebaseline) and [MCP boundary](TOOL_CONTRACT.md#native-mcp-boundary).
+
 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.
 
+The build keeps the complete emitted checkout tree, with its shared module-owned
+process environment and temporary-artifact cleanup state. Only the canonical
+`dist/extensions/agent-browser/index.js` is replaced by its bundle; the worker and
+all emitted libraries remain untouched. Six private package-only helper bundles
+live under `dist/packaged/lib/`: config policy, offline session conversion, parsing,
+playbook, snapshot, and runtime. npm publishes those helpers, the canonical extension,
+and the unchanged permissioned worker through exact `package.json` paths. CLI imports
+use the private packaged helpers; package imports stay external, including optional
+Pi peers. GitHub/source installs retain the same `prepare` build.
+
 ## Chosen shape
 
 ### Compact tools and native discovery
 
 `agent_browser` accepts native argv/stdin, result output path, timeout, and session mode. `agent_browser_code` accepts strict JSON source plus optional parent-selected session/namespace, timeout, and output path. Both use one ordinary CLI executor. Use direct calls for one action, native batch for fixed sequences, and code for branches, loops, or aggregation; return to the model at judgment boundaries.
 
+`orchestration/batch-stdin.ts` owns exact native batch-option filtering and raw-argument-over-stdin selection. Indexed `--omit-command` receipts regain their original-plan command at the native observation boundary, before existing lifecycle, ref, artifact, and redaction reducers. Skipped empty stdin rows retain their native indexes; prepared artifact requests use compact returned-row positions. Recording recovery uses those compact positions for artifact attribution and later-recording actions, preserving unrelated step evidence. Presentation uses index-only public receipts and spills. Canonical finish events retain already-redacted attribution before `BrowserCommandResult.complete` removes reconstructed commands from public per-step details; there is no second replay cache.
+
 `agent_browser_tools` inventories/enables five flat specialized tools: action, QA, Electron, UI source, and network source. `lib/tool-surface.ts` registers them once and adds them through Pi's native active-tool API, preserving unrelated tools, explicit host selections, and native selected-tool history. The five advanced direct tools use native `defaultActive: false`, not deferred registration. A narrow additive fallback restores transcript-enabled advanced tools on official Pi 1.0 initial resume, whose SDK bypasses native restoration by supplying initial tool names. It does not deactivate explicit/defaultTools selections or widen filtered catalogs/CLI allowlists; loader, tree and reload retain native selection semantics. It owns no parallel activation journal. QA verdicts, unique accessible select, host Electron lifecycle, and bounded source scans remain specialized capabilities rather than being reduced to raw-command approximations. The former public job DSL and isolated script route are removed.
 
 Optional `agent_browser_web_search` remains separately credential/config gated and independent of browser state.
@@ -36,9 +50,10 @@ 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
+- bound native process-identity queries at ten seconds on Windows, including PowerShell startup, and five seconds on POSIX. Linux runs no helper: it stores `linux-proc-boot-ticks-v1:` identities from the kernel boot ID and the boot-relative start ticks in `/proc/<pid>/stat`, which the kernel records once at fork, so wall-clock steps, timezone, and locale cannot impersonate PID reuse. Other POSIX `ps` probes, including Android/Termux, inherit the subprocess environment except for `TZ=UTC0` and `LC_ALL=C`, and store `posix-ps-utc-v1:`-qualified start times so timezone or locale changes cannot impersonate PID reuse. Termux's `ps` adds start ticks to its packaged boot time because Android denies apps `/proc/stat`, so those start times do not follow wall-clock steps. Windows retains invariant UTC ticks. Only identities of the same native format are compared; an untagged or other-format record is unknown, never proof of reuse. 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
+- treat unqualified persisted POSIX start times as incomparable to qualified UTC identities, not proof of a dead or matching owner. Still-live execution claims remain blocking until their owner releases or exits; stale-root cleanup retains ambiguous live roots, and restored Electron cleanup refuses to signal an unverified process or remove its profile. No local timestamp translation is attempted. Older running releases compare start times as exact strings and therefore read qualified identities as reused PIDs. Their cleanup can remove a newer process's unpublished claim candidate, which fails that call before any browser command runs, and its published claims older than 30 minutes, which lets another process acquire that identity while the long operation is still running. Restart every Pi process that loads the extension when upgrading. Daemon-generation comparison keeps PID/socket identity separate from the start-identity comparison. Incomparable saved/current start formats invalidate refs without declaring a live daemon cold or reopening its URL; only a positive match restores daemon provenance. Comparable changes still invalidate refs and detect replacement
 - 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
+- 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 numeric `close` codes then wrapper timeout (`124`) over the observed `exit` fallback (`ChildCompletion` / `resolveSpawnedChildExitCode` in `extensions/agent-browser/lib/process-child.ts`) so the tool cannot hang after the CLI process has already terminated. Signal-only termination maps to `128 + signal number`, never success; the observed signal is retained separately through public details. A nonzero process without an envelope reports its status and redacted stderr as an upstream failure rather than hiding them behind the secondary parse diagnostic
 - 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
 - support optional top-level `timeoutMs` as a per-call subprocess watchdog override for browser CLI input modes while Electron uses its flat action-specific timeout and code uses a whole-cell deadline
@@ -54,13 +69,15 @@ Limits are 25 attempted calls, 64 KiB source/final JSON, 1 MiB per IPC message,
 
 ### Ordered transitions and shared execution
 
-`lib/managed-session-policy-lock.ts` supplies cooperating-process execution coordination keyed by the **actual socket context**, canonical namespace, and session, separate from existing managed-daemon policy checks. The lock spans direct helper/action/state work and an entire code cell. Fresh replacement and multi-identity cleanup acquire sorted identity sets; namespace-wide direct close uses an exclusive namespace barrier. `lib/orchestration/execution-queue.ts` owns the existing local managed/artifact queues and keyed namespace barriers; branch-generation checks still protect in-process ownership/replay. Independent identities remain concurrent. Direct calls bound coordination waits using the existing configured/command-aware timeout, then retain their native subprocess and Electron action watchdogs. Code owns a whole-cell deadline, including local queue waits. Independently bounded cleanup can borrow an already-held covered claim after cancellation, but cannot acquire a new identity or release the outer claim.
+`lib/managed-session-policy-lock.ts` supplies cooperating-process execution coordination keyed by the **actual socket context**, canonical namespace, and session, separate from existing managed-daemon policy checks. The lock spans direct helper/action/state work and an entire code cell. Fresh replacement and multi-identity cleanup acquire sorted identity sets; namespace-wide direct close uses an exclusive namespace barrier. `lib/orchestration/execution-queue.ts` owns the existing local managed/artifact queues and keyed namespace barriers; branch-generation checks still protect in-process ownership/replay. Independent identities remain concurrent. Direct calls bound coordination waits using the existing configured/command-aware timeout, then retain their native subprocess and Electron action watchdogs. Code owns a whole-cell deadline, including local queue waits. Coordination deadlines and process-identity probe budgets are `performance.now()` timestamps, so system clock steps neither expire nor extend those waits. Electron launch readiness budgets, failed-launch SIGTERM grace, `electron.cleanup` process-exit windows, web-search request spacing, and managed-session close phase times use the same clock. Persisted claim and file timestamps stay wall-clock. Independently bounded cleanup can borrow an already-held covered claim after cancellation, but cannot acquire a new identity or release the outer claim.
+
+Waiting does not re-query a live owner on every poll. Outside native Windows, `lib/browser-execution-claim-endpoint.ts` has each claim owner listen on a local socket named for its claim token in the per-user coordination directory before it publishes a ticket, and close it after removing the claim. The kernel closes the socket when the owner exits, and close-on-exec keeps it out of child processes. A contender blocked by a published claim whose owner identity it has just confirmed connects once and sleeps until that connection closes, instead of querying the owner's process identity every 10 ms. Every wake, including a failed connection, re-runs the normal arbitration. Ticketless (still choosing) or unverifiable predecessors, owners whose endpoint is unavailable (it failed to listen, or the waiter's one connection attempt failed), including paths beyond the platform's Unix socket limit, and native Windows keep the 10 ms polling with fresh identity checks. On Windows, a busy named-pipe connect can hold a libuv worker for up to 30 seconds. Dead-claim cleanup removes the leftover socket name with the claim.
 
-All participating Pi processes must restart with the updated package. The lock is not a browser transaction, rollback, or a guarantee against humans, third-party native clients, older extensions, or separately named sessions attached to one external Chrome. Separate tool calls still need workflow coordination.
+All participating Pi processes must restart with the updated package; `/reload` can retain previously loaded compiled code, and mixed versions are outside the coordination guarantee. The lock is not a browser transaction, rollback, or a guarantee against humans, third-party native clients, older extensions, or separately named sessions attached to one external Chrome. Separate tool calls still need workflow coordination.
 
 `lib/browser-transcript.ts` defines one canonical `data.event` format and optional once-stored `data.snapshot`. Direct, advanced, code and Electron host operations record begin/finish receipts before dispatch and after observed effects, using outer tool-call ID plus inner index and a unique operation ID. The shared page reducer retains an inaccessible candidate during unresolved work and requires explicit reuse/replace/invalidate/unknown disposition. Ordinary results omit unchanged maps and unrelated artifact receipts; journal events carry redacted artifact-row changes in commit order. Final rendering queues actual spill writes and manifest publication, allowing unrelated small observations to finish while another namespace holds its artifact/lifecycle operation. `lib/orchestration/browser-run/artifact-merge.ts` preserves concurrent three-way manifest updates and recording lifecycle order. Native lifecycle evidence is retained before presentation/export. Failed begin blocks dispatch; failed finish stops dependent work and requires inspection without mutation replay. A named persistent journal requires actual publication even before Pi's first conversation. Disabled/no-file sessions use the native current in-memory ancestry for direct browser work without claiming durability; code still requires a published intent journal. Observation-only artifact receipts are optional without a published journal, so sessionless local results retain complete redacted private spills and selected files. Code lifecycle joins include outer finalization, and the shared generation guard keeps prior-branch observation spills process-private and prevents their artifact publication onto the new branch. JavaScript variables are never persisted.
 
-`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official 1.0.0 still eagerly loads native history before extension startup. Legacy adapters live only in `lib/browser-session-conversion.ts`, which publishes a validated stopped separate copy while retaining the source. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
+`lib/browser-journal.ts` token-projects published envelopes and ancestry through public Pi file/header/leaf APIs, loading only winning snapshot definitions. Replay retains one structural prefix per native manager/header and published file identity, reusing unchanged metadata or validating only appended bytes. Rotation, truncation, native reseed, same-size timestamp changes and failures fall back to full validation. Selected event and winning snapshot bodies are reread; this append-only index is neither a ref cache nor a replacement for publication receipts. It captures the selected leaf before asynchronous reads and validates that same branch through public `getEntry()` ancestry on both hosts. Capture-local admission reuses a validated append-only prefix while checking endpoint identity/parent and new suffixes; publication/durability checks remain independent. Startup/tree restoration uses one queued captured replay for branch state and cleanup leases, with one per-session launch-configuration fold. Stock official 1.0.0 still eagerly loads native history before extension startup. `lib/browser-legacy-projection.ts` and its shared field projection normalize historical receipts read-only into this same canonical reducer at the journal boundary. Normal resume keeps the original bytes and locator; mixed-format ancestry, confirmation settings/provenance and cleanup ownership remain branch-relative. Non-winning legacy maps are discarded after each receipt. Native event validation cannot downgrade to the legacy path. `lib/browser-session-conversion.ts` reuses that decoder only when an operator explicitly requests a validated stopped separate archive copy. Native generation checks use PID/start and socket identity, never saved URL or delta revision alone. Filtered/helper captures share this check. Small owner-qualified launch receipts retain observed restore-key provenance; restart verifies the current native generation and key before treating that provenance as live. Full storage, migration and consumer-memory boundaries are documented in [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
 
 ### Canonical observations and image geometry
 
@@ -144,7 +161,7 @@ The optional `pi-change-working-dir` event protocol supplies one invocation exec
 
 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.
+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. `native-session-defaults.ts` resolves the root for direct and code calls: a pi-subagents child uses its equal, unpadded `PI_INTERCOM_ROOT_SESSION_ID`/`PI_INTERCOM_PARENT_SESSION_ID` (older releases: `PI_SUBAGENT_CHILD=1` with `PI_SUBAGENT_ROOT_SESSION_ID`); other 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:
 
@@ -185,7 +202,7 @@ Ownership rule:
 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
+- close the active extension-managed session when the originating `pi` process quits, while leaving explicit caller-provided sessions alone; a managed fork restart is not a quit (see below)
 - 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.
 - set an idle timeout on extension-managed sessions as a backstop for abnormal exits or cleanup failures, and apply that same `AGENT_BROWSER_IDLE_TIMEOUT_MS` value to every subprocess targeting that owned session (including wrapper helper snapshots, tab lists, and navigation-summary reads); caller-owned sessions instead retain native config/environment idle policy because changing the launch environment between calls can make upstream restart the background browser, discard the active tab, and invalidate fresh refs
 - for wrapper-owned implicit sessions only, set a transcript- and checkout-scoped `AGENT_BROWSER_RESTORE` key on compatible calls so cookies and web storage can survive idle shutdown, reload, and resume. Explicit caller sessions, restore/state choices, profiles, upstream config, file access, launch arguments, environment variables, local pages, output paths, and close arguments remain upstream-owned and pass through unchanged. `piab-*` names are not reserved; session/state lists and restore identifiers are not filtered or redacted. The wrapper validates only its automatic restore checkout/storage identity and coordinates same-daemon reuse so its own restore pools cannot mix. Ambiguous page-target transitions still require live `get url` verification before content calls. The current v4 set-valued ticket-claim lock is the only managed-daemon coordination protocol; no earlier lock bridge or compatibility path remains. Successful lock acquisition opportunistically inspects at most eight current-protocol candidates/removal artifacts/claims under the existing acquisition deadline (single-attempt `timeoutMs: 0` probes retain their existing no-deadline behavior). Published claims must be at least 30 minutes old, valid, and owned by a proven-dead process before rename/revalidation removal; contention still immediately reclaims proven-dead overlapping claims. Legacy or ambiguous claims remain untouched. Secure-temp allocation similarly inspects at most eight roots per call, retaining the 24-hour lease floor, dead-owner proof and protected Electron children. A randomized first window avoids a fixed retained prefix across short-lived processes; subsequent calls rotate in process. Cross-process progress is probabilistic, not a guaranteed number of calls. Listing/sorting still covers the whole directory; these are work-count bounds, not hard wall-clock deadlines.
@@ -197,11 +214,12 @@ 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
+- on a managed fork restart (`pi restart`/`/restart`: `session_shutdown` reason `quit` with `disposition: "handoff"` for a committed restart or `"provisional"` for an unready replacement that may roll back), transfer ownership instead of quitting. Re-read the active branch and keep every owned managed identity the replacement worker's `session_start` restore reclaims (branch-active identities including non-current ones, the current session, and interrupted owned intents); keep active branch-visible Electron launches and persistently protect their isolated `userDataDir` paths through process exit; close only owned managed sessions and Electron launches the replacement cannot restore, as on `/reload`. Live page JavaScript, unsaved forms, and in-progress recordings therefore continue in the same browser. `disposition: "release"` and an absent disposition (official Pi, SDK, print, RPC, and older launchers) keep quit cleanup; if the branch cannot be read at shutdown, only the current session is kept, as on `/reload`
 - 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
-- leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly, but before any DOM/content-bearing read or interaction against a caller-owned explicit session, live-probe that session with `get url` instead of trusting missing or stale transcript page state; hold the effective canonical namespace/session queue from that probe through semantic snapshot resolution and the main command so another cooperating updated Pi call cannot change tabs in between. Non-bail batch analysis retains every possible page left by a failed transition up to a fixed bound and blocks later content only when the target is unverified; exceeding the bound also fails closed to exact `batch --bail` guidance. Nested `batch` steps remain unsupported, and raw batch command strings mirror upstream's ASCII-space tokenizer, including quote/backslash handling, rather than splitting on other Unicode whitespace.
+- leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly, but before any DOM/content-bearing read or interaction against a caller-owned explicit session, live-probe that session with `get url` instead of trusting missing or stale transcript page state, unless the call carries browser launch flags and the explicit-local `session info` observation shows no running daemon (remembered-tab selection and page probes must both wait for the requested command to launch the browser with those flags, including after transcript reload; namespace and idle timeout already reach helpers). Preserve the validated dispatch guard inputs, then retire the stopped browser's tab identity and refs in output reconciliation. A successful command observes the replacement URL/tab; otherwise the target remains unknown, with the normal ordered ref invalidation and replay. The native command determines the replacement page, not the stopped browser's remembered URL: caller-owned sessions are not automatically reopened or reselected. A bootstrap-only URL/title observation establishes that new target without adding navigation or mutation evidence to a read-only native result. Hold the effective canonical namespace/session queue from that probe through semantic snapshot resolution and the main command so another cooperating updated Pi call cannot change tabs in between. Non-bail batch analysis retains every possible page left by a failed transition up to a fixed bound and blocks later content only when the target is unverified; exceeding the bound also fails closed to exact `batch --bail` guidance. Nested `batch` steps remain unsupported, and raw batch command strings mirror upstream's ASCII-space tokenizer, including quote/backslash handling, rather than splitting on other Unicode whitespace.
 - after profiled `open` / `goto` / `navigate` calls, verify the active tab still matches the returned page URL and best-effort switch back when restored profile tabs steal focus
 - 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
@@ -221,7 +239,7 @@ This is primarily about ownership clarity and avoiding surprise, not adding a he
 
 ### Lifecycle boundary
 
-Native Pi lifecycle callbacks and existing queues retain ownership-aware shutdown/reload behavior. Shared root and caller-owned browsers are not closed on Pi quit; wrapper-owned managed/fresh and Electron resources keep UUID/branch-qualified cleanup. An ordinary session fork does not inherit its parent's cleanup rights. Close or clean up owned resources before disabling/removing the extension: native reload after removal has no browser handover guarantee. Forced concurrent SDK reload and recovery after failed off-branch cleanup are not fully qualified lifecycle guarantees.
+Native Pi lifecycle callbacks and existing queues retain ownership-aware shutdown/reload/restart behavior. Shared root and caller-owned browsers are not closed on Pi quit; wrapper-owned managed/fresh and Electron resources keep UUID/branch-qualified cleanup. An ordinary session fork does not inherit its parent's cleanup rights. Close or clean up owned resources before disabling/removing the extension: native reload after removal has no browser handover guarantee. Forced concurrent SDK reload and recovery after failed off-branch cleanup are not fully qualified lifecycle guarantees.
 
 Native close/save and explicit URL reopen remain the persistence path, not a live browser snapshot. Page JavaScript, unsaved forms, history, IndexedDB and live recordings are not serialized by this extension. Neither supported Pi 1.0 target uses Browser checkpoint or fork metadata/revision hooks; retained legacy journal decoding remains confined to stopped-copy conversion.
 
@@ -247,7 +265,8 @@ Implementation detail lives in `extensions/agent-browser/lib/launch-scoped-flags
 - **Command discovery:** Leading argv is scanned with a value-taking allowlist so known global flags and documented command flags consume their values before the upstream command word is identified. Missing-value prevalidation is intentionally limited to upstream global value flags; command-scoped flags and literal text are left to upstream parsing so values like `fill #field --password` are not rejected by wrapper heuristics before the CLI sees them. Upstream 0.35.0 and newer accept `--restore=<key>` but reject other global `--flag=value` tokens during normal command execution, so the wrapper rejects those unsupported assignments before they can be mistaken for command or artifact operands. Plain help/version inspection preserves exact caller argv because upstream accepts those top-level shapes. Nested batch rows do not parse global flags, so their equals forms never receive the top-level inspection or restore exceptions. When upstream adds new global flags that take values ahead of the command, extend both the command-discovery and prevalidation allowlists; when it adds command-specific flags, extend only command discovery/redaction as needed. A smaller set of global boolean flags may be followed by an optional `true`/`false` literal; when present, that literal is consumed as the flag value before command discovery continues.
 - **`--state` disambiguation:** Persisted browser `--state` before the command participates in launch-scoped validation and tab-correction hints. The same flag spelling after a `wait` command is excluded from startup-scoped detection so upstream help examples such as `wait @ref --state hidden` do not spuriously require `sessionMode: "fresh"` while an implicit session is active. As of the current upstream baseline, the parser still does not implement those `wait --state` examples as distinct wait modes, so agent-facing docs recommend `wait --fn` predicates for disappearance checks instead.
 - **`--auto-connect`:** Treated as launch-scoped only when enabled (`--auto-connect` bare or `true`). `--auto-connect false` is ignored for startup-scoped blocking so disabled attach hints do not force a fresh launch.
-- **`--engine`:** Treated as launch-scoped for Chrome and Lightpanda, using the same fresh-session recovery instead of letting native engine changes replace a running managed page. Caller-owned sessions remain native-owned. Chrome stays default; Lightpanda is opt-in with no bundle, second driver, emulation or automatic fallback. See [engine limits](COMMAND_REFERENCE.md#lightpanda-engine).
+- **`--engine`:** Treated as launch-scoped for Chrome, Lightpanda, and experimental Obscura, using the same fresh-session recovery instead of letting native engine changes replace a running managed page. Caller-owned sessions remain native-owned. Chrome stays default; alternative engines are opt-in with no bundle, second driver, emulation or automatic fallback. Non-Chrome engines omit wrapper Chrome bootstrap defaults. See [Lightpanda](COMMAND_REFERENCE.md#lightpanda-engine) and [Obscura limits](COMMAND_REFERENCE.md#obscura-engine-experimental).
+- **CLI HTTPS trust:** `--use-system-ca` is a native optional boolean, not a browser launch flag. Alongside `--ca-cert`, `AGENT_BROWSER_USE_SYSTEM_CA`, and fallback `SSL_CERT_FILE`, it configures CLI requests from read/install/upgrade/doctor. Native owns per-session read trust and verification; the wrapper only strips the global option for command discovery and passes caller argv/environment through. Browser CA trust remains a separate Linux Chromium launch setting. A native `outcome_unknown` failure after a lost mutating response is inspection-only evidence, never grounds for wrapper replay.
 - **`--webgpu`:** Treated as launch-scoped for both enabled and explicit `false` values. Enabled WebGPU selects upstream's platform-specific local-launch preset; explicit false can override an environment/config default and still belongs to a fresh browser launch. Upstream rejects enabled WebGPU with CDP, auto-connect, or provider launches.
 - **`--no-webmcp`:** Treated as launch-scoped for bare/`true` and explicit `false` values because it selects whether upstream 0.36.0 enables experimental WebMCP for a locally managed Chrome launch.
 - **`--headed`:** Treated as launch-scoped for both enabled and explicit `false` values so a visible-window choice cannot be silently ignored by an already-running managed session.

package/docs/CODE_QUALITY.md

@@ -26,12 +26,18 @@ relaxations require concrete evidence and explicit approval.
 | `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                                          |
+| `npm run quality:mutations`        | Require clean acceptance, then prove the real workflow rejects syntax, semantic, compiler, formatting, and allowance-isolation mutations in disposable copies, diagnostics surviving log shortening    |
 
 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.
 
+The default, quality, pre-pr, platform-target, and release facades run scope and
+suppression-policy validation once through `lint`, before the corrected checker.
+Standalone `quality:policy` and `quality:scope` remain available for focused
+inspection and intentional scope regeneration; running them separately in the
+facade would repeat the same validation without adding coverage.
+
 ### Test scheduling
 
 `npm test` builds once and prepares the corrected checker once, then runs
@@ -41,18 +47,34 @@ The default/quality verification gates use the same two stages. File isolation
 keeps environment patches process-local; the shared browser harness supplies a
 private short socket directory unless `PI_AGENT_BROWSER_SOCKET_DIR` is already set.
 The harness also clears inherited Pi/delegation identity variables; root-default
-tests set their identities explicitly after import. No in-file concurrency is enabled.
+tests set their identities explicitly after import. Its default Pi ID is generated once
+per file worker, remaining stable across that worker's harness/reload/resume instances.
+Independent Windows fake browsers must also use distinct explicit session/namespace
+identities: native Windows coordination ignores private socket roots. Namespace-wide
+`close --all` fixtures use private namespaces unless the literal default namespace is
+the contract under test. Do not isolate identical native identities by changing their
+coordination directory or relaxing lock checks. No in-file concurrency is enabled.
 
 The serial lane contains `test/agent-browser.startup.serial.test.ts` and
 `test/agent-browser.prompt-policy.serial.test.ts` for wall-clock budgets, plus
-`test/agent-browser.managed-session-policy-lock.serial.test.ts` for fixtures in
-the shared policy collector directory. Their timing and global-GC contracts must
-not compete with the parallel lane. Build/pack fixtures must use disposable source trees rather
+`test/agent-browser.managed-session-policy-lock.serial.test.ts` for cross-process
+lock contracts in the shared policy collector directory. Every process's opportunistic
+GC, including other test runs and Pi sessions, reclaims proven-dead artifacts there, so
+GC rule tests run the production sweep on private directories and shared-directory
+fixtures stay live or young. `test/agent-browser.extension-validation-coordination.serial.test.ts`
+retains genuine default-namespace close-all contention and recording ownership cases;
+uniquely namespaced contention cases stay parallel. Their timing, namespace-wide and
+global-GC contracts must not compete with the parallel lane. Build/pack fixtures must use disposable source trees rather
 than rewriting this checkout's `dist/` while other files consume it.
 `platform-target` retains its explicit serial subset; `quality:probes` remains a
 focused serial checker suite. The allowance-isolation mutation must fail in the
 parallel stage with its named `code-quality.test.ts` diagnostic.
 
+The real prepare/pack fixture in `test/verify-package.test.ts` also runs a plain
+Node child against emitted checkout modules. It verifies shared process-environment
+session/namespace propagation and snapshot-spill cleanup through the imported temp
+owner; source-loaded tests cannot detect bundles overwriting these shared modules.
+
 ## Language and role scope
 
 The root `.oxlintrc.json` enables type-aware rules and compiler diagnostics. The
@@ -121,6 +143,11 @@ 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.
+The compiler submodule update and patch application use Git's command-scoped
+`core.longpaths=true` so Git for Windows can materialize and inspect the pinned
+compiler's long test-data paths during checkout and `git am` index refresh. This
+setting is not persisted to repository, user, or system Git configuration;
+compiler revision checks, patch verification, and cache integrity remain unchanged.
 
 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