pi-ui-extend 1.0.20 → 1.0.21

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

@@ -251,9 +251,11 @@ The built-in `browser-qa` role runs on `antigravity/gemini-3-flash-preview`, wit
 `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.
+`--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`,
@@ -288,13 +290,18 @@ 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
+caches generated storage state under `.pi/qa-auth-state`. 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/core/config.ts

@@ -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,21 @@ 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. `.pi/qa_auth.jsonc` and reusable
+`.pi/qa-auth-state/` remain project-local and persistent.
+
+## 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 +113,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,106 @@
+# 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 and removes
+secret-bearing evidence if it detects disclosure.
+
+## Evidence strategy
+
+The runner always attempts a final or failure screenshot, records video, and
+creates a sanitized trace once the browser launches. 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 and reusable
+auth state are separate persistent inputs and stay under project `.pi/`.

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

@@ -10,7 +10,9 @@ 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 EXIT_AUTH_UPDATE_REQUIRED = 42;
 const EXIT_PROFILE_REQUIRED = 43;
 const PROFILE_ID = /^[A-Za-z0-9._-]+$/;
@@ -80,23 +82,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 });
@@ -779,6 +783,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 +837,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`);
 }
 

package/package.json

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