pi-ui-extend 1.0.37 → 1.0.39

package/docs/desktop-task-manager.md

@@ -0,0 +1,124 @@
+# Spec: Desktop Project Task Manager
+
+## Type
+
+Change
+
+## Goal
+
+Add a project-scoped task list to Pix Desktop in a persistent left sidebar and
+allow a saved task to start work immediately in a new session tab.
+
+## Scope
+
+- A collapsible, resizable left sidebar with `Tasks` and `Project` tabs.
+- A compact task list with create, edit, delete, filtering, and manual status
+  changes.
+- Task type (`bug`, `feature`, `improvement`), status (`backlog`, `todo`,
+  `in-progress`, `done`), and priority (`low`, `medium`, `high`, `urgent`).
+- Project-local persistence in `.pi/tasks.json` with a versioned schema.
+- Starting a task in a new ACP session, automatically sending a generated
+  prompt, marking the task in progress, and storing the new session id.
+- Opening an already-linked session instead of creating a duplicate.
+
+## Non-goals
+
+- Kanban, drag and drop, subtasks, dependencies, assignees, due dates,
+  comments, or task history.
+- Automatic transition to `done` when an agent turn finishes.
+- Synchronizing the project task file with the agent's session-local todo list.
+- Concurrent multi-window file merging.
+
+## Behavior
+
+1. The sidebar is visible below the title/session chrome, starts on `Tasks`,
+   remembers its width and collapsed state locally, and preserves the main
+   session workspace at narrow window sizes.
+2. Task rows show a title, type, status, priority, and actions. Status and
+   priority are communicated by a Lucide icon, text, and color so meaning never
+   depends on color alone. `done` is green, `in-progress` is yellow, and idle
+   states are neutral; all colors support light and dark themes.
+3. Creating or editing validates a non-empty title. A description is optional.
+4. Filters affect only the visible list and do not modify persisted ordering.
+5. A missing `.pi/tasks.json` is treated as an empty version-1 document.
+6. Starting an unlinked task creates and selects a new ACP session, persists
+   its id and `in-progress` status, appends the generated user prompt to the
+   transcript, and sends it immediately.
+7. Starting a linked task loads that session. A missing/stale linked session is
+   reported as a recoverable error and does not silently create another one.
+8. Task completion remains manual.
+
+## Contracts
+
+- Project file: `.pi/tasks.json` containing `{ version: 1, tasks: [...] }`.
+- Every task has a unique id, title, type, status, priority, `createdAt`, and
+  `updatedAt`; description and `sessionId` may be omitted.
+- Tauri exposes narrow read/write commands for this one file. Workspace paths
+  are validated and `.pi` symlinks may not escape the workspace.
+- The webview sends a complete validated document on each mutation. Writes use
+  a same-directory temporary file and replacement to avoid partial JSON.
+
+## Invariants
+
+- The task document version must be supported before it is displayed or saved.
+- Duplicate ids, unknown enum values, empty titles, and malformed timestamps
+  are rejected.
+- A task is linked to at most one session in this MVP.
+- Starting a task is disabled while another prompt/session operation is active.
+- A failed save does not leave the UI claiming a task state that was not
+  persisted.
+
+## Edge cases
+
+- Switching workspaces discards the previous workspace's in-memory task view
+  and loads the new project file.
+- Empty and missing files have distinct behavior: missing means no tasks;
+  malformed or empty JSON is an error.
+- Save, session creation, and prompt failures remain visible and retryable.
+- Collapsing the sidebar keeps its tab rail available; choosing a tab expands
+  it.
+
+## Related files
+
+- `desktop/src/App.svelte`
+- `desktop/src/components/`
+- `desktop/src/lib/`
+- `desktop/src/styles.css`
+- `desktop/src-tauri/src/lib.rs`
+
+## Verification
+
+- Unit tests for task parsing, validation, filtering, prompt generation, and
+  sidebar preference parsing.
+- Rust tests for missing/read/write/malformed files and workspace escape.
+- `npm --prefix desktop test`
+- `npm --prefix desktop run check`
+- `npm --prefix desktop run build:web`
+- `cargo test --manifest-path desktop/src-tauri/Cargo.toml`
+
+## Risks / unknowns
+
+- Whole-document writes assume one active desktop writer per project.
+- A linked session may later be removed outside Pix Desktop; the first version
+  reports this rather than automatically unlinking it.
+- Windows replacement semantics may require a fallback around replacing an
+  existing task file while retaining best-effort crash safety.
+
+## Evidence
+
+- Confirmed by code: desktop session creation/loading and prompt submission are
+  orchestrated in `desktop/src/App.svelte` through `AcpClient`.
+- Confirmed by code: Tauri already validates workspace-contained project file
+  reads in `desktop/src-tauri/src/lib.rs`.
+- Confirmed by tests: session tab ordering and ACP request behavior have focused
+  Vitest coverage under `desktop/src/lib/`.
+- Confirmed by docs: `DESIGN.md` specifies a compact persistent sidebar,
+  semantic theme roles, Lucide icons, and non-color status cues.
+- Implemented: `.pi/tasks.json` now has an explicit version-1 contract and
+  rejects unsupported versions rather than guessing a migration.
+- Verified by tests: all 82 desktop Vitest tests and all 8 Rust tests pass;
+  Svelte/TypeScript checks report no errors or warnings.
+- Verified visually: browser QA covered clean preference state, resize/collapse,
+  tabs, filters, and semantic colors in light/dark themes.
+- Verified natively: actual Tauri UI/backend CRUD, Run, persisted linkage,
+  Open session without duplication, and delete cleanup all passed.

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

@@ -44,9 +44,9 @@
     "vscode-languageserver-protocol": "^3.17.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-ai": "0.85.0",
+    "@earendil-works/pi-coding-agent": "0.85.0",
+    "@earendil-works/pi-tui": "0.85.0",
     "typebox": "*"
   },
   "devDependencies": {

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

@@ -210,7 +210,7 @@
       "model": "zai/glm-5.3-flash",
       "fallbackModels": ["openai-codex/gpt-5.6-luna"],
       "thinking": "low",
-      "timeoutMs": 120000,
+      "timeoutMs": 300000,
       "tools": ["read", "grep", "bash"]
     },
 
@@ -234,6 +234,14 @@
       "description": "Use when the sub-agent should make or plan code changes for a feature, bug fix, or refactor.",
       "model": "openai-codex/gpt-5.6-sol",
       "fallbackModels": ["zai/glm-5.3"],
+      // Avoid Sol recursively doing routine implementation work for a Sol parent.
+      // Luna also escalates substantial implementation to Terra. modelByParent
+      // wins over preset role models, so this prevents both Luna -> Sol and
+      // Sol -> Sol for implement tasks under the built-in `gpt` preset.
+      "modelByParent": {
+        "openai-codex/gpt-5.6-luna*": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5.3"] },
+        "openai-codex/gpt-5.6-sol*": { "model": "openai-codex/gpt-5.6-terra", "fallbackModels": ["zai/glm-5.3"] }
+      },
       "thinking": "high"
     },
 

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

@@ -1,6 +1,6 @@
 import { isGptLikeModel } from "./ultrawork-auto.js";
 
-export type AgentStrategyName = "parallel-first" | "deep-work";
+export type AgentStrategyName = "parallel-first" | "deep-work" | "escalation-aware" | "cost-aware-orchestrator";
 
 export interface AgentStrategyOptions {
 	modelRef?: string;
@@ -27,13 +27,40 @@ Default: autonomous deep worker. Build context directly, make progress, edit, an
 For broad work, keep delegation explicit and bounded: focused review/research/tests/frontend/deep tracks, plus one oracle only for high-stakes uncertainty or final plan checks. Read compact results, decide in the parent session, and report only what matters. If compressing unfinished work, preserve active objective + next step via todo/DCP rules.
 </agent_strategy>`;
 
+const ESCALATION_AWARE_STRATEGY_PROMPT = `<agent_strategy name="escalation-aware">
+Execution hint for Pi, not a replacement for system/developer/user instructions.
+
+Default: self-sufficient with tiered escalation. Solve narrow, well-bounded work directly, but do not grind through a large or uncertain task at the current model tier when a stronger focused subagent is appropriate. Use todo for the plan and async subagents for escalation; read compact results first and keep the parent context lean.
+
+For a Luna parent, prefer Terra workers for substantial multi-file research, tests, or implementation, and escalate deep root-cause analysis, architecture/security review, high-risk decisions, or repeatedly failing complex work to Sol through the deep/review roles. For a Terra parent, handle routine research/tests/implementation directly; escalate deep root-cause analysis, architecture/security review, high-risk decisions, or stubborn complex failures to Sol through deep/review. Do not escalate merely because a plan has several steps, and do not delegate a tiny known-file edit or exact lookup.
+
+Keep user questions, plan/todo changes, integration decisions, and the final report in the parent. Independent read-only escalations may run in parallel; serialize overlapping edits unless scopes are clearly disjoint. When work is delegated, synchronize its todo lifecycle: mark it in progress, collect and verify the worker result, then complete/update it before moving on.
+</agent_strategy>`;
+
+const COST_AWARE_ORCHESTRATOR_STRATEGY_PROMPT = `<agent_strategy name="cost-aware-orchestrator">
+Execution hint for Pi, not a replacement for system/developer/user instructions.
+
+Default: cost-aware orchestration. You are an expensive parent model, so keep the parent session focused on planning, decisions, integration, verification, and the final user-facing answer. For non-trivial todo work, prefer focused async subagents for repo scanning, multi-file research, documentation, tests, frontend work, and implementation steps that would otherwise require several repository tool calls. Read compact subagent results first; inspect raw artifacts or redo work in the parent only when verification or uncertainty requires it.
+
+Keep user questions, todo/plan changes, architecture tradeoffs, cross-worker integration decisions, high-stakes review, and the final report in the parent. Do not delegate merely to avoid one cheap exact lookup or a tiny known-file edit. Independent read-only tracks may run in parallel; serialize overlapping edits unless scopes are clearly disjoint. When a todo item is delegated, keep its lifecycle synchronized: mark it in progress, collect and verify the worker result, then complete/update it before moving on.
+</agent_strategy>`;
+
 export function agentStrategyPrompt(options: AgentStrategyOptions = {}): string | undefined {
 	const env = options.env ?? process.env;
 	const override = strategyOverride(env);
 	if (override === "off") return undefined;
 	if (options.customPrompt && shouldSkipCustomPrompt(env)) return undefined;
 
-	const strategy = override ?? (isGptLikeModel(options.modelRef) ? "deep-work" : "parallel-first");
+	const strategy = override
+		?? (isExpensiveGptParent(options.modelRef)
+			? "cost-aware-orchestrator"
+			: isEscalationAwareGptParent(options.modelRef)
+				? "escalation-aware"
+			: isGptLikeModel(options.modelRef)
+				? "deep-work"
+				: "parallel-first");
+	if (strategy === "cost-aware-orchestrator") return COST_AWARE_ORCHESTRATOR_STRATEGY_PROMPT;
+	if (strategy === "escalation-aware") return ESCALATION_AWARE_STRATEGY_PROMPT;
 	return strategy === "deep-work" ? DEEP_WORK_STRATEGY_PROMPT : PARALLEL_FIRST_STRATEGY_PROMPT;
 }
 
@@ -49,10 +76,22 @@ function strategyOverride(env: NodeJS.ProcessEnv): AgentStrategyName | "off" | u
 	if (FALSE_ENV_PATTERN.test(value)) return "off";
 	if (value === "parallel-first") return "parallel-first";
 	if (value === "deep-work") return "deep-work";
+	if (value === "escalation" || value === "escalation-aware") return "escalation-aware";
+	if (value === "cost-aware" || value === "cost-aware-orchestrator" || value === "orchestrator") return "cost-aware-orchestrator";
 	if (TRUE_ENV_PATTERN.test(value)) return undefined;
 	return undefined;
 }
 
+function isExpensiveGptParent(modelRef: string | undefined): boolean {
+	if (!modelRef) return false;
+	return /(?:^|\/)gpt-5\.6-sol(?:$|[-.:])/i.test(modelRef.trim());
+}
+
+function isEscalationAwareGptParent(modelRef: string | undefined): boolean {
+	if (!modelRef) return false;
+	return /(?:^|\/)gpt-5\.6-(?:luna|terra)(?:$|[-.:])/i.test(modelRef.trim());
+}
+
 function shouldSkipCustomPrompt(env: NodeJS.ProcessEnv): boolean {
 	const raw = firstEnv(env, "PI_AGENT_STRATEGY_WITH_CUSTOM_PROMPT", "ASYNC_SUBAGENTS_AGENT_STRATEGY_WITH_CUSTOM_PROMPT");
 	return raw ? !TRUE_ENV_PATTERN.test(raw.trim()) : true;

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

@@ -218,12 +218,16 @@ const BUILTIN_CONFIG: SubagentConfig = {
 			model: "zai/glm-5.3-flash",
 			fallbackModels: ["openai-codex/gpt-5.6-luna"],
 			thinking: "low",
-			timeoutMs: 120_000,
+			timeoutMs: 300_000,
 			tools: ["read", "grep", "bash"],
 			isolatedSkills: [getBrowserQaSkillPath()],
 		},
 		implement: {
 			description: "Use when the sub-agent should make or plan code changes for a feature, bug fix, or refactor.",
+			modelByParent: {
+				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-terra", fallbackModels: ["zai/glm-5.3"] },
+				"openai-codex/gpt-5.6-sol*": { model: "openai-codex/gpt-5.6-terra", fallbackModels: ["zai/glm-5.3"] },
+			},
 			thinking: "high",
 		},
 		tests: {
@@ -234,10 +238,18 @@ const BUILTIN_CONFIG: SubagentConfig = {
 		},
 		review: {
 			description: "Use for review/audit of existing code or changes: correctness, security, performance, maintainability, API risks, quality. Do not implement new code.",
+			modelByParent: {
+				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
+				"openai-codex/gpt-5.6-terra*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
+			},
 			thinking: "high",
 		},
 		deep: {
 			description: "Use for broad hard reasoning: architecture, root-cause analysis, cross-module impact, complex debugging or tradeoffs.",
+			modelByParent: {
+				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
+				"openai-codex/gpt-5.6-terra*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
+			},
 			thinking: "high",
 		},
 		oracle: {

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

@@ -32,6 +32,7 @@ import { registerSubagentsTool } from "./tools/subagents.js";
 import type { LiveAgent, SubagentsLiveStateEvent } from "./types.js";
 import type { AgentState } from "./core/types.js";
 import { publishStartupSection } from "../startup-section.js";
+import { publishRpcSessionState } from "../lib/rpc-session-state.js";
 
 function isTerminalAgentStatus(status: AgentState["status"]): boolean {
 	return status === "done" || status === "failed" || status === "stopped";
@@ -83,8 +84,8 @@ function createLiveStatePayload(
 }
 
 function agentMatchesSession(agent: LiveAgent, sessionFile: string | undefined): boolean {
-	if (!sessionFile || !agent.parentSession) return true;
-	return pathsEqual(sessionFile, agent.parentSession);
+	if (!sessionFile) return true;
+	return agent.parentSession !== undefined && pathsEqual(sessionFile, agent.parentSession);
 }
 
 function isStaleExtensionContextError(error: unknown): boolean {
@@ -100,6 +101,7 @@ export default function (pi: ExtensionAPI) {
 	const subagentOverlay = new SubagentOverlay(liveAgents);
 	let sawAutoUltraworkCandidate = false;
 	let currentSessionFile: string | undefined;
+	let currentSessionStateContext: Parameters<typeof publishRpcSessionState>[0];
 	let completionWatchTimer: ReturnType<typeof setInterval> | undefined;
 	publishSubagentPresetsStartupSection();
 
@@ -109,6 +111,7 @@ export default function (pi: ExtensionAPI) {
 			const liveState = createLiveStatePayload(liveAgents, currentSessionFile);
 			pi.events?.emit?.(SUBAGENTS_LIVE_COUNT_EVENT, { count: liveState.count });
 			pi.events?.emit?.(SUBAGENTS_LIVE_STATE_EVENT, liveState);
+			publishRpcSessionState(currentSessionStateContext, SUBAGENTS_LIVE_STATE_EVENT, liveState);
 			updateCompletionWatcher();
 		} catch (error) {
 			ignoreStaleExtensionContextError(error);
@@ -168,6 +171,7 @@ export default function (pi: ExtensionAPI) {
 		try {
 			sawAutoUltraworkCandidate = false;
 			currentSessionFile = sessionFileFromContext(ctx);
+			currentSessionStateContext = ctx;
 			subagentOverlay.restoreRunningAgents(ctx.cwd, currentSessionFile);
 			refreshSubagentOverlay();
 		} catch (error) {

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

@@ -24,12 +24,18 @@ the requested target in the browser.
 
 ## Workflow
 
-Treat target discovery as a 30-second preflight and invoke the runner within 45
-seconds of starting. Use at most one runner invocation unless the task explicitly
-requests multiple auth profiles. If you cannot identify a reachable target and
-a supported deterministic assertion inside that preflight, return a structured
-`BLOCKED` result immediately. Do not consume the launcher budget on further
-source reading, server polling, capability probing, or retries.
+Treat target discovery as a 30-second preflight and begin browser execution within
+45 seconds of starting. For a verification task, use at most one actual `run`
+browser execution per profile. Metadata/preparation commands such as `profiles`
+and form-auth `scaffold` do not count as browser verification runs. For an
+explicit exploratory/manual-QA task, use at most three `run` rounds, give each a
+unique `--run-id`, bound each with `--runner-timeout-ms 60000`, and let each round
+test one concrete hypothesis learned from the prior evidence. Stop earlier once
+the requested behavior is explained or no new supported hypothesis remains. If
+you cannot identify a reachable target and a supported deterministic assertion
+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.
 2. Use the launcher-provided `$PI_SUBAGENT_AGENT_DIR/browser-qa/` workspace.
@@ -56,15 +62,27 @@ source reading, server polling, capability probing, or retries.
    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
-   origin becomes the fail-closed allowlist. Only for authenticated QA, add
-   `--profile <id>`; the selected profile then owns the URL and allowlist.
+   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,
+   or inferred sibling domain; undeclared origins remain blocked. Only for
+   authenticated QA, add `--profile <id>`; the selected profile then owns the
+   URL and allowlist.
    Profile id, URL, and flow path are non-secret; never pass credentials as
    arguments or environment variables.
 7. Report deterministic assertions and every artifact returned by the runner.
-   For each screenshot, video, trace, or retained download, 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.
+   For each screenshot, video, trace, or retained download, 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`.
+   When screenshots are present, inspect at least one representative meaningful
+   PNG directly with the `read` tool on its absolute path before claiming visual
+   QA. Inspect additional screenshots when they represent materially different
+   states or popups. Record `visualInspection: inspected` plus the inspected
+   paths and concrete findings. If image reading is unavailable in the active
+   model, report `visualInspection: unavailable` and do not claim a visual pass;
+   deterministic assertions may still be reported separately. Visual inspection
+   supplements assertions; it does not replace them.
 
 ## Scenario design
 
@@ -84,11 +102,14 @@ source reading, server polling, capability probing, or retries.
   animation/debounce. Set flow `timeoutMs` only as high as the target
   legitimately needs.
 - The runner waits after every visible interaction until the document is ready,
-  requests started by the interaction have finished, and common visible busy
+  observes requests started by the interaction for a bounded readiness window,
+  and waits for common visible busy
   markers (including `aria-busy`, progress bars, loading/spinner/skeleton test
-  ids and classes) disappear. It then keeps the stable state on video for 500
-  ms. A busy page that does not settle within `timeoutMs` fails instead of
-  continuing against a skeleton. For an app-specific loader not covered by
+  ids and classes) to disappear. EventSource/WebSocket traffic is excluded and
+  a long-poll/background request cannot pin readiness for the full flow timeout;
+  visible busy UI can. It then keeps the stable state on video for 500 ms. A
+  busy page that does not settle within `timeoutMs` fails instead of continuing
+  against a skeleton. For an app-specific loader not covered by
   those conventions, add an explicit `waitFor`/`assertHidden` for that loader
   and assert the loaded content before interacting with it.
 - Recorded pointer actions are annotated automatically: clicks and double-clicks
@@ -101,7 +122,8 @@ source reading, server polling, capability probing, or retries.
   pointer input, and clears before the runner's post-action stable interval
   completes.
 - Place `authRejectedIf` immediately after navigation or any transition that
-  may reveal expired authentication.
+  may reveal expired authentication. It must declare `urlIncludes` or a locator;
+  an empty rejection check is invalid.
 - 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.
@@ -120,7 +142,7 @@ Supported actions:
   `uncheck`, `selectOption`, `wheel`, `evaluate`, `dragTo`, `uploadFiles`,
   `openPopup`, `download`
 - assertions: `assertVisible`, `assertHidden`, `assertEnabled`,
-  `assertDisabled`, `assertChecked`, `assertUnchecked`, `assertText`,
+  `assertDisabled`, `assertChecked`, `assertUnchecked`, `assertText`, `assertTextContent`,
   `assertValue`, `assertAttribute`, `assertCount`, `assertURL`,
   `assertDOMMetric`
 - evidence/auth: `screenshot`, `authRejectedIf`
@@ -128,6 +150,9 @@ Supported actions:
 Locators accept one of `testId`, `role` (plus optional `name`), `label`,
 `placeholder`, `text`, or `css`; add `exact: true` where useful. String
 assertions require exactly one of `equals` or `includes`.
+`assertText` matches visible, user-facing `innerText` and therefore fails for a
+hidden locator. Use `assertTextContent` only when raw DOM text, including hidden
+content, is intentionally the oracle.
 `assertAttribute` additionally requires a bounded `attribute` name and is
 useful for `aria-*`, `data-*`, `href`, and similar observable state. All
 assertions retry until `timeoutMs` and report generic failures without exposing
@@ -208,7 +233,11 @@ oracle. Raw JavaScript remains intentionally unsupported.
 ```jsonc
 {
   "viewport": { "width": 844, "height": 847 },
-  "environment": { "locale": "en-GB", "timezoneId": "Europe/London", "colorScheme": "dark" },
+  "environment": {
+    "locale": "en-GB",
+    "timezoneId": "Europe/London",
+    "colorScheme": "dark"
+  },
   "steps": [
     { "action": "goto", "path": "/settings" },
     { "action": "authRejectedIf", "urlIncludes": "/login" },
@@ -216,7 +245,11 @@ oracle. Raw JavaScript remains intentionally unsupported.
       "action": "assertVisible",
       "locator": { "role": "heading", "name": "Settings", "exact": true }
     },
-    { "action": "wheel", "locator": { "css": ".settings-panel" }, "deltaY": 500 },
+    {
+      "action": "wheel",
+      "locator": { "css": ".settings-panel" },
+      "deltaY": 500
+    },
     {
       "action": "assertDOMMetric",
       "locator": { "css": ".settings-panel" },
@@ -226,9 +259,17 @@ oracle. Raw JavaScript remains intentionally unsupported.
     {
       "action": "click",
       "locator": { "testId": "save-settings" },
-      "expectResponse": { "path": "/api/settings", "method": "PUT", "status": 200 }
+      "expectResponse": {
+        "path": "/api/settings",
+        "method": "PUT",
+        "status": 200
+      }
+    },
+    {
+      "action": "assertText",
+      "locator": { "testId": "toast" },
+      "includes": "Saved"
     },
-    { "action": "assertText", "locator": { "testId": "toast" }, "includes": "Saved" },
     { "action": "screenshot", "name": "settings-saved" }
   ]
 }
@@ -301,6 +342,8 @@ After any runner invocation that actually performed browser testing, include
 all non-empty `artifacts.screenshots`, `artifacts.videos`, and
 `artifacts.traces`, and `artifacts.downloads` groups in the final response.
 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`.

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

@@ -19,6 +19,12 @@ 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:
@@ -42,13 +48,14 @@ 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, completion of requests started by that action, disappearance of
-common visible `aria-busy`/progress/loading/spinner/skeleton markers, and a
-500 ms stable interval. If those signals remain busy through the flow timeout,
-the run fails rather than interacting with a loading shell. 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.
+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
@@ -58,7 +65,9 @@ behavior. If a normal operation legitimately needs more time, adjust the flow's
 
 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. Use `assertAttribute` for
+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.
 
@@ -177,6 +186,12 @@ 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: