pi-ui-extend 1.0.20 → 1.0.22

package/external/pi-tools-suite/README.md

@@ -247,13 +247,15 @@ For an oh-my-openagent-style workflow, run `/ultrawork` or `/ulw` to ask the par
 
 ### Private browser QA and project auth
 
-The built-in `browser-qa` role runs on `antigravity/gemini-3-flash-preview`, with
-`openai-codex/gpt-5.4-mini` as its fallback. Its browser workflow is an explicit
-private skill under `src/async-subagents/private-skills/`, outside normal Pi skill
-discovery. The role's first-class `isolatedSkills` setting launches the child with
-`--no-skills` plus the private workflow and the packaged `skills/playwright-cli`
-skill. Both are mandatory even when configuration adds other isolated skills;
-parent and ordinary sub-agent sessions do not discover the private workflow.
+The built-in `browser-qa` role runs on `openai-codex/gpt-5.4-mini`, with
+`antigravity/gemini-3-flash-preview` and then `zai/glm-5.3` as fallbacks. Its browser
+workflow is an explicit private skill under `src/async-subagents/private-skills/`,
+outside normal Pi skill discovery. The role's first-class `isolatedSkills` setting launches the child with
+`--no-skills` plus one self-contained private workflow. It bundles the relevant
+scenario-design, locator, waiting, assertion, evidence, and cleanup guidance next
+to its trusted runner, so browser QA does not depend on a separately installed
+skill or CLI. The private workflow remains mandatory when configuration appends
+other isolated skills; parent and ordinary sub-agent sessions do not discover it.
 
 Keep named dev/staging auth profiles in project `.pi/qa_auth.jsonc` (there is no
 `/qa-auth` command). The private runner supports `form`, `cookie`, `localStorage`,
@@ -286,15 +288,23 @@ blocked. Example:
 }
 ```
 
-Do not place credential values in prompts, QA flows, shell arguments, reports,
-or evidence. The helper reads JSONC internally, emits only redacted statuses, and
-caches generated storage state under `.pi/qa-auth-state`. Evidence is isolated by
-run/profile under `.pi/qa-runs`; trace archives have network records and non-image
-resources removed, then known configured/runtime credential values are redacted
-and verified before the trace is retained. Missing, ambiguous, rejected, or
-expired auth returns `QA_PROFILE_REQUIRED` or `QA_AUTH_UPDATE_REQUIRED`, naming
-only the profile/file/reason needed for the parent to ask the user for an update
-and rerun. See
+Do not place credential values in prompts, QA flows, shell arguments, or reports.
+The helper reads JSONC internally and emits only redacted statuses. For form auth,
+video recording begins on the login page and captures the field-filling and submit
+sequence; password inputs remain browser-masked, but the private video may show
+other visible login identifiers and must be treated as sensitive evidence. Tracing
+starts only after login succeeds and is sanitized before retention. The launcher
+provides each browser QA process with its own
+`.pi/subagents/<run>/<agent-id>/browser-qa/` workspace. Declarative flows,
+screenshots, video, sanitized traces, and result manifests stay there, so normal
+session shutdown or `subagents cleanup` removes them with the run directory.
+The runner validates the owning agent metadata and refuses flows outside that
+workspace; reusing an agent id clears stale browser QA files first. Trace archives
+have network records and non-image resources removed, then known
+configured/runtime credential values are redacted and verified before retention.
+Missing, ambiguous, rejected, or expired auth returns `QA_PROFILE_REQUIRED` or
+`QA_AUTH_UPDATE_REQUIRED`, naming only the profile/file/reason needed for the
+parent to ask the user for an update and rerun. See
 `src/async-subagents/private-skills/browser-qa/references/qa-auth.example.jsonc`
 for complete profile shapes and `references/qa-flow.example.jsonc` beside it for
 the declarative, non-executable QA action/assertion format.

package/external/pi-tools-suite/docs/browser-qa-subagent.md

@@ -17,9 +17,10 @@ evidence. The role uses `antigravity/gemini-3-flash-preview`, falling back to
   Antigravity-backed role unavailable.
 - A type profile may declare `isolatedSkills`. Spawning that profile adds
   `--no-skills` followed by one explicit `--skill` per configured path.
-- The `browser-qa` profile always loads both its private workflow and the
-  packaged `skills/playwright-cli` skill. Configuration may append isolated
-  skills but cannot remove either mandatory browser skill.
+- The `browser-qa` profile always loads one self-contained private workflow.
+  Relevant browser-test design guidance is bundled beside its trusted runner;
+  no separately discovered skill or browser CLI is required. Configuration may
+  append isolated skills but cannot remove the mandatory private workflow.
 - Other sub-agent profiles and the parent session must not discover the private
   skill automatically.
 
@@ -40,9 +41,11 @@ evidence. The role uses `antigravity/gemini-3-flash-preview`, falling back to
 - The bundled runner reads secrets internally. Credentials must never be copied
   into prompts, generated QA flows, shell arguments, transcripts, reports,
   or QA evidence.
-- Generated browser state is private cache under `.pi/qa-auth-state`; evidence
-  is written under `.pi/qa-runs`. Multiple profiles always use separate browser
-  contexts and evidence directories.
+- Generated browser state is private cache under `.pi/qa-auth-state`. Ephemeral
+  flows, evidence, and result manifests are written under the owning agent's
+  `.pi/subagents/<run>/<agent-id>/browser-qa/` workspace. Multiple profiles use
+  separate browser contexts/evidence directories, and normal sub-agent shutdown
+  or cleanup removes the whole workspace with its run.
 - Missing, ambiguous, rejected, or expired auth returns a machine-readable
   update-required/profile-required status naming only the profile id, config
   file, and redacted reason. The parent asks the user to update the file and
@@ -54,6 +57,10 @@ evidence. The role uses `antigravity/gemini-3-flash-preview`, falling back to
   trusted runner implements a bounded set of navigation, interaction,
   assertion, screenshot, and auth-rejection actions and never gives the flow a
   Playwright context or credential values.
+- The launcher injects `PI_SUBAGENT_AGENT_DIR`, pre-creates a private
+  `browser-qa/flows/` workspace, and clears stale browser QA files when an agent
+  id is reused. The runner validates the directory's project/type metadata and
+  refuses flows outside it; the model cannot select a shared evidence root.
 - The runner owns browser lifecycle, origin checks, auth application, tracing,
   screenshots, video finalization, and redacted result output. Before retaining
   a trace it removes network/non-image resource entries, redacts configured and
@@ -69,10 +76,10 @@ evidence. The role uses `antigravity/gemini-3-flash-preview`, falling back to
 
 ## Acceptance criteria
 
-1. `browser-qa` resolves to the intended model/fallback, private workflow, and
-   packaged `playwright-cli` skill, and its isolated child process can register
-   the configured Antigravity model.
-2. Spawn args contain `--no-skills` and both mandatory explicit skills for this
+1. `browser-qa` resolves to the intended model/fallback and its self-contained
+   private workflow, and its isolated child process can register the configured
+   Antigravity model.
+2. Spawn args contain `--no-skills` and the mandatory private skill for this
    profile; ordinary profiles retain existing skill discovery behavior.
 3. Auth profile listing and all error output are redacted; model-authored input
    cannot execute code in the credential-bearing process.
@@ -80,9 +87,11 @@ evidence. The role uses `antigravity/gemini-3-flash-preview`, falling back to
    origins, path/mode hardening, private empty-template creation, explicit
    credential requests, non-executable flows, and successful redacted evidence
    creation.
-5. Completed test runs report clickable screenshot, video, and trace links
+5. Browser QA flows/evidence live only inside the owning sub-agent directory;
+   deleting the run removes them while persistent auth config/state remains.
+6. Completed test runs report clickable screenshot, video, and trace links
    whenever those artifacts exist.
-6. Suite tests/typecheck, host checks, and suite sync pass.
+7. Suite tests/typecheck, host checks, and suite sync pass.
 
 ## Real-browser regression test
 
@@ -96,6 +105,8 @@ npm run test:browser-qa-e2e
 ```
 
 Normal suite tests keep this case skipped; the Publish workflow runs it on
