pi-agent-browser-native 0.2.61 → 0.2.62

package/dist/extensions/agent-browser/lib/results/presentation/batch.js

@@ -5,7 +5,7 @@ import { formatSessionArtifactRetentionSummary } from "../artifact-manifest.js";
 import { classifyAgentBrowserFailureCategory } from "../categories.js";
 import { detectConfirmationRequired } from "../confirmation.js";
 import { applyNetworkRouteRecords, buildNetworkRouteDiagnostics } from "../network-routes.js";
-import { withOptionalSessionArgs } from "../next-actions.js";
+import { applyNamespaceToNextActions, withOptionalSessionArgs } from "../next-actions.js";
 import { stringifyModelFacing } from "./common.js";
 import { buildArtifactVerificationSummary, classifyPresentationSuccessCategory, manifestHasNewNoticeWorthyEntries } from "./artifacts.js";
 import { formatBatchStepCommand, getPresentationImages, getPresentationPaths, getPresentationText, isStringArray } from "./content.js";
@@ -181,7 +181,7 @@ function formatBatchStepsText(steps) {
     return lines.join("\n\n");
 }
 async function buildBatchStepPresentation(options) {
-    const { artifactManifest, artifactRequest, buildNestedToolPresentation, cwd, index, item, networkRoutes, persistentArtifactStore, sessionName } = options;
+    const { artifactManifest, artifactRequest, buildNestedToolPresentation, cwd, index, item, namespace, networkRoutes, persistentArtifactStore, sessionName } = options;
     const command = isStringArray(item.command) ? item.command : undefined;
     const redactedCommand = command ? redactInvocationArgs(command) : undefined;
     const commandText = formatBatchStepCommand(hasModelFacingArgRedaction(redactedCommand) ? redactedCommand : command, index);
@@ -196,13 +196,13 @@ async function buildBatchStepPresentation(options) {
             errorText,
         });
         const confirmationRequired = detectConfirmationRequired(item.error);
-        const nextActions = mergePresentationNextActions(buildAgentBrowserNextActions({
+        const nextActions = applyNamespaceToNextActions(mergePresentationNextActions(buildAgentBrowserNextActions({
             args: command,
             command: command?.[0],
             confirmationId: confirmationRequired?.id,
             failureCategory,
             resultCategory: "failure",
-        }), isWaitTextAssertionCommand(command) ? [buildWaitTextAssertionFailureNextAction(sessionName)] : undefined);
+        }), isWaitTextAssertionCommand(command) ? [buildWaitTextAssertionFailureNextAction(sessionName)] : undefined), namespace);
         const presentation = {
             content: [{ type: "text", text: errorText }],
             failureCategory,
@@ -254,7 +254,7 @@ async function buildBatchStepPresentation(options) {
     });
     const text = getPresentationText(presentation) || presentation.summary;
     const stepSucceeded = presentation.resultCategory !== "failure";
