pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/docs/subagent-model-pools.md

@@ -0,0 +1,109 @@
+# Sub-agent model pools
+
+Sub-agents primarily reduce the cost of bounded work and keep intermediate
+source, searches and logs out of the parent context. The parent owns planning,
+integration, decisions and the final answer. Actual savings depend on worker
+quality, retries and how much work the parent repeats; the configuration is
+not a price oracle.
+
+## Five execution modes
+
+- `research`: read-only evidence gathering, searches and independent diff review.
+- `implement`: bounded code, documentation, test and frontend changes.
+- `verify`: run checks and interpret logs, without fixing source or tests.
+- `browser-qa`: isolated browser workflow with assertions and visual artifacts.
+- `oracle`: a deliberate strong second opinion, not automatic worker escalation.
+
+Task-specific discipline belongs in the brief or `promptAppend`. A new project
+agent is warranted when it adds a durable contract, capabilities or resources,
+not merely a professional title. `verify` has a behavioral no-edit contract;
+shell access is not a read-only filesystem sandbox.
+
+## Agent priority, preset availability
+
+Each Markdown profile owns its ordered `models` list. This is one candidate
+chain for initial selection and subsequent quota fallbacks:
+
+```yaml
+---
+description: Make bounded implementation changes.
+models:
+  - zai/glm-5.3-flash
+  - openai-codex/gpt-5.6-terra
+  - openai-codex/gpt-5.6-luna
+thinking: medium
+---
+```
+
+A preset contains a set of available models, not a per-agent matrix:
+
+```jsonc
+{
+  "asyncSubagents": {
+    "presets": {
+      "gpt": {
+        "description": "Models available for this session",
+        "models": [
+          "openai-codex/gpt-5.6-luna",
+          "openai-codex/gpt-5.6-terra",
+          "openai-codex/gpt-5.6-sol"
+        ]
+      }
+    }
+  }
+}
+```
+
+The example agent selects Terra, not Luna: the agent's order wins. Sol is
+available in the pool but absent from this worker's chain, so it cannot become
+an automatic implementation fallback. The oracle can declare Sol in its own
+chain. Model references must be exact `provider/model` values, not wildcards.
+
+The resolver intersects the agent chain with the selected pool. Runtime
+selection then skips unregistered, unauthenticated or session-exhausted models.
+Tasks with images and browser QA require confirmed image support. The first
+eligible candidate runs; only the remaining eligible candidates are passed to
+quota fallback. An empty intersection or unavailable chain rejects the batch
+before any children or run state are created. Model selection makes no LLM
+completion request; the optional role router is a separate operation.
+
+Oracle prefers another provider when possible, but still respects the pool.
+It never substitutes an ordinary cheap candidate merely to avoid a selection
+error. A single-provider pool cannot promise cross-provider independence.
+
+Explicit task `model`, CLI `--model`, and `FORCE_CURRENT_MODEL` remain deliberate
+overrides: they bypass the pool and do not add automatic fallback candidates.
+The parent should not use these to evade the configured budget. The pool is
+a selection policy, not a security boundary against explicit overrides.
+
+## Selection and compatibility
+
+Use `/subagent-preset <name>`, `AGENTS_PRESET=<name>` or
+`/subagent-preset session <name>`. Clearing the preset uses agent priorities
+without a pool filter. The shipped names remain compatible with saved choices:
+`cheap` is the GLM pool, `gpt` the GPT pool, and `deep` the mixed pool. The last
+name no longer means that ordinary workers should escalate to flagship models.
+
+Old role names are not implicit aliases. `quick`, `scan`, `review`, `deep`,
+`docs`, `frontend`, and `tests` work only when explicitly defined as ordinary
+custom/project types. This keeps the effective catalog and accepted names exact.
+
+Legacy `model` plus `fallbackModels` and `modelByParent` still load. New profile
+`models` replaces inherited legacy selection fields; an explicit legacy model
+override can still replace an inherited new list. Empty `models` means no
+candidates, not permission to inherit the parent model. Model-less project
+specialists must declare candidates or receive an explicit model override.
+
+Legacy preset role matrices remain readable. A preset with `models` uses only
+the pool contract, dropping stale legacy model/thinking/type overrides. Switching
+a higher-priority config layer back to a legacy preset removes the inherited
+pool. Configuration loading never rewrites user files; review old overrides
+when migrating, since explicitly saved profiles can retain expensive models.
+
+## Compact handoff
+
+Give workers a scope, acceptance criteria and the evidence needed to start.
+Read compact results first and inspect raw artifacts selectively. One noisy
+sequential investigation can justify a worker; a command whose exit status is
+sufficient usually only needs a saved log, not another LLM. Independent review
+uses a fresh `research` invocation, not a separate built-in persona.