-Linux after installing Chromium. Explicit runs retain the latest artifacts in
-`.pi/qa-runs/browser-qa-e2e/latest/` and print a clickable link for every file.
-Set `BROWSER_QA_KEEP_EVIDENCE=0` to clean up without publishing evidence.
+Linux after installing Chromium. The runner writes into a temporary simulated
+sub-agent directory. For manual inspection only, explicit E2E runs copy the
+latest artifacts to `.pi/qa-runs/browser-qa-e2e/latest/` and print clickable
+links; this test-only published copy is not the runtime storage contract. Set
+`BROWSER_QA_KEEP_EVIDENCE=0` to skip that copy.

package/external/pi-tools-suite/src/async-subagents/async-subagents.sample.jsonc

@@ -116,7 +116,7 @@
         "research": { "model": "zai/glm-5-turbo", "thinking": "low" },
         "docs": { "model": "zai/glm-4.5-air", "thinking": "low" },
         "frontend": { "model": "antigravity/gemini-3-flash-preview", "fallbackModels": ["zai/glm-5.3"], "thinking": "medium" },
-        "browser-qa": { "model": "antigravity/gemini-3-flash-preview", "fallbackModels": ["openai-codex/gpt-5.4-mini"], "thinking": "medium" },
+        "browser-qa": { "model": "openai-codex/gpt-5.4-mini", "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"], "thinking": "medium" },
         "tests": { "model": "zai/glm-5-turbo", "thinking": "medium" },
         "review": { "model": "zai/glm-5.3", "thinking": "high" },
         "implement": { "model": "zai/glm-5.3", "thinking": "high" },
@@ -132,7 +132,7 @@
         "research": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5-turbo"], "thinking": "low" },
         "docs": { "model": "openai-codex/gpt-5.6-luna", "fallbackModels": ["zai/glm-4.5-air"], "thinking": "low" },
         "frontend": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"], "thinking": "medium" },
-        "browser-qa": { "model": "antigravity/gemini-3-flash-preview", "fallbackModels": ["openai-codex/gpt-5.4-mini"], "thinking": "medium" },
+        "browser-qa": { "model": "openai-codex/gpt-5.4-mini", "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"], "thinking": "medium" },
         "tests": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5-turbo"], "thinking": "medium" },
         "review": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
         "implement": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