-    const nextActions = presentation.nextActions ?? buildAgentBrowserNextActions({
+    const nextActions = applyNamespaceToNextActions(presentation.nextActions ?? buildAgentBrowserNextActions({
         artifacts: presentation.artifacts,
         args: command,
         command: command?.[0],
@@ -262,7 +262,7 @@ async function buildBatchStepPresentation(options) {
         resultCategory: stepSucceeded ? "success" : "failure",
         savedFilePath: presentation.savedFilePath,
         successCategory: presentation.successCategory,
-    });
+    }), namespace);
     const pageChangeSummary = buildPageChangeSummary({
         artifacts: presentation.artifacts,
         commandInfo: commandInfoWithTokens,
@@ -299,7 +299,7 @@ async function buildBatchStepPresentation(options) {
     };
 }
 export async function buildBatchPresentation(options) {
-    const { artifactRequests, buildNestedToolPresentation, cwd, data, networkRoutes, persistentArtifactStore, sessionName, summary } = options;
+    const { artifactRequests, buildNestedToolPresentation, cwd, data, namespace, networkRoutes, persistentArtifactStore, sessionName, summary } = options;
     const steps = [];
     const protectedPersistentPaths = [];
     let currentArtifactManifest = options.artifactManifest;
@@ -312,6 +312,7 @@ export async function buildBatchPresentation(options) {
             cwd,
             index,
             item,
+            namespace,
             networkRoutes: currentNetworkRoutes,
             persistentArtifactStore: persistentArtifactStore ? { ...persistentArtifactStore, protectedPaths: protectedPersistentPaths } : undefined,
             sessionName,

package/dist/extensions/agent-browser/lib/results/presentation.js

@@ -37,7 +37,7 @@ function shouldAddAnnotatedScreenshotGuidance(commandInfo, args) {
     return commandInfo.command === "screenshot" && (args?.includes("--annotate") ?? false);
 }
 export async function buildToolPresentation(options) {
-    const { args, artifactManifest, artifactRequest, commandInfo, compiledSemanticAction, cwd, envelope, errorText, networkRouteDiagnostics, networkRoutes, persistentArtifactStore, sessionName, } = options;
+    const { args, artifactManifest, artifactRequest, commandInfo, compiledSemanticAction, cwd, envelope, errorText, namespace, networkRouteDiagnostics, networkRoutes, persistentArtifactStore, sessionName, } = options;
     const commandInfoWithTokens = commandInfo.commandTokens || !args ? commandInfo : { ...commandInfo, commandTokens: extractCommandTokens(args) };
     const presentationCommandInfo = resolvePresentationCommandInfo(commandInfoWithTokens, compiledSemanticAction);
     if (errorText) {
@@ -58,6 +58,7 @@ export async function buildToolPresentation(options) {
             buildNestedToolPresentation: buildToolPresentation,
             cwd,
             data,
+            namespace,
             networkRoutes,
             persistentArtifactStore,
             sessionName,

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

@@ -10,7 +10,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from "./argv-descriptor.js";
-import { GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, PREVALIDATED_VALUE_FLAGS, } from "./argv-grammar.js";
+import { GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, PREVALIDATED_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
 import { isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
 import { LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, LAUNCH_SCOPED_TAB_CORRECTION_FLAGS } from "./launch-scoped-flags.js";
@@ -326,18 +326,22 @@ export function getImplicitSessionCloseTimeoutMs(env = process.env) {
     return parseTimeoutMs(env[IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV], 0) ?? DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS;
 }
 export function resolveManagedSessionState(options) {
-    const { command, managedSessionName, priorActive, priorSessionName, succeeded } = options;
+    const { command, managedSessionName, managedSessionNamespace, priorActive, priorNamespace, priorSessionName, succeeded } = options;
     if (!managedSessionName) {
-        return { active: priorActive, sessionName: priorSessionName };
+        return { active: priorActive, ...(priorNamespace ? { namespace: priorNamespace } : {}), sessionName: priorSessionName };
     }
     if (isCloseCommand(command) && managedSessionName === priorSessionName) {
-        return { active: succeeded ? false : priorActive, sessionName: priorSessionName };
+        if (managedSessionNamespace !== priorNamespace)
+            return { active: priorActive, ...(priorNamespace ? { namespace: priorNamespace } : {}), sessionName: priorSessionName };
+        const namespace = succeeded ? undefined : priorNamespace;
+        return { active: succeeded ? false : priorActive, ...(namespace ? { namespace } : {}), sessionName: priorSessionName };
     }
     if (!succeeded) {
-        return { active: priorActive, sessionName: priorSessionName };
+        return { active: priorActive, ...(priorNamespace ? { namespace: priorNamespace } : {}), sessionName: priorSessionName };
     }
     return {
         active: true,
+        ...(managedSessionNamespace ? { namespace: managedSessionNamespace } : {}),
         replacedSessionName: priorActive && priorSessionName !== managedSessionName ? priorSessionName : undefined,
         sessionName: managedSessionName,
     };
@@ -395,13 +399,13 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
     let closedSessionName;
     let freshSessionOrdinal = 0;
     const freshSessionRanks = new Map();
-    const applyManagedClose = (sessionName) => {
+    const applyManagedClose = (sessionName, namespace) => {
         const restoreRank = getManagedSessionRestoreRank({
             fallbackSessionName,
             freshSessionRanks,
             sessionName,
         });
-        if (restoreRank === undefined || sessionName !== restoredState.sessionName)
+        if (restoreRank === undefined || sessionName !== restoredState.sessionName || namespace !== restoredState.namespace)
             return;
         restoredState = { active: false, sessionName: restoredState.sessionName };
         closedSessionName = sessionName;
@@ -427,6 +431,7 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         }
         const explicitSessionName = extractExplicitSessionName(args);
         const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
+        const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
         const sessionMode = details.sessionMode === "fresh" || details.sessionMode === "auto" ? details.sessionMode : undefined;
         const usedImplicitSession = details.usedImplicitSession === true;
         const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
@@ -468,7 +473,7 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         const succeeded = outcomeRepresentsActiveCurrentSession ? true : messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
         if (commandClosesSession) {
             if (succeeded)
-                applyManagedClose(managedSessionName);
+                applyManagedClose(managedSessionName, namespace);
             continue;
         }
         const staleCompletion = succeeded && restoreRank < activeRestoreRank;
@@ -478,7 +483,9 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         restoredState = resolveManagedSessionState({
             command,
             managedSessionName,
+            managedSessionNamespace: namespace,
             priorActive: restoredState.active,
+            priorNamespace: restoredState.namespace,
             priorSessionName: restoredState.sessionName,
             succeeded,
         });
@@ -720,6 +727,31 @@ export function extractExplicitSessionName(args) {
     }
     return undefined;
 }
+export function extractExplicitNamespace(args) {
+    for (const [index, token] of args.entries()) {
+        if (token === "--namespace") {
+            return args[index + 1];
+        }
+        if (token.startsWith("--namespace=")) {
+            return token.slice("--namespace=".length);
+        }
+    }
+    return undefined;
+}
+function stripExplicitNamespaceArgs(args) {
+    const stripped = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--namespace") {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--namespace="))
+            continue;
+        stripped.push(token);
+    }
+    return stripped;
+}
 function hasLaunchScopedFlagToken(args, flag) {
     const commandStartIndex = findCommandStartIndex(args);
     const command = commandStartIndex === undefined ? undefined : args[commandStartIndex];
@@ -728,6 +760,8 @@ function hasLaunchScopedFlagToken(args, flag) {
             return false;
         if (flag === "--auto-connect")
             return isBooleanFlagEnabled(args, flag);
+        if (flag === "--restore" && token === "--restore" && optionalGlobalValueFlagConsumesNext(flag, args[index + 1]))
+            return true;
         if (flag === "--state" && command === "wait" && commandStartIndex !== undefined && index > commandStartIndex) {
             return false;
         }
@@ -750,13 +784,15 @@ export function hasLaunchScopedTabCorrectionFlag(args) {
 }
 export function buildExecutionPlan(args, options) {
     const invalidValueFlag = getInvalidValueFlagDetails(args);
-    const startupScopedFlags = getStartupScopedFlags(args);
+    const explicitNamespace = extractExplicitNamespace(args);
+    const startupScopedFlags = getStartupScopedFlags(args).filter((flag) => !(flag === "--namespace" && explicitNamespace === options.managedSessionNamespace));
     const plainTextInspection = isPlainTextInspectionArgs(args);
     const argvDescriptor = parseArgvDescriptor(args);
     const commandTokens = argvDescriptor.commandTokens;
     const commandInfo = argvDescriptor.commandInfo;
     const commandNeedsManagedSession = !plainTextInspection && needsManagedSession(argvDescriptor);
     const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
+    let namespace = explicitNamespace;
     if (invalidValueFlag) {
         return {
             commandInfo: {},
@@ -772,6 +808,7 @@ export function buildExecutionPlan(args, options) {
         return {
             commandInfo,
             effectiveArgs,
+            namespace,
             plainTextInspection,
             startupScopedFlags,
             usedImplicitSession: false,
@@ -779,7 +816,12 @@ export function buildExecutionPlan(args, options) {
     }
     const explicitSessionName = extractExplicitSessionName(args);
     const shouldCreateFreshManagedSession = !explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && !isCloseCommand(commandInfo.command);
+    let argsToAppend = args;
     const compatibilityWorkaround = getCompatibilityWorkaround(args, commandInfo);
+    if (explicitSessionName && explicitNamespace) {
+        effectiveArgs.push("--namespace", explicitNamespace);
+        argsToAppend = stripExplicitNamespaceArgs(args);
+    }
     let managedSessionName;
     let recoveryHint;
     let sessionName = explicitSessionName;
@@ -799,26 +841,36 @@ export function buildExecutionPlan(args, options) {
             ].join(" ");
         }
         else {
+            namespace = explicitNamespace ?? options.managedSessionNamespace;
+            if (namespace)
+                effectiveArgs.push("--namespace", namespace);
             effectiveArgs.push("--session", options.managedSessionName);
+            if (explicitNamespace)
+                argsToAppend = stripExplicitNamespaceArgs(args);
             managedSessionName = options.managedSessionName;
             sessionName = options.managedSessionName;
             usedImplicitSession = true;
         }
     }
     else if (shouldCreateFreshManagedSession && commandNeedsManagedSession) {
+        if (namespace)
+            effectiveArgs.push("--namespace", namespace);
         effectiveArgs.push("--session", options.freshSessionName);
+        if (explicitNamespace)
+            argsToAppend = stripExplicitNamespaceArgs(args);
         managedSessionName = options.freshSessionName;
         sessionName = options.freshSessionName;
     }
     if (compatibilityWorkaround) {
         effectiveArgs.push("--user-agent", getDefaultHeadlessCompatUserAgent());
     }
-    effectiveArgs.push(...args);
+    effectiveArgs.push(...argsToAppend);
     return {
         commandInfo,
         compatibilityWorkaround,
         effectiveArgs,
         managedSessionName,
+        namespace,
         plainTextInspection,
         recoveryHint,
         sessionName,

package/dist/extensions/agent-browser/lib/session-page-state.js

@@ -291,6 +291,11 @@ function stripRefSnapshotOrder(snapshot) {
 function stripRefSnapshotInvalidationOrder(invalidation) {
     return invalidation ? { reason: invalidation.reason, summary: invalidation.summary } : undefined;
 }
+export function getSessionPageStateKey(sessionName, namespace) {
+    if (!sessionName)
+        return undefined;
+    return namespace ? `${namespace}\u0000${sessionName}` : sessionName;
+}
 export class SessionPageState {
     refSnapshotInvalidations = new Map();
     refSnapshots = new Map();
@@ -310,13 +315,15 @@ export class SessionPageState {
             if (!details)
                 continue;
             const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
-            if (!sessionName)
+            const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+            const sessionKey = getSessionPageStateKey(sessionName, namespace);
+            if (!sessionKey)
                 continue;
             const command = typeof details.command === "string" ? details.command : undefined;
             const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
             if (isCloseCommand(command) && message.isError !== true) {
                 restoredOrder += 1;
-                state.clearSession(sessionName);
+                state.clearSession(sessionKey);
                 continue;
             }
             const tabTarget = getRestoredSessionTabTarget(details, command, subcommand);
@@ -326,14 +333,14 @@ export class SessionPageState {
                 continue;
             restoredOrder += 1;
             if (tabTarget)
-                state.tabTargets.set(sessionName, { order: restoredOrder, target: tabTarget });
+                state.tabTargets.set(sessionKey, { order: restoredOrder, target: tabTarget });
             if (refSnapshotInvalidation) {
-                state.refSnapshots.delete(sessionName);
-                state.refSnapshotInvalidations.set(sessionName, { ...refSnapshotInvalidation, order: restoredOrder });
+                state.refSnapshots.delete(sessionKey);
+                state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
             }
             else if (refSnapshot) {
-                state.refSnapshotInvalidations.delete(sessionName);
-                state.refSnapshots.set(sessionName, { ...refSnapshot, order: restoredOrder });
+                state.refSnapshotInvalidations.delete(sessionKey);
+                state.refSnapshots.set(sessionKey, { ...refSnapshot, order: restoredOrder });
             }
         }
         state.updateOrder = Math.max(restoredOrder, getLatestTabTargetOrder(state.tabTargets), getLatestRefStateOrder(state.refSnapshots, state.refSnapshotInvalidations));

package/docs/ARCHITECTURE.md

@@ -153,9 +153,9 @@ 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 may synthesize a tiny upstream `batch` that re-selects that tab and then runs the requested command in the same upstream invocation; routine same-session commands avoid `tab list` preflights to reduce probes that can perturb upstream click behavior
 - 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 this post-command `tab list` probe
 - 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 it from persisted tool `details` when reloading, resuming, or moving to a different Pi session-tree branch, store bounded ref role/name metadata from the same snapshot for wrapper-side current-ref diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), and refuse mutation-prone `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, or when `batch` stdin would reuse `@e…` on a guarded step after an earlier invalidating step without a later `snapshot` step in the same stdin array. 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
-- for top-level non-Electron direct `click` commands, 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 is intentionally skipped for unresolved `find … click` locators and for `batch`/`job`/`qa` click steps. For `@e…` targets it only covers current refs whose latest stored `refSnapshot.refs` role is `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`; it uses that role/name metadata, including snapshot-order `duplicateIndex` for duplicate-name refs, instead of taking a fresh pre-click snapshot that could recycle upstream 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 uses that role/name metadata, including snapshot-order `duplicateIndex` for duplicate-name refs, instead of taking a fresh pre-click snapshot that could recycle upstream refs. The probe is intentionally skipped for CSS selector clicks, unresolved `find … click` locators, and `batch`/`job`/`qa` click steps
 - derive narrow prompt guards only for concrete evidence invariants: exact required screenshot paths block browser close until the artifact manifest verifies those paths. 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
-- after successful `get text` on a non-ref CSS selector, optionally issue one read-only `eval --stdin` probe per qualifying selector when multiple DOM matches or a hidden first match with visible peers could misread tabbed or off-screen content; merge `details.selectorTextVisibility` / `selectorTextVisibilityAll`, visible warning lines, and `inspect-visible-text-candidates*` next actions as documented in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) and `RQ-0074` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
+- after successful `get text` on a qualifying non-ref CSS selector, optionally issue one read-only `eval --stdin` probe per selector when multiple DOM matches or a hidden first match with visible peers could misread tabbed or off-screen content; simple id selectors and sensitive-looking literals skip this probe. Merge `details.selectorTextVisibility` / `selectorTextVisibilityAll`, visible warning lines, and `inspect-visible-text-candidates*` next actions as documented in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) and `RQ-0074` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 - for local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit
 - keep wrapper-spawned upstream CLI calls bounded by clamping `AGENT_BROWSER_DEFAULT_TIMEOUT` to the upstream documented 25-second default while deriving a longer subprocess watchdog for explicit long `wait <ms>` / `wait --timeout <ms>` calls; dialog commands, likely dialog-trigger clicks/taps/finds, and `eval --stdin` snippets that look like alert/confirm/prompt/dialog triggers use shorter wrapper subprocess budgets so blocking JavaScript prompts surface recovery actions before the full default watchdog
 
@@ -166,7 +166,7 @@ This is primarily about ownership clarity and avoiding surprise, not adding a he
 `agent-browser` startup flags are sticky once a session is already running.
 The extension should surface that clearly and avoid hidden restart behavior in v1.
 
-That means explicit startup-scoping flags like `--auto-connect`, `--cdp`, `--enable`, `--executable-path`, `--init-script`, `--device`, `--profile`, `--provider`, `-p`, `--session-name`, and `--state` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
+That means explicit startup-scoping flags like `--auto-connect`, `--cdp`, `--enable`, `--executable-path`, `--init-script`, `--device`, `--namespace`, `--profile`, `--provider`, `-p`, `--restore`, `--restore-save`, restore check flags, `--session-name`, and `--state` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
 
 The wrapper may still apply narrow compatibility normalizations when observed behavior justifies them and the result remains thin, local, and opt-out. For example, if a specific site starts rejecting the default local headless Chrome user agent while the same flow works with a normal Chrome UA, the extension may inject a domain-specific fallback UA only when the caller did not already choose `--user-agent`, `--headed`, `--cdp`, `--auto-connect`, or a provider-backed launch.
 
@@ -177,10 +177,10 @@ That failure should include a structured recovery hint pointing to `sessionMode:
 Implementation detail lives in `extensions/agent-browser/lib/launch-scoped-flags.ts` (canonical flag metadata shared with playbook/docs assertions), `extensions/agent-browser/lib/argv-descriptor.ts` and `extensions/agent-browser/lib/argv-grammar.ts` (command discovery, `VALUE_FLAGS`, `parseArgvDescriptor`) plus `extensions/agent-browser/lib/runtime.ts` (`getStartupScopedFlags`, `buildExecutionPlan`):
 
 - **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. 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 upstream `agent-browser 0.30.1`, 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.
+- **`--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.
 
-**Sessionless inspection and local commands:** Plain-text global help and version probes (`--help`, `-h`, `--version`, `-V`) must never allocate or bind the extension-managed session. The same session-ownership rule applies to read-only upstream `skills list`, `skills get …`, and `skills path …`, local auth profile management (`auth save/list/show/delete/remove`), plus local/setup surfaces such as `profiles`, `dashboard start/stop`, `device list`, `doctor`, `install`, `upgrade`, `session list`, and targeted/all local saved-state maintenance (`state list/show`, `state clear --all`, `state clear -a`, `state clear <session-name>`, `state clean --older-than <days>`, `state rename`). Non-plain-text sessionless commands still run with `--json` for machine-readable output, but the planner does not prepend the implicit managed `--session`, so an agent can inspect local capabilities or start/stop the standalone dashboard without consuming the implicit session slot before a real `open`. Browser-backed, context-dependent, or incomplete commands such as root `session`, untargeted `state clear`, bare `state clean`, `auth login`, `state save`, and `state load` keep normal managed-session injection. Command-shape allowlisting lives in `extensions/agent-browser/lib/command-policy.ts` (`needsManagedSession`), while `extensions/agent-browser/lib/runtime.ts` (`isPlainTextInspectionArgs`, `buildExecutionPlan`) applies that decision to execution planning.
+**Sessionless inspection and local commands:** Plain-text global help and version probes (`--help`, `-h`, `--version`, `-V`) must never allocate or bind the extension-managed session. The same session-ownership rule applies to read-only upstream `skills list`, `skills get …`, and `skills path …`, local auth profile management (`auth save/list/show/delete/remove`), plus local/setup surfaces such as `profiles`, `dashboard start/stop`, `device list`, `doctor`, `install`, `upgrade`, `session id`, `session info`, `session list`, and targeted/all local saved-state maintenance (`state list/show`, `state clear --all`, `state clear -a`, `state clear <session-name>`, `state clean --older-than <days>`, `state rename`). Non-plain-text sessionless commands still run with `--json` for machine-readable output, but the planner does not prepend the implicit managed `--session`, so an agent can inspect local capabilities or start/stop the standalone dashboard without consuming the implicit session slot before a real `open`. Browser-backed, context-dependent, or incomplete commands such as root `session`, untargeted `state clear`, bare `state clean`, `auth login`, `state save`, and `state load` keep normal managed-session injection. Command-shape allowlisting lives in `extensions/agent-browser/lib/command-policy.ts` (`needsManagedSession`), while `extensions/agent-browser/lib/runtime.ts` (`isPlainTextInspectionArgs`, `buildExecutionPlan`) applies that decision to execution planning.
 
 A successful unnamed `sessionMode: "fresh"` launch should become the new extension-managed session so later default calls follow that browser instead of silently snapping back to the older managed session.