package/external/pi-tools-suite/package.json

@@ -29,6 +29,13 @@
     "test:prompt-evals:async": "PROMPT_EVAL_E2E=1 bun test --concurrent --max-concurrency=5 test/async-subagents/selection-e2e.test.ts test/prompt-evals/async-routing-e2e.test.ts",
     "test:prompt-evals:dcp": "PROMPT_EVAL_E2E=1 bun test --concurrent --max-concurrency=5 test/prompt-evals/dcp-summary-e2e.test.ts",
     "test:prompt-evals": "PROMPT_EVAL_E2E=1 bun test --concurrent --max-concurrency=5 test/tool-selection-e2e.test.ts test/async-subagents/selection-e2e.test.ts test/prompt-evals",
+    "test:evals:contracts": "bun test test/evals/extension-contracts.test.ts test/evals/harness.test.ts",
+    "test:evals:live": "PI_TOOLS_SUITE_EVALS_LIVE=1 bun test --concurrent --max-concurrency=4 test/evals/live-evals.test.ts",
+    "evals": "npm run test:evals:contracts && bun test test/evals/live-evals.test.ts",
+    "evals:report": "bun test/evals/run-evals.ts",
+    "evals:p01n": "bun test/evals/run-p01n-paired.ts",
+    "evals:context-gateway-observe": "bun test/evals/run-context-gateway-observe.ts",
+    "evals:context-gateway-recovery": "bun test/evals/run-context-gateway-recovery.ts",
     "bench:locate": "PI_LOCATE_BENCH_ITERATIONS=5 PI_LOCATE_BENCH_FAKE_IDX=0 PI_LOCATE_BENCH_MODEL=zai/glm-5-turbo PI_LOCATE_BENCH_MODES=direct-read-grep,ast-structural,repo-search-hybrid,repo-discovery,subagent-search,unrestricted-suite node test/fixtures/hard-to-find-project/benchmark/run-locate-benchmark.mjs",
     "bench:locate:analyze": "node test/fixtures/hard-to-find-project/benchmark/analyze-locate-benchmark.mjs",
     "test:locate-benchmark-e2e": "PI_LOCATE_BENCH_E2E=1 PI_LOCATE_BENCH_MODEL=zai/glm-5-turbo bun test test/locate-benchmark-e2e.test.ts",
@@ -44,9 +51,9 @@
     "vscode-languageserver-protocol": "^3.17.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.85.0",
-    "@earendil-works/pi-coding-agent": "0.85.0",
-    "@earendil-works/pi-tui": "0.85.0",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "typebox": "*"
   },
   "devDependencies": {

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

@@ -2206,12 +2206,60 @@ foreach ($candidatePid in $descendants) {
 		});
 		return;
 	}
+
+	// Prefer parent-based enumeration when available. macOS sandboxed hosts can
+	// deny `ps` while still allowing pgrep(1); relying only on `ps` leaves a
+	// detached Playwright/browser process alive after a timeout. Collect the
+	// whole tree before killing anything so descendants cannot be re-parented
+	// out of reach, then terminate deepest-first. A detached child is normally a
+	// process-group leader, so also try its negative PID before the individual
+	// PID; non-group-leaders simply yield ESRCH and fall through safely.
+	const pgrepDescendants = [];
+	const pgrepPendingParents = [process.pid];
+	let pgrepAvailable = true;
+	for (let index = 0; index < pgrepPendingParents.length; index += 1) {
+		const parentPid = pgrepPendingParents[index];
+		const result = spawnSync("pgrep", ["-P", String(parentPid)], {
+			encoding: "utf8",
+			timeout: 1000,
+			maxBuffer: 256 * 1024,
+		});
+		if (result.error?.code === "ENOENT") {
+			pgrepAvailable = false;
+			break;
+		}
+		if (result.status !== 0 && result.status !== 1) {
+			pgrepAvailable = false;
+			break;
+		}
+		for (const line of (result.stdout ?? "").split("\n")) {
+			const pid = Number(line.trim());
+			if (!Number.isInteger(pid) || pid <= 0 || pgrepDescendants.includes(pid)) continue;
+			pgrepDescendants.push(pid);
+			pgrepPendingParents.push(pid);
+		}
+	}
+	if (pgrepAvailable) {
+		for (const pid of [...pgrepDescendants].reverse()) {
+			try { process.kill(-pid, "SIGKILL"); } catch { /* not a group leader or already gone */ }
+			try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+		}
+		return;
+	}
+
 	const snapshot = spawnSync("ps", ["-axo", "pid=,ppid=,pgid="], {
 		encoding: "utf8",
 		timeout: 1000,
 		maxBuffer: 2 * 1024 * 1024,
 	});