@@ -148,7 +148,7 @@
         "research": { "model": "antigravity/gemini-3.1-pro-preview", "fallbackModels": ["openai-codex/gpt-5.4-mini", "zai/glm-5-turbo"], "thinking": "medium" },
         "docs": { "model": "antigravity/gemini-2.5-flash", "fallbackModels": ["openai-codex/gpt-5.3-codex-spark", "zai/glm-4.5-air"], "thinking": "medium" },
         "frontend": { "model": "antigravity/gemini-3.1-pro-preview-customtools", "fallbackModels": ["openai-codex/gpt-5.4-mini", "zai/glm-5.3"], "thinking": "low" },
-        "browser-qa": { "model": "antigravity/gemini-3-flash-preview", "fallbackModels": ["openai-codex/gpt-5.4-mini"], "thinking": "medium" },
+        "browser-qa": { "model": "openai-codex/gpt-5.4-mini", "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"], "thinking": "medium" },
         "tests": { "model": "antigravity/antigravity-claude-sonnet-4-6", "fallbackModels": ["openai-codex/gpt-5.4-mini", "zai/glm-5-turbo"], "thinking": "high" },
         "review": { "model": "antigravity/antigravity-claude-sonnet-4-6", "fallbackModels": ["openai-codex/gpt-5.6-sol", "zai/glm-5.3"], "thinking": "high" },
         "implement": { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"], "thinking": "high" },
@@ -199,8 +199,8 @@
 
     "browser-qa": {
       "description": "Use for browser-based visual QA: reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.",
-      "model": "antigravity/gemini-3-flash-preview",
-      "fallbackModels": ["openai-codex/gpt-5.4-mini"],
+      "model": "openai-codex/gpt-5.4-mini",
+      "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"],
       "thinking": "medium",
       "tools": ["read", "grep", "bash"]
     },

package/external/pi-tools-suite/src/async-subagents/core/config.ts

@@ -207,8 +207,8 @@ const BUILTIN_CONFIG: SubagentConfig = {
 		},
 		"browser-qa": {
 			description: "Use for browser-based visual QA: reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.",
-			model: "antigravity/gemini-3-flash-preview",
-			fallbackModels: ["openai-codex/gpt-5.4-mini"],
+			model: "openai-codex/gpt-5.4-mini",
+			fallbackModels: ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"],
 			thinking: "medium",
 			tools: ["read", "grep", "bash"],
 			isolatedSkills: [getBrowserQaSkillPath()],
@@ -288,21 +288,6 @@ export function getBrowserQaSkillPath(): string {
 	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "private-skills", "browser-qa", "SKILL.md");
 }
 
-export function getPlaywrightCliSkillPath(): string {
-	const bundledPath = path.resolve(
-		path.dirname(fileURLToPath(import.meta.url)),
-		"../../../../..",
-		"skills",
-		"playwright-cli",
-		"SKILL.md",
-	);
-	const installedPaths = [
-		path.join(os.homedir(), ".agents", "skills", "playwright-cli", "SKILL.md"),
-		path.join(os.homedir(), ".pi", "agent", "skills", "playwright-cli", "SKILL.md"),
-	];
-	return [bundledPath, ...installedPaths].find((candidate) => fs.existsSync(candidate)) ?? bundledPath;
-}
-
 export function getSubagentConfigInitTargetPath(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
 	return explicitSubagentConfigPath(cwd, env) ?? getDefaultSubagentConfigPath();
 }
