pi-agent-browser-native 0.2.25 → 0.2.26

package/extensions/agent-browser/lib/playbook.ts

@@ -17,10 +17,10 @@ export const QUICK_START_GUIDELINES = [
 	"Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin find-locator shorthand compiled to find argv), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch), or the experimental sourceLookup / networkSourceLookup helpers (each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and other command/stdin combinations are rejected before launch; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device state.",
 	"There is no first-class reusable named browser recipe runtime above top-level job, the qa preset, and raw batch stdin; keep recurring flows in documentation examples or those inputs (closed RQ-0068; see docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet).",
 	"Common first calls: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
-	"Locator-first clicks and fills without hand-building find argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } } or { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }; details.compiledSemanticAction shows the derived find command, and stale-ref failures for compiled semantic targets can return a retry-semantic-action-after-stale-ref next action when retry safety is provable.",
+	"Locator-first clicks and fills without hand-building find argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } } or { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the derived find command; selector-not-found failures may append bounded try-*-candidate next actions (and an Agent-browser candidate fallbacks prose block) for specific placeholder/text/label shapes, and stale-ref failures can return retry-semantic-action-after-stale-ref when retry safety is provable.",
 	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { job: { steps: [{ action: \"open\", url: \"https://example.com\" }, { action: \"assertText\", text: \"Example Domain\" }, { action: \"screenshot\", path: \".dogfood/example.png\" }] } }, { qa: { url: \"https://example.com\", expectedText: \"Example Domain\", screenshotPath: \".dogfood/qa-example.png\" } }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"auth\", \"save\", \"name\", \"--password-stdin\"], stdin: \"<password from user-approved secret source>\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }.",
 	"High-value command reference: download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation.",
-	"For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
+	"For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
 	"When details.nextActions is present, prefer those exact native agent_browser follow-up payloads over prose guidance; they may include args, stdin, sessionMode, safety notes, or artifactPath for saved files.",
 ] as const;
 
@@ -28,7 +28,8 @@ export const BRAVE_SEARCH_PROMPT_GUIDELINE =
 	"When a non-empty BRAVE_API_KEY is available in the current environment, prefer the Brave Search API via bash/curl to discover specific destination URLs, then open the chosen URL with agent_browser instead of browsing a search engine results page just to find the target.";
 
 export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
-	"Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs can become stale.",
+	"Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs are page-scoped; the wrapper fails mutation-prone stale/recycled refs before upstream can silently target a different current-page element.",
+	"When snapshot -i compacts because the tree is oversized, scan visible output for Omitted high-value controls and optional details.data.highValueControlRefIds before opening the spill file: those list bounded searchboxes, textboxes, comboboxes, buttons, tabs, checkboxes, radios, options, and menuitems that did not fit the key/other ref previews.",
 	"When a visible text or accessible-name target should survive ref churn, prefer find locators such as role, text, label, placeholder, alt, title, or testid with the intended action instead of guessing a CSS selector.",
 	"Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.",
 	"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
@@ -47,8 +48,8 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
 	"For downloads, prefer download <selector> <path> when an element click should save a file. Do not rely on click alone when you need the downloaded file on disk.",
 	"When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
-	"When using eval --stdin for extraction, return the value you want instead of relying on console.log as the primary result channel.",
-	"When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone.",
+	"When using eval --stdin for extraction, return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); if a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. If get text on a CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.",
+	"When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction.",
 	"When commands save or spill files (screenshots, downloads, PDFs, traces, recordings, HAR, large snapshot spills), treat paths as provisional until details.artifactVerification shows every row verified: branch on missingCount, pendingCount, unverifiedCount, per-entry state, and optional limitation before downstream file use.",
 	"Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.",
 ] as const;

package/extensions/agent-browser/lib/results/presentation.ts

@@ -22,6 +22,7 @@ import { buildSnapshotPresentation, formatRawSnapshotText, formatSnapshotSummary
 import {
 	type AgentBrowserBatchResult,
 	type AgentBrowserEnvelope,
+	type AgentBrowserNextAction,
 	type AgentBrowserPageChangeSummary,
 	type ArtifactVerificationEntry,
 	type ArtifactVerificationSummary,
@@ -29,6 +30,7 @@ import {
 	buildAgentBrowserResultCategoryDetails,
 	classifyAgentBrowserFailureCategory,
 	classifyAgentBrowserSuccessCategory,
+	classifyNetworkRequestFailure,
 	type BatchFailurePresentationDetails,
 	type BatchStepPresentationDetails,
 	type ArtifactStorageScope,
@@ -43,6 +45,7 @@ import {
 	formatSessionArtifactRetentionSummary,
 	mergeSessionArtifactManifest,
 	stringifyUnknown,
+	summarizeNetworkFailures,
 	truncateText,
 } from "./shared.js";
 
@@ -589,7 +592,9 @@ function formatNetworkRequestLine(item: Record<string, unknown>, index: number):
 	const url = getStringField(item, "url") ?? "(no url)";
 	const requestId = getStringField(item, "requestId") ?? getStringField(item, "id");
 	const idText = requestId ? ` [${redactSensitiveText(requestId)}]` : "";
-	const lines = [`${index + 1}. ${status} ${method} ${truncateText(redactSensitiveText(url), 180)}${type ? ` (${type})` : ""}${idText}`];
+	const failureClassification = classifyNetworkRequestFailure(item);
+	const impactText = failureClassification ? ` [${failureClassification.impact}: ${failureClassification.reason}]` : "";
+	const lines = [`${index + 1}. ${status} ${method} ${truncateText(redactSensitiveText(url), 180)}${type ? ` (${type})` : ""}${idText}${impactText}`];
 	appendNetworkPreview(lines, "Payload", getPreviewCandidate(item, NETWORK_PREVIEW_FIELD_CANDIDATES.request), NETWORK_BODY_PREVIEW_MAX_CHARS);
 	appendNetworkPreview(lines, "Response", getPreviewCandidate(item, NETWORK_PREVIEW_FIELD_CANDIDATES.response), NETWORK_BODY_PREVIEW_MAX_CHARS);
 	appendNetworkPreview(lines, "Error", getPreviewCandidate(item, NETWORK_PREVIEW_FIELD_CANDIDATES.error), NETWORK_ERROR_PREVIEW_MAX_CHARS);
@@ -600,10 +605,14 @@ function formatNetworkRequestsText(data: Record<string, unknown>): string | unde
 	const requests = getArrayField(data, "requests");
 	if (!requests) return undefined;
 	if (requests.length === 0) return "No network requests captured.";
-	const shown = requests.slice(0, DIAGNOSTIC_REQUEST_PREVIEW_LIMIT).flatMap((item, index) => {
+	const networkFailureSummary = summarizeNetworkFailures(requests);
+	const shown = networkFailureSummary.totalCount > 0
+		? [`Network failure summary: ${networkFailureSummary.actionableCount} actionable, ${networkFailureSummary.benignCount} benign low-impact (${networkFailureSummary.totalCount} total).`]
+		: [];
+	shown.push(...requests.slice(0, DIAGNOSTIC_REQUEST_PREVIEW_LIMIT).flatMap((item, index) => {
 		if (!isRecord(item)) return [`${index + 1}. ${stringifyModelFacing(item)}`];
 		return formatNetworkRequestLine(item, index);
-	});
+	}));
 	if (requests.length > DIAGNOSTIC_REQUEST_PREVIEW_LIMIT) {
 		shown.push(`... (${requests.length - DIAGNOSTIC_REQUEST_PREVIEW_LIMIT} additional requests omitted from preview)`);
 	}
@@ -1478,6 +1487,65 @@ function getSelectorRecoveryHint(errorText: string): string | undefined {
 	return undefined;
 }
 
+interface CommandSuggestion {
+	args?: string[];
+	description: string;
+	id?: string;
+}
+
+const UNKNOWN_COMMAND_SUGGESTIONS: Record<string, CommandSuggestion[]> = {
+	attr: [
+		{ description: "Use `get attr <selector> <name>` to read an attribute from a selector or current `@ref`." },
+	],
+	count: [
+		{ description: "Use `get count <selector>` to count matching elements." },
+	],
+	html: [
+		{ description: "Use `get html <selector>` to read element HTML, or `get html` for the page when upstream supports it." },
+	],
+	text: [
+		{ description: "Use `get text <selector>` to read text from a selector or current `@ref`; run `snapshot -i` first when you need a safe `@ref`." },
+	],
+	title: [
+		{ args: ["get", "title"], description: "Use `get title` to read the current page title.", id: "use-get-title" },
+	],
+	url: [
+		{ args: ["get", "url"], description: "Use `get url` to read the current page URL.", id: "use-get-url" },
+	],
+	value: [
+		{ description: "Use `get value <selector>` to read form control value from a selector or current `@ref`." },
+	],
+};
+
+function getUnknownCommandSuggestions(command: string | undefined, errorText: string): CommandSuggestion[] {
+	if (!command) return [];
+	const normalizedCommand = command.trim().toLowerCase();
+	if (!/\bunknown\s+command\b|\bunknown\s+subcommand\b|\bunrecognized\s+command\b/i.test(errorText)) return [];
+	return UNKNOWN_COMMAND_SUGGESTIONS[normalizedCommand] ?? [];
+}
+
+function formatUnknownCommandSuggestionText(suggestions: CommandSuggestion[]): string | undefined {
+	if (suggestions.length === 0) return undefined;
+	return ["Agent-browser hint: This looks like a getter shortcut, but upstream getter commands are grouped under `get`.", ...suggestions.map((suggestion) => suggestion.description)].join(" ");
+}
+
+function withSessionPrefix(sessionName: string | undefined, args: string[]): string[] {
+	return sessionName ? ["--session", sessionName, ...args] : args;
+}
+
+function buildUnknownCommandSuggestionActions(suggestions: CommandSuggestion[], sessionName: string | undefined): AgentBrowserNextAction[] | undefined {
+	const actions = suggestions
+		.filter((suggestion): suggestion is CommandSuggestion & { args: string[]; id: string } => suggestion.args !== undefined && suggestion.id !== undefined)
+		.map((suggestion) => ({
+			id: suggestion.id,
+			params: { args: withSessionPrefix(sessionName, suggestion.args) },
+			reason: suggestion.description,
+			safety: "Read-only getter command; safe to retry when you intended to inspect page state.",
+			tool: "agent_browser" as const,
+		}));
+	return actions.length > 0 ? actions : undefined;
+}
+
 function appendSelectorRecoveryHint(errorText: string): string {
 	const hint = getSelectorRecoveryHint(errorText);
 	if (!hint || errorText.includes("Agent-browser hint:")) {
@@ -2137,12 +2205,22 @@ export async function buildToolPresentation(options: {
 }): Promise<ToolPresentation> {
 	const { args, artifactManifest, artifactRequest, commandInfo, cwd, envelope, errorText, persistentArtifactStore, sessionName } = options;
 	if (errorText) {
-		const hintedErrorText = appendSelectorRecoveryHint(redactModelFacingText(errorText));
+		const safeErrorText = redactModelFacingText(errorText);
+		const selectorHintedErrorText = appendSelectorRecoveryHint(safeErrorText);
+		const unknownCommandSuggestions = getUnknownCommandSuggestions(commandInfo.command, safeErrorText);
+		const unknownCommandSuggestionText = formatUnknownCommandSuggestionText(unknownCommandSuggestions);
+		const hintedErrorText = unknownCommandSuggestionText && !selectorHintedErrorText.includes("Agent-browser hint:")
+			? `${selectorHintedErrorText}\n\n${unknownCommandSuggestionText}`
+			: selectorHintedErrorText;
 		const categoryDetails = buildAgentBrowserResultCategoryDetails({ args: [commandInfo.command, commandInfo.subcommand].filter((item): item is string => item !== undefined), command: commandInfo.command, errorText: hintedErrorText, succeeded: false });
+		const nextActions = [
+			...(buildUnknownCommandSuggestionActions(unknownCommandSuggestions, sessionName) ?? []),
+			...(buildAgentBrowserNextActions({ args, command: commandInfo.command, failureCategory: categoryDetails.failureCategory, resultCategory: "failure" }) ?? []),
+		];
 		return {
 			...categoryDetails,
 			content: [{ type: "text", text: hintedErrorText }],
-			nextActions: buildAgentBrowserNextActions({ args, command: commandInfo.command, failureCategory: categoryDetails.failureCategory, resultCategory: "failure" }),
+			nextActions: nextActions.length > 0 ? nextActions : undefined,
 			summary: hintedErrorText,
 		};
 	}

package/extensions/agent-browser/lib/results/shared.ts

@@ -368,6 +368,7 @@ export function classifyAgentBrowserFailureCategory(options: {
 	) {
 		return "selector-unsupported";
 	}
+	if (command === "find" && /could not locate element|element not found|no elements? found|unable to find/i.test(text)) return "selector-not-found";
 	if (reportsSelectorMatchFailure) return "selector-not-found";
 	if ((command === "download" || text.includes("wait --download") || /\bdownload\b/i.test(text)) && /missing|not verified|not found|failed|timeout|timed out/i.test(text)) {
 		return "download-not-verified";
@@ -592,6 +593,77 @@ export function buildAgentBrowserResultCategoryDetails(options: {
 	};
 }
 
+export type NetworkFailureImpact = "actionable" | "benign";
+
+export interface NetworkFailureClassification {
+	impact: NetworkFailureImpact;
+	reason: string;
+	resourceType?: string;
+	status?: number;
+	url?: string;
+}
+
+export interface NetworkFailureSummary {
+	actionableCount: number;
+	benignCount: number;
+	failures: NetworkFailureClassification[];
+	totalCount: number;
+}
+
+function getStringRecordField(value: Record<string, unknown>, key: string): string | undefined {
+	const field = value[key];
+	return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
+}
+
+function getNetworkRequestUrlPath(url: string | undefined): string | undefined {
+	if (!url) return undefined;
+	try {
+		return new URL(url).pathname;
+	} catch {
+		const withoutQuery = url.split(/[?#]/, 1)[0];
+		return withoutQuery.length > 0 ? withoutQuery : undefined;
+	}
+}
+
+function isFailedNetworkRequest(request: Record<string, unknown>): boolean {
+	return (typeof request.status === "number" && request.status >= 400) || request.failed === true || typeof request.error === "string";
+}
+
+function isBenignAssetFailure(request: Record<string, unknown>, url: string | undefined, resourceType: string | undefined): boolean {
+	const path = getNetworkRequestUrlPath(url);
+	if (!path) return false;
+	const normalizedResourceType = resourceType?.toLowerCase();
+	return /(?:^|\/)(?:favicon(?:[-.\w]*)?\.(?:ico|png|svg)|apple-touch-icon(?:[-.\w]*)?\.png)$/i.test(path)
+		&& (request.status === 404 || request.failed === true || typeof request.error === "string")
+		&& (!normalizedResourceType || ["image", "img", "other"].includes(normalizedResourceType) || normalizedResourceType.startsWith("image/"));
+}
+
+export function classifyNetworkRequestFailure(request: Record<string, unknown>): NetworkFailureClassification | undefined {
+	if (!isFailedNetworkRequest(request)) return undefined;
+	const url = getStringRecordField(request, "url");
+	const resourceType = getStringRecordField(request, "resourceType") ?? getStringRecordField(request, "mimeType");
+	const status = typeof request.status === "number" ? request.status : undefined;
+	if (isBenignAssetFailure(request, url, resourceType)) {
+		return { impact: "benign", reason: "low-impact browser icon asset", resourceType, status, url };
+	}
+	return { impact: "actionable", reason: "document, script, API, or non-benign request failure", resourceType, status, url };
+}
+
+export function summarizeNetworkFailures(requests: unknown[]): NetworkFailureSummary {
+	const failures = requests.flatMap((request) => {
+		if (!isRecord(request)) return [];
+		const classification = classifyNetworkRequestFailure(request);
+		return classification ? [classification] : [];
+	});
+	const benignCount = failures.filter((failure) => failure.impact === "benign").length;
+	return {
+		actionableCount: failures.length - benignCount,
+		benignCount,
+		failures,
+		totalCount: failures.length,
+	};
+}
+
 export function stringifyUnknown(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (typeof value === "number" || typeof value === "boolean") return String(value);

package/extensions/agent-browser/lib/results/snapshot.ts

@@ -34,6 +34,7 @@ const SNAPSHOT_SECTION_PREVIEW_LINES = 2;
 const SNAPSHOT_MAX_ADDITIONAL_SECTIONS = 2;
 const SNAPSHOT_KEY_REF_MAX_LINES = 8;
 const SNAPSHOT_OTHER_REF_MAX_LINES = 4;
+const SNAPSHOT_HIGH_VALUE_REF_MAX_LINES = 10;
 const SNAPSHOT_ROLE_COUNT_MAX_ENTRIES = 4;
 const SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES = 12;
 const SNAPSHOT_NAME_MAX_CHARS = 96;
@@ -58,6 +59,7 @@ const SNAPSHOT_SIGNAL_ROLES = new Set([
 	"radio",
 	"region",
 	"row",
+	"searchbox",
 	"tab",
 	"textbox",
 ]);
@@ -69,14 +71,15 @@ const SNAPSHOT_ROLE_PRIORITY: Record<string, number> = {
 	menu: 3,
 	region: 4,
 	heading: 5,
-	button: 6,
+	searchbox: 6,
 	textbox: 7,
 	combobox: 8,
-	checkbox: 9,
-	radio: 10,
-	tab: 11,
-	option: 12,
-	link: 13,
+	button: 9,
+	checkbox: 10,
+	radio: 11,
+	tab: 12,
+	option: 13,
+	link: 14,
 	listitem: 14,
 	row: 15,
 	gridcell: 16,
@@ -103,6 +106,28 @@ const SNAPSHOT_CHROME_SECTION_PATTERNS = [
 	/\brecommended\b/i,
 	/\bsuggested\b/i,
 ];
+const SNAPSHOT_HIGH_VALUE_CONTROL_ROLES = new Set([
+	"button",
+	"checkbox",
+	"combobox",
+	"menuitem",
+	"option",
+	"radio",
+	"searchbox",
+	"tab",
+	"textbox",
+]);
+const SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY: Record<string, number> = {
+	searchbox: 0,
+	textbox: 1,
+	combobox: 2,
+	button: 3,
+	tab: 4,
+	checkbox: 5,
+	radio: 6,
+	option: 7,
+	menuitem: 8,
+};
 
 interface SnapshotRefEntry {
 	id: string;
@@ -458,6 +483,25 @@ function formatCompactRef(entry: SnapshotRefEntry): string {
 	return `- ${entry.id} ${entry.role}${suffix}`;
 }
 
+function isHighValueControlRef(entry: SnapshotRefEntry): boolean {
+	if (!SNAPSHOT_HIGH_VALUE_CONTROL_ROLES.has(entry.role)) return false;
+	if (isNoiseName(entry.name) || isChromeSectionName(entry.name)) return false;
+	return entry.name.length > 0 || entry.role === "searchbox" || entry.role === "textbox" || entry.role === "combobox";
+}
+
+function rankHighValueControlRefs(left: SnapshotRefEntry, right: SnapshotRefEntry): number {
+	const rolePriority =
+		(SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[left.role] ?? 50) -
+		(SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY[right.role] ?? 50);
+	if (rolePriority !== 0) return rolePriority;
+
+	const leftHasName = left.name.length > 0 ? 0 : 1;
+	const rightHasName = right.name.length > 0 ? 0 : 1;
+	if (leftHasName !== rightHasName) return leftHasName - rightHasName;
+
+	return compareRefIds(left.id, right.id);
+}
+
 function shouldCompactSnapshot(rawText: string, data: Record<string, unknown>): boolean {
 	const snapshot = getSnapshotText(data) ?? "";
 	const refEntries = getSnapshotRefEntries(data);
@@ -611,7 +655,16 @@ export async function buildSnapshotPresentation(
 	const otherRefEntries = visibleRankedRefEntries
 		.filter((entry) => !keyRefIdSet.has(entry.id))
 		.slice(0, SNAPSHOT_OTHER_REF_MAX_LINES);
-	const omittedOtherRefs = Math.max(0, visibleRankedRefEntries.length - keyRefEntries.length - otherRefEntries.length);
+	const displayedRefIdSet = new Set([...keyRefEntries, ...otherRefEntries].map((entry) => entry.id));
+	const omittedHighValueControlEntries = visibleRankedRefEntries
+		.filter((entry) => !displayedRefIdSet.has(entry.id) && isHighValueControlRef(entry))
+		.sort(rankHighValueControlRefs);
+	const visibleHighValueControlEntries = omittedHighValueControlEntries.slice(0, SNAPSHOT_HIGH_VALUE_REF_MAX_LINES);
+	const omittedHighValueControls = Math.max(0, omittedHighValueControlEntries.length - visibleHighValueControlEntries.length);
+	const omittedNonHighlightedRefs = Math.max(
+		0,
+		visibleRankedRefEntries.length - keyRefEntries.length - otherRefEntries.length - omittedHighValueControlEntries.length,
+	);
 	const origin = getSnapshotOrigin(data);
 
 	const lines: string[] = [
@@ -658,8 +711,14 @@ export async function buildSnapshotPresentation(
 	if (otherRefEntries.length > 0) {
 		lines.push("", "Other refs:", ...otherRefEntries.map(formatCompactRef));
 	}
-	if (omittedOtherRefs > 0) {
-		lines.push(`- ... (${omittedOtherRefs} additional refs omitted)`);
+	if (omittedNonHighlightedRefs > 0) {
+		lines.push(`- ... (${omittedNonHighlightedRefs} additional refs omitted)`);
+	}
+	if (visibleHighValueControlEntries.length > 0) {
+		lines.push("", "Omitted high-value controls:", ...visibleHighValueControlEntries.map(formatCompactRef));
+		if (omittedHighValueControls > 0) {
+			lines.push(`- ... (${omittedHighValueControls} additional high-value controls omitted)`);
+		}
 	}
 
 	lines.push(
@@ -689,6 +748,7 @@ export async function buildSnapshotPresentation(
 			previewMode: fallbackPreview ? "outline" : "structured",
 			spillError: spillErrorText,
 			previewRefIds: [...previewRefIds],
+			highValueControlRefIds: visibleHighValueControlEntries.map((entry) => entry.id),
 			additionalSectionsOmitted: omittedAdditionalSectionCount,
 			previewSections: [
 				...(primarySegment

package/extensions/agent-browser/lib/runtime.ts

@@ -649,9 +649,14 @@ export function restoreManagedSessionStateFromBranch(
 
 		const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
 		const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
-		const succeeded = messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
+		const outcome = typeof details.managedSessionOutcome === "object" && details.managedSessionOutcome !== null ? details.managedSessionOutcome as Record<string, unknown> : undefined;
+		const outcomeStatus = typeof outcome?.status === "string" ? outcome.status : undefined;
+		const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
+		const outcomeActiveAfter = outcome?.activeAfter === true;
+		const outcomeRepresentsActiveCurrentSession = outcomeActiveAfter && outcomeCurrentSessionName === managedSessionName && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged");
+		const succeeded = outcomeRepresentsActiveCurrentSession ? true : messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
 		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
-		if (succeeded && sessionMode === "fresh") {
+		if ((succeeded || outcomeRepresentsActiveCurrentSession) && sessionMode === "fresh") {
 			freshSessionOrdinal += 1;
 		}
 		const staleCompletion = succeeded && command !== "close" && restoreRank < activeRestoreRank;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",