-	if (snapshot.status !== 0 || !snapshot.stdout) return;
+	if (snapshot.status !== 0 || !snapshot.stdout) {
+		// Sandboxed macOS hosts can deny `ps` process enumeration while still
+		// allowing parent-scoped `pgrep -P`. Fall back to a bounded recursive
+		// parent walk so a detached browser process is not left behind merely
+		// because the broader process snapshot is unavailable.
+		terminateRunnerDescendantsWithPgrep(process.pid);
+		return;
+	}
 	const processes = snapshot.stdout
 		.split("\n")
 		.map((line) => line.trim().split(/\s+/).map(Number))
@@ -2241,6 +2289,39 @@ foreach ($candidatePid in $descendants) {
 	}
 }
 
+function terminateRunnerDescendantsWithPgrep(rootPid) {
+	const descendants = [];
+	const seen = new Set([rootPid]);
+	const pendingParents = [rootPid];
+	for (let index = 0; index < pendingParents.length && descendants.length < 4096; index += 1) {
+		const parentPid = pendingParents[index];
+		const result = spawnSync("pgrep", ["-P", String(parentPid)], {
+			encoding: "utf8",
+			timeout: 500,
+			maxBuffer: 256 * 1024,
+		});
+		// pgrep exits 1 when there are no matching children. Any other failure is
+		// fail-closed for this fallback; callers still terminate the runner itself.
+		if (result.status !== 0 && result.status !== 1) continue;
+		for (const line of (result.stdout ?? "").split("\n")) {
+			const pid = Number.parseInt(line.trim(), 10);
+			if (!Number.isInteger(pid) || pid <= 0 || seen.has(pid)) continue;
+			seen.add(pid);
+			descendants.push(pid);
+			pendingParents.push(pid);
+		}
+	}
+
+	// Kill leaves before their parents so descendants cannot be reparented
+	// before we have sent them a signal. Detached children are killed by PID;
+	// unlike the primary `ps` path this fallback does not need their PGID.
+	for (let index = descendants.length - 1; index >= 0; index -= 1) {
+		try {
+			process.kill(descendants[index], "SIGKILL");
+		} catch { /* already gone */ }
+	}
+}
+
 function sanitizeTraceArchiveInWorker(tracePath, secrets, deadline) {
 	return new Promise((resolve, reject) => {
 		const worker = new Worker(new URL(import.meta.url), {

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

@@ -1,15 +1,25 @@
 ---
-name: browser-qa-private
-description: Private self-contained workflow for deterministic browser bug reproduction and fix verification with redacted project auth and Playwright evidence.
+description: Use for browser-based visual QA - reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.
+icon: globe
+models: [zai/glm-5.3-flash, openai-codex/gpt-5.6-luna]
+thinking: low
+timeoutMs: 300000
+tools: [read, grep, bash]
 ---
 
 # Browser QA
 
-Use this skill's bundled runner as the only browser interface. It already owns
+Use this agent'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.
 
+The launcher sets `PI_BROWSER_QA_RUNNER` to the absolute path of the installed
+runner. Invoke it as `node "$PI_BROWSER_QA_RUNNER"`; do not guess a path from
+the project cwd, override this variable, or copy/reimplement the runner.
+The complete workflow and scenario-design guidance are included below. No
+additional skill or instruction-file discovery is needed.
+
 Never read, print, grep, copy, or edit credential values from
 `.pi/qa_auth.jsonc` yourself.
 
@@ -37,7 +47,8 @@ inside the preflight, return a structured `BLOCKED` result immediately. Do not
 consume the launcher budget on open-ended source reading, server polling,
 capability probing, or retries.
 
-1. Resolve `scripts/browser-qa-runner.mjs` relative to this skill.
+1. Use the launcher-provided `PI_BROWSER_QA_RUNNER` path. If it is missing,
+   report a launcher configuration blocker rather than selecting another runner.
 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
@@ -48,7 +59,7 @@ capability probing, or retries.
    be reached or started, report the concrete blocker instead of switching to a
    mock target or substituting static checks for browser QA.
 4. If the requested behavior requires authentication, run
-   `node <runner> profiles`. A missing auth config is valid and returns an empty
+   `node "$PI_BROWSER_QA_RUNNER" profiles`. A missing auth config returns an empty
    list without creating `.pi/qa_auth.jsonc`. Otherwise skip profile discovery
    and use public mode. Choose an auth profile only when the task names its id,
    safe profile traits make the choice unambiguous, or a public run proves that
@@ -61,7 +72,8 @@ capability probing, or retries.
    executable JavaScript in it. The `evaluate` action exposes only the safe
    operations documented below; it does not accept expressions or scripts.
 6. Run public QA with
-   `node <runner> run --base-url <url> --flow <flow.jsonc>`. The URL's exact
+   `node "$PI_BROWSER_QA_RUNNER" run --base-url <url> --flow <flow.jsonc>`.
+   The URL's exact
    origin becomes the fail-closed allowlist. When the real app requires known
    API/CDN origins, add repeatable `--allow-origin <exact-origin>` flags. Each
    value must be an exact `http(s)` origin with no path, credentials, wildcard,
@@ -128,8 +140,8 @@ capability probing, or retries.
   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.
+Use the detailed scenario-design guidance below for non-trivial flows,
+ambiguous failures, and decisions about what evidence proves the result.
 
 ## Flow contract
 
@@ -293,7 +305,7 @@ When a public HTTPS login page (or loopback HTTP page for local development) is
 known and there is no usable profile, invoke the trusted runner once:
 
 ```sh
-node <runner> auth scaffold \
+node "$PI_BROWSER_QA_RUNNER" auth scaffold \
   --profile <safe-id> \
   --login-url <public-login-url>
 ```
@@ -322,7 +334,7 @@ Do not request credentials merely because `.pi/qa_auth.jsonc` is absent. If the
 task explicitly requires authenticated behavior, or a public run reaches the
 flow's `authRejectedIf` check, and `profiles` returned no usable profile, run
 form-auth scaffolding when supported. Otherwise run
-`node <runner> profiles --require-auth`. Only these explicit authenticated paths
+`node "$PI_BROWSER_QA_RUNNER" profiles --require-auth`. Only these paths
 may create the private auth file.
 
 If that command or an authenticated run returns `QA_AUTH_UPDATE_REQUIRED`, stop
@@ -345,5 +357,242 @@ These links are mandatory so the user can open the evidence directly.
 Also include `visualInspection` with `inspected` or `unavailable`; never infer a
 visual pass from a successful runner status alone.
 
-See `references/qa-auth.example.jsonc`, `references/qa-flow.example.jsonc`,
-`references/qa-design.md`, and `references/auth-scaffold-spec.md`.
+### Scaffold safety and edge cases
+
+The trusted runner discovers the most likely form, fillable fields, submit
+control, and form container on the unauthenticated page. It writes only
+discovered selectors and generated placeholders to the private `0600` config.
+The agent treats that config as opaque and user-owned. Scaffold status exposes
+only the file path, profile id, counts, and action, never inspected DOM text,
+input values, URLs, or selectors.
+
+Scaffolding rejects pages without a discoverable fillable field or submit
+control, form-less pages without an explicit success condition, remote HTTP
+login pages, cross-origin base URLs, malformed success options, symlinked or
+permissive auth paths, and invalid or non-empty existing configuration. Report
+these blockers; do not bypass them. No generated profile is usable until the
+user replaces its secret placeholders.
+
+## Detailed scenario-design guidance
+
+Use the bundled declarative runner throughout. This workflow does not require
+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.
+
+For explicit exploratory/manual QA, keep exploration bounded rather than turning
+it into an open-ended crawl. Run at most three minimal rounds. Each round should
+start from one concrete hypothesis, produce a deterministic observation plus a
+meaningful screenshot, and use that evidence to decide whether another round is
+justified. Verification tasks remain one browser run per profile.
+
+### 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.
+
+After navigation and visible interactions, the runner also waits for DOM
+readiness, tracks requests causally started by that action through a bounded
+readiness window, waits for common visible
+`aria-busy`/progress/loading/spinner/skeleton markers, and keeps a 500 ms stable
+interval. EventSource/WebSocket traffic is ignored, and a long poll is not
+allowed to pin the entire flow timeout. A visible busy indicator may still hold
+readiness until `timeoutMs`. This is a safe baseline, not an application-specific
+oracle: explicitly wait for a custom loader to become hidden and assert the
+loaded content when the application uses different readiness semantics.
+
+`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.
+
+All assertion actions retry until that timeout. This makes an action followed
+directly by `assertText`, `assertVisible`, `assertURL`, or another assertion
+safe for asynchronously rendered outcomes. `assertText` requires the locator to
+be visible and matches rendered `innerText`; use `assertTextContent` only when
+hidden/raw DOM text is deliberately part of the oracle. Use `assertAttribute` for
+observable state such as `aria-expanded`, `aria-invalid`, or `data-state`
+instead of reading DOM state through executable JavaScript.
+
+### Responsive and scrolling scenarios
+
+Set the flow's top-level `viewport` whenever the bug depends on a breakpoint or
+available height. Assert `viewportWidth` or `viewportHeight` with
+`assertDOMMetric` when the dimensions themselves are part of the proof; the
+runner also includes the applied viewport in its result.
+
+Use `wheel` to reproduce real pointer-wheel input. Add a locator when the wheel
+must target a nested scrolling container—the runner hovers it before sending
+the input. Because browser scrolling may be scheduled after the wheel event,
+wait only for a short known settling interval when a direct metric assertion is
+otherwise racy.
+
+Use safe `evaluate` `scrollTo`/`scrollBy` operations for deterministic setup or
+to distinguish input handling from layout behavior. Use the `metrics` operation
+to retain a named page/element snapshot in result `observations`, and use
+`assertDOMMetric` for pass/fail. Raw JavaScript expressions are intentionally
+excluded: flows remain declarative and cannot inspect authentication storage or
+execute arbitrary same-origin requests.
+
+### Deterministic browser environment
+
+Set top-level `environment` when locale, timezone, color scheme, or motion
+preferences can change the behavior. The runner otherwise uses stable defaults
+(`en-US`, `UTC`, `light`, `reduce`) instead of inheriting host settings. Prefer
+asserting product-visible copy or state derived from those settings; do not use
+screenshot pixels as the only oracle.
+
+### Causal network and dialog expectations
+
+Put `expectResponse` or `expectDialog` on the interaction that causes the event.
+The runner arms both listeners before the interaction, avoiding the race in a
+separate “click, then wait” sequence. Response expectations deliberately match
+only an exact allowlisted-origin pathname, HTTP method, and status. This proves
+that a matching request started and received a response within the action
+window without retaining its URL query, headers, or body.
+
+Dialog expectations match a fixed dialog type and exact/included message, then
+accept or dismiss it declaratively. A mismatch is dismissed before the step
+fails so the page cannot freeze. Actual event metadata is never included in
+failure diagnostics. Do not place secrets in expected messages or response
+paths even though the runner keeps diagnostics generic.
+
+### Drag, upload, and download scenarios
+
+Use `dragTo` for native DOM drag/drop and assert the resulting product state.
+Optional source/drop positions are relative bounded coordinates. Canvas-only,
+OS-native, or custom synthetic-event drag protocols remain unsupported; do not
+work around that with executable JavaScript.
+
+Uploads are memory-only base64 payloads declared in the flow. This intentionally
+prevents a flow from selecting arbitrary project files, credential config, or
+directories. Keep fixtures minimal and non-secret. An empty file list clears a
+file input.
+
+Use the atomic `download` action rather than clicking a download link directly.
+Always match the suggested filename and choose a tight `maxBytes`. Retain a
+download only when its contents are needed as evidence; otherwise the runner
+deletes it after validation. Retained downloads use generated private names,
+not server-provided paths, and are scanned for configured authentication before
+publication. `maxBytes` bounds the runner's private evidence copy and triggers
+cancellation while it grows, but it is not a network-bandwidth guarantee: the
+browser can receive temporary bytes before cancellation.
+
+### Same-origin frames and popups
+
+Use a scoped `target` for iframe or named popup interactions. The runner checks
+the live frame origin before every scoped step and checks a popup after it loads;
+both must remain in `allowedOrigins`. This supports embedded application UI and
+same-origin auxiliary windows without opening a route around the network guard.
+Cross-origin login, payment, and third-party widgets remain intentionally out of
+scope. Each popup adds a separate private video artifact, so open only the
+windows needed for the proof.
+
+### 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.
+
+Videos automatically show a transient cursor and yellow pulse for clicks and
+double-clicks. After a native `dragTo` gesture completes, its resolved
+source-to-target route is replayed over 450 ms with a large orange cursor and
+progressively drawn high-contrast trail, followed by a green drop marker. These
+annotations are
+runner-owned, pointer-transparent, and accessibility-hidden; they cover the main
+page, same-origin frames, declared popups, and form-auth submission. Their
+bounded animations finish within the normal post-action stable interval, so
+they explain the chronology without becoming screenshot or assertion oracles.
+
+Assertions determine pass/fail; evidence explains it. Preserve and link every
+artifact group returned on both passed and failed runs.
+
+For visual QA, do not stop at artifact generation. Open at least one meaningful
+PNG with the model's image-capable `read` path and inspect layout, clipping,
+overlap, state styling, and other visual defects relevant to the scenario. If
+the active model cannot read images, explicitly report visual inspection as
+unavailable rather than treating deterministic assertions as a visual pass.
+
+### 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/agents/implement.md

@@ -0,0 +1,20 @@
+---
+description: Make bounded changes to code, docs, tests, or UI using the parent's requirements and acceptance criteria. Follow local conventions and verify the change. Task-specific discipline belongs in the brief, not a separate role.
+icon: code
+models: [zai/glm-5.3-flash, openai-codex/gpt-5.6-terra, openai-codex/gpt-5.6-luna]
+thinking: medium
+---
+
+# Implement
+
+Execute the bounded change, including documentation, tests, or frontend work
+when requested. Inspect nearby conventions, preserve unrelated work, and do
+not broaden scope or make product/architecture decisions for the parent.
+
+For UI work, preserve the existing design language and inspect supplied visual
+references with an image-capable model. Report unavailable capabilities instead
+of claiming visual verification. Actual browser QA belongs to browser-qa.
+
+Run relevant targeted checks and report changed paths plus their results. If
+requirements conflict or the task exceeds your capabilities, stop with a
+concrete blocker and the evidence already gathered; do not re-plan the project.

package/external/pi-tools-suite/src/async-subagents/agents/oracle.md

@@ -0,0 +1,16 @@
+---
+description: Strong independent second opinion for hard or high-stakes uncertainty. Use sparingly to challenge architecture, plans, root-cause hypotheses, or risk decisions. Prefer another provider within the available pool; read-only advice, not routine execution.
+icon: sparkles
+models: [openai-codex/gpt-5.6-sol, zai/glm-5.3]
+thinking: max
+tools: [read, grep, bash]
+---
+
+# Oracle agent
+
+You are an oracle: a strong model giving an independent second opinion to the
+parent agent. A different provider is preferred within the available pool, but
+not guaranteed; do not claim cross-provider independence without checking.
+Give a concise, decisive recommendation with key
+tradeoffs and risks. Disagree when warranted; do not rubber-stamp. Do not edit
+unless explicitly asked.

package/external/pi-tools-suite/src/async-subagents/agents/research.md

@@ -0,0 +1,18 @@
+---
+description: Read-only evidence gathering - search files, trace behavior, investigate hypotheses, or independently review a diff. Return findings with paths, not raw source. Use verify for running checks and implement for changes.
+icon: search
+models: [zai/glm-5-turbo, openai-codex/gpt-5.6-luna]
+thinking: low
+tools: [read, grep]
+---
+
+# Research
+
+Investigate the assigned question within scope. Read and compare evidence; do
+not edit files or invent missing facts. A review is a fresh investigation of
+the supplied diff, not approval based on the implementer's summary.
+
+Return the answer and supporting file:line references, distinguishing confirmed
+findings from hypotheses. Report gaps or a concrete blocker when the available
+evidence is insufficient. Leave architecture decisions and escalation to the
+parent. Do not dump search results or source files unless explicitly requested.

package/external/pi-tools-suite/src/async-subagents/agents/verify.md

@@ -0,0 +1,18 @@
+---
+description: Run targeted tests, builds, or checks and diagnose their output in an isolated context. Return pass/fail, relevant failure evidence and log paths. Do not fix source code; creating or changing tests belongs to implement.
+icon: flask
+models: [zai/glm-5-turbo, openai-codex/gpt-5.6-luna]
+thinking: low
+tools: [read, grep, bash]
+---
+
+# Verify
+
+Select and run the smallest checks that establish the requested acceptance
+criteria. Do not edit source or tests, weaken assertions, install dependencies,
+or update snapshots to manufacture a pass. Report missing prerequisites.
+
+Keep noisy output in artifacts and return the command, exit status, relevant
+failure excerpt, and log path. Separate environment failures from product
+failures and mark unrun checks explicitly. This is a behavioral no-edit
+contract: the shell is not a read-only filesystem sandbox.