pi-ui-extend 1.0.19 → 1.0.21

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

@@ -251,8 +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 only that skill, so parent and ordinary sub-agent sessions do
-not discover it.
+`--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`,
@@ -287,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,6 +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 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.
 
@@ -37,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
@@ -51,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
@@ -66,9 +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 and private skill, and
-   its isolated child process can register the configured Antigravity model.
-2. Spawn args contain `--no-skills` and only the explicit private skill 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.
@@ -76,6 +87,26 @@ 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
+
+The repository includes a local mock-page E2E that launches real Chromium and
+asserts PNG screenshots, WebM video, sanitized trace output, and absolute
+path/`file:` URI metadata:
+
+```bash
+npx playwright install chromium
+npm run test:browser-qa-e2e
+```
+
+Normal suite tests keep this case skipped; the Publish workflow runs it on
+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/package.json

@@ -22,6 +22,7 @@
     "smoke:tools": "PI_OFFLINE=1 pi --no-session -p \"ping\"",
     "smoke": "npm run smoke:explicit && npm run smoke:auto && npm run smoke:tools",
     "test": "bun test test",
+    "test:browser-qa-e2e": "BROWSER_QA_RUNNER_E2E=1 bun test test/async-subagents/browser-qa-runner.e2e.test.ts",
     "test:async-subagents-e2e": "ASYNC_SUBAGENTS_E2E=1 ASYNC_SUBAGENTS_DEBUG_LOGS=1 ASYNC_SUBAGENTS_MODEL=zai/glm-5-turbo bun test --concurrent --max-concurrency=30 test/async-subagents",
     "test:async-subagents-selection-e2e": "ASYNC_SUBAGENTS_SELECTION_E2E=1 ASYNC_SUBAGENTS_MODEL=zai/glm-5-turbo bun test --concurrent --max-concurrency=30 test/async-subagents/selection-e2e.test.ts",
     "test:prompt-evals:tool-selection": "PROMPT_EVAL_E2E=1 bun test --concurrent --max-concurrency=10 test/tool-selection-e2e.test.ts",

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

@@ -381,7 +381,7 @@ export function resolveAgentTaskConfig(
 	return {
 		profile,
 		extraArgs,
-		isolatedSkills: arrayOfStrings(profile?.isolatedSkills) ?? [],
+		isolatedSkills: resolveIsolatedSkills(selectedType, profile),
 		fallbackModels,
 		retry: resolveRetryConfig(config.retry, profile?.retry),
 		maxResultBytes: profile?.maxResultBytes ?? config.maxResultBytes,
@@ -399,6 +399,12 @@ 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(), ...configured])];
+}
+
 export function resolveSubagentRoutingConfig(config: SubagentConfig): ResolvedSubagentRoutingConfig {
 	return { ...DEFAULT_ROUTING_CONFIG, ...(config.routing ?? {}) };
 }

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/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/external/pi-tools-suite/src/todo/state/replay.ts

@@ -1,6 +1,8 @@
 import type { TaskDetails } from "../tool/types.js";
 import { EMPTY_STATE, type TaskState } from "./state.js";
 