@@ -417,7 +402,7 @@ export function resolveAgentTaskConfig(
 function resolveIsolatedSkills(selectedType: string | undefined, profile: SubagentTypeConfig | undefined): string[] {
 	const configured = arrayOfStrings(profile?.isolatedSkills) ?? [];
 	if (selectedType !== "browser-qa") return configured;
-	return [...new Set([getBrowserQaSkillPath(), getPlaywrightCliSkillPath(), ...configured])];
+	return [...new Set([getBrowserQaSkillPath(), ...configured])];
 }
 
 export function resolveSubagentRoutingConfig(config: SubagentConfig): ResolvedSubagentRoutingConfig {

package/external/pi-tools-suite/src/async-subagents/core/spawn.ts

@@ -24,6 +24,8 @@ export interface SpawnAgentOptions {
 }
 
 export const DEFAULT_AGENT_TIMEOUT_MS = 30 * 60 * 1000;
+const BROWSER_QA_WORKSPACE_DIR = "browser-qa";
+const SUBAGENT_AGENT_DIR_ENV = "PI_SUBAGENT_AGENT_DIR";
 const AGENT_TIMEOUT_EXIT_CODE = 124;
 const AGENT_TIMEOUT_KILL_GRACE_MS = 5_000;
 const AGENT_SETTLED_TERMINATE_GRACE_MS = 50;
@@ -46,6 +48,7 @@ export function spawnAgent(
 	validateBasename(task.id, "task.id");
 	const agentDir = path.join(runDir, task.id);
 	fs.mkdirSync(agentDir, { recursive: true });
+	prepareBrowserQaWorkspace(agentDir, task.subagentType);
 
 	// Clean previous state when reusing a run directory/agent id.
 	for (const f of [
@@ -136,7 +139,7 @@ export function spawnAgent(
 
 	const proc = spawn(invocation.command, invocation.args, {
 		cwd,
-		env: subagentEnvironment(process.env),
+		env: subagentEnvironment(process.env, task.subagentType === "browser-qa" ? agentDir : undefined),
 		stdio: ["pipe", "pipe", "pipe"],
 	});
 	proc.stdin.on("error", (error: NodeJS.ErrnoException) => {
@@ -698,8 +701,8 @@ function getEnvModel(): string | undefined {
 	return trimmed ? trimmed : undefined;
 }
 
-function subagentEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
-	return {
+function subagentEnvironment(env: NodeJS.ProcessEnv, agentDir?: string): NodeJS.ProcessEnv {
+	const result: NodeJS.ProcessEnv = {
 		...env,
 		PI_MODEL_SUITABLE_TOOLS_PRESERVE_SELECTION: "1",
 		PI_TERMINAL_BELL_DISABLED: "1",
@@ -709,6 +712,21 @@ function subagentEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
 			"question",
 		]),
 	};
+	delete result[SUBAGENT_AGENT_DIR_ENV];
+	if (agentDir) result[SUBAGENT_AGENT_DIR_ENV] = fs.realpathSync(agentDir);
+	return result;
+}
+
+function prepareBrowserQaWorkspace(agentDir: string, subagentType: string | undefined): void {
+	const workspace = path.join(agentDir, BROWSER_QA_WORKSPACE_DIR);
+	fs.rmSync(workspace, { recursive: true, force: true });
+	if (subagentType !== "browser-qa") return;
+	const flows = path.join(workspace, "flows");
+	fs.mkdirSync(flows, { recursive: true, mode: 0o700 });
+	if (process.platform !== "win32") {
+		fs.chmodSync(workspace, 0o700);
+		fs.chmodSync(flows, 0o700);
+	}
 }
 
 function appendEnvList(value: string | undefined, items: readonly string[]): string {

package/external/pi-tools-suite/src/async-subagents/lib.ts

@@ -24,7 +24,6 @@ export {
 	existingSubagentConfigFiles,
 	getDefaultSubagentConfigPath,
 	getBrowserQaSkillPath,
-	getPlaywrightCliSkillPath,
 	getSubagentConfigInitTargetPath,
 	getSubagentConfigSamplePath,
 	isBlindModelRef,

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/SKILL.md

@@ -1,31 +1,71 @@
 ---
 name: browser-qa-private
-description: Private workflow for deterministic browser bug reproduction and fix verification with redacted project auth and Playwright evidence.
+description: Private self-contained workflow for deterministic browser bug reproduction and fix verification with redacted project auth and Playwright evidence.
 ---
 
 # Browser QA
 
-Use the bundled runner; do not read, print, grep, copy, or edit credential values
-from `.pi/qa_auth.jsonc` yourself.
+Use this skill's bundled runner as the only browser interface. It already owns
+Playwright, browser/context lifecycle, tracing, video, screenshots, origin
+isolation, authentication, redaction, and cleanup. Do not invoke another browser
+CLI, create shared/default browser sessions, or generate executable browser code.
+
+Never read, print, grep, copy, or edit credential values from
+`.pi/qa_auth.jsonc` yourself.
 
 ## Workflow
 
 1. Resolve `scripts/browser-qa-runner.mjs` relative to this skill.
-2. Run `node <runner> profiles`. Choose a profile only when the task names its
+2. Use the launcher-provided `$PI_SUBAGENT_AGENT_DIR/browser-qa/` workspace.
+   The launcher creates its private `flows/` directory and the runner rejects
+   flows or evidence destinations outside this owning sub-agent directory. Do
+   not override `PI_SUBAGENT_AGENT_DIR` or copy evidence to shared project paths.
+3. Discover the requested target, expected behavior, and the smallest scenario
+   that can prove it. If the target cannot be reached or started, report the
+   concrete blocker instead of substituting static checks for browser QA.
+4. Run `node <runner> profiles`. Choose a profile only when the task names its
    id or safe profile traits make the choice unambiguous. Otherwise stop with
    `QA_PROFILE_REQUIRED` and list only ids, descriptions, and traits.
-3. Inspect the target code and write a declarative JSONC flow under
-   `.pi/qa-flows/`. Never put credentials or executable JavaScript in it.
-4. Run:
+5. Inspect the target code and write a declarative JSONC flow under
+   `$PI_SUBAGENT_AGENT_DIR/browser-qa/flows/`. Never put credentials or
+   executable JavaScript in it.
+6. Run:
    `node <runner> run --profile <id> --base-url <url> --flow <flow.jsonc>`.
    Profile id, URL, and flow path are non-secret; never pass credentials as
    arguments or environment variables.
-5. Report deterministic assertions and every artifact returned by the runner.
+7. Report deterministic assertions and every artifact returned by the runner.
    For each screenshot, video, or trace, emit a separate clickable Markdown
    link using its `uri` and also show its absolute `path`. Do this for failed
    runs too whenever `artifacts` is present; never report only `evidenceDir`.
    Visual inspection supplements assertions; it does not replace them.
 
+## Scenario design
+
+- Define the expected postcondition before writing interactions. A successful
+  click or navigation is not proof; assert the resulting URL, text, value,
+  count, visibility, enabled state, or checked state.
+- Keep the flow minimal and reproducible. Capture setup, the action under test,
+  and at least one observable outcome; add a screenshot at the state that best
+  explains the result.
+- Prefer stable user-facing locators in this order: `testId`; semantic `role`
+  plus accessible `name`; `label`; `placeholder`; visible `text`; CSS only as a
+  last resort. Use `exact: true` when similar elements could make a match
+  ambiguous.
+- Let locator actions auto-wait. Use `waitFor` for an explicit UI state and use
+  `waitForTimeout` only for a short, unavoidable animation/debounce—not as a
+  substitute for an assertion. Set flow `timeoutMs` only as high as the target
+  legitimately needs.
+- Place `authRejectedIf` immediately after navigation or any transition that
+  may reveal expired authentication.
+- Never weaken an assertion merely to make a failing run pass. If the observed
+  product behavior differs from the expectation, preserve the failure evidence
+  and report the mismatch.
+
+Read `references/qa-design.md` when designing a non-trivial flow, diagnosing an
+ambiguous failure, or deciding what evidence proves the result.
+
+## Flow contract
+
 The flow is `{ "steps": [...] }` with at most 100 steps. Supported actions:
 
 - navigation: `goto`, `reload`, `waitFor`, `waitForTimeout`
@@ -50,16 +90,23 @@ assertions require exactly one of `equals` or `includes`.
       "locator": { "role": "heading", "name": "Settings", "exact": true }
     },
     { "action": "click", "locator": { "testId": "save-settings" } },
-    { "action": "assertText", "locator": { "testId": "toast" }, "includes": "Saved" }
+    { "action": "assertText", "locator": { "testId": "toast" }, "includes": "Saved" },
+    { "action": "screenshot", "name": "settings-saved" }
   ]
 }
 ```
 
-The runner owns Playwright/browser lifecycle, strict network-origin boundaries,
-auth application, assertions, screenshots, video, trace sanitization, and
-cleanup. Do not start an additional shared/default browser session. For multiple
-profiles, invoke the runner separately; each invocation gets an isolated context
-and exclusive evidence directory.
+For multiple profiles, invoke the runner separately. Every invocation gets an
+isolated browser context and exclusive evidence directory; the runner closes
+all owned browser resources on success and failure. Flows, screenshots, video,
+sanitized traces, and runner result manifests remain under
+`$PI_SUBAGENT_AGENT_DIR/browser-qa/` so normal sub-agent shutdown or cleanup
+deletes them with the run directory. For form auth, recording starts on the login
+page and includes field filling and submission; password inputs remain masked,
+but the private video may show visible login identifiers. Tracing starts only
+after login succeeds so credentials are not captured in the trace.
+
+## Credentials and blocked runs
 
 If the runner returns `QA_AUTH_UPDATE_REQUIRED`, stop and explicitly report that
 browser QA requires credentials or an auth-config update. Ask the user to fill
@@ -68,9 +115,13 @@ empty template was created at that path. Relay only the runner's profile, file,
 reason, action, and template-created state; never read the generated file or
 attempt to recover by exposing or replaying credentials.
 
+For any other blocked run, report the runner status and redacted reason. Do not
+claim that browser QA passed based on source inspection, unit tests, or a build.
+
 After any runner invocation that actually performed browser testing, include
 all non-empty `artifacts.screenshots`, `artifacts.videos`, and
 `artifacts.traces` groups in the final response. These links are mandatory so
 the user can open the evidence directly.
 
-See `references/qa-auth.example.jsonc` and `references/qa-flow.example.jsonc`.
+See `references/qa-auth.example.jsonc`, `references/qa-flow.example.jsonc`, and
+`references/qa-design.md`.

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/references/qa-design.md

@@ -0,0 +1,109 @@
+# Designing deterministic browser QA flows
+
+Use this reference with the bundled declarative runner. It intentionally does
+not describe a separate browser CLI or executable Playwright scripts.
+
+## Build the proof before the steps
+
+Write down three things first:
+
+1. **Setup:** the page and state needed to expose the behavior.
+2. **Action:** the smallest user interaction that exercises it.
+3. **Oracle:** the observable state that proves success or reproduces failure.
+
+Good oracles are product-visible and specific: an exact URL, a stable status
+message, a field value, item count, enabled/disabled state, or checked state.
+Avoid treating “the click did not throw” or “the screenshot looks plausible” as
+proof.
+
+When verifying a fix, prefer a focused regression flow over a broad tour of the
+application. If multiple independent states matter, assert each one explicitly.
+
+## Choose resilient locators
+
+Prefer locators that match how users and accessibility APIs identify controls:
+
+1. `testId` when the product exposes a stable test contract.
+2. `role` with accessible `name` for buttons, links, headings, dialogs, and
+   similar semantic elements.
+3. `label` for form controls.
+4. `placeholder` or visible `text` when they are stable product copy.
+5. `css` only when no semantic contract exists.
+
+Use `exact: true` when duplicate or substring matches are possible. Avoid CSS
+that encodes DOM depth, generated classes, styling details, or element order.
+If a locator is ambiguous, inspect nearby source or rendered copy and choose a
+more specific product contract rather than adding arbitrary delays.
+
+## Wait for state, not time
+
+Runner interactions inherit Playwright auto-waiting. Usually an action followed
+by an assertion is enough. Use `waitFor` only when the next operation depends on
+a distinct attached/detached/visible/hidden transition.
+
+`waitForTimeout` is bounded to five seconds and should be exceptional—for a
+known animation, debounce, or externally scheduled transition with no
+observable intermediate state. Sleeping longer hides races instead of proving
+behavior. If a normal operation legitimately needs more time, adjust the flow's
+`timeoutMs` rather than inserting repeated sleeps.
+
+## Authentication transitions
+
+Add `authRejectedIf` directly after initial navigation and after transitions
+that can redirect to login or display an expired-session marker. This converts
+stale credentials into an explicit update request instead of misreporting a
+product regression.
+
+Do not encode credentials, tokens, storage values, or login form secrets in the
+flow. The trusted runner applies the selected profile internally. For form auth,
+video starts on the login page and includes field filling and submission; password
+inputs remain masked, but visible identifiers can appear, so treat the video as
+sensitive private evidence. Tracing starts only after login succeeds and is
+sanitized before retention.
+
+## Evidence strategy
+
+The runner always attempts a final or failure screenshot, records video from the
+first page, and creates a sanitized post-auth trace. Add named `screenshot`
+steps only at states that materially help explain the result—for example before
+and after a destructive interaction, or when a transient success message is
+the oracle.
+
+Use evidence by purpose:
+
+- **Screenshot:** quick review of one meaningful visual state.
+- **Video:** chronological confirmation of the complete user flow.
+- **Trace:** action/DOM timing diagnosis for a failed or flaky interaction.
+
+Assertions determine pass/fail; evidence explains it. Preserve and link every
+artifact group returned on both passed and failed runs.
+
+## Diagnose failures without weakening the test
+
+Classify the first failing step:
+
+- wrong target/setup or service unavailable;
+- authentication rejected or expired;
+- locator no longer matches the product contract;
+- expected state never appeared;
+- actual product behavior contradicts the expectation.
+
+Fix the flow only when its setup or locator is wrong. Do not replace a precise
+assertion with a vague one, increase timeouts reflexively, or remove the failing
+step to manufacture a pass. Keep the failure artifacts and state the expected
+versus observed behavior.
+
+## Cleanup and isolation
+
+Each runner invocation owns one isolated context and evidence directory and
+closes its browser resources in a `finally` path. Do not create parallel shared
+or default sessions outside the runner. Test multiple auth profiles with
+separate invocations so cookies, storage, traces, and evidence cannot mix.
+
+Keep the declarative flow and every generated screenshot, video, trace, and
+result manifest inside `$PI_SUBAGENT_AGENT_DIR/browser-qa/`. The launcher owns
+that path and the runner validates it before opening a browser. Do not override
+the environment path or copy evidence into shared `.pi/qa-runs`/`.pi/qa-flows`
+directories: the agent-local workspace is intentionally removed by the normal
+sub-agent shutdown and cleanup lifecycle. Authentication config remains a
+separate persistent input under project `.pi/`.

package/external/pi-tools-suite/src/async-subagents/private-skills/browser-qa/scripts/browser-qa-runner.mjs

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 
-import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
@@ -9,8 +8,10 @@ import { parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
 import { strFromU8, strToU8, unzipSync, zipSync } from "../vendor/fflate.mjs";
 
 const CONFIG_RELATIVE = ".pi/qa_auth.jsonc";
-const STATE_RELATIVE = path.join(".pi", "qa-auth-state");
-const RUNS_RELATIVE = path.join(".pi", "qa-runs");
+const SUBAGENT_AGENT_DIR_ENV = "PI_SUBAGENT_AGENT_DIR";
+const QA_WORKSPACE_RELATIVE = "browser-qa";
+const EVIDENCE_RELATIVE = "evidence";
+const FORM_VIDEO_STEP_DELAY_MS = 250;
 const EXIT_AUTH_UPDATE_REQUIRED = 42;
 const EXIT_PROFILE_REQUIRED = 43;
 const PROFILE_ID = /^[A-Za-z0-9._-]+$/;
@@ -80,23 +81,25 @@ async function main() {
 	const profile = selected.profile;
 	const secrets = collectSecrets(profile.auth);
 	try {
-		await runQa({ cwd, args, profileId, profile });
+		const agentDir = resolveBrowserQaAgentDirectory(cwd, process.env[SUBAGENT_AGENT_DIR_ENV]);
+		await runQa({ cwd, agentDir, args, profileId, profile });
 	} catch (error) {
 		if (error instanceof QaStatusError) throw error;
 		throw new QaStatusError("QA_RUN_FAILED", redact(safeReason(error), secrets), 1, profileId);
 	}
 }
 
-async function runQa({ cwd, args, profileId, profile }) {
+async function runQa({ cwd, agentDir, args, profileId, profile }) {
 	if (!args.flow) throw new QaStatusError("QA_RUN_FAILED", "--flow is required", 1, profileId);
-	const flowPath = resolveExistingPrivateFile(cwd, args.flow, "QA flow", false);
+	const workspaceDir = path.join(agentDir, QA_WORKSPACE_RELATIVE);
+	const flowPath = resolveExistingPrivateFile(workspaceDir, args.flow, "QA flow", false);
 	const flow = readFlow(flowPath, profileId);
 	const allowedOrigins = normalizeAllowedOrigins(profile.allowedOrigins, profileId);
 	const baseURL = normalizeBaseUrl(args.baseUrl ?? profile.baseUrl ?? allowedOrigins[0], allowedOrigins, profileId);
 	validateAuthConfiguration(cwd, profile.auth, allowedOrigins, profileId);
 	const runId = safeRunId(args.runId ?? `${timestamp()}-${profileId}`);
-	const evidenceDir = path.join(cwd, RUNS_RELATIVE, runId, profileId);
-	createExclusivePrivateDirectory(cwd, evidenceDir);
+	const evidenceDir = path.join(workspaceDir, EVIDENCE_RELATIVE, runId, profileId);
+	createExclusivePrivateDirectory(agentDir, evidenceDir);
 
 	const playwright = loadPlaywright(cwd);
 	const browser = await playwright.chromium.launch({ headless: true });
@@ -108,7 +111,7 @@ async function runQa({ cwd, args, profileId, profile }) {
 	const runtimeSecrets = collectSecrets(profile.auth);
 	const tracePath = path.join(evidenceDir, "trace.zip");
 	try {
-		const contextOptions = await contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins, browser });
+		const contextOptions = await contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins });
 		context = await browser.newContext({
 			...contextOptions,
 			baseURL,
@@ -118,10 +121,11 @@ async function runQa({ cwd, args, profileId, profile }) {
 		});
 		await installOriginGuard(context, allowedOrigins, profile.auth);
 		await applyContextAuth(context, profile.auth, allowedOrigins, baseURL, profileId);
-		runtimeSecrets.push(...collectStorageStateSecrets(await context.storageState()));
-		await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
 		page = await context.newPage();
 		video = page.video();
+		await applyFormAuth(page, profile.auth, allowedOrigins, profileId);
+		runtimeSecrets.push(...collectStorageStateSecrets(await context.storageState()));
+		await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
 		await executeFlow({ page, context, baseURL, evidenceDir, flow, allowedOrigins, profileId, secrets: runtimeSecrets });
 		await assertPageDoesNotExposeSecrets(page, runtimeSecrets, profileId);
 		await page.screenshot({ path: path.join(evidenceDir, "final.png"), fullPage: true });
@@ -461,7 +465,7 @@ function isStringArray(value) {
 	return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string");
 }
 
-async function contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins, browser }) {
+async function contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins }) {
 	const auth = profile.auth;
 	if (auth.type === "storageState") {
 		if (typeof auth.path !== "string") throw authError(profileId, "storageState path is missing");
@@ -469,16 +473,7 @@ async function contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins,
 		return { storageState: filteredStorageState(statePath, allowedOrigins, profileId) };
 	}
 	if (auth.type === "form") {
-		const stateDirectory = path.join(cwd, STATE_RELATIVE);
-		const statePath = path.join(stateDirectory, `${profileId}-${authCacheKey(auth, allowedOrigins)}.json`);
-		if (!fs.existsSync(statePath)) {
-			ensurePrivateDirectory(cwd, stateDirectory);
-			for (const name of fs.readdirSync(stateDirectory)) {
-				if (name.startsWith(`${profileId}-`) && name.endsWith(".json")) fs.rmSync(path.join(stateDirectory, name), { force: true });
-			}
-			await createFormState({ statePath, auth, allowedOrigins, browser, profileId });
-		}
-		return { storageState: filteredStorageState(statePath, allowedOrigins, profileId) };
+		return {};
 	}
 	if (!["cookie", "localStorage", "sessionStorage", "bearer"].includes(auth.type)) {
 		throw authError(profileId, `unsupported auth type: ${auth.type}`);
@@ -486,39 +481,36 @@ async function contextOptionsForAuth({ cwd, profileId, profile, allowedOrigins,
 	return {};
 }
 
-async function createFormState({ statePath, auth, allowedOrigins, browser, profileId }) {
+async function applyFormAuth(page, auth, allowedOrigins, profileId) {
+	if (auth.type !== "form") return;
 	if (typeof auth.loginUrl !== "string" || !isAllowedUrl(auth.loginUrl, allowedOrigins)) {
 		throw authError(profileId, "form loginUrl is missing or outside allowedOrigins");
 	}
 	if (!Array.isArray(auth.fields) || auth.fields.length === 0 || typeof auth.submitSelector !== "string") {
 		throw authError(profileId, "form fields or submitSelector are missing");
 	}
-	const context = await browser.newContext();
 	try {
-		await installOriginGuard(context, allowedOrigins, auth);
-		const page = await context.newPage();
-		await page.goto(auth.loginUrl);
+		const timeout = Math.min(finitePositive(auth.timeoutMs) ?? 15_000, 60_000);
+		page.setDefaultTimeout(timeout);
+		page.setDefaultNavigationTimeout(timeout);
+		await page.goto(auth.loginUrl, { timeout });
+		await page.waitForTimeout(FORM_VIDEO_STEP_DELAY_MS);
 		for (const field of auth.fields) {
 			if (!isObject(field) || typeof field.selector !== "string" || typeof field.value !== "string") {
 				throw authError(profileId, "form fields must contain selector/value strings");
 			}
 			await page.locator(field.selector).fill(field.value);
+			await page.waitForTimeout(FORM_VIDEO_STEP_DELAY_MS);
 		}
 		await page.locator(auth.submitSelector).click();
-		const timeout = finitePositive(auth.timeoutMs) ?? 15_000;
 		if (isObject(auth.success) && typeof auth.success.url === "string") await page.waitForURL(auth.success.url, { timeout });
 		if (isObject(auth.success) && typeof auth.success.selector === "string") await page.locator(auth.success.selector).waitFor({ timeout });
 		if (!isObject(auth.success) || (typeof auth.success.url !== "string" && typeof auth.success.selector !== "string")) {
 			throw authError(profileId, "form success.url or success.selector is required");
 		}
-		fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
-		await context.storageState({ path: statePath });
-		fs.chmodSync(statePath, 0o600);
 	} catch (error) {
 		if (error instanceof QaStatusError) throw error;
 		throw authError(profileId, "form login was rejected or did not reach the configured success condition");
-	} finally {
-		await context.close().catch(() => {});
 	}
 }
 
@@ -546,10 +538,6 @@ async function applyContextAuth(context, auth, allowedOrigins, baseURL, profileI
 	}
 }
 
-function authCacheKey(auth, allowedOrigins) {
-	return createHash("sha256").update(JSON.stringify({ auth, allowedOrigins })).digest("hex").slice(0, 16);
-}
-
 async function installOriginGuard(context, allowedOrigins, auth) {
 	await context.route("**/*", async (route) => {
 		const request = route.request();
@@ -779,6 +767,45 @@ function isAllowedUrl(raw, allowedOrigins) {
 	}
 }
 
+function resolveBrowserQaAgentDirectory(cwd, value) {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new Error(`${SUBAGENT_AGENT_DIR_ENV} is required for browser QA runs`);
+	}
+	const projectRoot = fs.realpathSync(cwd);
+	const subagentRoot = path.join(projectRoot, ".pi", "subagents");
+	const resolved = path.resolve(value);
+	if (!fs.existsSync(resolved)) throw new Error("browser QA agent directory is missing");
+	const real = fs.realpathSync(resolved);
+	if (!isInside(subagentRoot, real)) throw new Error("browser QA agent directory must be inside .pi/subagents");
+	assertNoSymlinkComponents(projectRoot, real, "browser QA agent directory");
+	if (!fs.statSync(real).isDirectory()) throw new Error("browser QA agent directory must be a real directory");
+
+	const promptFile = path.join(real, "prompt.md");
+	const projectFile = path.join(real, "project_cwd");
+	const typeFile = path.join(real, "subagent_type");
+	for (const [file, label] of [[promptFile, "prompt"], [projectFile, "project metadata"], [typeFile, "type metadata"]]) {
+		if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`browser QA ${label} is missing`);
+		assertNoSymlinkComponents(real, file, `browser QA ${label}`);
+	}
+	const recordedProject = fs.readFileSync(projectFile, "utf8").trim();
+	if (!recordedProject || fs.realpathSync(recordedProject) !== projectRoot) {
+		throw new Error("browser QA agent directory belongs to another project");
+	}
+	if (fs.readFileSync(typeFile, "utf8").trim() !== "browser-qa") {
+		throw new Error("browser QA runner requires a browser-qa sub-agent directory");
+	}
+
+	const workspace = path.join(real, QA_WORKSPACE_RELATIVE);
+	if (!fs.existsSync(workspace)) throw new Error("browser QA workspace is missing");
+	assertNoSymlinkComponents(real, workspace, "browser QA workspace");
+	const workspaceStat = fs.statSync(workspace);
+	if (!workspaceStat.isDirectory()) throw new Error("browser QA workspace must be a real directory");
+	if (process.platform !== "win32" && (workspaceStat.mode & 0o077) !== 0) {
+		throw new Error("browser QA workspace must use private directory permissions (0700)");
+	}
+	return real;
+}
+
 function resolveExistingPrivateFile(cwd, value, label, requirePrivate = true) {
 	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} path is missing`);
 	const root = fs.realpathSync(cwd);
@@ -794,9 +821,13 @@ function resolveExistingPrivateFile(cwd, value, label, requirePrivate = true) {
 	return real;
 }
 
-function assertInside(root, target, label) {
+function isInside(root, target) {
 	const relative = path.relative(root, target);
-	if (!relative || (!relative.startsWith("..") && !path.isAbsolute(relative))) return;
+	return !relative || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function assertInside(root, target, label) {
+	if (isInside(root, target)) return;
 	throw new Error(`${label} must be project-local`);
 }
 
@@ -843,10 +874,6 @@ function createExclusivePrivateDirectory(cwd, target) {
 	createPrivateDirectory(cwd, target, true);
 }
 
-function ensurePrivateDirectory(cwd, target) {
-	createPrivateDirectory(cwd, target, false);
-}
-
 function createPrivateDirectory(cwd, target, exclusive) {
 	const root = fs.realpathSync(cwd);
 	const resolved = path.resolve(target);

package/external/pi-tools-suite/src/default-pi-tools-suite-config.ts

@@ -300,6 +300,13 @@ export const DEFAULT_PI_TOOLS_SUITE_CONFIG_JSONC = String.raw`{
           "When no mockup exists, choose a clear aesthetic direction and explain it briefly. Verify with targeted build/lint/tests or screenshot-relevant checks when possible."
         ]
       },
+      "browser-qa": {
+        "description": "Use for browser-based visual QA: reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.",
+        "model": "openai-codex/gpt-5.4-mini",
+        "fallbackModels": ["antigravity/gemini-3-flash-preview", "zai/glm-5.3"],
+        "thinking": "medium",
+        "tools": ["read", "grep", "bash"]
+      },
       "tests": {
         "description": "Use for tests: locate coverage, find gaps, run/check targeted test commands, diagnose failing tests.",
         "model": "zai/glm-5-turbo",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {