Skip to content

fix(studio): recorded tests can be saved, and Run follows the open file - #764

Open
jay23606 wants to merge 60 commits into
AlphaWaveSystems:mainfrom
jay23606:pr-go/397-studio-recorder-a-recording-cannot-be-sa
Open

jay23606 wants to merge 60 commits into
AlphaWaveSystems:mainfrom
jay23606:pr-go/397-studio-recorder-a-recording-cannot-be-sa

Conversation

@jay23606

Copy link
Copy Markdown

The bug

After Record and Stop, the editor held only the recorded steps, so the test "recorded flow" header was lost. The file label showed recorded.probe, but no file existed and currentPath stayed null. Save did nothing and Run stayed enabled while doing nothing.

The change

  • Stop keeps the header: the buffer is the test header followed by the recorded steps (src/recording.ts).
  • Stop and Record refresh the Run button, so Run follows whether a file is open.
  • Save with no file open asks for a name in the open folder (default recorded.probe), writes it, and makes it the current file. Save, Ctrl/Cmd+S and Run then work on it. It asks before it replaces an existing file.
  • The Save button is enabled whenever there are unsaved changes, so it can save a recording.

How it was tested

  • node --test studio/frontend/recording-tests/recording.test.ts: passes on the fix (4 tests).
  • The same test run against the base main.ts fails with Expected values to be strictly equal for the Stop wiring, Run refresh and Save-as checks.

Not covered: the Save-as dialog and the Run button in a running app, and the native smoke test 07. The main.ts handlers need the DOM and the Wails bindings, so the new test reads their source to check the wiring rather than running them.

Regression test: fails on base twice (/ERR_MODULE_NOT_FOUND|Expected values to be strictly equal/), passes on fix twice (node --test studio/frontend/recording-tests/recording.test.ts)

Fixes #397

…est (AlphaWaveSystems#756)

## Summary

`TestEveryWaitlistLinkPointsToAValidTarget` (from AlphaWaveSystems#752) also failed when the site had no waitlist link at all. The pricing rewrite removes the waitlist, so that condition would fail a correct page.

The test still checks every waitlist link that exists: each must go to `mailto:support@alphawavesystems.com` or to `#waitlist`. A site with no waitlist link now passes. If the scan finds no links at all, `siteLinks` already catches it in `TestEveryApplyLinkPointsToAValidTarget`.

This is a test-only change, so there's no CHANGELOG entry. The CHANGELOG line from AlphaWaveSystems#752 is still true.

## Mutation check

The two waitlist mutants from AlphaWaveSystems#752 are still killed. Each was applied to `pricing.astro` on main, the test run, and the file restored byte for byte.

| Broken rule | Result |
|---|---|
| a waitlist link to another page | killed |
| the waitlist email to another address | killed |

## Test plan

- [x] The site's form and link tests in `go test ./scripts/` pass on main.
- [x] The same tests pass on the pricing rewrite's pages (no waitlist link) with main's docs and issue templates.
- [x] `gofmt` clean.
…it passes when run again (AlphaWaveSystems#758)

## Summary

I looked for timing-fragile tests in `internal/` by running the whole tree under load: `go test -race -count=3 ./internal/...`, with one `yes > /dev/null` per CPU (18 processes) for the whole run, on macOS (darwin/arm64).

Only one test failed, `TestNoteNamedSecretMasksByNameOnly` in `internal/sysdialog`, in 2 of its 3 runs. Its cause is shared state, not the clock. It fails the same way under plain `go test -count=2`, with no load.

**Cause.** `NoteNamedSecret` adds a value to the secret list, which lives for the whole process. The test checks that the text changes from before to after the value is noted. On the second run of the test, the value is already in the list before it is noted, so nothing changes and every case that should be masked reports a failure:

```
password="hunter2-page-Zq": masked = true, want true ("****")
```

**Fix.** A test helper, `emptyKnownSecrets(t)`, gives the test an empty secret list and restores the old list when the test ends. The test now checks the same thing on every run. No product code changes, so there is no CHANGELOG entry.

## Results

| Run | Result |
|---|---|
| Before: `go test -race -count=3 ./internal/...` under load | 1 failing test: `TestNoteNamedSecretMasksByNameOnly`, 2 of 3 runs. Every other package `ok`. |
| Before: `go test -count=2 -run TestNoteNamedSecretMasksByNameOnly$ ./internal/sysdialog/` without load | FAIL |
| After: `go test -race -count=20` of the test | ok |
| After: `go test -race -count=3 ./internal/sysdialog/` | ok |

## Mutation check

Each mutant was applied, the test was run with `-count=2`, and the file was restored byte for byte.

| Mutant | Result |
|---|---|
| `NoteNamedSecret` notes nothing | killed |
| the test does not call the helper (the original bug) | killed |
| the helper keeps the old list instead of emptying it | survives: equivalent for this bug |

The third mutant survives because the helper does two things, and either one alone fixes this bug. Restoring the old list at the end drops what the run added, and emptying the list at the start makes the next run clean. Both stay. Emptying keeps the test independent of values that other tests note, and restoring keeps other tests independent of this one.

## Timing-sensitive tests that did not fail (listed, not changed)

None of these failed in the 3 runs under load above.

- About 30 real-clock upper bounds on how fast something must fail or finish. Most are 2 to 10 s, for example in `internal/probelink`, `internal/httpcall`, `internal/device` (webview session, cdp, crash collect) and `internal/runner` (timeouts, reconnect).
- The tightest bounds:
  - `internal/runner` `TestWaitAtOrAboveTheLimitFailsAtOnce`, under 500 ms.
  - `internal/runner/test_timeout_pins_test.go:189`, a window of 900 ms to 2.5 s.
- 52 `time.Sleep` calls in tests across `internal/`.

The wait-rule race in `internal/runner` was fixed in AlphaWaveSystems#750.

Also noticed: `gofmt -l` lists `internal/sysdialog/roles.go`. That file is the same as on main, so it is not part of this change.

## Test plan

- [x] Load run before the fix (table above).
- [x] The test and its package after the fix (table above).
- [x] Mutation check (table above).
- [x] `gofmt` clean on the changed file.
…get use in the Flutter sample apps (AlphaWaveSystems#759)

## Summary

This PR adds `docs/compat/NEXT.md`, a ranked plan of the compatibility tests to write next, and `docs/compat/widget-usage.py`, the count behind it. Documentation only: no matrix cell changes, and nothing in it claims how FlutterProbe behaves with a widget.

- **Ranking.** For each widget in `catalog.json` (Flutter 3.50.0), the script counts how many of the 36 packages of `flutter/samples` construct it. The commit is pinned to `12a1916` (2026-11-11). Tests, generated files and comments are excluded. Layout-only widgets are excluded, apart from the ones that change what `see` or `tap` mean.
- **The 11 items.** `Text`, then the app bar and routes, widgets without text, scrolling lists, tiles, progress indicators, gestures, dialogs, snack bars, the Cupertino bars and overlapping widgets. Each item names:
  - the fixture screen (`PROBE_FIXTURE_WIDGETS=<family>`);
  - the ProbeScript steps, all of which exist in the grammar today. The one follow-up that needs a missing verb (`store text of` a Flutter widget) says so;
  - the variants that must fail;
  - the open question the test settles.
- **Two open questions worth naming:**
  - The route rule on a device. The agent does not match a route under an opaque one, and an agent unit test covers that (`probe_agent/test/finder_test.dart`, PT-03). Under a dialog, popup or sheet the page stays matched by design. What is open is a device run.
  - Does a lazy list's unbuilt row count as absent?
- **Also listed:**
  - the follow-ups for the cells the matrix marks "partly";
  - the families the source cannot rank (pickers, menus, tabs, drawers, sheets are rare in demo apps), without a usage claim;
  - the limits of the method.
- `docs/compat/README.md` lists the two files, and the CHANGELOG has the entry.

The newest stable Flutter in the official release manifest is still 3.50.0 (Dart 3.14.0, 2026-11-11), which `RELEASES.md` already records. Nothing to add there.

## Test plan

- [x] The committed script, run on the same checkout, gives output byte-identical to the run the ranking was taken from (36 packages, 185 widgets used).
- [x] Every step form named in the plan exists in `website/src/content/docs/probescript/grammar.md` or in an existing suite.
- [x] The newest stable release was checked against the official manifest.
… for; any other address asks first (AlphaWaveSystems#754)

## Summary
A saved WiFi token was looked up by the device's announced name, and any machine on the network can announce any name. Selecting a look-alike at another local address with the token field blank sent it the saved token (the 10.x/192.168.x check only refuses non-local addresses).

- `SaveWiFiToken` binds the token to the address (host and port) of the WiFi connection that has just accepted it (a second keychain item per device).
- `ConnectWiFiSaved` sends the token to that address as before. For any other address, and for a token with no address (saved before this change), it asks first, in the window: "Send the saved token?", naming the announced name, the address it would go to and the one the token was saved for. Cancel is focused, Enter does not press the send button, Escape is a no, and the send button is armed after half a second (the clear-data dialog's rules). No answer, no window (the headless bridge cannot answer), a timeout: all a no, and nothing is dialled.
- A public address is refused before anyone is asked. After a confirmed connection the token is bound to the new address. Forgetting a token forgets its address; a new token with no connection to bind it to drops the old address.
- The confirmation machinery is generalised (`askInWindow`, extracted from the clear-data path with no change in behaviour: its existing tests and the browser confirm-dialog specs pass).

## Tests and mutants
Go, against a real fake agent: same address connects with no question; a spoofed name at another address is asked about with both addresses, a no dials nothing (the agent saw no ping), a yes connects and binds; no window and an unanswered question are a no; a legacy token asks once and is then bound; forget and replace drop the address; a public address is refused before the question; the question's text is cleaned; address spellings compare equal. 11 mutants killed: never ask, ask for a legacy token never, ask at the bound address, a no ignored, a public address asked about, an approved address not bound, a replaced token keeping the old address, forget keeping it, save not binding, case not folded, no window not a no. Node tests for the dialog copy.

Not run in the real window yet: the dialog itself for this kind (the clear-data one has been, by hand).

## Docs
CHANGELOG (Security), Studio docs (Physical devices). The CLI keeps no saved tokens, so the CLI docs are unchanged.

## Test plan
- [x] `go test -race ./studio` (whole package)
- [x] `npm run test:confirm`, `test:wifi`; browser confirm-dialog specs (10 passed)
- [x] mutants as above
- [x] disclosure scan



## Review fixes
- The address that is compared is the address that is dialled: `ConnectWiFiSaved` normalises the host (no brackets, no trailing dot, no surrounding space, lower case) and dials that, so `127.0.0.1.` can no longer compare equal to the bound address yet be resolved as a name.
- A confirmed connection that fails binds nothing; the bind happens only if the token saved now is still the one this connection used.
- A token saved with no address is asked about as "saved without an address"; DOM specs cd-11 and cd-12 cover the new dialog kind (focus on Cancel, Enter on Send token does nothing, armed after half a second, Escape a no).
- Mutants added: the raw host dialled, one round of trimming, no lower-casing, a failed connection binding, no generation check, an approved address never bound: all killed.
Signed-off-by: jay23606 <4602056+jay23606@users.noreply.github.com>
@jay23606
jay23606 requested a review from a team as a code owner November 17, 2026 05:14
@github-actions

Copy link
Copy Markdown


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

…r go on a command line (AlphaWaveSystems#768)

## Summary

The VS Code extension typed the cloud key, the cloud secret and the relay token into its terminal as command-line flags. A command line is visible to other users in the process list and stays in shell history. With this change these values never go on a command line.

**The finding, checked against the code on main:**
- `vscode/src/probe.ts:174-184`: `buildTestArgs` pushed `--cloud-key`, `--cloud-secret` and `--relay-token` with their values, taken from the options or the workspace settings.
- `vscode/src/terminal/probeTerminal.ts:34`: `runInTerminal` types the whole command with `terminal.sendText`. Every `buildTestArgs` caller runs through it: `extension.ts`, `commands/test.ts`, `providers/testExplorer.ts`, `providers/sessionManager.ts` and `views/runProfile.ts`.
- The CLI read these three only as flags (`internal/cli/test.go:189-200`).

## The change

**CLI**
- `probe test` reads `--cloud-key`, `--cloud-secret` and `--relay-token` from `PROBE_CLOUD_KEY`, `PROBE_CLOUD_SECRET` and `PROBE_RELAY_CLI_TOKEN` when the flag is not given (`internal/cli/secret_flags.go`).
- A flag that is given wins, even when it is given empty, so existing scripts behave the same.
- The relay token's variable is not `PROBE_RELAY_TOKEN`. That name is the agent's dart-define, which holds the relay session's **agent** token. `cloud.RelaySession` has both an `agent_token` and a `cli_token`, and they are different values. A CI job that exports the agent token for the app build would otherwise hand the CLI the wrong token.

**Extension**
- `buildTestArgs` no longer writes the three flags, and it no longer takes them as options. `buildTestRun` strips them with `withoutSecrets` before calling it.
- The new `buildTestRun` returns `{ args, env }`, with the secrets from the options or the settings in `env` (`vscode/src/secretArgs.ts`).
- All 13 test-run call sites pass `run.env`. `runInTerminal` now takes a required `env`, so a missed caller fails to compile. Other commands (init, lint, report, convert, record, devices, studio) pass `{}`.
- `runInTerminal` throws if a command line still carries one of the three flags, in either the `--flag value` or the `--flag=value` form.
- The terminal is created with `env`. A terminal's environment is fixed when it is created, so a terminal is replaced when a run's secrets differ from the ones it was made with. The check compares a fingerprint (name, length and a 32-bit hash), which stays in memory and is never printed.

**Settings (breaking for a workspace that sets them)**
- `flutterprobe.cloudKey`, `flutterprobe.cloudSecret` and `flutterprobe.relayToken` are now `"scope": "machine"`, and so are the two settings that decide where they are sent: `relayUrl` (it receives the relay CLI token) and `cloudProvider` (it receives the key and the secret). `SECRET_SETTINGS` in `secretArgs.ts` lists the five, and a test checks each in `package.json`. VS Code's contribution-points reference says such a setting can be written only in user or remote settings, cannot be overridden in workspace or folder settings, and is left out of Settings Sync.
- So a value in `.vscode/settings.json` is now ignored, and a repository cannot set these settings. On activation the extension shows a one-time notice (per workspace, through `workspaceState`) naming any of the five that the workspace's `.vscode/settings.json` still sets, so the value is not dropped silently.
- What this does **not** cover: `probe test` also reads the workspace's `probe.yaml`, whose `cloud:` section can name a provider and a relay service URL. And which binary the extension runs is a separate setting (tool paths, restricted in the follow-up PR); until then, only open workspaces you trust. The README, the CHANGELOG and the notice say so.
- **Where the secrets live:** in the FlutterProbe terminal's environment for the terminal's whole life, inherited by every command typed there and by the programs `probe` starts (`adb`, `flutter`). Whether VS Code restores a terminal's environment after a restart was not verified. The README says this too.
- The vscode README, the CHANGELOG (under Changed) and `cloud-farms.md` say how to move the value: to user settings, or to the environment variable.
- VS Code still stores settings in plain text. Moving them to `SecretStorage` would be a separate change.

**Docs.** The vscode README covers the settings table, a note on the change and the setup examples (now "user settings"). The root README's cloud example uses `export PROBE_CLOUD_KEY=… PROBE_CLOUD_SECRET=…`. `website/src/content/docs/tools/cloud-farms.md` documents the variables and the two relay tokens. The CHANGELOG has the entry.

## Tests

- **Go** (`internal/cli/secret_flags_test.go`):
  - each flag falls back to its variable;
  - a flag that is given wins, and a flag given empty stays empty;
  - a non-secret flag reads no variable;
  - `test.go` has the three flags and reads them only through `secretFlag`, never `GetString`.
- **Extension** (`vscode/src/test/secretArgs.test.ts`, `node --test`):
  - the variable names, and empty values left out;
  - a secret flag is found in both forms;
  - the fingerprint tells values apart and does not contain them;
  - a source check that `runInTerminal` refuses a secret flag and creates the terminal with `env`. It imports `vscode`, so a unit test cannot call it.
  - a source check that no file but `secretArgs.ts` names one of the three flags. It is a prefix match, so it also catches `'--cloud-key=' + value`.
  - the five secret and destination settings are machine-scoped (parsed from `package.json`);
  - `terminalAction`: a terminal is reused only when alive and made with the same secrets, otherwise replaced or created; plus a source check that `getOrCreateTerminal` follows it;
  - `staleWorkspaceSettings` finds the settings a workspace file still names, and only exact keys;
  - `withoutSecrets` takes the three out of the options;
  - a source check of the hand-off: all 13 `runInTerminal` calls with `run.args` pass `run.env`, no caller uses `buildTestArgs`, and the run profile hands its form's three secrets to `buildTestRun`;
  - a source check that activation shows the notice once.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 22 were killed. Five mutants first failed to compile or matched more than one place; they were rewritten, and those runs are the ones counted. One survived at first (`getOrCreateTerminal` ignoring `terminalAction`); the source test was extended and it is now killed.

| Mutant | Result |
|---|---|
| CLI: a secret flag ignores its variable | killed |
| CLI: a flag given empty falls back to the variable | killed |
| CLI: the relay token reads `PROBE_RELAY_TOKEN` | killed |
| CLI: `probe test` reads `--cloud-secret` with `GetString` | killed |
| CLI: a non-secret flag reads a variable | killed |
| ext: `buildTestArgs` puts `--cloud-secret` back | killed |
| ext: `secretEnv` keeps an empty value | killed |
| ext: the cloud secret goes to the wrong variable | killed |
| ext: `secretFlagIn` misses the `--flag=value` form | killed |
| ext: the fingerprint ignores the value | killed |
| ext: `runInTerminal` does not refuse a secret flag | killed |
| ext: the terminal is created without `env` | killed |
| ext: `buildTestArgs` pushes the `--cloud-key=value` form | killed |
| ext: `relayUrl` is not machine-scoped | killed |
| ext: `cloudProvider` is not machine-scoped | killed |
| ext: a terminal with other secrets is reused | killed |
| ext: `getOrCreateTerminal` ignores `terminalAction` | killed |
| ext: a stale workspace setting is not found | killed |
| ext: the notice is not shown on activation | killed |
| ext: the run profile drops the cloud secret | killed |
| ext: the test explorer passes no env | killed |
| ext: `withoutSecrets` keeps the relay token | killed |

## Not covered

- An end-to-end run in a VS Code window. The terminal's environment was checked through the source and the types, not by running the extension.
- A secret in the environment is still readable by processes of the same user, as every environment is. This change removes the exposure to other users and to shell history.

## Test plan

- [x] `go test ./internal/cli/` and `go vet ./internal/cli/` pass.
- [x] `npm test` in `vscode/` passes: 59 tests, including the 12 new ones.
- [x] Mutation check (table above).
- [x] `gofmt` clean on the changed Go files.
…pp id, the no-question line says when the wipe happens, the per-device log line (AlphaWaveSystems#766)

## Summary
The three review nits of the clear-data PRs, each with a test and a mutant:

1. **The `--yes` line is per device, not per run, and the docs said per run.** A parallel run prints it in each lane. The line now reads `... will be wiped BEFORE EVERY TEST on this device`, and the CHANGELOG and CLI reference say the question and the line are once for each device of the run (a parallel run: once in each lane).
2. **The refusal hint printed the app id raw.** `askWipe`'s reason now takes the app id through `CleanOneLine` like the question does (control and direction characters, length).
3. **The no-question line did not say when the wipe happens.** For the before-every-test question, Studio's note is now "Will clear data before every test of this run, of <package> on <device> (<id>) without asking: ..." (`runner.IsBeforeEachTestQuestion` tells the per-test question from a step's); the CLI's line already carried the question text and a test now pins that it names the package, the device and BEFORE EVERY TEST, and that a `clear app data` step's line does not claim it.

Mutants killed: the raw app id in the hint, the per-test question not recognised, the log wording back to per run, Studio's note never saying when.

## Test plan
- [x] `go test -race` on the runner, CLI and Studio tests that cover the three
- [x] mutants as above
- [x] disclosure scan
AlphaWaveSystems#769)

## Summary

A repository could choose which binary the VS Code extension runs. This change makes the extension run only binaries the user chose, and run them by absolute path.

**The finding, checked against the code on main:**
- `vscode/package.json`: `flutterprobe.probePath`, `convertPath`, `adbPath` and `flutterPath` had no `scope`. A workspace's `.vscode/settings.json` could set all four.
  - The extension runs `probePath` and `convertPath` itself.
  - It passes `adbPath` and `flutterPath` to `probe test` as `--adb` and `--flutter` (`vscode/src/probe.ts:231-235`).
- `vscode/src/config.ts:14-42`: with no path configured, the extension ran `<workspace>/bin/probe` or `bin/probe-convert` whenever the file existed. Otherwise it spawned the bare name `probe`, with the workspace as the working directory.
- **On Windows that bare name is looked up in the working directory first.** Sources:
  - libuv's `search_path` (`src/win/process.c`, which Node's `child_process.spawn` uses) says: "If there's really only a filename, check the current directory for file, then search all path directories". It tries `.com` and then `.exe`, unless `NoDefaultCurrentDirectoryInExePath` exists ([NeedCurrentDirectoryForExePathW](https://learn.microsoft.com/en-us/windows/win32/api/processenv/nf-processenv-needcurrentdirectoryforexepathw)).
  - cmd.exe searches `.;%PATH%` (same page).
  - PowerShell does not ([about_Command_Precedence](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_command_precedence)).
  - Node's [child_process docs](https://nodejs.org/api/child_process.html) say a `.bat` or `.cmd` file needs a shell.

  So a `probe.exe` or `probe.com` in a repository's root ran ahead of the one on PATH.
- The manifest declared no `capabilities.untrustedWorkspaces`. VS Code's [Workspace Trust guide](https://code.visualstudio.com/api/extension-guides/workspace-trust) says such an extension "will be treated as not supporting Workspace Trust" and stays disabled in Restricted Mode. So an untrusted workspace was not exposed. A trusted workspace was, and the trust click is the only consent the person gives.

## The change

- **Machine-scoped settings.** The four path settings, and the new `flutterprobe.useWorkspaceBinaries`, are `"scope": "machine"`. Per the [contribution points reference](https://code.visualstudio.com/api/references/contribution-points), they are read only from user or remote settings (on SSH, WSL or a container, the remote settings). A workspace value is now ignored. This is breaking, and documented with the move.
- **The extension resolves the binary itself and runs it by absolute path** (`vscode/src/toolPath.ts`, pure, called by `config.ts`). It uses the configured path when that is an absolute path to a regular file, or a command name looked up on PATH. A relative path with folders is refused, since it would be relative to the workspace. Otherwise it looks up `probe` on PATH.
  - Only the absolute folders of PATH are searched. Empty and relative entries (`.`, `bin`) are dropped, and quoted Windows entries are unquoted.
  - On Windows the name is tried with `.com` and then `.exe`, as libuv does.
  - A directory is not a match (`fs.statSync(...).isFile()`).
- **When nothing is found:**
  - On macOS and Linux the bare name is returned; there a bare name is looked up on PATH only.
  - On Windows it is an error that says what to do ("probe was not found on PATH: install it, or set flutterprobe.probePath…"). `listDevices` and lint-on-save return nothing instead of throwing; the commands surface the error.
- **`bin/probe` and `bin/probe-convert` in the workspace are opt-in.** They are used only with `flutterprobe.useWorkspaceBinaries` (machine scope, default `false`) and in a trusted workspace. Trusting a folder is not consent to run its binaries. Breaking for anyone who relied on the automatic pick; documented.
- **`capabilities.untrustedWorkspaces.supported: false`**, with its reason. This is the same as VS Code's default, now stated in the manifest.
- **`runInTerminal` quotes the command like its arguments.** It doesn't on Windows: the terminal's shell is not known there (PowerShell treats a quoted path as a string and cmd.exe does not read single quotes), and the path is absolute anyway.
- **The one-time notice** (from the secrets PR) now also names the five tool settings when a workspace's `.vscode/settings.json` still sets them, so their values are not dropped silently either (`TOOL_SETTINGS` in `toolPath.ts`; a source test checks the call).
- **README.** The Tool Paths table is fixed: the "Changed" note no longer splits it, and the `studioPort` row is back in it. The table has the new setting, and the section has the remote-settings note and the Windows lookup.

**Not changed:** `probe test` still reads the workspace's `probe.yaml`, whose `tools:` section can name `adb` and `flutter`. The CLI rule for that is a separate change.

## Tests

`vscode/src/test/toolPath.test.ts`, with `node --test`, covers:
- the PATH match as an absolute path, and the first match winning;
- a directory not being a match;
- empty and relative PATH entries never searched, including a `probe` or `probe.exe` in the working directory;
- Windows `.com` then `.exe`, and quoted entries;
- a configured absolute path, a non-file, a bare name, and a relative path refused;
- the opt-in and trust for `bin/probe`, on both platforms;
- the not-found outcome per platform and per reason;
- the manifest: five machine-scoped settings, the opt-in off, trust `false`;
- source checks that `config.ts` passes the opt-in, trust, platform, PATH and a regular-file check, that the terminal quotes the command, and that `listDevices` and `runLint` catch the not-found error.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 16 were killed (15, plus one for the notice after main was merged in). One mutant first made its branch unreachable, which `tsc` rejects; it was rewritten to compile, and that run is the one counted.

| Mutant | Result |
|---|---|
| the workspace binary is used without trust | killed |
| the workspace binary is used without the opt-in | killed |
| relative PATH entries are searched | killed |
| Windows tries `.exe` before `.com` | killed |
| Windows PATH quotes are kept | killed |
| a configured path that is not a file is used | killed |
| a configured relative path is accepted | killed |
| Windows not-found runs the bare name | killed |
| `config.ts` turns the opt-in on | killed |
| `config.ts` accepts a directory | killed |
| the terminal command is not quoted | killed |
| the opt-in is on by default | killed |
| `listDevices` lets the error out | killed |
| `probePath` is not machine-scoped | killed |
| the extension declares support for untrusted workspaces | killed |
| the notice leaves out the tool settings | killed |

## Not covered

- No run on a Windows machine. The lookup order is taken from the cited sources, and the resolver is tested with Windows paths.
- Windows terminal quoting for a path with a space.
- A `.cmd` or `.bat` `probePath` cannot be spawned without a shell, per Node's docs. It is used as given, so running it fails with Node's error.

## Test plan

- [x] `npm test` in `vscode/` passes on the branch with main merged in: 69 tests, including the 10 in `toolPath.test.ts`.
- [x] `npm run compile` passes.
- [x] Mutation check (table above).
…plorer runs get the settings' secrets (AlphaWaveSystems#770)

## Summary

Programs the VS Code extension starts inherit VS Code's environment. This change removes the three secret variables (`PROBE_CLOUD_KEY`, `PROBE_CLOUD_SECRET`, `PROBE_RELAY_CLI_TOKEN`) from every child that is not a test run, and gives Test Explorer runs the secrets from the settings, as terminal runs already get them. Nothing else changes in the environment.

**Why not an allowlist.** An environment allowlist was considered and rejected:
- A `${NAME}` in a ProbeScript step reads any environment variable (`internal/runner/executor.go`, `expandEnv`, `os.LookupEnv`), as documented in `probescript/syntax.md`. An allowlist would make `${USER_EMAIL}` type its literal text.
- Most runs go through a terminal, which starts the person's own shell and its profile anyway.
- A process of the same user can read the same files directly.

The boundary is which binaries the extension runs and in which workspaces (the tool path settings and Workspace Trust).

**The spawn sites, on main:**
- `vscode/src/probe.ts` `runCommand` (`probe device list`, `probe lint`): `env: { ...process.env }`.
- `vscode/src/commands/deviceView.ts` (the device view's hub): `env: { ...process.env }`.
- `vscode/src/testing/testController.ts` (Test Explorer runs of `probe test`): no `env`, so it inherited VS Code's environment and did not get the secrets from the settings.

## The change

- `childEnv(base, { allow, add })` in `vscode/src/secretArgs.ts` (pure). It builds a new environment without each of the three secret variables that is not allowed, and puts `add` on top. The base is not changed.
  - Names are compared without regard to case. Windows reads `Probe_Cloud_Key` as `PROBE_CLOUD_KEY`, and Node keeps the casing an environment was given, so a differently cased secret would otherwise slip through.
  - A name in `add` replaces any casing of itself, so two casings of one variable never reach a child.
- `runCommand` and the device view use `childEnv(process.env)`, so they get no secrets.
- Test Explorer uses `childEnv(process.env, { allow: ALL_SECRETS, add: settingsSecretEnv() })`: the secrets VS Code's environment has, with the settings' values on top.
- The terminal runs are unchanged: they get their secrets from `buildTestRun` (AlphaWaveSystems#768).
- **Not changed, and stated in the docs:** the other terminals (Studio, record, convert, init, lint, report, devices) are created with no extra variables, but a VS Code terminal still inherits VS Code's own environment. If VS Code itself was started with one of the three variables set, those terminals have it.

**Docs.**
- The extension README gets a "What else the programs inherit" paragraph.
- The VS Code docs page gets a Security section covering the secrets, the binaries and what children inherit, with `probePath` described as a user setting.
- The CHANGELOG entry is under Changed, not breaking.

**AlphaWaveSystems#769 is merged and main is merged into this branch.** The docs page's binaries bullet was re-read against the merged code. It now says the extension looks the binary up in the absolute folders of PATH and runs the path it found. When nothing is found, it says so on Windows and runs the bare name on macOS and Linux.

## Tests

`vscode/src/test/childEnv.test.ts`, with `node --test`:
- a non-test child loses exactly the three, and keeps `PATH`, `HOME`, a `${NAME}` variable and `PROBE_CLOUD_URL`;
- mixed-case names (`Probe_Cloud_Key`, `probe_cloud_secret`) are removed, and a settings value replaces another casing of its name;
- the base is not changed;
- `allow` keeps only the named secrets;
- `add` overrides an inherited secret;
- a source check that each of the three spawn sites uses `childEnv` with its role, and that none passes `{ ...process.env }` any more. The spawn sites import `vscode`, so a unit test cannot call them.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 10 were killed: the first 8 on the first version, and the case-insensitive version re-checked with the 5 that apply to it.

| Mutant | Result |
|---|---|
| `childEnv` strips nothing | killed |
| `childEnv` ignores `allow` | killed |
| `childEnv` drops `add` | killed |
| the settings do not override the inherited secret | killed |
| `childEnv` changes its base | killed |
| `runCommand` passes the whole environment | killed |
| the device view passes the whole environment | killed |
| Test Explorer gets no settings secrets | killed |
| `childEnv` compares names with case | killed |
| `add` does not replace another casing | killed |

## Test plan

- [x] `npm test` in `vscode/` passes on the branch with main merged in: 73 tests.
- [x] `npm run compile` passes.
- [x] Mutation check (table above).
…lks to FlutterProbe (AlphaWaveSystems#767)

## Summary
Two design notes in `docs/proposals/`, no code, so the decisions can be made before anything is built. Both start from what the code does today (read from it, not from memory).

- **`studio-ai-next-feature.md`**: "Explain this failed step". What it does and never does; what it may read and may send (bounded, after the outbound gate and the preview); local-first, bring-your-own-key, no relay; consent and wipe rules stated for the model like `AskClearData` (nothing the model writes is executed, no wipe or connection is reachable from its output, no skip for hosted previews, not callable from automation or MCP); a failure-mode table with what pins each; six measurable targets (including a measured usefulness number that is reported, not claimed); a first slice; open decisions.
- **`ide-transport.md`**: the five local surfaces that exist and what a stray local process or a web page can reach on each; a threat model; what the transport must and must not be; six things found while reading the code that should be fixed first (cloud secrets in the terminal arguments of the VS Code extension, a workspace-scoped binary path, the whole environment passed to children, the automation discovery file not re-checking an existing folder or link, the test-only bridge's token, two MCP servers sharing one token file name); three options (a stdio child process, the automation endpoint, MCP over HTTP) with a recommendation; how it relates to the bound-method decision table and MCP; a first slice; measurable targets; open decisions.

Both are public-safe: nothing about plans, pricing, customers or other projects.

## Test plan
- [x] every claim about the code checked against the files and tests it names (two read-only fact sheets, then read again)
- [x] disclosure scan
…ults of a run in another workspace are not offered for export (AlphaWaveSystems#765)

## Summary
The run state machine is now tested directly (`studio/run_slot_test.go`), with `-race`: the run slot (`claimRun`, `releaseRun`, `CancelRun`, `runActive`) and the state a run leaves in `RunState`.

- The slot moves free, claimed, cancelled, released: a second claim is refused and does not disturb the first; `CancelRun` stops the run's context but keeps the slot until the run ends, twice or with no run is harmless; a release frees it and stops the context; a new run is not born cancelled.
- 64 concurrent starts: exactly one wins.
- A run that cannot start (a scope that matches nothing, a path outside the folders) gives its slot back, and no connection is refused before the slot is taken.
- Finish after cancel (real run on a blocked fake device): finished, no step in flight, the reason `run cancelled`, slot free; a late cancel changes nothing; the next run starts clean (no old error, results or finished flag).
- Cancel while starting: the run ends as cancelled and leaves nothing to export.
- Workspace changes mid-run (below).

## Found and fixed
The results kept for Export were attributed to the workspace open **when the run finished**. Open another folder while a run goes and the finished run's results were offered for export there, with JUnit names relative to the wrong folder. `executeRun` now notes the workspace it started in and `keepForExport` keeps nothing when it is not the open one at the end. Re-opening the same workspace during a run keeps the results (a test).

## Mutants
Eleven, all killed: claim does not refuse a second run, release keeps the slot, release does not stop the context (needed a test line; added), a run starts without a connection, a run that cannot start keeps the slot, finish leaves the current step, finish does not mark finished, finish drops the error, begin keeps the old state, a run of another workspace is kept, CancelRun does nothing.

"Lane results" has no Studio counterpart (Studio runs one device); the multi-device lanes are the CLI's and are tested there.

## Test plan
- [x] `go test -race` on the new tests (count=3) and the export tests; mutants as above
- [x] disclosure scan



## Review fixes
- The workspace check and the keep are one step under `a.mu`, which `SetWorkspace` and `useWorkspace` also hold while they change the workspace and clear the export; a test forces the interleaving through a seam and a change that arrives between the two leaves nothing kept.
- The run's workspace is taken with its slot (`claimRun`), not in `executeRun` after the path check; a test switches with `useWorkspace` after the claim.
- Both the open and the starting workspace are compared in one spelling (cleaned, links resolved): a trailing slash, a dot segment or a link to the same folder is the same workspace (tests).
- The report base held after a kept run is asserted. Mutants killed: compare and keep under separate locks, the raw spelling compared, SetWorkspace/useWorkspace not clearing the export, the run's workspace not recorded at claim, a wrong report base.
…haWaveSystems#771)

## Summary
Follow-up of a review of the clear-data wording change: the question of a `clear app data` step, the reinstall question and hint, the "Clearing all data for X on Y" line and the notifications reinstall line still printed `dc.AppID` and `dc.Serial` raw. They now take one cleaned app and serial (`CleanOneLine`, 80 characters) like the before-every-test question and the refusal hint do. One test covers the messages that can be reached without a device (both questions in both modes, both hints, the reinstall question and hint and the clearing line, with a hostile app id and serial: line breaks, an escape, a direction override, 300 characters); five mutants (each of those raw again) are killed. The notifications reinstall line (`DenyPermission`, iOS simulator) is cleaned the same way but has no unit test: it needs a simulator.

## Test plan
- [x] `go test -race` on the runner tests for the wipe messages; mutants as above
- [x] disclosure scan
…: the launcher gives it, and it travels in a header (AlphaWaveSystems#777)

## Summary
Finding 5 of the IDE transport note. The headless bridge (`PROBE_STUDIO_HEADLESS=1`, tests only) wrote its token into `/__headless/bridge.js`, which any local process could fetch without the token, and the event stream took it as `?token=` in the address. So on that surface the token separated nobody from a local process, and it ended up in logs and history.

- The launcher now gives the token: `PROBE_STUDIO_HEADLESS_TOKEN` (at least 32 characters). Without it, headless mode does not start and says what to set. Studio takes it out of its environment, so adb, simctl and other children do not inherit it.
- The page script and the page hold no secret. The token is checked only in the `X-Headless-Token` header, on calls and on the event stream. A token in the query string is refused.
- The Playwright config makes one token per run (workers read it from the environment the main process sets), starts the server with it and sends it with every request of every page (`extraHTTPHeaders`); the two specs that start their own Studio make their own and set it on the browser context.

## Tests and mutants
Go: the bridge script, the index and the assets never contain the token or a place for it; no token, a short token and one character under the minimum are refused with a message naming the variable, exactly the minimum works and the variable is gone from the environment afterwards; calls and events need the header; a wrong header and the right token in the query string are refused. Six mutants killed: the script serving the token, the page carrying it, the query string accepted for events, a short token accepted, the token left in the environment, calls needing no token. The whole browser suite passes with the header-borne token (189 passed).

## Test plan
- [x] `go test -race` on the headless tests; the browser suite (189 passed)
- [x] disclosure scan
…aWaveSystems#780)

## Summary

A device or simulator id no longer shapes a file path.

**On main:**
- **`internal/ios/devicectl.go:68` `FindPID`** (a physical iPhone's process list) wrote devicectl's output to `filepath.Join(os.TempDir(), fmt.Sprintf("devicectl-procs-%s.json", udid[:8]))` and then ran `defer os.Remove(tmpFile)`. This had three problems:
  - **Path traversal and deletion:** an id such as `../../x` names a file outside the temporary folder, and the deferred `os.Remove` deletes it.
  - **A crash:** `udid[:8]` panics for an id shorter than 8 characters.
  - **A link in a shared folder:** the name is predictable in the shared temporary folder, so it could be replaced by a symlink before devicectl writes.
- **`internal/ios/simctl.go:426` `simDataPath`** built `~/Library/Developer/CoreSimulator/Devices/<udid>/data`. `ReadToken` globbed and read token files under it. With an id holding `..`, a separator or a glob character, the read would be shaped by the id.
- **`internal/runner/device_context.go:923` `iosTokenPath`** built the same path from the serial, and the reconnect **removes** that file.

## The change

- **`ios.ValidDeviceUDID` and `ios.ValidSimulatorUDID`** (`internal/ios/udid.go`) accept exact forms only: hex digits and dashes.
  - A device UDID is 8 hex, a dash and 16 hex (iPhone XS and later), or 40 hex (earlier devices). Sources: [Reincubate](https://docs.reincubate.com/deviceidentifier/apple), [Corellium](https://support.corellium.com/device-settings/customizing-device-ids), [TechTarget](https://www.techtarget.com/whatis/definition/unique-device-identifier-UDID). These are third-party pages: Apple publishes no format.
  - A UUID is accepted too, for devicectl's CoreDevice identifier.
  - A simulator UDID is a UUID.
- **`FindPID`** refuses an id that is not a device id before anything runs. Its output goes to `processes.json` in a new private folder (`os.MkdirTemp`: mode 0700, name chosen by the system, under the temporary folder), and the folder is removed after the call. devicectl creates the file itself, so a 0700 folder that only this process can write into rules out a planted link.
- **`simDataPath`** is `""` for anything but a simulator UDID. `ReadToken` then skips the glob and the legacy fallback: built on `""`, they would be relative to the working directory, or the shared `/tmp/probe/token`.
- **`iosTokenPath`** is `""` for anything but a simulator UDID, so the reconnect removes nothing.

## Other paths built from device or app strings (checked, listed)

| Site | Built from | State |
|---|---|---|
| `internal/ios/devicectl.go:68` | device UDID | **fixed here** |
| `internal/ios/simctl.go:271, 280` (token glob and fallback via `simDataPath`) | simulator UDID | **fixed here** |
| `internal/runner/device_context.go:923` (token path, then `os.Remove`) | serial | **fixed here** |
| `internal/cli/record.go:329` `deviceSlug(device)` | device name | safe: every run of characters outside `[a-z0-9]` becomes `-`, so no separator or `..` survives |
| `internal/record/bundle.go:174` `e.ID+".json"` | exchange id | safe: `bundleID.MatchString(e.ID)` is checked first |
| `internal/runner/runner.go:736` | recipe file names | safe: read through the confined opener |
| `simctl.AppDataPath` / `appContainerDataPath` | the path `simctl get_app_container` prints | not built from the id; it is the local tool's own answer |

Ids passed as **command arguments** (`xcrun devicectl … --device <udid>`, `adb -s <serial>`) go through `exec` without a shell, as separate arguments, so they cannot become a path or a command there.

## Tests

- `TestUDIDForms`: the three valid forms pass. These do not: `../../x`, an absolute path, `..`, a UDID with `/../../x` behind it or a path in front of a UUID, a NUL, `*` and `?`, 4096 characters, a non-ASCII digit (U+0660), the empty string, a short one.
- `TestFindPIDRefusesAHostileUDID`: each hostile id is refused, and the fake `xcrun` on PATH never runs.
- `TestFindPIDWritesToAPrivateFolder`: the `--json-output` file is `processes.json` in a `probe-devicectl-` folder under the temporary folder, with nothing of the id in the path, and the folder is gone after the call.
- `TestReadTokenIgnoresPathsAHostileUDIDWouldShape`: a token planted where the old relative glob would look (`<cwd>/Containers/Data/Application/x/tmp/probe/token`) is not read for `../../x`.
- `TestIOSTokenPathOnlyForASimulatorUDID`: no path for hostile serials or a device UDID; a simulator UUID gives the usual path.

Hostile Unicode is built from code points in the test source, so the source stays ASCII (staticcheck ST1018).

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 8 were killed. "The simulator id is not anchored" survived at first, because no hostile id held a valid UUID with more around it. Two such ids were added, and it is now killed.

| Mutant | Result |
|---|---|
| the device id regex is not anchored | killed |
| the simulator id regex is not anchored | killed |
| `FindPID` does not check the id | killed |
| the output file is named after the id again | killed |
| the private folder is not removed | killed |
| `simDataPath` does not check the id | killed |
| the token glob runs without a data path | killed |
| `iosTokenPath` does not check the serial | killed |

## Test plan

- [x] `go test ./internal/ios/ ./internal/runner/ ./internal/device/` passes.
- [x] `go vet` and `staticcheck` pass on `./internal/ios/` and `./internal/runner/`.
- [x] No raw format characters in the changed files.
- [x] Mutation check (table above).
…tems#781)

## Summary
Test only. A bridge token of visible ASCII characters is required; the committed refusal map of the headless token test had a control character (BEL) but not DEL (`\x7f`), the one control character above the visible range. DEL is added; the mutant that accepts it (`t[i] > 0x7f` in `validHeadlessToken`) is killed.

## Test plan
- [x] `go test -race` on the headless token test; mutant as above; staticcheck (only the old S1011)
- [x] disclosure scan
…e printed as plain text on one line (AlphaWaveSystems#775)

## Summary

Device names, serials and app ids that come from `adb` or `simctl` output are now printed as plain text on one line. This is the first of three small changes. The other two cover the run's device context and the parallel run's device labels.

A device name can hold anything. A simulator name in simctl's JSON can hold a new line, and an `adb` model name can hold an escape sequence. Printed raw, it could carry a terminal escape (clear the screen, set the window title), a bidi override, a zero-width character, or a second line that looks like one of probe's own ("pass --yes to continue"). Each of these sites now prints its value through `device.CleanOneLine(value, 80)`, the existing helper the runner already uses for app ids and serials. **Display only:** the value given to `adb` and `simctl`, and every value used in logic, is unchanged.

| Site | What is printed |
|---|---|
| `internal/cli/device.go` `probe device list` | each row's serial, state and name |
| `internal/cli/device_view.go` `probe device view` | "Connecting to the agent on <name> (<id>)" |
| `internal/cli/device_set.go` `probe device set` | both refusals (state, physical iOS): name, id, state |
| `internal/device/manager.go` | the install, grant and launch lines (app path, serial, app id) on Android and iOS; "device … not found"; "Created simulator … (<udid>)"; the token-not-found error's app id |
| `internal/device/adb.go` | "versionName not found for <app id>" |
| `internal/device/port_follow.go` | the port-following notice: the app id, and each package name of the holder, cleaned one by one so the notice's own wording is kept |
| `internal/device/webview_forward.go` | the four forward errors' serial |
| **after review:** `internal/cli/device_view.go` | the listening line in all three output modes (`opts.Device.Name`); the "several devices are ready" choice (the ids); the connect line, now `connectingLine` |
| **after review:** `internal/cli/device_set.go` | the done line, now `setDoneLine` (name, id) |
| **after review:** `internal/device/manager.go:311` | the simulator-mismatch error (both udids) |
| **after review:** `internal/device/adb.go` | the `adb` error that carries `adb`'s stderr (cut to 400); the `uiautomator dump` error that carries the device's output (cut to 400) |
| **after review:** `internal/ios/simctl.go` | "did not boot" (udid) and "is not installed on" (bundle id, udid) |
| **after review:** `internal/probelink/portholder.go` | the port-holder hint: the `lsof` process name of this machine (any program can choose it) and the pid |

**`internal/oneline` (new leaf package).** `internal/device` imports `internal/probelink`, so `probelink` could not use `device.CleanOneLine`. The cleaner, with its hidden-character rule and its cut, moved unchanged into `internal/oneline`. `device.CleanOneLine`, `hiddenRune` and `cutRunes` now delegate to it, and `probelink` and `ios` use it directly.

**Not cleaned, and why:**
- `probelink/version.go:100`: the agent's handshake app id is already limited to a plain application id by `plainAppID` (`version.go:112`). A hostile one never reaches the mismatch warning, and a test now shows it.
- The port-following notice: `PortOwners` keeps valid package names only, and the follower refuses an app id that is not a package name (`ValidPackageName`), so neither reaches the notice raw. The cleaning there is defense in depth. The test shows a hostile package name is filtered out, and the notice is clean with its wording kept.

A `%q` site was left as it is: Go's `%q` already escapes control, bidi and zero-width characters (`strconv.Quote`). Examples are "%d devices are named %q" and "simulator %q is %s".

## Tests (through the real print paths)

- `TestDeviceListPrintsAHostileNameCleaned`: `probe device list` against a fake `adb` on PATH whose model name holds an escape sequence, a bidi override and a zero-width space.
- `TestDeviceSetRefusalNamesAHostileDeviceOnOneLine` and `TestCleaningIsForDisplayOnly`: the `device set` refusals with a name holding a new line and a fake "pass --yes" line; `checkSettable` returns the device unchanged.
- `TestDeviceViewStartupLineNamesAHostileDeviceCleaned`: `serveDeviceView` in json, plain and print-token mode with a hostile device name.
- `TestDeviceViewChoiceListsHostileIDsCleaned`: `pickViewDevice` with two ready devices whose serials hold an escape and a title sequence.
- `TestConnectAndSetDoneLinesNameAHostileDeviceCleaned`: `connectingLine` and `setDoneLine`. These two lines sit after a real agent connection or a real device setting, so the line builders the commands call are tested directly.
- `TestEnsureADBNamesTheSerialCleaned`, `TestStartIOSNamedPrintsIDsCleaned` (the mismatch error, and the created line with a hostile udid from a fake `xcrun`), `TestIOSInstallAndLaunchPrintsNamesCleaned` (simctl gets the real udid and bundle id), `TestInstallAndLaunchPrintsNamesCleaned` (Android: `adb` gets the real serial).
- **`TestAndroidLaunchGetsTheRealAppID`**: a fake `adb` logs each argument NUL-separated, so a new line inside an argument stays one argument. The `am start` call carries the real, hostile app id.
- `TestTokenErrorNamesTheAppCleaned`, `TestGetAppVersionNamesTheAppCleaned`, `TestADBErrorsCarryStderrCleaned` (`adb` stderr, and the dump retry), `TestUIAutomatorDumpCarriesDeviceOutputCleaned` (a dump that runs but does not dump), `TestWebViewForwardErrorsNameTheSerialCleaned`, `TestPortFollowNoticeNamesPackagesCleaned`.
- `TestSimctlErrorsNameIDsCleaned` (fake `xcrun`), `TestPortHolderNamesAHostileProcessCleaned` (a fake `lsof` on PATH, through `PortHolder`), `TestHostileHandshakeAppIDNeverReachesTheWarning`.

Hostile Unicode is built from code points in the test source, so the source is ASCII (staticcheck ST1018). An earlier push of this PR had raw U+202E and U+200B in two tests, and hosted Lint failed on it.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte.

- **First round: 8 of 8 killed.** "adb gets the cleaned serial" survived at first and was killed after the test checked each call.
- **After review: 16 of 18 killed.** "uiautomator: raw last error" survived until the dump-output test was added. **The two port-follow mutants survive by design:** their values are filtered upstream, as explained above, so no input reaches those lines raw.

| Mutant | Result |
|---|---|
| device list prints the raw name | killed |
| device set prints the raw name / the raw state | killed |
| the physical-device refusal prints the raw name | killed |
| the app-not-running error prints the raw app id | killed |
| Launching prints the raw app id | killed |
| Installing prints the raw serial (Android) | killed |
| adb gets the cleaned serial | killed |
| device view listening line: raw name | killed |
| device view choice: raw ids | killed |
| connect line: raw name | killed |
| set done line: raw name | killed |
| StartIOSNamed mismatch: raw udid | killed |
| StartIOSNamed created: raw udid | killed |
| EnsureADB: raw serial | killed |
| iOS Installing: raw serial | killed |
| **Android launch gets the cleaned app id** | killed |
| versionName: raw app id | killed |
| adb run: raw stderr | killed |
| uiautomator: raw last error | killed |
| webview forward: raw serial | killed |
| port holder: raw command name | killed |
| simctl boot: raw udid | killed |
| simctl reinstall: raw bundle id | killed |
| port follow: raw app id | survives: filtered upstream (`ValidPackageName`) |
| port follow: raw holder names | survives: filtered upstream (`PortOwners`) |

## Not covered

- `internal/runner` (the device context, the reconnect hints, the orchestrator's labels) is in the next two PRs.

## Test plan

- [x] `go test ./internal/...` passes.
- [x] `staticcheck ./...` passes, and there are no raw format characters in the changed files.
- [x] `go vet ./internal/cli/ ./internal/device/` passes.
- [x] Mutation check (table above).
… one writer of secret files, with its checks (AlphaWaveSystems#774)

## Summary
Finding 4 of the IDE transport note. The discovery file holds the automation token. Studio made its folder 0700 and wrote the file 0600 but did not re-check an existing folder or file, did not refuse a link, and fell back to the system temp folder with no user config folder. `probe-mcp --http` already did all of that for its token file in `writeTokenFile`.

- New `internal/secretfile` is the one writer, moved from `writeTokenFile` with its refusals unchanged and one addition: a folder or file that belongs to another user is refused too. `probe-mcp --http` is now a thin wrapper over it (its tests are unchanged and pass).
- Studio's discovery file uses it. For a file named by `PROBE_STUDIO_AUTOMATION_FILE` the folder is the person's own (their home folder may be 0755), so it must only be a real folder, theirs, not writable by others; the default folder must be private (0700). The file itself is always 0600, written by rename.
- No temp-folder fallback: with no user config folder and no named file the endpoint does not start, and the error says to set `PROBE_STUDIO_AUTOMATION_FILE`.
- On exit a server removes the file only while it holds its own document.

## Tests and mutants
`secretfile` table tests (existing file open to others, file link, dangling link, not a regular file, private folder open, folder link, another user's folder and file via a seam, a shared folder writable by others, replaced flag, no temp file left, Remove only its own), and Studio tests through `startAutomation` (a link or open file refused and the target untouched, a folder link or writable folder refused, a readable named folder accepted with a 0600 file, no config folder leaves the temp folder empty, a stale file replaced and only own removed). Eleven mutants killed: each check removed or inverted, written in place instead of renamed, the temp fallback back, Close removing another server's file.

## Test plan
- [x] `go test -race ./internal/secretfile ./internal/mcp ./studio`
- [x] Windows build of `internal/secretfile`
- [x] disclosure scan
…ervers do not overwrite each other (AlphaWaveSystems#778)

## Summary
Finding 6 of the IDE transport note, **stacked on the finding 4 change** (it edits the same function, `writeTokenFile`, which that change moves into `internal/secretfile`; merge that one first, then this branch retargets main).

Two `probe-mcp --http` servers of one user wrote to one file, `flutter-probe-mcp/http-token`: the second replaced the first's token, and the first server's token was no longer on disk (the server only said so on start).

- The file is now `http-token-<port>`, for the port the server is bound to (after a `:0` start, the real port). A port belongs to one server at a time, so the file does too: a second server on another port has its own file, each removes only its own on stop, and a second server on the same port cannot start (the listen fails before any file is touched, as before).
- The replaced note now says what it means: a file of this port was left by a server that did not stop cleanly.
- Docs (`mcp.md`) and the CHANGELOG say the name and that a script reading the fixed `http-token` path must use the file of its port or the path in the start-up line.

## Tests and mutants
Two servers on two ports have two files, neither says it replaced one, both tokens work and each refuses the other's, stopping one removes only its file; the name follows the port; the RunHTTP tests find their file by the real port; the stale-file test uses a fixed port. Mutants killed: every port the same name, the name from a wrong port, a server removing any token file, the replaced wording.

## Test plan
- [x] `go test -race ./internal/mcp ./cmd/probe-mcp`
- [x] disclosure scan
… one line (AlphaWaveSystems#776)

## Summary

A parallel run (`--devices`) now names each lane's device as plain text on one line. This is part 2 of 3. Part 1 (AlphaWaveSystems#775) covered the names printed by `probe device`, and part 3 covers the run's device context.

**On main**, `internal/runner/orchestrator.go` printed a lane's device id and name as `adb` or `simctl` reported them:
- `deviceLabel` (the "Device N: …" lane list);
- `shortID` (the `[device]` label of the progress, warning and "Connected" lines and of the result rows; it cut the id to 12 **bytes**, which can split a multi-byte character);
- the `[id]` prefix of the port-forward, hold, token, connect and handshake errors;
- the run's error summary.

A name can hold a new line, an escape sequence, a bidi override or a zero-width character, and so could print a second line that looked like probe's own ("pass --yes to continue").

## The change

- **`shortID`** cleans the id with `device.CleanOneLine` and cuts it to 12 **characters**. A plain serial reads exactly as before (`emulator-5554` → `emulator-555`).
- **`label`** (new) is the whole id for error messages, cleaned.
- **`deviceLabel`** returns the cleaned name, or the cleaned id when there is no name.
- **Display only:** the lane's `DeviceID` and `DeviceName` are unchanged. That is the id given to `adb` and `simctl`, used for the port, and written to the JSON and JUnit reports, whose encoders escape it.

## Tests (through the real run)

- `TestParallelRunPrintsHostileDeviceLabelsCleaned` runs a one-lane parallel run with the orchestrator harness. The lane's name and id hold a new line with a fake "pass --yes to continue" line, an escape sequence, an OSC title sequence, a bidi override and a zero-width space. No printed line forges its own line or carries one of those characters; the color codes probe adds itself are allowed. The name's visible text is shown.
- `TestFailedLaneErrorNamesTheDeviceCleaned` runs a lane whose connect fails, because no fake agent is on its port. Its error and the run's summary name the hostile id on one clean line, and a lane with no name is listed by its cleaned id.
- `TestLaneLabelsAreDisplayOnly`: the lane keeps its raw id and name; `shortID` cuts by characters (Japanese text) and leaves a plain serial as before.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 5 were killed. "label prints the raw id" survived at first, because the happy-path run never reaches an error message. The failed-lane test was added for it, and it is now killed.

| Mutant | Result |
|---|---|
| `shortID` prints the raw id | killed |
| `shortID` cuts bytes | killed |
| `deviceLabel` prints the raw name | killed |
| `label` prints the raw id | killed |
| the Connected line prints the raw id | killed |

## Test plan

- [x] `go test ./internal/runner/` passes.
- [x] `go vet ./internal/runner/` passes.
- [x] Mutation check (table above).
…elf; Cut no longer panics below 1 (AlphaWaveSystems#785)

## Summary

Follow-ups from the review of AlphaWaveSystems#775 (device names, serials, app ids and process names printed as one clean line). Mostly tests, plus one small fix.

**Tests for the five cleaning sites that had none.** In each, a hostile id (a new line with a forged `pass --yes` line, a screen clear, a title sequence, a bidi override, a zero-width space) must come out as one clean line, with its visible text kept:
- the WebView forward fallback error, `adb forward tcp:%d … failed on <serial>`;
- the WebView forward error after every fallback port was in use, `… after 5 ports were in use`;
- the WebView forward removal error, `adb forward --remove tcp:%d failed on <serial>`;
- the Android "Granting all permissions for <app>" line, with `grantPerms` on. Every `pm grant` call still gets the real app id;
- adb's error, which names the command it ran: the joined arguments are cleaned;
- the pid from `lsof` in the port-holder message: cleaned and cut to 20 runes.

**`internal/oneline` has its own tests** (`oneline_test.go`):
- `Clean` on every class of character it handles: controls, escape and title sequences, bidi controls and isolates, zero-width, line and paragraph separators, Hangul fillers, braille blank, grapheme joiner, object replacement, invalid UTF-8; also collapsing and trimming, and visible text in other scripts left unchanged;
- the limit is counted after cleaning;
- `Cut` never splits a rune;
- `Hidden` on a hidden and a visible list.

**Fix:** `oneline.Cut` panicked for a limit below 1 on non-empty text (`r[:n-1]`). It now returns an empty string. Every caller passes 20 or more, so no run hit it.

**Style:**
- The Hangul fillers, braille blank, combining grapheme joiner and object replacement character in `oneline.go` are written as `\u` escapes instead of literal glyphs.
- The `internal/oneline` import moved out of the standard-library group in `crash_collect.go`, `webview_ops.go`, `ios/simctl.go` and `probelink/portholder.go`. The other files with a mixed group were already like that on `main`, so they are left alone.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 12 were killed.

| Mutant | Result |
|---|---|
| fallback `tcp:%d` error prints the raw serial | killed |
| ports-in-use error prints the raw serial | killed |
| removal error prints the raw serial | killed |
| grant line prints the raw app id | killed |
| adb error prints the raw arguments | killed |
| `lsof` pid printed raw | killed |
| `Hidden` misses the Hangul fillers | killed |
| `Hidden` misses braille blank / grapheme joiner / object replacement | killed |
| `Clean` keeps a leading space | killed |
| `Clean` does not trim the end | killed |
| `Cut` has no guard below 1 | killed |
| `Cut` marks no cut | killed |

## Test plan

- [x] `go test ./internal/oneline/ ./internal/device/ ./internal/probelink/ ./internal/ios/` passes.
- [x] `go vet` and `staticcheck` pass on those packages.
- [x] No raw format or blank characters in the changed files.
- [x] Mutation check (table above).
…line (AlphaWaveSystems#786)

## Summary

A follow-up from the review of AlphaWaveSystems#776: a parallel lane's **error** is now printed as one clean line, as its device name already was.

The error of a lane that failed can carry text from the device or the agent: a refused dial or handshake, adb's output. `internal/runner/orchestrator.go` printed it with `%v` in four places, so a new line, an escape sequence or a bidi override in it reached the terminal (or the run's error) as is:
- the retry line, `[<lane>] attempt N failed: …`;
- the failure line, `[<lane>] all attempts failed: …`;
- the run's error, `device errors: [<lane>] …`;
- the device summary, `<lane>  error: …`.

All four now go through `errShown(err)`, which is `device.CleanOneLine(err.Error(), 400)`. The error itself is unchanged: the report's not-run results keep it as it is, and so do the retry decision (`errors.As` on `connectError`) and the caller.

## Tests

`TestFailedLaneErrorTextIsPrintedCleaned`: the dial fails with `refused\n  pass --yes to continue<ESC>[2J<RLO>end`. Across the run's output, `PrintSummary` and the run's error, it checks that:
- no line starts with a forged `pass --yes`;
- no line holds an escape, carriage return, bidi or zero-width character (probe's own color codes aside);
- the visible text is shown;
- the retry, failure and summary lines are present.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 4 were killed.

| Mutant | Result |
|---|---|
| retry line prints the raw error | killed |
| failure line prints the raw error | killed |
| run error holds the raw error | killed |
| device summary prints the raw error | killed |

## Test plan

- [x] `go test ./internal/runner/` passes.
- [x] `go vet` and `staticcheck` pass on `./internal/runner/`.
- [x] Mutation check (table above).
… a host path as it is (AlphaWaveSystems#782)

## Summary

A screenshot path from the agent is no longer used as a host path as it is.

**On main:**
- `internal/probelink/client.go` `Client.Screenshot` and `http_client.go` `HTTPClient.Screenshot` saved the image when the answer carried `data`. Otherwise, and also when the data did not decode, they **returned the agent's `path` as the host path**.
- The runner then used that path as a host file:
  - `captureRedactedScreenshot` (`executor.go`, the `with ai` steps) read it with `os.ReadFile` and, with `ai.redact` rules, **wrote the redacted image back over it** with `os.WriteFile(path, …, 0644)`. Without redact rules the bytes went on as the screenshot, for example to the AI provider.
  - `take screenshot`, `compare screenshot` (which crops next to it) and the failure screenshot attach or read it.

So an agent could make probe read, copy or overwrite another host image.

The current agent always sends the image in `data` (`probe_agent/lib/src/executor.dart`, "The image always travels in `data`"). Only an older agent, or a hostile one, sends a path without it.

## The change

`savedScreenshot` (`internal/probelink/screenshot_save.go`) is now the only way an answer becomes a host path, and both clients return it:

- **With data:** the image is saved in `reports/screenshots` under the base name of the agent's path, in a **new file** (`O_CREATE|O_EXCL`). If that name is taken, `-2`, `-3`… is added. An existing file, or a planted link of that name, is never written through. The name always ends in `.png`. It becomes `screenshot.png` when it can't be used on every system: `.`, `..`, nothing, a trailing dot or space, or a name Windows reserves (`CON`, `PRN`, `AUX`, `NUL`, `COM0`–`COM9`, `LPT0`–`LPT9`, with or without an extension). Undecodable data is an error, no longer a fallback to the path.
- **Without data** (what an older agent on an iOS simulator sends, since a simulator shares the host's file system), the file is read by `internal/confined.ReadFile`, which has **no check-then-use gap**:
  - The file is **opened once**, with `O_NOFOLLOW | O_NONBLOCK`. A link as the last part of the path is refused, and a FIFO can't block the run.
  - On the **open file**: `Fstat` must say it is a regular file with **exactly one name** (`nlink == 1`), so a hard link can't give a host file an allowed name.
  - Its **real path is asked of the open descriptor**, not of the path: `fcntl(F_GETPATH)` on macOS, `/proc/self/fd/N` on Linux, `GetFinalPathNameByHandleW` on Windows. It must be in a simulator's data folder, `<simulators>/<UUID>/data/…`.
  - The bytes are **read from that same descriptor** (at most 64 MiB).
  - `savedScreenshot` saves those bytes as a new file in `reports/screenshots`, like data, and returns that path. **No consumer ever opens the agent's path**: not redaction, not the AI step, not `ScreenshotBytes`' fallback, not `compare screenshot` or `PullArtifacts`. A link swapped in after the check is never followed.
  - Anything else is an error naming the path (`%q`). An older agent on Android or a physical iPhone, whose path isn't on the host anyway, gets that error.
- **Redaction** (`captureRedactedScreenshot`) writes the redacted image to a **new file**, `reports/screenshots/<name>-redacted-*.png` (`os.CreateTemp`: exclusive, mode 0600), and returns that path. It never writes over the file the screenshot came from.
- The five file helpers in `http_client.go`, which were only used by the old save, are removed.

## Tests

- `TestScreenshotWithoutDataRefusesAHostFile`: with no data, these are refused: a host file outside a simulator folder, `/etc/passwd`, a relative path, a non-UUID folder, a non-`.png` file, a file outside `data`, a folder named like a png, a `..` traversal out of the simulator folder, nothing, and **a link from a simulator's data folder to a host file**. A real screenshot in a simulator's data folder is accepted: its bytes are **copied into `reports/screenshots`**, and that copy is returned. The host file is unchanged.
- `TestScreenshotWithoutDataSurvivesASwap`: **the race**. A goroutine renames, as fast as it can, a regular screenshot and a link to a host secret over the same path in a fake `<UUID>/data`, while the test reads it for 2 s. Last run: 102,838 reads, 27,852 returned the screenshot, **0 returned the secret**. The test also fails if no read returned the screenshot, so it can't pass by refusing everything. (Its first version swapped two links, so every read was refused and the read-by-path mutant survived; that was fixed.)
- `TestScreenshotWithoutDataRefusesAHardLink`, `…RefusesALinkInsideTheSimulator` (a link even to another file in `data`), and `…RefusesAFIFO` (Unix: neither accepted nor blocking; 3 s guard).
- `TestScreenshotFileName`: `.png` is forced; Windows reserved names (`CON`, `nul.png`, `COM1.png`, `lpt9`) and trailing dot or space give `screenshot.png`; `COM10.png` and `console.png` are kept.
- `TestScreenshotWithDataIsANewFileInTheScreenshotsFolder`: hostile agent paths (`../../../x.png`, `/etc/x.png`, `..`, empty, a Windows path) are all saved inside the folder. An existing `taken.png` and a planted link `linked.png` get new names; the old file and the link's target are unchanged.
- `TestScreenshotWithBadDataIsAnError`: undecodable data is an error even with a path that would pass.
- `TestScreenshotWithoutAUsableNameIsScreenshotPNG`.
- `TestBothClientsUseSavedScreenshot`: source check of both clients, and the HTTP client against a fake agent server that answers `{"path":"/etc/passwd"}`.
- `TestRedactionNeverWritesOverTheScreenshotItCameFrom`: the source PNG is byte-identical after a redacted capture. The new file is in `reports/screenshots`, holds the redacted image and has mode 0600.
- The existing `TestScreenshotStillSavesAFileForTestRuns` passes unchanged: the base name is kept.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte.

**Round 2 (this push): 11 of 11 killed.**
- First run: 3 survived, 1 did not compile.
- "The regular-file check is gone" survived because a folder fails to read anyway. That led to the FIFO case, and to `O_NONBLOCK`: a FIFO used to block the open.
- "O_NOFOLLOW is dropped" survived because the real-path check covered it. That led to the link-inside-the-simulator case.
- "The bytes are read again by path" survived because the swap test was too weak; it was fixed (see Tests).
- "The real path must end in .png" was **equivalent**, because with `O_NOFOLLOW` the base name cannot change, so that check was removed.
- One mutant was rewritten to compile.

| Mutant | Result |
|---|---|
| the opened file's real path is not checked | killed |
| the link count is not checked | killed |
| the regular-file check is gone | killed |
| **the bytes are read again by path after the check (the race)** | killed |
| `O_NOFOLLOW` is dropped | killed |
| no data: the agent's path is returned | killed |
| the UUID folder check is gone | killed |
| the `data` folder check is gone | killed |
| Windows reserved names allowed | killed |
| trailing dot or space allowed | killed |
| `.png` not forced | killed |

**Round 1, still valid:**
- The with-data mutants: `O_TRUNC`, bad data falling back to the path, the base name not checked, the HTTP client returning the agent's path. All killed.
- Redaction writing over the source: rerun on this push, killed.

## Not covered

- The WebSocket client (`Client.Screenshot`) is checked through its source and through the shared `savedScreenshot`, not against a fake WebSocket agent.
- `PullArtifacts` (an agent-named host file copied into the reports folder) is a separate change (AlphaWaveSystems#783). It gets the same open-once read.
- `internal/confined` has no test file of its own: every branch of it is exercised through the probelink tests above, and each check has a mutant. On Windows it is only built and vetted here (`GOOS=windows go vet`, `staticcheck`), not run.

## Test plan

- [x] `go test ./internal/probelink/ ./internal/runner/ ./internal/cli/` passes.
- [x] `go vet` and `staticcheck` pass on `./internal/probelink/`, `./internal/confined/` and `./internal/runner/`, and with `GOOS=linux` and `GOOS=windows` on `confined` and `probelink`.
- [x] No raw format characters in the changed files.
- [x] Mutation check (table above).
… the app id and serial as plain text (AlphaWaveSystems#779)

## Summary

This makes the lines a run prints about the app and the device show the app id and the serial as plain text on one line. It is part 3 of 3: AlphaWaveSystems#775 covered `probe device` and `internal/device`, and AlphaWaveSystems#776 the parallel run's lane labels.

**On main**, these printed `dc.AppID` and `dc.Serial` (or `deviceSerial`) as given:
- `internal/runner/device_context.go`: the single-device warning `[serial]`, force-stopping, relaunching (×5), the reinstall question, clearing data, the data-path error, the set-language error, iOS notification reinstall, granting permissions, killing, launching;
- `internal/runner/reconnect_hint.go`: the three "the app … is not running" hints;
- `internal/runner/runner.go`: the pull error;
- `internal/cli/test.go`: "Physical device detected";
- `internal/cli/record.go`: "Recording on".

A serial comes from `adb` or `simctl`. The app id is validated when it comes from `probe.yaml`, but these lines print whatever the device context holds. A value with a new line, an escape sequence, a bidi override or a zero-width character could forge a line or change the terminal.

## The change

- `DeviceContext.appShown()` and `serialShown()` return `device.CleanOneLine(value, 80)`. Each of the 15 print sites in `device_context.go` and the hint and pull sites use them. The two CLI sites call `device.CleanOneLine` directly.
- **Display only:** every value given to `adb`, `simctl` or `devicectl`, and every comparison, still uses `dc.AppID` and `dc.Serial` as they are.
- The reconnect hint is only reached for an app id that passes `ValidPackageName`, so a hostile id never got there. It is cleaned anyway, the same way.
- Script-authored names printed by the runner (test, recipe and measurement names, mostly `%q`) are not device output and are not part of this change.

## Tests (through the real print path)

`TestLifecycleLinesPrintAppAndSerialCleaned` runs kill, launch, restart and clear data on a `DeviceContext` with the recording fake `adb` (`recordingDevice`). Its app id holds a new line with a fake "pass --yes to continue" line, an escape sequence, a bidi override and a zero-width space, and its serial an OSC title sequence. For each step:
- no printed line forges its own line or carries one of those characters (probe's own color codes are allowed);
- every `adb -s` call gets the **real** serial.

## Mutation check

Each mutant was applied, the test was run, and the file was restored byte for byte. All 5 were killed.

| Mutant | Result |
|---|---|
| `appShown` returns the raw app id | killed |
| `serialShown` returns the raw serial | killed |
| the kill line prints the raw app id | killed |
| the clear line prints the raw serial | killed |
| adb gets the cleaned serial (display-only rule broken) | killed |

## Not covered

- The two CLI lines ("Physical device detected", "Recording on") are cleaned with the same call but have no test of their own: they sit deep in the `probe test` and `probe record` flows.

## Test plan

- [x] `go test ./internal/runner/ ./internal/cli/` passes.
- [x] `go vet ./internal/runner/ ./internal/cli/` passes.
- [x] Mutation check (table above).


## Review follow-up

- **Windows build:** `printed_device_names_test.go` uses `recordingDevice`, which is defined only for `!windows`, so it now has the same build tag. `GOOS=windows go vet ./internal/...` passes.
- **More prints cleaned in `probe test`:**
  - "Connected to ProbeAgent on <serial>" (an auto-picked id comes from the device list and is not validated);
  - the `-v` "ensuring adb + device <serial> reachable" line;
  - the cloud run's "Connected to ProbeAgent on <device>";
  - both "App uploaded: <id>" lines (the id is the provider's API response).
- **Data-path errors** quote the path `simctl` returned with `%q`.
- **Tests for the other sites**, through their real paths with hostile values:
  - the three data-path errors;
  - set language on a physical iPhone;
  - grant all permissions (the grants still get the real id);
  - the reconnect hint, which is skipped for an app id that is not a package name, so its cleaning is a second line behind that gate.

  A failed pull is not printed, so its cleaning can't be observed; the CHANGELOG now says which sites are tested and which are a second line. A source check covers the `probe test` prints.
- **Mutants:** 10 of 10 killed.
  - raw data path (×3), raw serial in the data-path error;
  - raw app id in set language and in grant;
  - the hint's package-name gate removed;
  - raw connected, trace and upload prints.

## Second follow-up

- **Cloud prints:** the cloud upload and session start, which were the same code in two paths, are now one function, `uploadAndStartCloudSession`. Its "Starting cloud session on <device>" line and the relay "Connected to ProbeAgent via relay on <device>" line print the device cleaned, like the other cloud lines.
- **The provider gets the real values:** `TestCloudSessionGetsTheRealValuesAndPrintsThemCleaned` checks, with a fake provider, that `UploadApp` gets the app path and `StartSession` gets the id `UploadApp` returned and the target device as they are, while both printed lines are clean.
- **Mutants:** 5 of 5 killed: the provider gets a cleaned device, the provider gets a cleaned app id, and the starting, upload and relay lines printed raw.
- **CHANGELOG:** says the data-path errors quote the path with `%q`, and names the cloud lines.
…ing characters (AlphaWaveSystems#787)

## Summary

A printed name is no longer split by spaces at its joining characters. The joining characters are removed from the printed name.

`oneline.Clean` (behind `device.CleanOneLine`) turned every hidden character into a space. That is right for bidi controls and zero-width spaces, but these characters change nothing else; they only join what is around them:
- the zero-width joiner, U+200D (emoji sequences);
- the zero-width non-joiner, U+200C (Persian and Indic words);
- the variation selectors, U+FE00–FE0F (such as the emoji presentation selector) and U+E0100–E01EF.

Turning them into spaces split a name apart:
- a family emoji printed as three spaced faces;
- `❤️` printed as `❤` and a space;
- a Persian, Kannada, Odia or Telugu word with a non-joiner printed as two words.

## The change

- New `oneline.Joiner(r)`: U+200C, U+200D, U+FE00–FE0F, U+E0100–E01EF.
- `Clean` **drops** a joiner instead of writing a space.
- Bidi controls, zero-width spaces, BOM, controls and every other hidden character still become spaces, as before.
- `Hidden` is unchanged: joiners are still hidden characters.

Dropping is safe: a joiner can't move, reorder or hide visible text, or start a line. What the printed name looks like after the change:
- a joined emoji prints as its parts side by side, without spaces (the family emoji is three faces, not one glyph);
- without U+FE0F, an emoji may show in its text style;
- letters a ZWNJ kept apart in Persian or Indic text are printed joined.

That is closer to the name than spaces were; it is not the exact rendering. Keeping the joiners would preserve it, but I'd rather not send them to a terminal: how they render varies by terminal, and the job of this function is a plain, predictable line.

**Lookalike ids.** An id with a joiner, such as `a<ZWJ>b`, now prints as `ab` (it was `a b`); this affects the wipe warning, the clear-data line and "several devices are ready". An id that went through validation can never hold a joiner: the `--device` serial (`config.ValidateDeviceSerial`), the `probe.yaml` app id (config load), a package name read from the device (`device.ValidPackageName`) and a UDID (`ios.ValidSimulatorUDID` / `ValidDeviceUDID`) all refuse one, and `TestValidatedIDsNeverHoldAJoiner` checks each against every joiner. Two values are **not** validated: a device **name**, and a **serial picked from the device list** when `--device` is not given (a USB device can choose its own serial). For those, a joiner is dropped from the printed text; the value given to adb or simctl is unchanged.

**One implementation.** `probelink.cleanHolderText` (the port-holder message) was a hand copy of the old rules. It missed the combining grapheme joiner, noncharacters and the supplementary variation selectors, and it turned joiners into spaces. It now calls `oneline.Clean`. `probelink` can import `internal/oneline`, a leaf package, though it can't import `device`. `TestCleanHolderTextIsOnelineClean` compares the two on those characters.

## Tests

- `TestCleanDropsJoiners`: a family emoji, a heart with its selector, a Persian word with a ZWNJ, an ideographic variation selector, and joiners at the ends, between spaces and alone. A bidi override or a zero-width space next to a joiner still becomes a space. Dropped joiners don't count against the limit.
- `TestJoiner`: the joiners (each still `Hidden`), and neighbours that are not joiners: U+200B, U+200E, U+202E, U+2060, U+2066, U+FEFF, U+FE10, U+E00FF, U+E01F0.
- `TestValidatedIDsNeverHoldAJoiner` and `TestCleanHolderTextIsOnelineClean` (above).
- The `device`, `probelink`, `ios`, `runner`, `cli` and `sysdialog` tests pass unchanged, including the existing `cleanHolderText` cases.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 7 were killed.

| Mutant | Result |
|---|---|
| joiners still become spaces | killed |
| every hidden character is dropped | killed |
| ZWNJ is not a joiner | killed |
| ZWJ is not a joiner | killed |
| the selector range ends at U+FE10 | killed |
| the supplementary selectors are missing | killed |
| `cleanHolderText` with its own rules again (fields joined, cut) | killed |

## Test plan

- [x] `go test` passes on `oneline`, `device`, `probelink`, `ios`, `runner`, `cli` and `sysdialog`.
- [x] `staticcheck ./internal/oneline/`; `GOOS=windows go vet ./internal/...`.
- [x] No raw format characters (tests build them from code points).
- [x] Mutation check (table above).
…ig load, token read, kill (AlphaWaveSystems#784)

## Summary

Follow-ups from the review of AlphaWaveSystems#780: a device id that is not one is now refused where it would act, not later.

1. **`device.ios_device_id` must be a UDID.** It becomes the iOS device serial (`internal/cli/test.go`), and a simulator id shapes host paths. Until now it was not validated: `config.ValidateDeviceSerial` allows `/` and `.`, and does not see this key.
   - `config.LoadFile` now refuses anything but a simulator UDID or a device UDID (`ios.ValidSimulatorUDID` / `ios.ValidDeviceUDID`), with a message that names the key and says where to find the id.
   - Breaking for a `probe.yaml` that put a device name there. As the `--device` serial, a name with a space already failed.
2. **`DeviceCtl.Terminate` no longer hides a failed process lookup.** It returned nil, meaning "not running", whenever `FindPID` failed, including for an id AlphaWaveSystems#780 refuses. So on a physical iPhone a kill could pass silently and a relaunch could start beside a running app. It now returns the lookup error, and `KillApp` prints `the app was not stopped: …` in one line. The error quotes the id with `%q`.
3. **`SimCtl.ReadToken` fails fast** for an id that is not a simulator UDID (a physical device's, or not an id), instead of polling for the whole timeout.
4. **The token paths are built in one place**, `SimCtl.tokenFileCandidates`: the app's container, every data container, then the legacy device-level file. With an id that is not a simulator UDID it returns no path at all, the legacy file included. It is testable on its own; that mutant survived in AlphaWaveSystems#780.
5. **CHANGELOG wording of AlphaWaveSystems#780, corrected:**
   - the device UDID is 8 hex digits, a dash and **exactly 16** hex digits (not "8-16"), or 40;
   - only the id's first 8 characters were used, so the reach was a `.json` file **one folder above** the temporary folder.

Docs: `advanced/configuration.md` (the `ios_device_id` row) and `platform/ios.md` say the value must be a UDID. Their example is a valid UUID.

## Tests

- `TestTokenFileCandidatesNeedASimulatorUDID`: no paths for a device UDID or any of AlphaWaveSystems#780's hostile ids. A simulator's list ends with the legacy file.
- `TestReadTokenFailsFastForAnIDThatIsNotASimulator`: a hostile id, a device UDID and an empty id are each refused in under a second, with a 5 s timeout.
- `TestTerminateReportsALookupFailure`: a refused id gives the lookup error, and the fake `xcrun` never runs.
- `TestKillOnAPhysicalIPhoneWarnsWhenTheLookupFails`: the warning line is printed.
- `TestIOSDeviceIDMustBeAUDID`: empty, a UUID, a 25-character and a 40-character device UDID load. `../../x`, `/etc`, `iPhone 16`, a UUID with `/../x` and `*` are refused with the key named.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 5 were killed.

| Mutant | Result |
|---|---|
| `ReadToken` does not fail fast | killed |
| the legacy fallback is built without a data path | killed |
| `Terminate` hides the lookup failure | killed |
| `KillApp` drops the warning | killed |
| the config accepts any `ios_device_id` | killed |

## Test plan

- [x] `go test ./internal/ios/ ./internal/config/ ./internal/runner/ ./internal/cli/` passes.
- [x] `go vet` and `staticcheck` pass on the changed packages.
- [x] No raw format characters in the changed files.
- [x] Mutation check (table above).
… load now requires (AlphaWaveSystems#788)

## Summary

The Studio tests are green again. Since AlphaWaveSystems#784, `config.Load` refuses a `device.ios_device_id` that is not a simulator or device UDID. Four Studio tests still wrote or saved made-up ids (`ABC`, `SIM-UDID`, `X`, `IOS-1`), so they failed on `main`. The hosted Studio workflow does not run, so the failures did not show in CI.

On `main`, `go test -race ./studio/...` failed in four tests:
- `TestRandomProbeYAMLShapesAreEditedExactlyOrRefused`: "only 143 of 500 random files could be saved". The generator wrote `ios_device_id: ABC`, so those shapes no longer load.
- `TestSaveWorkspaceSettingsKeepsEverythingElseInProbeYAML`: "invalid device.ios_device_id "SIM-UDID"".
- `TestSaveWorkspaceSettingsRemovesClearedKeys`: saved `X`, and clearing it then failed because the file no longer loads.
- `TestConcurrentSavesOfDifferentFieldsAllLand`: one of its fields was `IOS-1`.

The fix is test data only: each of those ids is now a simulator UDID (a UUID). No production code changes, so there is no CHANGELOG entry.

## Test plan

- [x] `go test -race -count=1 ./studio/...` with a stub `studio/frontend/dist/index.html`:
  ```
  ok  	github.com/alphawavesystems/flutter-probe/studio	215.472s
  ok  	github.com/alphawavesystems/flutter-probe/studio/e2e	1.212s
  ```
  No data race reported.
- [x] The same four tests fail on `origin/main` without this change; reproduced on a clean checkout.
…lphaWaveSystems#789)

## Summary

Follow-ups from the review of AlphaWaveSystems#784: every way to name an iOS device now follows the rule of `device.ios_device_id`, which must be a simulator UDID or a device UDID.

- **`probe test --device`** for an iOS simulator or device must be a UDID (`validIOSDeviceFlag`). Until now it only had `config.ValidateDeviceSerial`'s character class, which allows `/` and `.`, while the same id shapes host paths (a simulator's data folder) and devicectl arguments. The check runs once the platform is known, so Android serials keep their rule.
- **Studio's Settings** refuse to save an iOS device that is not a UDID, and write nothing; before, a value the CLI then refused to load could be saved. The check applies only when that field changed, so an old value doesn't block saving other fields (the config load reports it).
- **Messages** point at `probe device list`, in the config load error, the `--device` error and Studio's error.
- **Docs:** the missing period in the `ios_device_id` row of `advanced/configuration.md`; the `--device` row of `tools/cli-reference.md`; a sentence in `platform/ios.md`.

Not covered: the parallel `--devices` list keeps its current check (each serial must be a connected device). It can follow in its own change.

The Studio test values are the same as in AlphaWaveSystems#788, which fixes the Studio tests on `main`; this branch has the same edits, so the two merge cleanly in either order.

## Tests

- `TestIOSDeviceFlagMustBeAUDID`: a simulator UDID, a 25-character and a 40-character device UDID pass. `../../x`, `/etc`, `iPhone.16`, a UUID with `/../x` and `abc` are refused, and the message names `--device` and `probe device list`. Android serials, including `ip:port`, pass.
- `TestProbeTestChecksTheIOSDeviceFlag`: a source check that `probe test` calls it.
- `TestSaveWorkspaceSettingsRefusesAnIOSDeviceIDThatIsNotAUDID`: four bad values are refused and not written; three good ones are saved.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 6 were killed. Two did not compile at first (an unused import) and were rewritten.

| Mutant | Result |
|---|---|
| `probe test` does not call the check | killed |
| any iOS id accepted | killed |
| device UDIDs refused | killed |
| Android held to the iOS rule | killed |
| Studio saves any id | killed |
| Studio refuses device UDIDs | killed |

## Test plan

- [x] `go test ./internal/cli/ ./internal/config/` passes.
- [x] `go test -race -count=1 ./studio/...` (stub `frontend/dist`): `studio` ok in 216 s, `studio/e2e` ok, no data race.
- [x] `staticcheck` on `cli` and `config`. In `studio`, staticcheck reports one finding, S1011 in `replace_line_classify_test.go`; that file is already on `main` and this PR doesn't touch it.
- [x] `GOOS=windows go vet ./internal/...`.
- [x] No raw format characters.
…WaveSystems#790)

## Summary

staticcheck S1011 in `studio/replace_line_classify_test.go`: a loop that appended a slice one element at a time is now one `append(stepTypes, steps...)`. Test-only, the same result, so there is no CHANGELOG entry.

## Test plan

- [x] `staticcheck` in `studio/`: clean.
- [x] `go test -race -count=1 ./studio/...` (stub `frontend/dist`): `studio` ok, `studio/e2e` ok, no data race.
…d on two named devices (AlphaWaveSystems#792)

## Summary

**Widget family: Navigation (app bar and routes).** Item 2 of `docs/compat/NEXT.md`: a fixture screen, a ProbeScript suite, the variants that must fail, and the matrix results, set only from runs on named devices.

- **Screen** (`PROBE_FIXTURE_WIDGETS=navigation`, `native-test-apps/flutter/lib/widget_families.dart`):
  - a `Scaffold` whose `AppBar` is titled "Inbox", with an action `IconButton` with the tooltip "Search" (`wf_search`), counted in the state text `Queries: N`;
  - a button "Open message" (`wf_open_message`) that pushes a `MaterialPageRoute` titled "Message", whose body is `From: Ada`.

  No label is part of a state text, since text selectors match substrings; that is why the counter is `Queries` and not `Searches`. Every control has a `Semantics(identifier:)` and a `ValueKey` of the same name, as in the other families.
- **Suite** `probe-tests/widgets/navigation.probe` (4 tests): the bar's title, and its action by tooltip and by `#id`; a pushed route is seen; **the route under the top one is not seen**; `go back` returns to the first route.
- **Negative variants** `probe-tests/negative/navigation.probe.expect-fail` (5 tests, each with its `# Expected:` line): the route under the top one seen; one tap counted twice; the second route before it is pushed; the second route after `go back`; a tooltip that is not on the screen.
- **Matrix:** a Navigation section, and the family row now points to it. The cells are set only for `AppBar` and `Navigator`; `NavigationBar`, `TabBar` and `Drawer` stay not assessed. `NEXT.md` item 2 says it is assessed; the README lists the family. CHANGELOG under Added.

## What it settles

- **The route rule holds on a device.** While the message route (opaque) is on top, the first route's title, texts and button are not matched: `don't see "Inbox"`, `"Queries: 0"` and `"Open message"` pass, and `see "Inbox"` fails. This is the agent's rule (`_isVisible` and `_routeOnScreen` in `probe_agent/lib/src/finder.dart`), which until now had only a unit test (PT-03).
- **Finding: during a pop, the leaving route is still matched, on both devices.** Right after `go back`, `wait until "Inbox" appears` passes at once, while the message route is still on screen in Material's page transition. The first run of the suite failed at `don't see "From: Ada"`: it found 2 elements. Those steps alone, 5 runs on each device: the leaving route was found in 4 of 5 runs on `Compat-Pixel-API35` and in 5 of 5 on `Compat-iPhone`. A test that checks a pop now waits for the leaving route to go (`wait until "From: Ada" disappears`). The suite says this in a comment, and the negative N4 uses the same wait.
- `go back` is the agent calling `Navigator.pop()`. It is not the Android back key or the iOS edge swipe; neither was run.

## Evidence (devices)

Flutter **3.44.8** (installed; `pubspec.lock` unchanged, nothing added or upgraded). The probe CLI was built from this branch; the agent is the fixture's path dependency (0.27.0).

- **Android:** AVD `Compat-Pixel-API35` (created for this work from the installed `android-35/google_apis/arm64-v8a` image, Pixel 6 profile), Android 15 (API 35), `emulator-5590`. The name was read back (`adb -s emulator-5590 emu avd name`) before each step. Host port 48690, device port 48686.
- **iOS:** simulator `Compat-iPhone`, UDID `A57AEE67-3473-4C20-BE25-8847C2A9D6BE` (created for this work), iPhone 17 Pro, iOS 26.5, always addressed by UDID. The agent was built with `--dart-define=PROBE_PORT=48691`, its own port, since a simulator shares the host's network.

| Run | `Compat-Pixel-API35` | `Compat-iPhone` |
|---|---|---|
| `navigation.probe`, 3 runs | 4 passed, 3 times | 4 passed, 3 times |
| the negative file, run as its header says | 0 passed, 5 failed, each with its stated message | 0 passed, 5 failed, each with its stated message |

Flutter 3.50.0 was not run for this family; the matrix says so. I've asked where a 3.50.0 SDK copy is; if one is available, the suite runs on it in a follow-up and the cells name both versions.

## Not covered

`NavigationBar`, `TabBar`, `Drawer`; a route that is not opaque (a dialog, a popup menu, a sheet, where the page under it stays matched by design; item 8); named routes and `go_router`; the system back key and the iOS edge swipe; a nested `Navigator`; Cupertino routes (item 10); a physical device; other screen sizes, text scales and accessibility services. CI does not build the fixture.

## Test plan

- [x] The suite and the negative file on both named devices (table above).
- [x] `make ci-local`: 5 of 5 required checks at cc5bf40 (Build, Go unit tests, probe-convert tests, Lint, Disclosure guard).
- [x] `go test ./scripts/`: the negative-suite guards accept the new file.
- [x] `dart format` and `flutter analyze lib`: no issues.

## Review follow-up

- **The transition finding names its devices**, in the matrix, the CHANGELOG and here: Android 4 of 5 runs, iOS 5 of 5 (`pop-repro`: tap, wait for the message, `go back`, `wait until "Inbox" appears`, `don't see "From: Ada"`).
- **A positive control in test 3:** `see "Inbox"` and `see "Queries: 0"` run before the push, so the `don't see` steps can't pass on a text that never existed. N1 of the negative file sees `"Inbox"` before the push too, and fails only at the check after it (line 17).
- **`NEXT.md` item 2** says "back: in-app pop only (not the system back key or iOS edge swipe)".
- **Rerun after the change**, on each device: `navigation.probe` passed 4 of 4 three times, and the negative file gave 0 passed and 5 failed, each with its stated message. Main is merged in; there was no conflict.
…o named devices (AlphaWaveSystems#794)

## Summary

**Widget family: Text and display (the text part).** Item 1 of `docs/compat/NEXT.md`: a fixture screen, a ProbeScript suite, the variants that must fail, and the matrix results, set only from runs on named devices.

- **Screen** (`PROBE_FIXTURE_WIDGETS=display`, `native-test-apps/flutter/lib/widget_families.dart`):
  - `Text("Order total: 42.00")` (`wf_text`);
  - a one-line `Text` cut with an ellipsis, longer than the screen is wide (`wf_ellipsis`);
  - a `Text.rich` of "Hello " and a bold "world" (`wf_rich`);
  - a `RichText` of "Painted " and "rich text" (`wf_richtext`).

  Each has a `Semantics(identifier:)` and a `ValueKey` of the same name.
- **Suite** `probe-tests/widgets/display.probe` (5 tests):
  - a plain text by its whole text, a part, and `contains`;
  - the spans of `Text.rich`, and of `RichText`, as one text and as parts;
  - the cut text by its whole string, including the part that isn't painted;
  - every widget by `#id`.
- **Negative variants** `probe-tests/negative/display.probe.expect-fail` (6 tests): a number one cent off; `contains` a value the text doesn't hold; a text that isn't on the screen; another case; two spaces between the spans; the painted, cut form.
- **Matrix:** a "Text and display: text" section, and the family row points to it. Cells are set for `Text` and `RichText` only; `Icon`, `Image` and the rest are item 3. `NEXT.md` item 1 is marked assessed; the README lists the family. CHANGELOG under Added.

## What it settles

- **A text selector matches the text the app gave the widget, not what is painted.** The cut text is found by its whole string, including "United States of America", which is not on screen, and not by the cut form with `…`.
- **It matches the whole text or any part of it, exactly.** Case counts and spaces count. The spans of a `Text.rich` or a `RichText` are matched as one text, joined as written.
- **Found, and filed as AlphaWaveSystems#793:** right after `restart the app`, the agent can answer while the screen is still being built. On `Compat-Pixel-API35`, the suite without a wait failed 3 of 10 runs; with a wait for the first item, 1 of 10; with a wait for the screen's last widget, 10 of 10 passed. The suite waits for the last widget, with a comment pointing to AlphaWaveSystems#793. The merged `buttons` suite fails 7 of 10 runs there for the same reason; that's for a separate PR.

## Evidence (devices)

Flutter **3.44.8** (installed; `pubspec.lock` unchanged). The probe CLI was built from this branch; the agent is the fixture's path dependency (0.27.0).

- **Android:** `Compat-Pixel-API35`, Android 15 (API 35), `emulator-5590`, name read back before each step; host port 48690, device port 48686.
- **iOS:** `Compat-iPhone`, UDID `A57AEE67-3473-4C20-BE25-8847C2A9D6BE`, iPhone 17 Pro, iOS 26.5, by UDID; the agent is built with `PROBE_PORT=48691`.

| Run (final suite, with the wait) | `Compat-Pixel-API35` | `Compat-iPhone` |
|---|---|---|
| `display.probe` | 5 of 5 tests, in 10 of 10 runs | 5 of 5 tests, in 5 of 5 runs (and 3 of 3 before the wait was added) |
| the negative file | 0 passed, 6 failed, each with its stated message | 0 passed, 6 failed, each with its stated message |

Before writing the suite, two exploratory files (14 and 7 questions) were run on both devices with the same results; they are not committed.

Flutter 3.50.0 was not run for this family; the matrix says so.

## Not covered

`SelectableText`; text scale; right-to-left and other scripts; `semanticsLabel` (item 3); soft wrapping without `maxLines`; `Icon`, `Image`, `FlutterLogo`, `CircleAvatar` (item 3); a physical device.

## Test plan

- [x] The suite and the negative file on both named devices (table above).
- [x] `make ci-local`: 5 of 5 required checks at 90a7d2e.
- [x] `go test ./scripts/`: the negative-suite guards accept the new file.
- [x] `dart format` and `flutter analyze lib`: no issues.

## Review follow-up

- **Read tests for every read cell.** These are now in the suite, each with a negative variant:
  - `see "Hello world" contains "world"` (N7 `contains "earth"`);
  - `see "Painted rich text" contains "rich text"` (N8 `contains "plain text"`);
  - `see "Shipping address" contains "United States of America"` (N9 `contains "Canada"`).

  What `contains` reads for a `Text.rich`: the failing N7 shows the text read is the whole `"Hello world"`, not an empty string. The matrix read cells say this.
- **The ellipsis text** is described as *chosen* longer than the screen is wide: an inference from its length, since the agent doesn't report the painted width.
- **N6** says it shows the finding by its construction.
- **The README comma** after "Cupertino fields)" is fixed.
- **`NEXT.md` item 1** says "find and read", and that `Icon` and `Image` stay item 3.
- The 3 of 10 to 10 of 10 figure stays labelled as measured on `Compat-Pixel-API35`.
- **Main merged in**, after the navigation family: both families are in the fixture, README, matrix, NEXT and CHANGELOG.
- **Rerun after the change:** `display.probe` passed 5 of 5 tests in 10 of 10 runs on `Compat-Pixel-API35` and in 5 of 5 runs on `Compat-iPhone`. The negative file, now 9 tests, gave 0 passed and 9 failed on each device, each with its stated message. One more Android run after the merge passed 5 of 5.
…app (issue AlphaWaveSystems#793) (AlphaWaveSystems#795)

## Summary

Interim fix for AlphaWaveSystems#793: the widget-family suites of the Flutter fixture wait for their screen's last element right after `restart the app`, so they no longer fail on a slower device.

After a relaunch, an app can draw its first frames with a 0×0 view for about a second (measured on an Android 15 emulator; see the issue). A `ListView` laid out then builds only its first child, and a step that runs in that window sees half the screen. Each suite's `before each test` now does:

```
restart the app
# the last element of the screen: right after a restart the agent can answer while the screen is still being built (issue AlphaWaveSystems#793)
wait until #<last element> appears
```

Last elements: `buttons` `#wf_long_press_state`, `selection` `#wf_cupertino_switch_state`, `textinput` `#wf_cupertino_state`, `navigation` `#wf_open_message`. The negative files of `buttons` and `navigation` get the same wait, so they fail for the reason they state and not because of the restart.

This changes only the suites. The fix for the cause is in the agent: it should answer only once the view has its real size. That comes in a separate PR, after which these waits can stay as harmless or be removed.

## Evidence

AVD `Compat-Pixel-API35`, Android 15 (API 35), `emulator-5590`, name read back before each run; Flutter 3.44.8. Each suite ran 10 times, as on `main` and as in this branch:

| Suite | `main` | this branch |
|---|---|---|
| `buttons.probe` | 3 of 10 runs passed | 10 of 10 |
| `selection.probe` | 7 of 10 | 10 of 10 |
| `textinput.probe` | 3 of 10 | 10 of 10 |
| `navigation.probe` | 10 of 10 | 10 of 10 |

The negative files, run once each with the wait: `buttons` 0 passed, 8 failed; `navigation` 0 passed, 5 failed; each failure gives its stated message.

Not run: the iOS simulator. The suites passed there in every earlier run without the wait.

## Test plan

- [x] The table above.
- [x] `go test ./scripts/`: the negative-suite guards accept the changed files.

## Review follow-up

- **The comment on each wait** says the target must be on screen: `wait until ... appears` matches only what is on screen, so the wait needs a screen tall enough to show the screen's last element with an id (measured on a Pixel 6 profile), and on a shorter screen it would time out. The fix in the agent removes the need.
- **An earlier target was tried and measured, and was not enough.** I tried the list's second element with an id (`#wf_elevated_state`, `#wf_checkbox_state`, `#wf_textfield_state`), which is on screen on any phone. On `Compat-Pixel-API35`: `buttons` 10 of 10, `selection` 10 of 10, but `textinput` **8 of 10**. One failure listed the visible texts as only the first two items (`"Plain text"`, `"Plain: (empty)"`): the screen can be partly built past the first item. So the waits stay on the last element (`buttons` `#wf_long_press_state`, `selection` `#wf_cupertino_switch_state`, `textinput` `#wf_cupertino_state`, `navigation` `#wf_open_message`), which measured 10 of 10 on all four (the table above).
- **Negative files.** Each header says a failure at the shared `wait until` (a timeout) is not the expected failure. I read every failure message after adding the wait; each test fails at its own step:
  - `buttons` (0 passed, 8 failed):
    - N1 `see "Elevated: 2"` not found;
    - N2 `"Press elevated"` is enabled;
    - N3 `"Cannot press"` is disabled;
    - N4 `see "Disabled: 1"` not found;
    - N5 `see "Elevated: 0"` not found;
    - N6 `tap "Press elevatd"`: widget not found, with the full list of visible texts;
    - N7 `see "Hold: tap 0, long 1"` not found;
    - N8 `see "Icon button: 1"` not found.
  - `navigation` (0 passed, 5 failed):
    - N1 `see "Inbox"` not found;
    - N2 `see "Queries: 2"` not found;
    - N3 `see "From: Ada"` not found;
    - N4 `see "From: Ada"` not found;
    - N5 `tap "Serch"`: widget not found.

  None failed at the wait.
- Main is merged in, after AlphaWaveSystems#794.
…ssors list from privacy (AlphaWaveSystems#749)

## Summary

Draft pages, not in effect and not indexed:

- **Subprocessors** (`/subprocessors/`): the providers that process data for the hosted services (Stripe, Cloudflare, Resend), what each is used for and what it receives. Two rows are TODO for the owner to confirm: GitHub Pages (what it receives when a page loads) and GitHub as a possible sign-in or repository-ownership provider.
- **Company details** (`/company/`): a template. The legal name is the one already on the contact page. The registered address, tax ID and registration details are TODO fields for the owner. No value is invented.
- **Privacy**: one sentence added to "Who processes it for us", linking to the subprocessors page. No other text in the privacy, terms or refund pages changed.

Both draft pages:

- carry `noindex` and are left out of the sitemap, until the lawyer review;
- show "Draft, not yet in effect" under the title, instead of the layout's fixed "Last updated" date (the layout takes an optional `updated` prop; the other legal pages keep their date).

The footer links to these pages come after the lawyer review, not in this change.

## Test plan

- [x] `npm run build` in `website/`: exit 0, 64 pages
- [x] `dist/subprocessors/` and `dist/company/` carry `<meta name="robots" content="noindex">`; neither appears in `sitemap-0.xml`
- [x] Terms and privacy pages keep their existing "Last updated" line
- [ ] Reviewer: check every claim on `/subprocessors/` against the maintainers' records, and confirm every TODO is still a TODO
- [ ] Reviewer: the privacy link opens the subprocessors page at 400px and 1280px, and the draft line shows on both new pages
… to the wait (AlphaWaveSystems#750)

## Summary

`TestWaitRuleIsOffWithoutALimit` failed once under load with `wait 1 seconds timed out after 1s (context deadline exceeded)`. The test built its executor with a **step timeout** of 1 s and then ran `wait 1 seconds`, so the wait raced the step's own deadline. That deadline is not the test limit (`test_timeout`) the test is about.

`TestWaitBelowTheLimitStillWaits` had the same race (1 s step timeout, 1 s wait, limit 2 s), so it gets the same fix.

Both tests now use a step timeout of 30 s (`waitStepTimeout`), far above the wait. Neither test changes its meaning:

- `TestWaitRuleIsOffWithoutALimit`: with no limit, a 1 s wait runs and is not refused.
- `TestWaitBelowTheLimitStillWaits`: with a 2 s limit, a 1 s wait runs for its full second.

No sleep was added and no product code changed. Test-only, so no CHANGELOG entry.

## Load runs

The command was `go test -race -count=50 -cpu 1,4 -run <tests> ./internal/runner/`, run with one `yes > /dev/null` per CPU (18 processes) for the whole run, on macOS (darwin/arm64).

| | Tests | Runs | Failures | Result |
|---|---|---|---|---|
| Before (origin/main 5cc9d8d) | `TestWaitRuleIsOffWithoutALimit` | 100 | 1: `line 2: wait 1 seconds timed out after 1s (context deadline exceeded)` | FAIL, 101.2 s |
| After | `TestWaitRuleIsOffWithoutALimit`, `TestWaitBelowTheLimitStillWaits` | 200 | 0 | ok, 206.1 s |

## Mutation check

Each mutant was applied to `runWait` in `internal/runner/executor.go`, both tests were run, and the file was restored byte for byte.

| Broken rule | Result |
|---|---|
| The wait rule is on without a limit: `e.testLimit > 0 && d >= e.testLimit` becomes `d >= e.testLimit` | killed by `TestWaitRuleIsOffWithoutALimit` |
| A wait below the limit is refused: the condition becomes `2*d >= e.testLimit` | killed by `TestWaitBelowTheLimitStillWaits` |

## Same pattern elsewhere in `internal/runner` (listed, not changed)

I searched for a wait of N against a step timeout or limit of N in the runner tests.

- `TestWaitBelowTheLimitStillWaits`: same race, fixed here.
- `TestWaitAtOrAboveTheLimitFailsAtOnce`: 1 s step timeout, but the 2 s wait is refused before it starts. It asserts that the refusal takes less than 500 ms. That is a real-clock upper bound and the only timing risk left there. It passed in every run above.
- `TestWaitAtTheLimitThroughARunIsAPlainFailure`: limit 1 s, wait 1 s, refused on purpose, nothing waits. No race.
- `TestAfterEachWaitRunsToItsEndAndIsNotRefused` and `TestOnFailureWaitRunsInsideTheCleanupBudget`: 3 s waits against limits of 2 s and 1 s, which is deliberate. Their step timeout is 30 s (`newTimeoutRunner`). No race.
- `TestHarnessLanesEachHaveTheirOwnLimit` and `TestHarnessRetryWorstCaseIsRetriesPlusOneLimits`: a 1 s limit against a slow fake tap, which is deliberate. Their bounds are checked by a separate allowance.
- The `dryrun_test.go` recipes with `wait 1 seconds` run against a 5 s step timeout. No race.

A wider search of `internal/` for timing-fragile tests (sleeps, real clocks) follows as its own PR.

## Test plan

- [x] Before and after load runs (table above)
- [x] Mutation check (table above)
- [x] `go test -count=1 ./internal/runner/` passes
- [x] `gofmt` clean
…) answers no unseen in the window (AlphaWaveSystems#760)

## Summary
Found in the native-window check: with unsaved changes, clicking another file did nothing. The only `confirm()` in the frontend (`openProbeFile`, "Discard unsaved changes?") is not shown by the window's webview and answers no, so the click was swallowed. (Playwright's headless browser shows native dialogs, which is why the browser specs never saw it.)

- New `discard-dialog.ts` and a card in `index.html`, with the clear-data question's safe defaults: "Keep editing" is focused, Escape is a no, Enter on "Discard changes" does nothing (click or Space says yes), a click on the dark area is not an answer, Tab stays inside, one question at a time.
- `goto-line` spec gl-03 now drives the in-page dialog (and fails if a native dialog appears) instead of accepting a native one: Escape, Enter-on-Discard (nothing), Keep editing, then Discard.
- A node test fails on any `confirm(`, `alert(` or `prompt(` in `studio/frontend/src` (it ignores declarations such as `deps.confirm`, comments and strings); reintroducing the native call fails it (checked).

I have not seen the native confirm fail in the real window myself; the report comes from the window check. The in-page dialog is correct either way.

## Test plan
- [x] `npm run test:confirm` (incl. the new test), browser `goto-line` specs (8 passed)
- [x] mutant: the native `confirm(` back in `main.ts` is caught
- [x] disclosure scan
…licked (the Disconnect click in the window check) (AlphaWaveSystems#761)

## Summary
Test-only. The window check reported that a click on Disconnect left the clear-data dialog open. It is not a bug in `Disconnect`: `App.Disconnect()` does say no to the open question and closes the dialog (`TestDisconnectDeniesAPendingQuestionAndClosesTheDialog`). The click never reaches the button: the dialog is modal, its overlay covers the page, and a click on the dark area is by design not an answer (cd-06, cd-07). So the dialog stays until Cancel, Escape or Clear data answers it.

This adds cd-13: while the question is open, the Connect/Disconnect button is covered by the overlay (checked with `elementFromPoint`), a click on it makes no `Disconnect` call and is not an answer, and Escape still says no. A mutant that makes the overlay ignore the pointer is caught.

Already covered at DOM level, no change: Enter on Clear data does nothing (cd-03), and the 500 ms dead time (cd-08).

If Disconnect should work while a question is open, that is a design change (the dialog would have to answer no for the person); this PR does not make it.

## Test plan
- [x] browser confirm-dialog specs (11 passed); mutant caught
- [x] disclosure scan
…aits, and leaves an unchanged list alone (AlphaWaveSystems#762)

## Summary
From the native-window check: the first selection in the device dropdown after a fresh launch was ignored; the second worked.

Reproduced in the browser (spec `device-picker`): `refreshDevices` cleared the picker, then awaited `DeviceListNote()` (it looks for adb and can take a moment), and only then refilled the options, although a comment in the function says the list is rebuilt in one synchronous step. dp-01 (the picker keeps its options while the note is awaited) and dp-02 (a refresh that finds the same devices keeps the same options and the pick) failed on main. A native dropdown that is open at that moment has its options replaced and loses the pick, which fits the report.

- The note is read first; the list is then replaced in one synchronous step (`previous` read at that moment, so a pick made while the refresh was in flight survives).
- A refresh that finds the same devices (id, label, booted) does not touch the picker at all.
- A stale refresh that was overtaken while the note was read does nothing.
- dp-03 keeps the existing behaviour: a changed list rebuilds and keeps the pick when its device is still there; a gone pick selects nothing and disables Connect.

Limit: I have not seen the native popup lose a pick in the real window; the cause is read from the code and the emptied picker is reproduced, so this may not be the whole story. If the first selection is still ignored in the window after this, the next place to look is the start-up order of the two refreshes.

## Test plan
- [x] whole browser suite (dp-01..03 pass, they failed on main for dp-01 and dp-02); mutant `rebuild always` is caught
- [x] disclosure scan
AlphaWaveSystems#763)

## Summary
From the window check (after a restart, Record then Stop gave only two steps and no `test "recorded flow"` header). Not a restart problem: the header is added when the recording **starts** (`btn-record`, `main.ts`), and **stopping** replaced the whole editor with what `StopRecording` returned, which is the recorded steps alone. So every Studio recording lost its `test` block and `open the app` line, leaving steps outside any test. (`probe record` writes the block; Studio's stop did not.)

- New pure `recording-script.ts` (`recordingHeader`, `recordedScript`): stop puts the steps under the header the recording started with; no steps leaves the header alone.
- Node tests (`test:recording`, added to `studio-ci.yml` and `ci-local.sh`): one `test` block, steps under it, indentation kept, blank edges dropped, no-step cases.
- This is a design reading, not a decision: the header is kept at stop rather than moved to the save step, so the editor always shows a runnable file.

The real recording path (Stop in the window with a device) was not run here; the function is what the stop handler now calls.

## Test plan
- [x] `npm run test:recording` (4 pass); frontend build
- [x] disclosure scan
…AlphaWaveSystems#755)

## Summary
`TestTooManyValuesStopTheSave` failed once under full parallel load on a 3-second wall-clock assertion, and `TestCardSearchHasNoSizeLimit` had the same kind of limit. Both now check what they were after, linear work, by counting allocations, which do not depend on how busy the machine is: a body with twice the digit groups may allocate at most 2.5 times as much, and a megabyte of one digit run allocates a handful of times. The functional assertions are unchanged. A third test shows the check fails on superlinear allocation and passes on linear.

Limit, stated plainly: an allocation count does not see a loop that is slow without allocating. A quadratic loop of that kind would still hit the test binary's own timeout rather than a tight limit.

## Mutants
Adding an allocation inside the group loop that grows with the number of groups (`len(groups)/1000` per group) is killed (1.3M allocations for 50,000 groups against 5.1M for 100,000). An earlier version of that mutant survived because the compiler kept its allocation on the stack; it had to escape to the heap to count, which is also why the self-test stores into a sink.

## Test plan
- [x] `go test -race -count=3` on the three tests
- [x] mutant as above
- [x] disclosure scan
… ways it wrote more than one step (AlphaWaveSystems#757)

## Summary
A coverage-guided fuzz test of the recorder's mapping from an event to a ProbeScript line (`FuzzStep`, new in `internal/scriptgen`) found four ways one event could be written as a line that reads back as more than one step, or as the wrong one. Each is fixed here with a regression test, and the inputs that found them are committed under `testdata/fuzz/FuzzStep` so they run with every plain `go test`.

1. **Direction**: a swipe or scroll direction was any cleaned word, so `up steps: 1 tap "x"` added steps to the same line. Now up, down, left or right (any case); anything else is a comment naming the action only.
2. **Ids**: an id was written as one word if it could be held, but the lexer reads `#id` as a letter or underscore then letters, digits and underscores. `tap #login-button` read as the id `login` plus more words. Now only that shape is written; others fall back to the next lookup, then `the element`.
3. **Widget types**: a type was written after `the` as any holdable text (`the Foo" bar`, `the 0`, `the f$000`, `the field` and `the SAve`, which are words of the grammar). Now a capital or underscore, then letters, digits and underscores.
4. **Typing into a widget type**: `type "x" into the TextField` is not a form the language has (it reads as two steps, losing the target). It is now written as `type "x"` into the focused field.

Last line of defence: every line is read back with the real parser before it is written; a line that is not exactly one step becomes a comment that names the action. (SAve was caught by the fuzzer, not by the rules above.)

`FuzzSaveStep` (Save as step, already existing) gains two properties: the saved lines read back as exactly one step, and the names to fill are plain upper-case names. Both fuzz tests document how to fuzz for longer, and that a failing input is committed with its fix.

Fuzzed with no failure after the fixes: `FuzzStep` 4 minutes (43 million executions), `FuzzSaveStep` 3 minutes (5.9 million).

## Behaviour change
An id with a hyphen or a dot is no longer written as a truncated id; the recording falls back to the element's text (before, it was a different lookup at replay). Listed in the CHANGELOG.

## Mutants
Direction accepts any word, a wider direction list, selector id only holdable, flat id only holdable, type name only holdable, type name may start lower-case, type into a widget type, no read-back gate: all killed.

## Test plan
- [x] `go test -race ./internal/scriptgen ./internal/cli`; the Studio record/step tests
- [x] fuzz runs as above; mutants as above
- [x] disclosure scan
…d the entry must agree with the code (AlphaWaveSystems#751)

## Summary
Test-only plus one data file. Every exported `App` method is callable from the window and, in the headless build, from a page script with the bridge token, so adding one is a decision. The decision table already existed in the test as a Go map with a category; it is now `studio/bound_methods.json`, the one place decisions are written, with one entry per method:

- `category`, `does` (one sentence), `callers` (window, bridge, automation), `touches` (files, devices, network, keychain) and `confirm` (none, asks, answers, native-dialog).

`bound_methods_test.go` reads the file (the other tests use the same data) and fails:
- for a new method with no entry, and the message prints the entry to add;
- for an entry whose method no longer exists;
- when an entry contradicts the code: `callers` against the headless bridge's block list and the automation endpoint's method set, a secret that touches no keychain, a pure method that touches something, a run (`RunFile*`) that does not ask, a window-only preference that is not native-dialog, unknown values, a duplicate entry.

## Mutants
Run against the real code and file: a new method with no entry, an entry removed, a stale entry, a secret whose touches were emptied, a run whose confirm was set to none: all killed. A second test runs the check on 12 deliberately wrong inputs (including the message naming the method and the entry to add).

Writing the 67 entries meant stating what each touches, and one was wrong in my first pass (`CheckReplaceLine` reads nothing from disk), which the check caught. No production code changes.

## Test plan
- [x] `go test -race ./studio` (whole package)
- [x] mutants as above
- [x] disclosure scan
…te path outside the repository (AlphaWaveSystems#772)

## Summary

A `probe.yaml` belongs to the repository it sits in, and `tools.adb` and `tools.flutter` in it name a program. Before this change, `probe test` and `probe doctor` used those values as given, so a repository could make `probe test` run a binary it carries. This change makes the CLI apply the rule Studio already used for `tools.adb`.

**On main:**
- `internal/cli/test.go`: the parallel path (around line 553) and the single-device path (around line 923) put `cfg.Tools.ADB` and `cfg.Tools.Flutter` into `device.ToolPaths` unchecked.
- `internal/cli/doctor.go`: the flutter and adb checks look those values up, and doctor's device list runs them.
- Studio enforced the rule in `studio/adb_tools.go` `workspaceADB`, as documented in `tools/studio.md`.

## The change

- **`internal/toolpath`** (new): Studio's rule, moved out of Studio and generalized to `flutter`. A path passes when all of these hold:
  - it is an absolute path to a regular, executable file with the tool's name: `adb`, or `adb.exe` on Windows; `flutter`, or `flutter.bat` or `flutter.exe` on Windows;
  - it is outside the repository of the `probe.yaml`: the folder above it with a `.git` (a directory or a file, so worktrees and submodules count), or with none, outside the `probe.yaml`'s folder;
  - symlinks are resolved first, and both the given name and the resolved name are checked.

  A relative path is never resolved.
- **CLI.** `configTool` and `runToolPaths` (`internal/cli/config_tools.go`) are used by both `probe test` paths and by `probe doctor`.
  - A refused path stops `probe test` with a message that names the key and the file, gives the reason, and says the way out: `tools.adb in /…/probe.yaml is not used: it is inside the repository of this probe.yaml. Set it to the full path of adb outside this repository, remove it to use the one on PATH, or pass --adb`.
  - `probe doctor` reports the same message as a `fail` check, and its device list uses only a passing path.
  - **`--adb` and `--flutter` are used as given**, since the person typed them. A flag for one tool does not excuse a bad `tools.` value for the other.
- **`config.Config.Source`** (`yaml:"-"`, never read from the file) records the absolute path of the `probe.yaml` a config came from, so the rule knows which repository the file belongs to.
- **Studio** calls `toolpath.Check` and keeps its own wording through a small replacer. Its messages are unchanged, and its existing tests pass unmodified.

**Breaking:** a `probe.yaml` with a relative `tools:` path, or one inside its own repository, now stops `probe test`. The escape, stated in the CHANGELOG and the docs: pass `--adb` or `--flutter`, or move the binary outside the repository and give its absolute path.

**Docs:**
- `advanced/configuration.md`: the `tools` table and the rule.
- `platform/android.md`: the `tools.adb` example.
- The root README's config example.
- The `probe init` template comments.
- The CHANGELOG, under Changed, marked breaking.

## Tests

- **`internal/toolpath/toolpath_test.go`:**
  - `Names` per tool and system;
  - `Check` passes a tool outside the repository and an empty value;
  - `Check` refuses a relative path, a missing file, another program's name, a link to another program's name, a non-executable file, a directory, a tool elsewhere in the repository, one in the project folder, and a link from outside into the repository;
  - with no repository, the folder is the boundary;
  - a `.git` file marks a repository;
  - `IsExecutableFile`.
- **`internal/cli/config_tools_test.go`:**
  - `LoadFile` records `Source`, and records none without a file;
  - the outside path is used, and the in-repository path is refused with the key, the file, the reason and `--adb`;
  - a relative `tools.flutter` is refused;
  - flags win as typed, and a flag for adb does not excuse `tools.flutter`;
  - no tools section means PATH;
  - doctor fails both refused checks;
  - a source check that `test.go` and `doctor.go` never read `cfg.Tools.` directly.

## Mutation check

Each mutant was applied, the tests were run (Studio's against Studio's own suite), and the file was restored byte for byte. All 18 were killed. One first left a variable unused and did not compile; it was rewritten, and that run is the one counted.

| Mutant | Result |
|---|---|
| a relative path is accepted | killed |
| symlinks are not resolved | killed |
| the name is not checked | killed |
| the resolved name is not checked | killed |
| a non-executable file is accepted | killed |
| the repository is not the boundary | killed |
| no folder boundary without a repository | killed |
| a `.git` file is not a repository | killed |
| Windows flutter is not `flutter.bat` | killed |
| a directory counts as executable on Windows | killed |
| `configTool` does not check | killed |
| `LoadFile` does not record the source | killed |
| a flag does not win | killed |
| `probe test` (parallel) uses `cfg.Tools` as it is | killed |
| doctor does not fail a refused flutter | killed |
| doctor's device list runs `cfg.Tools` | killed |
| Studio: `workspaceADB` does not check | killed |
| Studio: its wording is lost | killed |

## Not covered

- No run on Windows. The Windows names come from the Flutter SDK's `bin/flutter.bat` and `adb.exe`, and the tests that need execute bits and symlinks are skipped there.
- `gofmt -l` flags `internal/config/config.go` on main already: field alignment, pre-existing. This change adds no new difference.

## Test plan

- [x] `go test ./internal/cli/ ./internal/config/ ./internal/toolpath/ ./internal/device/` passes.
- [x] `go test .` in `studio/` passes (with a placeholder `frontend/dist`, not committed).
- [x] `go vet` passes on the changed packages and Studio.
- [x] `npm run build` in `website/` passes (62 pages).
- [x] Mutation check (table above).


## Review follow-up

- **Blocker: folders, not strings.** `Check` compared paths with `filepath.Rel` after `EvalSymlinks`, which doesn't normalize letter case. On APFS, `/x/evil/tools/adb` was "not under" `/x/Evil` and the repository's binary ran. The new `toolpath.Within(folder, p)` walks each folder from the resolved file up to the filesystem root and compares it with the protected folder by `os.SameFile`, so spelling doesn't matter. `TestAnotherSpellingOfTheRepositoryIsStillTheRepository` creates `Evil/Tools/adb` and checks the lowercase path; it skips where the file system is case-sensitive, and it ran here (APFS). Studio's `workspaceADB` calls `toolpath.Check`, so it gets the fix too. `go test ./studio/...` passes.
- **(3) Nested repositories:** `RepoRoots` returns every folder up to the filesystem root that holds a `.git`, and the tool must be outside all of them (`TestTheOuterRepositoryIsProtectedToo`).
- **(4) A symlinked `probe.yaml`:** `configTool` checks the link's folder and the real file's folder (`toolpath.CheckIn`); tests at both levels.
- **(2) No `.git` at all** (Docker `COPY`, `git archive`): only the `probe.yaml`'s own folder is protected. This is now stated prominently in `advanced/configuration.md`, `platform/android.md` and the CHANGELOG, with the advice to keep the `.git` or pass the flags. I didn't add a refusal of the parent folder for an `e2e/` or `tests/` subfolder: guessing a project root from folder names would refuse legitimate layouts.
- **(5) Doctor's wording:** `configTool` and `runToolPaths` take `withFlag`. `probe test` says "or pass --adb"; doctor's message doesn't offer a flag it doesn't have.
- **(6) Exit code:** `TestProbeTestExitsNonZeroOnARefusedToolsPath` runs `probe test` through the root command and checks the error names `tools.adb` and `ExitCode(err) != 0`. It resets `--config` afterwards: without that, four later `port_follow` tests in the package inherited its `probe.yaml` and failed. That was found and fixed while doing this.
- **(1) A wider source guard:** every non-test Go file under `internal/`, `studio/` and `cmd/` that reads `.Tools.ADB` or `.Tools.Flutter` must be in an allowlist of the two checked readers (`internal/cli/config_tools.go`, `studio/app.go`). The test also fails if it finds fewer readers than the allowlist.
- **Mutants:** 6 of 6 killed:
  - `Within` comparing spelling;
  - only the innermost repository;
  - `CheckIn` checking only the first folder;
  - the real folder of a symlinked yaml ignored;
  - doctor offering `--adb`;
  - no-repository folder not protected.
- **Gate:** `go test ./internal/toolpath/ ./internal/cli/` and `go test ./studio/...` pass; `staticcheck`, and `GOOS=windows go vet` for `./internal/...` and `studio`, are clean. Main is merged in.
…veSystems#797)

## Summary
Two web specs failed on main after the in-page discard dialog merged (the hosted Studio CI is off, so it was not seen): cd-01 found two `.confirm-card` elements (the discard card uses the same class), and gl-03 pressed Tab to the discard button before it was armed (a disabled button cannot take the focus). cd-01 now scopes to `#confirm-overlay`, gl-03 waits for the button to be enabled. Spec-only change.

## Test plan
- [x] Web suite (no device): 194 passed.
…d for the terminal's shell (AlphaWaveSystems#773)

## Summary

Three follow-ups from the review of AlphaWaveSystems#769, in the VS Code extension's binary resolution.

1. **A behavior test for the real regular-file check.** `isFile` in `config.ts` was checked only through its source text, so the reviewer's mutant `isFile() || true` survived. It is now `isRegularFile` in the pure `toolPath.ts`, and `config.ts` passes it to the resolver. It is tested on real files: a file, a directory, a missing path, a link to a directory and a link to a file.
2. **No fallback to a bare name.** On macOS and Linux, when `probe` was on no absolute folder of PATH, the extension ran the bare name `probe`. That name could only be found through an empty or relative PATH entry (`::`, `.`, `bin`), and those resolve against the working directory, which is the workspace. Not found is now an error on every system, as it already was on Windows. `listDevices` and lint-on-save still return nothing instead of throwing (AlphaWaveSystems#769), and the commands show the message.
3. **Terminal quoting of the command path.** A command path with a space (`C:\Program Files\…`) broke in the terminal. `commandWord` (pure, `toolPath.ts`) quotes the command for the shell the terminal runs, taken from `vscode.env.shell` (per the API, "the detected default shell for the extension host"), or refuses a path it cannot type safely. A path made only of safe characters is typed as it is.

   | Shell | What is typed |
   |---|---|
   | bash, sh, zsh, dash, ksh (also Git Bash or WSL on Windows) | POSIX single quotes |
   | PowerShell | `& '…'`, with `'`, `‘` and `’` doubled. [about_Quoting_Rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules) says PowerShell treats the typographic quotes "as normal quotation marks" and that a quote inside a single-quoted string is doubled. A path with `‚` or `‛` (not listed on that page) is **refused**: doubling a non-quote would change the path, and not doubling a quote would end the string. |
   | cmd.exe | `"…"`. A path with `%` (or `"`) is **refused**: `%NAME%` expands inside double quotes, and the [cmd reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd) documents no way to escape it on a command line. |
   | any other shell (fish, nu, csh, pwsh on macOS or Linux, or none detected) | A path with a shell metacharacter (`& \| ; < > ^ \` $ ( ) ' " % !`, a newline, and on macOS and Linux a backslash) is **refused**. Otherwise the path is single-quoted on macOS and Linux, and typed as it is on Windows (a space only). |

   A refusal is an error that says what to do: install it in a folder without that character, or use another terminal shell. **This covers the command word only. The arguments are still quoted the POSIX way on every system**; that is a separate fix.

The README and the unreleased CHANGELOG entry of AlphaWaveSystems#769 now describe both changes: not found is an error on every system, and the command is quoted (or refused) per shell. The VS Code docs page describes the not-found rule; it makes no quoting claim.

## Tests

`vscode/src/test/toolPath.test.ts`:
- `isRegularFile` on real files and symlinks (the symlinks are skipped on Windows);
- not found is an error with no platform argument;
- `commandWord` per shell: PowerShell with `'`, `‘` and `’` doubled (including a crafted `C:\x’; calc; ‘\probe.exe`, which stays one string, and `O’Brien`), and `‚` `‛` refused; cmd.exe refusing `%` and keeping `&` inside the quotes; unknown Windows and POSIX shells refusing each metacharacter and quoting a plain space;
- **a real-shell test:** for each of bash, sh, zsh, dash and ksh installed (all five ran on macOS), seven hostile paths (a `'` with `; touch PWNED;`, `$(…)`, backticks, a newline, `" ; | &`, bidi and zero-width characters) are typed through `commandWord` and printed back by the shell. Each comes back as one word, byte for byte, and `PWNED` is never created;
- `quotePosix` with a `'`;
- the source checks updated: `config.ts` passes `isRegularFile`, and the terminal uses `commandWord(command, process.platform, vscode.env.shell)`.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 18 were killed: 9 for the first version, and 9 for the per-shell rules after the review.

| Mutant | Result |
|---|---|
| `isRegularFile` accepts anything (`\|\| true`) | killed |
| `isRegularFile` accepts a directory | killed |
| not found falls back to the bare name | killed |
| PowerShell without the call operator | killed |
| cmd.exe gets the path as it is | killed |
| Git Bash is not quoted | killed |
| the POSIX command is not quoted | killed |
| a single quote is not escaped | killed |
| the terminal ignores `commandWord` | killed |
| PowerShell: `’` not doubled | killed |
| PowerShell: `‘` not doubled | killed |
| PowerShell: U+201A not refused | killed |
| cmd.exe: `%` not refused | killed |
| an unknown shell gets a metacharacter | killed |
| POSIX: a backslash not refused under an unknown shell | killed |
| every shell treated as POSIX | killed |
| dash not a verified shell | killed |
| `quotePosix` does not escape a quote | killed |

## Not covered

- No run in a real Windows terminal. The PowerShell and cmd.exe quoting follows Microsoft's pages, cited above, and is tested as text. The POSIX quoting ran in real shells.
- The arguments are still quoted the POSIX way on every system, as before this change. An argument with a space typed into a cmd.exe or PowerShell terminal is a separate fix.

## Test plan

- [x] `npm test` in `vscode/` passes: 79 tests.
- [x] `npm run compile` passes.
- [x] Mutation check (table above).


## Review follow-up

- **Control characters are refused, for every shell, in the command and in every argument.** A line-editing shell acts on a control character while the text is typed: in bash, ^U deletes back to the start of the line, ^A moves to it and ^C cancels it, so a quoted path could lose its opening quote and run what follows (found in review with a real pty). `commandWord` now refuses U+0000 to U+001F and U+007F first, on every platform and shell. The arguments go through `quoteArg` in `toolPath.ts` (`shellEscape` in `probeTerminal.ts` now calls it), which refuses them too. This predates the PR, since the arguments had it.
- **The backslash is typed unquoted only on Windows.** The safe-characters shortcut excluded nothing, so `/x/back\slash/probe` was typed bare on POSIX and the shell dropped the backslash. Now on macOS and Linux it is single-quoted for bash, sh, zsh, dash, ksh and WSL, and refused for any other shell. The earlier claim is now true: `commandWord('/a\\b/p', 'linux', '/bin/fish')` throws.
- **PowerShell on macOS and Linux** runs a single-quoted path as a string, not a command, so only a path of plain characters is typed there; a space, `'`, `‘` or `’` is refused with a message.
- **Tests:**
  - control characters (NUL, ^A, ^C, tab, LF, CR, ^U, ESC, U+001F, DEL) refused for 8 shell and platform pairs and for arguments;
  - the backslash quoted or refused on POSIX;
  - `wsl` on Windows (the earlier survivor);
  - pwsh on POSIX.

  The real-shell test of bash, sh, zsh, dash and ksh now uses a plain backslash path instead of the backslash-newline one, which is refused now.
- **Mutants:** 6 of 6 killed:
  - control characters not refused, in the command;
  - control characters not refused, in the arguments;
  - the backslash safe on POSIX;
  - pwsh on POSIX typing any path;
  - `wsl` not a POSIX shell;
  - `CONTROL` missing U+007F.
- `npm test`: 83 passed, 0 failed. Main is merged in.

## Second review follow-up

- **C1 control characters (U+0080 to U+009F) are refused too**, in the command and in every argument. Under a single-byte locale (`LC_ALL=C`), readline reads a C1 character's second byte as a meta key: U+0092 is revert-line and U+0088 is M-Backspace, so the opening quote could be stripped (found in review in a real bash). `CONTROL` is now `[\^@-\^_\u007f-\^_]`. The tests add U+0080, U+0085, U+0088, U+0092 and U+009F for every shell and platform pair and for arguments.
- **The refusal message escapes** DEL, C1, U+2028 and U+2029 as `\uXXXX`, so the message carries none of them. There's a test for this. U+2028/U+2029 are still allowed in a path: typed quoted, they did nothing.
- Mutants: 4 of 4 killed (C1 missing, the message not escaping, and the two refusals again). `npm test`: 84 passed, 0 failed.
… wording, run gate evidence (AlphaWaveSystems#801)

## Summary
Hardening of the guard that checks what each window-callable Studio method touches (`studio/bound_methods.json`), from the review of the first version:
- The walk counts any use of a sink package's name again (a function value such as `runDoctor = ai.Doctor`, a package client such as `http.DefaultClient`, a call), and websocket and the file helpers it had missed (`toolpath`) are sinks. A test of the walk on small sources has a case for each way it used to slip, and for what must not count (a constant, a type, a function nobody calls).
- The file says exactly what the check sees and what it cannot see; the CHANGELOG title no longer says "can no longer understate".
- `previewed` is defined by what Go compares; `ExplainPreviewed` only compares a destination label, and its decision says so.
- The run methods' `asks` is tied to the run path (`executeRun` binds the confirmations to the run and runs with the connection's device context) and to the tests that show a clear step asking, which the guard requires to exist.
- The comment of the linear-work test says what it catches (allocation-heavy regressions deterministically; a pure-CPU regression only past 30 s).

## Test plan
- [x] Mutants killed: the narrower walk (9 failures), executeRun without `setConfirmRun`.
- [x] `go test ./studio/...`, staticcheck, `GOOS=windows go vet`.
…ative variants and matrix results (AlphaWaveSystems#798)

## Summary

The Lists and scrolling widget family: a fixture screen, a suite, negative variants, and the matrix cells and findings, in one pull request (the second of three families; the next is Dialogs and sheets).

- **Screen** (`PROBE_FIXTURE_WIDGETS=lists`, `native-test-apps/flutter/lib/widget_families.dart`): a lazy `ListView.builder` of 200 rows, with a page each for a `GridView.count` (60 cells), a `CustomScrollView` with a `SliverList` (200 items), a `SingleChildScrollView` (40 lines and a button), and tiles (`Card` holding a `ListTile` with a title, a subtitle and a trailing icon; a `CupertinoListTile`). Every element has a `Semantics` identifier and a `ValueKey`, and every state is also shown as text.
- **Suite** `probe-tests/widgets/lists.probe`, 11 tests, and **negative variants** `probe-tests/negative/lists.probe.expect-fail`, 9 tests that must fail, each with its expected message in a `# Expected:` comment (covered by the guard of AlphaWaveSystems#746).
- **Matrix** (`docs/compat/MATRIX.md`): the family row, a section with a table and findings, the how-it-was-run paragraph; `docs/compat/NEXT.md` items 4 and 5; the fixture README; CHANGELOG.

## Findings (all measured, in the matrix)

- A lazy list, grid or sliver list builds the rows near the top only: `see` and `tap` do not find the others until `scroll down until` builds them. `scroll down until` a target that does not exist ends with "not found after scrolling" and does not run on.
- A `SingleChildScrollView` builds every child: `tap "Bottom button"` scrolls to it by itself.
- A text selector takes the first widget that holds the text, so a name that a state text also holds selects the state text: after `tap "Alice"`, `long press "Alice"` lands on `Tapped: Alice`, not on the tile. (My first draft of the suite failed on exactly this; it is now a test.)
- A tile's title is not a container of its tile: `see "Online" in "Alice"` fails; `"Online" below "Alice"` works.
- **A line of a `SingleChildScrollView` that is built but below the fold is not seen** (`see "Line 39"` fails), while `tap "Bottom button"` still scrolls to a built button.
- **`see exactly 1 "<one Text>"` reports "found 2"** on both Flutter versions (a row title, a state text and a button label, each measured): the finder matches both the `Text` and the `RichText` it builds. It is pinned by negative variant N9 (which must be flipped or removed when the agent is fixed) and not fixed here.

## Checked

- Device: emulator-5600, AVD `ProbeWebViewSpike` (Android 15, API 35; the name was read back before each install and run). A build by Flutter 3.44.8 and one by 3.50.0 (the 3.50.0 build in a scratch copy with a private SDK): `lists.probe` **10 of 10** on each; the negative file **0 passed, 9 failed** on each, every test at its own step with the message in its comment. After review edits (a test of a line below the fold, a precondition `don't see "Bottom button"`, quoted messages) and a merge of main: **11 of 11** and **0 of 9** again, on the 3.44.8 build on the same emulator (the 3.50.0 build was not re-run).
- Before the final suite, small diagnostic files measured each behavior above; the failing ones became the findings and negatives.
- `flutter analyze` on the fixture screen: no issues. The new code was formatted in a temporary file (the existing file was not reformatted).
- `make ci-local`: 5 of 5 required checks. Disclosure scan clean. A fresh clone of the branch has the new files, the guard test passes, and its fixture source equals the one that was built and run.

## Not checked / limits

- One device and one Android version; no iOS, no physical device, no TalkBack, no other screen sizes or text scales.
- Not covered by the screen: `PageView`, `Scrollbar`, a horizontal list, two scrollables on one screen, `ListView.separated`, pull to refresh, a list inside a dialog, a list under an open keyboard, scroll by an amount. 
- In some earlier small diagnostic runs the first test failed in `before each test` ("restart the app: reconnect with pre-shared token: agent not reachable within 20s"); it did not happen in the full-suite runs reported here and is under investigation (a follow-up of issue AlphaWaveSystems#793).
- No mutants of the fixture: the 9 negative variants are the check that the positive tests can fail.

## Test plan

- [x] `lists.probe` 10 of 10 on a Flutter 3.44.8 build and a 3.50.0 build (emulator-5600); 11 of 11 on 3.44.8 after the review edits
- [x] negative file 0 of 9 passing on both builds, each at its own step
- [x] `make ci-local` 5 of 5, scan clean, fresh clone checked
- [ ] Review of every matrix cell against the suite
…ts a Text twice (issue AlphaWaveSystems#800) (AlphaWaveSystems#806)

## Summary

Fixes AlphaWaveSystems#800: `see exactly N "<text>"` counted an ordinary `Text` twice.

**Cause.** In `probe_agent/lib/src/finder.dart`, `_matchesText` matches a `Text` by its `data`, and also the `RichText` that `Text` builds internally, by `toPlainText()`. Both elements were returned for one visible text, so:
- `see exactly 1` found 2;
- an ordinal (`2nd "Row"`) could pick the first `Text`'s own inner `RichText`;
- a text inside a container (`see "x" in "y"`) was doubled.

**Fix.** `_oncePerText` runs on the matches of the text search and of the container search. It leaves out a `RichText` whose nearest `Text` above it, the one that built it, is also in the matches. The `Text` stays; its render object is the same paragraph. These are kept:
- a `RichText` of its own;
- a `Text.rich`, which matches only through its `RichText`;
- a `Text` and a separate `Text.rich` with the same words (two texts, two matches).

**Breaking** for a suite that asserted the doubled count: `see exactly 2` for one `Text` now fails.

## Tests

`probe_agent/test/finder_count_test.dart` (9 tests):
- a plain `Text` is one match, and so is a part of it;
- a `Text.rich`, a `RichText` and a button's label are each one match;
- two equal `Text`s are 2;
- `2nd "Row"` is the second `Text`, not the first one's `RichText`;
- in a container, the `Text` and its `RichText` are one match;
- a `Text` and a `Text.rich` with the same words are 2.

Five of these failed on `main`'s code: a `Text` 2, its part 2, a button 2, two `Text`s 4, and the ordinal picking the inner one.

`probe_agent/test/executor_see_exactly_test.dart` (3 tests): `see exactly 1` on one `Text` passes and `exactly 2` fails with "found 1"; two equal `Text`s pass `exactly 2`; a button's label counts once.

All 261 `probe_agent` tests pass.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. All 4 were killed. Two survived at first, because the container test found nothing and a lone `Text.rich` never reached the check; the two tests above were added for them.

| Mutant | Result |
|---|---|
| the text search is not deduped | killed |
| the container search is not deduped | killed |
| every `RichText` is dropped | killed |
| the `Text` is dropped instead of its `RichText` | killed |

## Device check

`Compat-Pixel-API35` (Android 15, API 35, `emulator-5590`) and `Compat-iPhone` (iPhone 17 Pro, iOS 26.5, UDID `A57AEE67-3473-4C20-BE25-8847C2A9D6BE`); Flutter 3.44.8, the `buttons` screen. Three tests: `see exactly 1 "Press elevated"`, `see exactly 1 "Elevated: 0"`, and `see exactly 2 "Press elevated"` (which must fail):

| Agent | `exactly 1` (label) | `exactly 1` (state text) | `exactly 2` |
|---|---|---|---|
| without this fix (Android) | **fails: "found 2"** | **fails: "found 2"** | passes |
| this PR (Android) | passes | passes | fails: "found 1" |
| this PR (iOS) | passes | passes | fails: "found 1" |

## Docs

- `probescript/dictionary.md`: what `see exactly` counts.
- `tools/agent.md`: "one visible text is one match".
- `docs/compat/MATRIX.md`: the Lists finding is fixed in the next `probe_agent` release.
- `CHANGELOG.md` and `probe_agent/CHANGELOG.md`, Fixed, marked breaking.

**The Lists negative variant N9** (`probe-tests/negative/lists.probe.expect-fail`) pins the 0.27.0 behaviour. It will pass once an agent with this fix runs, so the Lists screen's owner updates it when this lands; that's coordinated.

No version bump: it happens at release time, per the checklist.

## Test plan

- [x] `flutter test` in `probe_agent`: 261 passed.
- [x] `go test ./scripts/`: the negative-suite guards pass.
- [x] Device check above, on both named devices.

## Review follow-up

- **Breaking, ordinals too.** Both CHANGELOGs and `tools/agent.md` now also say that an ordinal which landed on the inner paragraph of a single `Text` (`tap 2nd "8"` where only one "8" is shown) now finds nothing; write `tap "8"`.
- **The example suites** `tests/login.probe`, `tests/cart.probe` and `tests/recipes/login.probe` use `tap 2nd "<digit>"` on a keypad. They belong to an old example app (an activation-code keypad) that isn't in this repository. No workflow, gate or docs page runs them; the READMEs' `tests/login.probe` example doesn't use `2nd`. Whether they relied on the quirk depends on that app's screen:
  - if a digit is shown once, the old `2nd` found that key's own inner paragraph, and it now fails;
  - if a display also shows the digit after a tap, the old `2nd` found the *display's* inner paragraph (a wrong target), and it's now the key.

  I couldn't run them, so I left them unchanged rather than guess, and flag them here.
- **The mixed-screen test** (a `Text` and a `Text.rich` with the same words, 2 matches) is marked in a comment as the key guard: a rule that dropped every `RichText`, or none, fails it.
- **N9 of `lists.probe.expect-fail`:** its owner flips it once this merges.
…veSystems#799)

## Summary
The line about the app's build in the Device pane had no style of its own and ran over the boundary between the editor and the device view at some window sizes. It now wraps inside the pane, with a thin rule under it.

## Test plan
- [x] Playwright bv-05 measures that the line is inside the pane and does not reach the editor; it fails without the CSS (checked).
- [x] The other web specs pass; cd-01 and gl-03 fail on main until the spec fix in the sibling PR.
…Systems#796)

## Summary
A click on the error text (and on the suggested-fix and reason rows) under a failing step in Results now opens the step's line, like a click on the row. Text selected to copy it is not a click.

## Test plan
- [x] Playwright gl-07: a drag selection in the error does not move the caret; a click does (line 5).
- [x] Web suite: 190 passed (no-device).
…WaveSystems#802)

## Summary
A Connect to a device whose app was not running showed its reason in a toast and in the status for 2.5 seconds, then the status said "disconnected": a person who looked away saw no reason. The status now says `connection failed: <first line of the reason>` (the full text with its fix hint is the tooltip) until another device is picked or Connect is pressed again. The Wi-Fi connect form is unchanged.

## Test plan
- [x] node test of the line (4 cases), wired into the Studio CI file and ci-local.
- [x] Playwright cf-01 (the reason is still there after 3.5 s; picking another device clears it) and cf-02; cf-01 fails with the old 2.5 s reset put back (checked).
- [x] Web suite 194 passed apart from two specs that are red on main until the spec-fix PR merges.
…lphaWaveSystems#804)

## Summary
Studio reopens the last workspace at every start, so a Dock launch could never show the empty first-run guidance again. A **✕** next to the folder button (shown while a workspace is open) closes the workspace: the panes go back to the state of a first start, the open file is cleared and the remembered folder is forgotten. Unsaved changes are asked about first (the in-page discard question); closing is refused while a run or a recording is going. `PROBE_STUDIO_WORKSPACE`, when set, still opens its folder at the next start. **By design, the folders named in `PROBE_STUDIO_WORKSPACE` and `PROBE_STUDIO_AUTOMATION_ROOTS` stay reachable by the automation endpoint after Close** (they are the environment's, not the window's); the docs say so. A Go test (`TestAnEmptyWorkspaceReachesNoFolder`) shows that with no such variables nothing of the closed workspace can be read, listed or written, from the window, the bridge or the automation endpoint (they share the roots). Frontend only: it uses the existing `SetWorkspace` with an empty path, so no new bound method.

## Test plan
- [x] Playwright fr-07: Keep editing leaves everything; Discard closes; the guidance and the disabled Run reason come back; no workspace key is left in storage. It fails when the key is not removed (checked).
- [x] Web suite 195 passed (no device); `go test ./studio` ok.
- [x] CHANGELOG and docs/tools/studio.md updated.
…s#811)

## Summary

## Test plan
- [x] `npm run check:probescript` and `npm run test:probescript` pass.
AlphaWaveSystems#812)

## Summary
Follow-ups from the reviews of the failed-connect line and Close workspace:
- the status line keeps a zero-width joiner between letters or emoji (a family emoji, a Persian word), and turns a zero-width space or a direction character into a space;
- the status span is no longer a live region: the toast already announces the failure, so it was announced twice;
- `CloseWorkspace` checks the run slot and the recording flag and makes the change under the run slot's lock and the state lock together, and `claimRun` now reads the workspace inside the same locked step as it takes the slot (it read it before, so a close between the two left a run holding the slot with a closed workspace); its allowlist entry says it does what `SetWorkspace` does with no folder, in memory only (so touches stays empty).

## Test plan
- [x] node tests of the line (joiners kept, a joiner next to a space dropped, ZWSP and direction characters become a space).
- [x] Go: the Close tests pass with `-race`, including a racing test of Close against a run claim that fails on the old `claimRun` (checked) and passes with `-race`.
- [x] `go test ./studio`, staticcheck, `GOOS=windows go vet`.
## Summary
A design, no code, for an "Insert before the step" button on the rule-based "Suggested fix" row (the line `wait until "X" appears`, which belongs before the failed step, so Replace the line does not apply). It lists what is inserted and where, the checks Go makes first (the step must not have moved, nothing stacked twice, the file must parse into the old steps plus one), one undo, and what happens to the results on screen. One open question for the owner at the end.

## Test plan
- [x] Docs only; PR text and diff scanned.
…tension tests for ProbeScript doc changes (AlphaWaveSystems#815)

## Summary

Main is red on two VS Code extension checks: "the generated keyword files are up to date with the docs" and "the generated snippet files are up to date with the docs". AlphaWaveSystems#806 changed the `see exactly` entry in `website/src/content/docs/probescript/dictionary.md` and didn't regenerate the extension's files from it.

- **Regenerated** with `npm run gen:keywords` and `npm run gen:snippets` in `vscode/`. The diff is one line in each file: the `see exactly` snippet description, and the docs hash in `probescriptKeywords.generated.ts`.
- **Why it wasn't caught:** `scripts/ci-local.sh` adds the Studio frontend check to a default run when the change touches the ProbeScript docs. It didn't add the VS Code extension tests, which are made from the same docs, and the hosted workflow only runs for changes under `studio/` and `vscode/`. Both checks are now added for those paths, and the run's note says so. `--all` and `--job` are unchanged.

No CHANGELOG entry: generated files and local CI tooling only, with nothing user-facing.

## Test plan

- [x] `npm test` in `vscode/`: 84 of 84 pass (the two checks fail on main).
- [x] `go test ./scripts/` passes. `ci_local_plan_test.go` now expects both checks, and the note, for each docs input. It expects neither check for other paths, and each check once under `--all` with no note.
- [x] Mutant: adding only the frontend, as before, fails the plan test.
…ize (issue AlphaWaveSystems#793) (AlphaWaveSystems#803)

## Summary

Fixes AlphaWaveSystems#793: a step right after `restart the app` no longer runs on a half-built screen.

### The cause, measured

On an Android 15 emulator, after a relaunch, an app draws its first frames with a **0×0 view** for about 1 to 1.2 s (logged per frame in a temporary build; see AlphaWaveSystems#793). A `ListView` laid out then builds only its first child.

My first version waited while the view was 0×0. **It did not fix the bug:** `buttons.probe` without waits still failed 2 of 10 runs. I instrumented the agent to log every request: **none of 530 requests arrived while the size was 0×0**. The real gap is one step later. `physicalSize` changes the moment the engine reports it, but the widgets are laid out at that size only in the next frame. A request that arrives in between passes a "has a real size" check and still sees the tree laid out at 0×0.

### The change (agent; the CLI only reads a diagnostic)

- **`probe_agent/lib/src/view_ready.dart`** (new):
  - `ProbeAgent.start` calls `ViewReady.instance.attach()`, which registers a persistent frame callback that records the size each frame was laid out at.
  - The view is **ready** when the size of the last laid-out frame equals the view's current, non-empty size. When it isn't, `wait()` waits until it is.
  - **The hot path** is a synchronous check (`isReady`) with no `await`.
  - **Never slow when there's nothing to wait for:** no wait when the app has no view (`views` empty) or is not resumed (paused, hidden, inactive). It stops at once if the app goes to the background during the wait.
  - **The cap** is 2.5 s, measured by a `Timer`, not a stopwatch. After a capped wait, the agent doesn't wait again until the view's metrics change, so there is at most one capped wait per "size unknown" episode.
  - **A resize** (a rotation) waits for at most one frame.
  - **Without `attach`** (an embedder that never calls `start`), the earlier rule applies: a real size is ready.
- **`executor.dart`**: every request first does `if (!ViewReady.instance.isReady) await ViewReady.instance.wait();`, before the request's own work. A step's own waiting (a `wait until`, a scroll) isn't shortened, and the wait isn't counted against it twice: it happens before the step's own deadline starts.
- **`probe.ping`** reports `view_ready_ms`, the wait in ms (0 when none). The capability `waits_for_view_size` is added; the existing names use underscores, like `press_key`. Both are for diagnostics.
- **Go:** `PingResult.ViewReadyMS` is kept raw. `HandshakeResult.ViewReadyMS` accepts only a digits-only integer from 0 to 60000, and is −1 when absent or anything else (null, negative, a fraction, an exponent, a string). `CapabilityWaitsForViewSize` is added. Nothing depends on them.
- **Compatibility:** an older CLI ignores the field and gets the fix. A new CLI with an older agent behaves as before. There's no protocol change.

### Why 2.5 s

The cap stays well under every limit around the handshake:
- the dial timeout: 30 s by default in the CLI, **5 s in Studio**; the HTTP client's ping runs inside it and retries every second;
- the reconnect loop (`ReconnectWithToken`, 2 s between dials, up to the token timeout);
- the keep-alive ping (every 5 s, 2 s write deadline).

The 0×0 phase measured about 1.2 s.

## Tests

`probe_agent/test/view_ready_test.dart` (11 tests):
- a 0×0 view builds part of the list, and `wait` ends once the real size is laid out, with the whole list there;
- **the gap:** the size is reported but no frame laid out yet, so the view isn't ready;
- the wait lasts until a frame is laid out, using `binding.delayed` to advance time without a frame;
- the cap ends the wait, and the same episode doesn't wait again;
- a metrics change starts a new episode;
- a paused app isn't waited for, and going to the background mid-wait ends the wait;
- no view: no wait and no error;
- a rotation waits for one frame;
- without `attach`, the earlier rule applies.

`probe_agent/test/executor_view_ready_test.dart` (3 tests): a ping during 0×0 answers only after the real size, with `view_ready_ms` and the capability; a ping with a real size has `view_ready_ms` 0; **a ping in the gap waits for the frame.**

`internal/probelink/view_ready_ms_test.go`: the field's parsing (12 inputs), decoding with and without the field, and the capability name.

All 263 `probe_agent` tests pass; `executor_ping_test`'s pinned field set now includes `view_ready_ms`.

## Mutation check

Each mutant was applied, the tests were run, and the file was restored byte for byte. 9 of 10 were killed.

| Mutant | Result |
|---|---|
| no views still waits | killed |
| a backgrounded app is waited for | killed |
| the cap is not remembered | killed |
| a metrics change does not start a new episode | killed |
| **a reported size counts as laid out (the gap)** | killed |
| the frame callback records nothing | killed |
| without attach, a real size is not ready | killed |
| the executor does not wait | killed |
| ping without `view_ready_ms` | killed |
| after the frame wait, return without re-checking the laid-out size | **survived (equivalent under the test binding)** |

The survivor: in a widget test, `endOfFrame` always completes a frame laid out at the current size, so the re-check can't fail there. On a device, a frame already under way when the size changed would complete laid out at the old size; the re-check keeps waiting then. It is kept as a guard.

## Device evidence

AVD `Compat-Pixel-API35` (Pixel 6 profile, Android 15, API 35, `emulator-5590`, name read back before each run) and simulator `Compat-iPhone` (iPhone 17 Pro, iOS 26.5, UDID `A57AEE67-3473-4C20-BE25-8847C2A9D6BE`). Flutter 3.44.8. Each run is the merged `buttons.probe` **without** the interim waits of AlphaWaveSystems#795, so `restart the app` before every test.

| Agent | `Compat-Pixel-API35` | `Compat-iPhone` |
|---|---|---|
| `main` | 3 of 10 runs passed (measured twice: 3 of 10 each time) | passed in every run |
| first version (waits while 0×0) | 8 of 10 (2 half-built screens), plus one CLI hang, see below | 5 of 5 |
| **this PR** | **29 of 30** (20 of 20, then 9 of 10 with the machine loaded) | **5 of 5** |
| **this PR, cold boot** (`-no-snapshot-load`) | **10 of 10** with the machine idle; 7 of 10 while my Go and Studio tests loaded the machine, all 3 failures the reconnect timeout below | |

No run of this PR showed a half-built screen.

**Connect time** (a one-step test with `restart the app`, so relaunch, reconnect and handshake), 10 runs each, wall time:

| | `main` agent | this PR |
|---|---|---|
| `Compat-Pixel-API35` | median 4.90 s (one run failed with the reconnect timeout: 35.5 s) | median 4.90 s |
| `Compat-iPhone` | median 7.20 s | median 7.30 s |

No regression beyond run-to-run noise.

### Not fixed here: the reconnect timeout

`restart the app: reconnect with pre-shared token: agent not reachable within 30s` happened with **both** agents: once with `main`'s agent in the connect-time runs, once in the 30 runs of this PR, three times on the cold-booted emulator while the machine was loaded, and twice in another session's runs on `main`. It is a failed *dial* (the WebSocket upgrade, which doesn't go through the request handler this PR changes), and it tracks machine load. It needs its own investigation.

The CLI hang seen once with the first version (the CLI waited 25 minutes on a closed socket) did not recur in about 60 later runs. A CLI call on a closed WebSocket that never fails is still worth a look, and goes with that investigation.

## Release

This changes `probe_agent`, a pub.dev package. Its CHANGELOG entry is under Unreleased. The version bump happens at release time, per the release checklist; `pubspec.yaml` and `probeAgentVersion` are unchanged here.

## Test plan

- [x] `flutter test` in `probe_agent`: 263 passed. `flutter analyze`: the 25 issues reported are all in test files this PR doesn't touch.
- [x] `go test ./internal/probelink/ ./internal/runner/ ./internal/cli/` pass.
- [x] `go test ./studio/...`: `studio/e2e` ok. One Studio test, `TestExportWritesTheEnginesJSONReport`, failed once while the machine was loaded and passed 3 of 3 alone; this PR doesn't touch it.
- [x] `staticcheck`, `GOOS=windows go vet ./internal/...`.
- [x] Device evidence (above).

## Review follow-up

- **Blocker: `ProbeAgent.start()` threw without a binding.** `attach()` touched `WidgetsBinding.instance`, so an app that called `start()` before `runApp` failed at launch. Now `start()` calls `WidgetsFlutterBinding.ensureInitialized()` (as `runApp` would) before attaching. `attach()` itself never throws: if the frame callback can't be added, the agent stays unattached and keeps the earlier rule.
  - `test/view_ready_no_binding_test.dart` (no binding in that file) checks `attach()` doesn't throw and stays unattached.
  - `test/agent_start_no_binding_test.dart` runs `ProbeAgent.start()` with no binding and checks it completes and attaches. The agent starts only with the define, so the test is skipped without it: `flutter test --dart-define=PROBE_AGENT=true test/agent_start_no_binding_test.dart` passes. A redundant outer `try` in `start()` was removed (it gave an equivalent mutant).
- **Defect: one capped wait per episode, on every cap exit.** When the size was real but no frame came within the cap, the inner exit returned without marking the episode, so every later request waited 2.5 s again. Every cap exit now goes through `_giveUp()`. Test: a real size, no frame delivered, `binding.delayed` past the cap, then `gaveUp` is true and the view is ready.
- **Nit: only a new size starts a new episode.** `didChangeMetrics` also fires for keyboard insets and padding. The episode is now reset only when `physicalSize` differs from the size at the cap. The test changes the insets and the pixel ratio (same episode), then the size (a new one).
- "At most one capped wait per episode" now holds on every path.
- **Mutants:** 14 of 14 killed:
  - 4 new: `attach` throwing without a binding; the inner cap exit not marking the episode; any metrics change resetting it; `start()` not making the binding;
  - the 10 earlier ones, rerun on the changed code: all killed. The earlier equivalent survivor (the post-frame re-check) is now killed too, since the restructured exit is testable.
- `flutter test` in `probe_agent`: 265 passed, 1 skipped (the define-gated test, run separately).

## Second review follow-up

- **Blocker: the agent never initialises the binding.** The previous push called `WidgetsFlutterBinding.ensureInitialized()` in `start()`. An app that installs its own binding after `start()` (its own subclass, an error-reporting package's, `IntegrationTestWidgetsFlutterBinding`) then failed in debug with "Binding is already initialized". That call is removed, and the frame callback is added only when a binding exists:
  - at `start()`, if the app made its binding first. The fixture does this, and so does the documented setup.
  - otherwise, on the agent's first request under the app's binding (`attachToAppBinding`, a bool check once attached). When no frame is pending at that moment, the current size is taken as laid out, since a new size always schedules a frame, so that first request doesn't wait.
  - under a test binding (frames only on `pump`) it doesn't attach, and the earlier rule applies, as `ProbeSync` already does for settling. Without this, 9 executor widget tests hung.
  - `attach()` never throws.
- **Tests:**
  - `view_ready_lazy_attach_test.dart` (no binding in the file): `attach` does nothing; an app-defined `WidgetsFlutterBinding` subclass is then created without an assertion; the first request attaches, with `view_ready_ms` 0; a second request doesn't try again (`attachAttempts`).
  - `agent_start_no_binding_test.dart` (define-gated): `ProbeAgent.start()` with no binding doesn't attach, then the app's own binding subclass is created without an assertion, then attaching works.
  - `agent_start_with_binding_test.dart` (define-gated): `start()` after the app's binding attaches at once.
  - Both define-gated tests pass with `--dart-define=PROBE_AGENT=true`. The full suite: 266 passed, 2 skipped (those two).
- **Mutants:** 5 of 5 killed:
  - `start()` making the binding;
  - `start()` not attaching;
  - no lazy attach on a request;
  - lazy attach under a test binding (the hanging executor tests kill it);
  - a late attach not taking the settled size.
- **Device:** the final build, `buttons.probe` without waits on `Compat-Pixel-API35`, passed **10 of 10** with the machine otherwise idle. (The previous build's rerun was 8 of 10, both failures the reconnect timeout while my Go tests loaded the machine.) The fixture makes its binding before `start()`, so on the device the agent attaches at `start()`; the lazy path is covered by the unit tests.
…terLogo), measured on two named devices (AlphaWaveSystems#819)

## Summary

Compatibility item 3 of `docs/compat/NEXT.md`: widgets without text. The fixture's `display` screen (`PROBE_FIXTURE_WIDGETS=display`) adds four widgets:

- an `Icon` with `semanticLabel: "Favorite"` (`wf_icon`);
- an `Image` with `semanticLabel: "Logo"` (`wf_image`). It is built with `Image.memory` from an inline PNG, so the fixture needs no asset and `pubspec.yaml` and `pubspec.lock` are unchanged;
- a `CircleAvatar` showing "AB" (`wf_avatar`);
- a `FlutterLogo` (`wf_logo`) inside a `GestureDetector` that counts taps into the state text `Taps: N`.

No text on the screen holds "Favorite", "Logo" or "AB", so each match comes from the widget itself. The state text was first `Logo taps: N`, which would have let `see "Logo"` pass through it, so it was renamed before measuring.

## Results

These were measured on Flutter 3.44.8 with the agent from main (`edb0fce`, which waits for a laid-out view), on `Compat-Pixel-API35` (Android 15, `emulator-5590`) and `Compat-iPhone` (iOS 26.5 simulator):

| | Android | iOS |
|---|---|---|
| `display.probe` (8 tests: the 5 text tests and 3 new ones) | 3 of 3 runs pass | 3 of 3 runs pass |
| `display.probe.expect-fail` (12 variants: the 9 text ones and 3 new) | 0 passed, 12 failed | 0 passed, 12 failed |
| exploratory run, 16 single steps | 12 pass, 4 fail | the same 12 and 4 |

Each new negative failed with the message in its comment:

- `"Favourite"` is not found;
- `#wf_missing` is not found;
- `Taps: 0` is gone after `tap #wf_logo`.

**Findings (in `docs/compat/MATRIX.md`):**

- **A semantic label is a text selector.** `see "Favorite"` finds the icon and `see "Logo"` the image, through the agent's fallback to a `Semantics` label (the same fallback that matches a tooltip). The label is matched exactly.
- **A semantic label is found but not read:** `see "Logo" contains "Logo"` fails with `contains "", not "Logo"`. That's filed as AlphaWaveSystems#818, and the suite doesn't read labels until it's fixed.
- **`tap #wf_logo` reaches the `GestureDetector` around the logo**, which has no handler of its own (`Taps: 1`).
- **A `CircleAvatar` is found and read by its child text.**

## Mutation check (fixture, on `Compat-Pixel-API35`)

Each mutant was rebuilt and installed, then the file was restored byte for byte and the real build reinstalled. Both were killed by exactly the test they target:

| Mutant | Result |
|---|---|
| the `Icon` without its semantic label | 7 pass, 1 fails: "an Icon and an Image are found by their semantic label" |
| the logo's `onTap` not counting | 7 pass, 1 fails: "tap on a FlutterLogo by its id reaches the GestureDetector around it" |

## Docs

- `docs/compat/MATRIX.md`: a new section, the summary row, and the text section's "not covered" line.
- `docs/compat/NEXT.md`: item 3 is now assessed.
- The fixture README.
- `CHANGELOG.md` (Added).

## Test plan

- [x] `flutter analyze lib` in the fixture: clean.
- [x] Suite and negatives on both named devices, as above.
- [x] Fixture mutants: 2 of 2 killed.
…lphaWaveSystems#814)

## Summary
First step of "Insert before the step" (the design is in `docs/proposals/studio-insert-before-step.md`): an optional `RunOptions.ReadFile` hook that reads the `.probe` files a run parses, at the runner's three read sites for steps (the run's own file, the recipes folder's files, the target of a `use`). `nil` reads the disk as before, so the command line is unchanged. The hook may be called from several goroutines when the options are shared by the runners of a parallel run, and says so. Nothing uses it yet; Studio will, in the next PR, to keep the exact bytes a run ran.

## Test plan
- [x] The run parses the bytes the hook returns, not the disk, and every site goes through it (own file, `use` target, recipes folder); with no hook it reads the disk.
- [x] A mutant that reverts each site to `os.ReadFile` fails a test (checked for all three).
- [x] `go test ./internal/runner`, staticcheck, `GOOS=windows go vet`.
Signed-off-by: jay23606 <jay.abdal@outlook.com>

# Conflicts:
#	studio/frontend/src/main.ts

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Studio recorder: a recording cannot be saved, and Run stays enabled after Record

1 participant