+export const TODO_STATE_ENTRY_TYPE = "pi-tools-suite:todo-state";
+
 /**
  * Discriminator for `details` envelopes that match the persisted `TaskDetails`
  * shape. Defensive — branch entries from older or corrupt sessions are
@@ -12,10 +14,29 @@ export function isTaskDetails(value: unknown): value is TaskDetails {
 	return Array.isArray(v.tasks) && typeof v.nextId === "number";
 }
 
+function taskDetailsFromEntry(entry: unknown): TaskDetails | undefined {
+	const candidate = entry as {
+		type?: string;
+		customType?: string;
+		data?: unknown;
+		message?: { role?: string; toolName?: string; details?: unknown };
+	};
+
+	if (candidate.type === "custom" && candidate.customType === TODO_STATE_ENTRY_TYPE) {
+		return isTaskDetails(candidate.data) ? candidate.data : undefined;
+	}
+
+	const message = candidate.message;
+	if (candidate.type !== "message" || message?.role !== "toolResult" || message.toolName !== "todo") return undefined;
+	return isTaskDetails(message.details) ? message.details : undefined;
+}
+
 /**
- * Walk the current branch in chronological order; the LAST `toolResult` whose
- * `toolName === "todo"` and whose `details` shape matches `TaskDetails` wins
- * (last-write-wins). When no matching entry exists, returns `EMPTY_STATE`.
+ * Walk the current branch in chronological order; the LAST valid snapshot
+ * from either a `todo` tool result or a todo custom state entry wins
+ * (last-write-wins). Custom entries persist slash-command mutations, which do
+ * not otherwise produce tool results. When no matching entry exists, returns
+ * `EMPTY_STATE`.
  *
  * Pure of module state — `index.ts` writes the returned snapshot into the
  * store after this returns. The function explicitly does NOT touch the store
@@ -24,14 +45,11 @@ export function isTaskDetails(value: unknown): value is TaskDetails {
 export function replayFromBranch(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
 	let result: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
 	for (const entry of ctx.sessionManager.getBranch()) {
-		const e = entry as { type?: string; message?: { role?: string; toolName?: string; details?: unknown } };
-		if (e.type !== "message") continue;
-		const msg = e.message;
-		if (!msg || msg.role !== "toolResult" || msg.toolName !== "todo") continue;
-		if (!isTaskDetails(msg.details)) continue;
+		const details = taskDetailsFromEntry(entry);
+		if (!details) continue;
 		result = {
-			tasks: msg.details.tasks.map((t) => ({ ...t })),
-			nextId: msg.details.nextId,
+			tasks: details.tasks.map((t) => ({ ...t })),
+			nextId: details.nextId,
 		};
 	}
 	return result;

package/external/pi-tools-suite/src/todo/todo.ts

@@ -23,7 +23,7 @@ import {
 	syncPersistedPlan,
 } from "./state/persistence.js";
 import { AUTO_CLEAR_COMPLETED_MESSAGE, autoClearCompletedTodos } from "./state/auto-clear.js";
-import { replayFromBranch } from "./state/replay.js";
+import { replayFromBranch, TODO_STATE_ENTRY_TYPE } from "./state/replay.js";
 import { isTaskBlocked, selectTasksByStatus, selectTodoCounts } from "./state/selectors.js";
 import { applyTaskMutation } from "./state/state-reducer.js";
 import { activateStateScope, commitState, getState, replaceState } from "./state/store.js";
@@ -98,6 +98,7 @@ interface TodoToolRegistrationOptions extends TodoToolHooks {
 
 type TodoStateEventContext = { sessionManager?: { getSessionFile?: () => unknown; getSessionId?: () => unknown } };
 type TodoStateEventEmitter = { events?: { emit?: (channel: string, data: unknown) => void } };
+type TodoStateEntryWriter = { appendEntry<T = unknown>(customType: string, data?: T): void };
 
 interface TodosCommandOptions {
 	status?: TaskStatus;
@@ -238,6 +239,20 @@ export function publishTodoState(
 	});
 }
 
+function appendTodoStateSnapshot(
+	pi: TodoStateEntryWriter,
+	action: TaskAction,
+	params: Record<string, unknown>,
+): void {
+	const state = getState();
+	pi.appendEntry(TODO_STATE_ENTRY_TYPE, {
+		action,
+		params,
+		tasks: state.tasks,
+		nextId: state.nextId,
+	});
+}
+
 function handlePersistCommand(args: unknown, ctx: { cwd?: string; hasUI?: boolean; ui?: { notify?: (message: string, level?: NotifyLevel) => void } }): boolean {
 	const [command, subcommand = "status"] = getCommandTokens(args);
 	if (command !== "persist") return false;
@@ -310,12 +325,13 @@ function handleScopeCommand(
 }
 
 function clearTodos(
-	pi: TodoStateEventEmitter,
+	pi: TodoStateEventEmitter & TodoStateEntryWriter,
 	ctx: { cwd?: string; hasUI?: boolean; ui?: { notify?: (message: string, level?: NotifyLevel) => void } },
 ): void {
 	const result = applyTaskMutation(getState(), "clear", { action: "clear" });
 	if (result.op.kind !== "clear") return;
 	commitState(result.state);
+	appendTodoStateSnapshot(pi, "clear", { action: "clear" });
 	publishTodoState(pi, ctx, "clear", { action: "clear" });
 	const sync = syncPersistedPlan(ctx.cwd, result.state);
 	const persistedText = sync?.completed ? `\nProject todo plan removed: ${sync.path}` : "";
@@ -449,9 +465,12 @@ export function registerTodosCommand(pi: ExtensionAPI): void {
 		handler: async (args, ctx) => {
 			activateTodoStateScope(ctx);
 			if (handlePersistCommand(args, ctx)) return;
-			if (handleScopeCommand(args, ctx, () => publishTodoState(pi as TodoStateEventEmitter, ctx))) return;
+			if (handleScopeCommand(args, ctx, () => {
+				appendTodoStateSnapshot(pi, "update", { command: "scope" });
+				publishTodoState(pi as TodoStateEventEmitter, ctx);
+			})) return;
 			if (getCommandTokens(args)[0] === "clear") {
-				clearTodos(pi as TodoStateEventEmitter, ctx);
+				clearTodos(pi, ctx);
 				return;
 			}
 			if (!ctx.hasUI) {
@@ -529,7 +548,10 @@ export function registerTodosCommand(pi: ExtensionAPI): void {
 		description: "Select todo ids to continue from a persisted plan; pending/in_progress items outside the scope become deferred.",
 		handler: async (args, ctx) => {
 			activateTodoStateScope(ctx);
-			handleScopeCommand(`scope ${getCommandText(args)}`, ctx, () => publishTodoState(pi as TodoStateEventEmitter, ctx));
+			handleScopeCommand(`scope ${getCommandText(args)}`, ctx, () => {
+				appendTodoStateSnapshot(pi, "update", { command: "scope" });
+				publishTodoState(pi as TodoStateEventEmitter, ctx);
+			});
 		},
 	});
 
@@ -537,7 +559,7 @@ export function registerTodosCommand(pi: ExtensionAPI): void {
 		description: "Clear all todos on the current branch and remove the persisted project plan if enabled.",
 		handler: async (_args, ctx) => {
 			activateTodoStateScope(ctx);
-			clearTodos(pi as TodoStateEventEmitter, ctx);
+			clearTodos(pi, ctx);
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "1.0.19",
+  "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": {
@@ -58,6 +58,7 @@
     "test": "mise exec node@24.16.0 -- npm run test:inner",
     "test:inner": "node --import tsx --test \"tests/**/*.test.ts\"",
     "test:tools-suite": "npm --prefix external/pi-tools-suite test",
+    "test:browser-qa-e2e": "npm --prefix external/pi-tools-suite run test:browser-qa-e2e",
     "sync:pi-tools-suite": "node scripts/sync-pi-tools-suite.mjs",
     "sync:pi-tools-suite:check": "node scripts/sync-pi-tools-suite.mjs --check",
     "sync:sdk-pin": "node scripts/sync-sdk-pin.mjs",
@@ -86,6 +87,7 @@
   },
   "devDependencies": {
     "@types/node": "24.12.4",
+    "playwright": "1.62.1",
     "tsx": "4.22.1",
     "typescript": "5.9.3"
   },