@andorra-labs/code 0.0.0-stage → 0.1.5

package/tests/agent-centric-mcp-test-plan.md

@@ -0,0 +1,208 @@
+# Agent-centric MCP Graphs + Sessions — QA plan
+
+## Scope, acceptance criteria and prerequisites
+
+This plan validates Andorra Code's new local MCP server, graph authoring from a Hermes/OpenClaw-compatible client, recoverable graph validation errors, optimistic multi-editor saving, and project/session queries with live input and abandoned-run detection. It tests the **existing graph editor/runtime** as an integration target; the MCP server does not run graph nodes.
+
+Run on Windows (PowerShell), macOS (zsh) and Linux (bash), ideally on two machines with the same Andorra account for cloud-revision conflict checks. Use **throwaway graphs/projects and nonsecret prompts**. Install Node >=22.19, npm, the repo checkout and its dependencies. For graph operations sign in to a paid Andorra account and configure at least one provider from /providers; session-read operations can be tested without Graph Editor membership. External client: a Hermes/OpenClaw MCP connector or an MCP Inspector capable of listing resources/tools and sending arbitrary JSON arguments.
+
+### Build and local checks
+
+Use the feature branch in a dedicated worktree; do not switch an installed Andorra checkout away from main. From the worktree:
+
+\`\`\`bash
+git branch --show-current
+npm ci
+npm run check
+npm run build
+node scripts/run-tests.mjs dist/test/agent-mcp.test.js
+npm run ci:local
+\`\`\`
+
+Any skipped CI groups must be documented; do not call a partially skipped run green. Compare unrelated full-suite failures to main rather than assuming they are regressions. The repository intentionally does not run hosted PR CI.
+
+For a production-profile smoke with credentials configured:
+
+\`\`\`bash
+node dist/src/cli.js login
+node dist/src/cli.js mcp-server --stdio
+\`\`\`
+
+This command must remain silent until it receives MCP JSON-RPC over stdin; no CLI banner/progress log should contaminate stdout. Use a standards-compliant MCP client for requests, rather than sending a raw line manually (the protocol uses content-length/framing specified by the SDK).
+
+Suggested MCP Inspector invocation, if your environment provides it:
+
+\`\`\`bash
+npx @modelcontextprotocol/inspector node dist/src/cli.js mcp-server --stdio
+\`\`\`
+
+Use the Inspector to select the Tools and Resources tabs, invoke named tools with JSON objects, and inspect their text responses and the MCP isError flag. Alternatively configure Hermes/OpenClaw to launch the same stdio process, and ask it to read the graph guide before building a graph.
+
+### Independent test data
+
+1. Create workspaces named AgentMCP-Alpha and AgentMCP-Beta, plus a second path with the same display name as Alpha to test ambiguity. Use the desktop app's project add control; create a few sessions in each.
+2. Create a distinctive throwaway graph ID, e.g. agent-mcp-qa-<unique identifier> (only letters/numbers/dash). Never edit the bundled default graph.
+3. Choose a provider ID returned by andorra_providers_list; denote it P below.
+4. Prepare an innocuous task such as "Create a README in the test folder" for a session that can ask a question or require approval.
+5. On every test record the tool name, full request (with any secrets redacted), JSON reply, MCP isError, graph revision, session ID/status, and screenshot of any desktop status icon.
+
+### Graph QA cases
+
+| ID | Steps | Expected observable result |
+| --- | --- | --- |
+| G01 | Connect; list Tools and Resources; read andorra://graph/architecture and call andorra_graph_guide | Both explain all node types/ports, agent provider, bounded loops, Join caveats, validation and repair workflow; tool names are discoverable |
+| G02 | Call andorra_providers_list | IDs/models/types listed; **no API key, authorization header or token** in result |
+| G03 | Begin new graph mode=create with unique id/name; inspect graph with andorra_graph_get before publish | New draftId returned; published read still not found; empty draft not visible in Graph Editor |
+| G04 | Upsert node {"id":"checker","name":"Checker","type":"agent"} without provider | MCP isError=true; JSON ok=false; code NODE_PROVIDER_MISSING; nodeId checker; message contains "Provider not set. Please select a valid provider."; draft does not gain checker |
+| G05 | Upsert Agent checker with provider="provider-does-not-exist" | NODE_PROVIDER_INVALID, nodeId checker, explicitly requests valid provider |
+| G06 | Upsert checker with provider P and completion outcomes pass/fail; upsert End nodes accepted/review; patch graph entry checker; add only pass edge | andorra_graph_validate returns valid=false with NODE_ROUTE_MISSING, nodeId checker, port fail. Publish refuses with same code/port and does not write revision |
+| G07 | Add edge for fail outcome; rerun validate and publish | valid=true, issues=[]; publish returns revision 1 and local durable graph. GUI reload displays same nodes/labels, prompts/providers and both links |
+| G08 | Upsert edge with nonexistent source or target; then with nonexistent outcome | EDGE_SOURCE_MISSING, EDGE_TARGET_MISSING, EDGE_OUTCOME_INVALID respectively; no bad edge persists |
+| G09 | Upsert two equivalent source/outcome/target edges with different IDs | EDGE_DUPLICATE; graph remains unchanged by the refused call |
+| G10 | Remove fail edge and publish; restore it | Publish refuses with named nodeId/port. After restoring, publish succeeds without losing other edges |
+| G11 | Patch checker prompt, systemPrompt, provider and model; publish; inspect GUI | The node's matching fields are updated; only configured provider accepted; no silent override |
+| G12 | Create Loop node with maxIterations=3, body return cycle and done path; omit graph maxNodeVisits | Existing graph validator returns a meaningful finite-cycle/visit-bound error naming both a visit count and a wall clock. Add enough graph maxNodeVisits and all paths, then publish |
+| G13 | Create Condition node with source/path/equals and only true edge | Missing false path flagged with nodeId and port false; fixing it enables validation when predecessor/path constraints are met |
+| G14 | Create Join all from mutually exclusive outcomes | Structural GRAPH_INVALID prevents impossible barrier; changing Join to any or restructuring independent branches passes |
+| G15 | Create unreachable extra node or edge with invalid source port; validate | Graph refuses with structural or specific port error and no revision is published |
+| G16 | Begin two edit drafts A and B on same revision; publish A's rename; publish B's different rename | A publishes next revision; B receives REVISION_CONFLICT and instructions to reopen latest/reapply; latest retains A, old revision unchanged |
+| G17 | Open GUI graph editor on machine A and MCP draft B on same graph; edit/save GUI A; publish MCP B | MCP B receives REVISION_CONFLICT and cannot overwrite GUI revision |
+| G18 | Create MCP draft; close MCP client/server without publishing; reconnect | Old draft ID yields DRAFT_NOT_FOUND. No new graph/revision in GUI/cloud. Repeat with andorra_graph_discard |
+| G19 | Try to create or modify default bundled graph, invalid ID, invalid entry, removal of entry, >24 drafts | Explicit BUNDLED_GRAPH, INVALID_GRAPH_ID, ENTRY_NOT_FOUND, ENTRY_NODE, DRAFT_LIMIT as applicable |
+| G20 | Sign out / lose graph entitlement while MCP connected; call graph tool | Graph operations reject; no unauthorized graph read/write. Session-read operations should still use local home per product policy |
+| G21 | Publish account-owned graph from machine A; bring machine B online and allow graph sync; edit on B | Same account's saved graph appears after sync; do not claim MCP publish means cloud committed if sync status still pending/offline |
+| G22 | Use graph with inputs/schema/tools/capabilities/Orchestrator, including a migrated older graph | MCP read/patch/publish retains supported fields; authoritative validator enforces graph schema, orchestrator entry and tool restrictions |
+
+### Session QA cases
+
+| ID | Steps | Expected observable result |
+| --- | --- | --- |
+| S01 | Call andorra_projects_list with two registered projects and a workspace having sessions but no registry entry | Projects include registered and session-discovered workspaces, correct names/paths/counts, deterministic name ordering |
+| S02 | andorra_sessions_list with projectName AgentMCP-Alpha, then projectPath; compare result IDs | Matching project sessions only. Case-insensitive name match. Duplicate project display names return AMBIGUOUS_PROJECT with disambiguation paths |
+| S03 | Create blank session; query status=pending | Blank session returned pending, turns=0 |
+| S04 | Complete a trivial task; query status=completed | Session returned completed, with real updatedAt, task and summary |
+| S05 | Trigger a live desktop app-server run; query status=running | Run with a living process and no input prompt reports running (not completed based on older turn) |
+| S06 | Cause run to ask for clarification; leave question unanswered, poll andorra_sessions_attention | Session returned required_input; attention.kind=question; bounded prompt/ID/time, without tool-arguments/secrets |
+| S07 | Trigger an approval request and leave it pending | Session required_input, attention.kind=approval, with generic tool name only, no argument payload |
+| S08 | Answer/deny the question or approval, allow run to continue, poll | Pending attention sidecar cleared; session returns running or final status, not stale required_input |
+| S09 | Close/crash the engine mid-run, reopen app and query status=incomplete | Orphaned running marker is incomplete (yellow warning in client), not perpetually running; no stale sidecar produces false required_input |
+| S10 | Cancel or exhaust a run; create a needs_clarification stopped attempt | Cancelled/exhausted/interrupted/infrastructure_error classify incomplete; needs_clarification classifies required_input |
+| S11 | andorra_sessions_list with lookbackMinutes=5; compare sessions updated >5m ago | Only persisted updatedAt in lookback; lookbackMinutes=0 is legal and yields only exact-now matches |
+| S12 | Combine project/status/lookback filter, page with limit=1 and nextOffset | Intersection of filters, accurate total, stable descending updatedAt, correct offset; limit max 100 |
+| S13 | Archive a session; query includeArchived=true/false | Included by default and true; excluded with false; no data deletion |
+| S14 | andorra_session_get with correct UUID and historyLimit=5; then historyOffset=5 | Returns correct session/turn snippets with descending recency, offset pagination, and no arbitrary filesystem contents |
+| S15 | Have >100 saved sessions in one project; get oldest session by exact ID | Correct status/details, not an incorrect fallback status |
+| S16 | Unknown project, invalid UUID, negative minutes, invalid status, malformed ISO date | Coded PROJECT_NOT_FOUND / INVALID_SESSION_ID / INVALID_FILTER; no partial result pretending valid |
+| S17 | A supervisor polls andorra_sessions_attention twice without changes; then creates a new required_input session | Stable IDs/status allows supervisor to alert only on change; Andorra MCP itself emits no background notification |
+| S18 | Run on Mac, Windows and Linux (different path casing/symlinks); verify session/project resolution | Valid workspaces are found by canonical/normalized path; unreadable/corrupt session record does not hide healthy sessions |
+| S19 | Run same supervisor against two different Andorra installations | Each sees only its own ANDORRACODE_HOME; cross-host aggregation is explicitly not supported |
+| S20 | Kill the engine between writing a run claim and saving its running turn, then poll twice, rename the session without starting a run, and poll again | Both polls report incomplete with the same crashedAttempt run ID; renaming (which only moves updatedAt) does not change the status |
+| S21 | After S20, complete a new run in the same session, then poll; separately delete a session that has a crash marker and poll | The new run's persisted turn supersedes the crash and reports its own status; the deleted session's marker file is removed from `runs/` during the scan |
+| S22 | Cancel a run, then leave its finalized record on disk with the `.open-run` claim still present (failed best-effort removal), and poll | Status reflects the cancelled turn as incomplete and the response has no `crashedAttempt`; the stale claim is reclaimed |
+| S23 | From S20, make `runs/<runId>.mcp-crash` unwritable (for example a directory at that path), run startup recovery, and poll; then remove the obstruction and poll | Recovery keeps the `.open-run` claim, the first poll still reports incomplete with crashedAttempt, and the retry after removing the obstruction writes the marker and reclaims the claim |
+| S24 | Crash the engine before any turn is saved twice in the same session (two dead claims, no persisted turns), then poll | The session reports the newer attempt's run ID as crashedAttempt and exactly one `.mcp-crash` file remains in `runs/`; the older unresolved marker is reclaimed |
+| S25 | **Automated only** — no MCP tool exposes a stale session snapshot. Run `node scripts/run-tests.mjs dist/test/agent-mcp.test.js` and inspect `crash pruning never uses a session save newer than the query snapshot` | The stale-snapshot query reports incomplete and leaves the marker in place; the fresh query reports completed and removes the superseded marker. Public-path pruning is covered manually by S21 and S24 |
+| S26 | **Automated only** — concurrent query ordering needs a harness. Run `node scripts/run-tests.mjs dist/test/agent-mcp.test.js` and inspect `overlapping queries cannot prune a marker another scan still needs` | The scan holding the pre-recovery snapshot reports incomplete; the fresh query runs after it, reports completed, and only then removes the marker |
+
+### Security, concurrency and recoverability
+
+- Attempt Graph MCP edit without paid sign-in: no unauthorized read/write. Switch account during an open draft: draft state must not carry to the next account.
+- Inject unknown keys into node/edge, invalid schemas, oversized prompts, missing endpoints: validation or save rejects without altering latest snapshot.
+- Trigger simultaneous writes to a graph from MCP drafts and Graph Editor, including cloud-down state: optimistic revision CAS must refuse stale save; no last-writer-wins.
+- Terminate MCP server during draft/publish; restart and inspect latest.json/revision history: no partial snapshot should become latest.
+- Modify an underlying provider after a graph draft begins: publish re-checks configured provider and refuses an orphaned reference.
+- Try a session query with many files/corrupt interaction sidecars: no leak of full run journals or failed serialization; response limits are bounded.
+- Run Inspector with a user account lacking graph membership to verify session query tools do not accidentally disclose graph data.
+
+## Cleanup
+
+1. Close external MCP clients and app-server/Inspector processes.
+2. Discard live test drafts via andorra_graph_discard or exit the dedicated MCP process.
+3. Remove throwaway sessions/projects via standard GUI controls. Leave production sessions and existing graphs untouched.
+4. If a test graph was published, preserve its revision history unless the product has an authorized deletion path; record graph ID for housekeeping. Never manually remove published snapshots from a real account.
+5. Restore any test provider/config changes. If an installed CLI was switched off main, return it to main, rebuild and verify branch as required by AGENTS.md.
+
+## Validation evidence, known gaps and proposed QA
+
+**Automated checks (executed 2026-10-17 on Windows 10.0.22631, Node 24.13.1, branch `fix/pr185-crash-marker-followup`):**
+
+- `npm run check` — PASS (`tsc --noEmit`).
+- `npm run build` — PASS.
+- `node scripts/run-tests.mjs dist/test/agent-mcp.test.js` — 42 tests, **41 pass, 1 fail, 0 skipped**. The failure is `MCP reports backend/config failures separately from graph validation`, which also fails on a clean `origin/main` worktree on Windows: the test expects `ENOTDIR` when a regular file is used as the home path, but Windows reports `ENOENT`. It does not exercise the crash-marker code.
+- Targeted `dist/test/run-records.test.js` (`claim|reconcil|an open record|a marker|interrupted record|finalized record|repaired marker|stopped record|hand-edited|validSavedSession|checkpoint|parallel branches`) — **29 pass, 0 fail**. The file's load-sensitive concurrency/mutation-lock tests were excluded by name.
+- `node scripts/ci-local.mjs --base origin/main` — graph-studio group: 3/3 steps, **229/229 tests pass**. `graph-editor`, `rust-shell` and `full` were not selected (no matching paths for the first two; `full` is load-sensitive and must run alone).
+
+This run covers the automated counterparts of S20–S26 and R01–R05.
+
+**Manual checks:** All G cases, GUI persistence, provider entitlement, cloud multi-machine behavior, stdio MCP Inspector and physical-device Windows/macOS/Linux tests are pending execution. S20–S24 are proposed manual crash-recovery cases; none has been executed outside the fixtures above. No claim of a successful live agent-to-graph workflow is made until these are performed.
+
+**Known limitations:** Graph drafts are process-local and expire; graph publication acknowledges local persistence before cloud sync; session discovery is local (no multi-device aggregation); only desktop app-server live question/approval waits write the new sidecars; the MCP service itself does not poll in the background or send notifications, cannot answer user approvals, and does not execute authored graphs. Structural errors beyond missing providers/required routes are reported from the existing graph validator and can require human interpretation; the returned message is not guaranteed to name every affected node.
+
+**QA agent completion format:** For each case return PASS / FAIL / BLOCKED, machine/OS/Node version, tool name, redacted payload and response, graph/session IDs, observed vs expected result, and exact reproduction steps for failures. Separately report npm run check, build, targeted tests and ci:local with any skips.
+
+## Codex review regressions (PR #179)
+
+The following cases were added after the first Codex review. Their automated counterparts live in `test/agent-mcp.test.ts` and were executed with the results recorded under “Validation evidence” above.
+
+| ID | Procedure | Expected result |
+| --- | --- | --- |
+| R01 | Parse `package.json` and run `npm run check` | Manifest parses successfully; npm scripts can start. |
+| R02 | Create a draft with a missing `fail` edge *and* an invalid non-object output schema, then validate | Issue array contains `NODE_ROUTE_MISSING` with nodeId/port **and** `GRAPH_INVALID` for the schema in the same response. |
+| R03 | Connect an MCP client using revoked/expired auth and trigger a graph access request | Graph tool replies remain valid MCP JSON-RPC; no sign-out text appears on stdout. Errors are `AUTH_REQUIRED` for signed-out users or `MEMBERSHIP_REQUIRED` for signed-in users without active access, never `GRAPH_INVALID`. |
+| R04 | Submit concurrent disjoint patches to the same Agent node (name and instruction) | Both calls succeed and the final published node retains both changes. A patch waiting on provider I/O cannot change a draft being published or discarded. |
+| R05 | On first graph access, simultaneously call `andorra_graphs_list` twice while cloud snapshot initialization is still pending | Both wait on the same initial GraphSync promise; no reader sees stale pre-sync data. |
+| R06 | Pass `updatedAfter`/`updatedBefore` values such as `0`, `10/16/2026`, `2026-02-30T12:00:00Z` | Each returns `INVALID_FILTER`; valid zone-qualified ISO timestamps are accepted. |
+| R07 | Register a named symlink to an existing workspace holding saved sessions; query its project name | Exactly the saved session(s) appear, project label matches registered name, and project count isn't duplicated. Repeat on case-insensitive macOS volumes. |
+| R08 | Request `andorra_session_get` with `historyLimit:0` and then an offset past available turns | Empty history and `nextHistoryOffset:null`, never an unchanged non-advancing page token. |
+
+When reporting results, distinguish the fixture-level automated coverage from live authenticated third-party MCP Inspector, desktop, cloud and macOS filesystem integration. The latter remain manual unless explicitly run.
+## Codex second-round review regressions (PR #179)
+
+The following scenarios cover the later five review threads, with automated counterparts added to `test/agent-mcp.test.ts`. Run compiled Node tests and live agent/MCP checks before marking them passed. **Not executed by this GitHub-only authoring environment.**
+
+| ID | Steps | Expected observable behavior |
+| --- | --- | --- |
+| R09 | Make membership return paid for subject A while auth changes from subject A to B between reads. Call `andorra_graphs_list`. | Refuses `AUTH_CHANGED`; B's graph directory is not accessed using A's entitlement. Matching paid/auth subjects continue normally. |
+| R10 | Call `andorra_graph_get` for a missing ID or missing revision, and `andorra_graph_begin` mode=edit for missing ID. | Each returns `GRAPH_NOT_FOUND` with guidance to list or create graphs, not misleading `GRAPH_INVALID`. |
+| R11 | Begin valid graph publication, pause the pre-publish GraphSync pass, remove the referenced provider from config, then release sync. | Publication refuses `NODE_PROVIDER_INVALID`, includes the node ID, and saves no new revision. |
+| R12 | Save a legacy published graph with an Agent intentionally inheriting the session provider. Open an MCP edit draft, rename graph only, validate and publish. Then patch that Agent without specifying a provider. | Unchanged legacy Agent still inherits and publishing succeeds. Modifying that Agent requires a configured explicit provider and returns `NODE_PROVIDER_MISSING` until supplied. |
+| R13 | Have a session change/delete between two hypothetical store reads while requesting `andorra_session_get`. | Tool uses one saved session snapshot for both status/turn count and history; no inconsistent mixture or invented fallback `incomplete` status. |
+
+Review account-switch behavior again during long cloud synchronization; sensitive writes must not proceed for the wrong subject. Local filesystem and live provider/identity tests remain pending until run by the QA agent.
+
+## Codex third-round backend-error regression
+
+| ID | Steps | Expected observable behavior |
+| --- | --- | --- |
+| R14 | Corrupt the local config.json on a throwaway installation, invoke `andorra_providers_list` and `andorra_sessions_list`; then use a regular file as the installation directory and invoke `andorra_providers_list`. | Configuration parse failure returns `BACKEND_ERROR` for both graph-independent tools. ENOTDIR returns `STORAGE_ERROR` without disclosing raw filesystem paths. No such failure is mislabeled `GRAPH_INVALID`. Invalid graph schemas still return `GRAPH_INVALID` through the actual graph validator. |
+
+Fixture regression added to `test/agent-mcp.test.ts`. Automated execution remains pending in this GitHub-only development environment.
+
+## Codex fourth-round regression cases (PR #179)
+
+These cases have fixture counterparts in `test/agent-mcp.test.ts`. Automated test execution and physical-machine verification are still pending.
+
+| ID | Reproduction steps | Expected result |
+| --- | --- | --- |
+| R15 | Save a schema-v1/v2 graph, use `andorra_graph_get` on its immutable revision | Exact saved graph is returned: no new Orchestrator, rewritten edges or schema migration. `begin mode=edit` can still migrate an editing draft. |
+| R16 | Switch signed-in identity while the final provider reload is awaited during graph publication | Publication rejects `AUTH_CHANGED` before writing any revision for the old account. |
+| R17 | Save over 100 sessions; while `andorra_sessions_attention` scans page 1, reorder/update a session before page 2 | One store snapshot is used throughout the scan; no duplicate/missing IDs from offset drift. |
+| R18 | Make `GraphSync.start` fail on first account initialization, correct the transient failure, retry graph list without restarting MCP | First request fails with a proper backend/storage code; subsequent request initializes a fresh GraphSync and succeeds. |
+| R19 | Write a live run claim for a session whose last saved turn still says completed, before its new running marker lands | Session monitor returns `running` immediately; stale/dead claims remain ignored. |
+| R20 | Issue 32 concurrent `andorra_graph_begin mode=create` calls on one server | At most 24 drafts are created; remaining calls return `DRAFT_LIMIT`. |
+| R21 | Add 100 ordinary nodes and try adding a 101st; then make the 101st a version-3 Orchestrator Agent | Ordinary insertion fails immediately with `NODE_LIMIT`; one additional Orchestrator is permitted. |
+
+Run `npm run check`, `npm run build`, targeted `node scripts/run-tests.mjs dist/test/agent-mcp.test.js`, then `npm run ci:local` in a dedicated checkout. These checks have not been executed in this GitHub-only coding environment.
+
+## Codex fifth-round regression cases (PR #179)
+
+These cases have automated coverage in `test/agent-mcp.test.ts`. The tests have been committed but **not executed** from this GitHub-only editing environment.
+
+| ID | Steps | Expected result |
+| --- | --- | --- |
+| R22 | Switch the signed-in account from A to B or sign out during the awaited filesystem read in `andorra_graph_get` or `andorra_graphs_list`; also test edit-draft initialization | All return `AUTH_CHANGED` and disclose no account-A graph or draft to the now unauthenticated account-B client |
+| R23 | Call `andorra_graph_get` using `revision:` `"1"`, `null`, `0`, `-1`, `1.5`, non-safe numbers, or an object | All return `INVALID_ARGUMENTS` explaining positive safe integer revisions; only omitted/valid revision arguments can load a snapshot |
+| R24 | Create an open-run claim for a new run on an old completed session, then simulate the owning process dying before the `running` turn is saved | `andorra_sessions_attention` and list queries report `incomplete`, including on subsequent polls after dead claim cleanup, and expose only the abandoned run ID/timestamp |
+| R25 | Repeat R24, but allow startup `reconcileInterruptedRuns` (or the session rail guard) to clean up the dead claim before MCP monitoring begins | The monitor still reports `incomplete`; the persisted crash marker survives claim removal until superseded by a newly persisted successful attempt |
+
+Run the compiled targeted suite and the full local checks stated above before merging; include macOS, Windows and Linux process-liveness validation where machines are available.

package/tests/analytics-settings-test-plan.md

@@ -0,0 +1,165 @@
+# Analytics settings and the plan-gated anonymous-feedback opt-out QA
+
+## Scope and prerequisites
+
+This plan covers the Analytics settings page and `/feedback [on|off|status]`, and the rule that
+governs them. ADR 0021 replaces the earlier universal opt-out: collection is included with the Free
+and Legacy plans, only a confirmed Paid plan may turn it off, and an installation that has never
+confirmed a plan collects. The collector itself is covered by
+[`product-telemetry-test-plan.md`](product-telemetry-test-plan.md); this plan covers the preference,
+the gate, and the two surfaces that show it.
+
+Both surfaces write the same preference to the same configuration file
+(`$ANDORRACODE_HOME/config.json`, `~/.andorracode/config.json` by default). The plan cache lives in
+`$ANDORRACODE_HOME/telemetry/state.json` and keys a locally hashed auth subject to the tier that
+account service last confirmed; the hash never leaves the machine.
+
+Prerequisites for the manual checks:
+
+- Node 22.19+ and a built checkout: `npm ci`, `npm run build`.
+- A disposable configuration home, so a check cannot change the machine's real setting:
+  `export ANDORRACODE_HOME="$(mktemp -d)"` (Windows PowerShell: `$env:ANDORRACODE_HOME = Join-Path $env:TEMP "andorra-qa-home"`).
+  The export matters: a plain `ANDORRACODE_HOME=$(mktemp -d)` is a shell variable, and the Node
+  and desktop processes started afterwards would not see it and would use the real home instead.
+- The desktop application for the window checks. From the feature worktree:
+  `npm --prefix desktop run desktop:dev`.
+- For the Paid path, an account whose plan the service names. Free, Legacy and never-confirmed paths
+  need no account, and with no endpoint configured no telemetry leaves the machine.
+
+## How to use the feature
+
+### Never-confirmed installation (no account, or `state.json` absent)
+
+1. Start the CLI in the disposable home: `node dist/src/cli.js`.
+2. `/feedback status` reports `Anonymous feedback: on (included with your plan until this account's plan is confirmed)`.
+3. `/feedback off` is refused with a message that collection is included with the current plan and
+   an upgrade turns it off. `config.json` still has no `enabled: false`.
+4. `/feedback on` succeeds and is stored.
+5. `/feedback` with no argument attempts to flip the saved value; a flip to off is refused for the
+   same reason.
+
+### Paid installation
+
+Seed a confirmed Paid answer for the account that will operate the installation. The simplest
+repeatable way is to sign in with a Paid account while the account service answers `/me` with
+`tier: "paid"`; that writes the cache. For a scripted check without a network, write the cache
+directly with the account's subject hash, or reuse the automated case in `test/analytics.test.ts`.
+
+1. `/feedback status` reports `Anonymous feedback: on (saved preference)`.
+2. `/feedback off` reports off, and `config.json` contains `"analytics": { "enabled": false, "generation": 1 }`.
+3. `/feedback on` reports on and increments the generation again.
+4. Set the preference off, then delete the auth token to sign out. `/feedback status` still reports
+   off, and the emitter stays silent: a paid opt-out survives an outage and a sign-out.
+
+### Desktop window
+
+1. Start the application and open **Settings → Analytics**.
+2. For a Free, Legacy, or unconfirmed plan, the switch is replaced by
+   `Included with the Free plan. Upgrade to Paid to turn it off.` and the row's value reads
+   `Included` as plain text. The absence of a switch is deliberate: nothing pretends to change.
+3. For a confirmed Paid plan, the switch is shown, reflects the saved value, and turning it off
+   shows a toast and writes `analytics.enabled: false` (with a generation bump) to the file.
+4. Reopen Settings. The page re-reads the file, so a change made by a CLI is visible without a
+   restart.
+5. With an engine that does not advertise `config.analytics`, the page says the installed CLI
+   predates the setting. With `config.analytics` but not `config.analytics.planGate`, the page falls
+   back to the account's own tier rather than withholding the switch.
+
+Reset after testing: set the preference back on, or delete the `analytics` key. An absent key means
+on. To reset the plan cache, delete `$ANDORRACODE_HOME/telemetry/state.json`.
+
+## Test cases and expected results
+
+- **AN-01** A fresh installation opens **Settings → Analytics** with a Free or unconfirmed answer.
+  No switch is offered; the reason and the upgrade path are visible.
+- **AN-02** A confirmed Paid account sees the switch in its saved position and can turn it off.
+  The file contains `enabled: false` and a generation greater than before the change.
+- **AN-03** A confirmed Paid account turns reporting back on. The file contains `enabled: true` and
+  the generation increments again.
+- **AN-04** A Free account with `enabled: false` saved (written by hand) still reports: the
+  status line says the preference is off but the effective answer is included with the plan, and the
+  emitter does not honor the off value.
+- **AN-05** `/feedback status` distinguishes the two cases: included-with-plan copy for a plan that
+  cannot opt out, saved-preference copy for a confirmed Paid plan.
+- **AN-06** `/feedback off` on a Free, Legacy, or unconfirmed installation prints the refusal and
+  leaves the file byte-identical (no generation bump).
+- **AN-07** Two concurrent `/feedback` flips in a confirmed Paid installation cancel out, and the
+  generation advances by two. The flip is computed under the configuration's lock.
+- **AN-08** A signed-out installation with a cached Paid opt-out keeps reporting off after
+  `/me` fails. Restoring the network does not change the answer until the preference changes.
+- **AN-09** A different subject signs in on the same installation without a successful `/me`. The
+  gate answers `unknown` and collects; the earlier account's Paid opt-out is not applied to them.
+- **AN-10** A `/me` answer of `paid: true` with no tier is recorded as `unknown`, not `paid`: the
+  installation keeps collecting and the switch is withheld.
+- **AN-11** A `/me` answer of `tier: "free", paid: true` is recorded and shown as Legacy, matching
+  the account label elsewhere in the product.
+- **AN-12** `config.json` contains `"analytics": { "enabled": "no" }`. Loading fails with a message
+  that `analytics.enabled` must be a boolean.
+- **AN-13** `config.json` contains an unknown key inside `analytics`. Loading fails naming the
+  unsupported field.
+- **AN-14** `config.json` contains `"analytics": { "generation": -1 }`. Loading fails; a generation
+  is a non-negative integer.
+- **AN-15** An engine older than the setting (no `config.analytics`) leaves the switch withheld and
+  a note explaining why. `config.set` from a newer client is refused with `invalid-params`.
+- **AN-16** The Analytics page states that source code, prompts and responses, file names and paths,
+  repository and branch names, API keys, and MCP and plugin tool names are never collected.
+- **AN-17** The settings navbar search finds the page by its label, and a non-matching word leaves
+  no rows.
+- **AN-18** Autocompletion after `/feedback ` offers exactly `on`, `off`, and `status`, and `/help`
+  shows the same signature.
+- **AN-19** With the window open, a CLI changes the preference; reopening the page shows the file's
+  value.
+- **AN-20** `/feedback on extra` and `/feedback maybe` print the usage line and write nothing.
+- **AN-21** Turning reporting off from either surface purges queued telemetry: with no endpoint
+  configured, `$ANDORRACODE_HOME/telemetry/outbox/` holds no `.jsonl` files afterwards.
+
+## Edge cases and potential bugs
+
+- **Never-confirmed is not Premium.** Treating an unknown machine as opt-out-capable would let an
+  offline Free installation skip data it owes. The gate must collect.
+- **An outage must not resurrect reporting.** A Paid opt-out is persisted with the subject hash;
+  a failed `/me`, a sign-out, or an unreachable account service must not erase it.
+- **The cache must not leak the subject.** `state.json` contains only hashes, tiers, preferences and
+  timestamps. Seeing an email address or subject id in that file is a bug.
+- **Eviction must protect opt-outs.** Filling the cache with eight other accounts must not evict
+  the one Paid account that opted out; opt-outs are evicted only when nothing else remains.
+- **Generation drift.** An unrelated settings save that rewrites `analytics` with the same effective
+  answer must not change the generation, or the drainer would discard events nobody opted out of.
+- **A refused write must not look applied.** The window's switch is absent or disabled when the plan
+  cannot opt out; the CLI refuses rather than saving a value that is ignored.
+- **A stale window.** The page re-reads the file on open, because another writer changes it without
+  the engine emitting an event.
+- **Hand-edited files.** Invalid booleans, unknown keys and negative generations fail loudly.
+
+## Gaps and limitations
+
+- **No live deployment is exercised here.** The preference, gate and cache are local and covered by
+  automated cases; a Paid `/me` answer from a real deployment is simulated by the test.
+- **Backdated opt-out.** Opting out is prospective: events already uploaded stay, and queued events
+  are purged. A Paid user cannot ask for deletion of records already sent, which the ADR accepts
+  because no record identifies them.
+- **The manual window checks (AN-01, AN-02, AN-15, AN-16) still need a person** on a running desktop
+  application; the component tests render the same markup but do not click.
+- **The plan cache is per installation and per subject.** A shared machine keeps up to eight live
+  answers and up to 64 opt-out tombstones; a very long series of accounts can eventually evict an
+  opt-out, after which that account collects until its next successful `/me`.
+
+## Validation evidence
+
+Automated checks in this change:
+
+- `npm run build` — passed.
+- `npm run check` (root and desktop `tsc --noEmit`) — passed.
+- `node scripts/run-tests.mjs dist/test/analytics.test.js` — the preference, validation, file
+  round-trip, `/feedback` behavior, concurrent flips, and the engine's `config.set`/`config.get`
+  path. Updated for the plan gate: a confirmed Paid answer is seeded for the cases that turn the
+  preference off.
+- `node scripts/run-tests.mjs dist/test/telemetry-state.test.js` — the gate table, subject binding,
+  signed-out behavior, eviction, generation changes.
+- `npm run test --prefix desktop` — `SettingsAnalytics.test.ts` covers the included-with-plan copy,
+  a Paid switch, the never-collected statement, and the withheld switch; `capabilities.test.ts`
+  covers the plan-gate capability.
+
+Manual checks still pending: AN-01, AN-02, AN-15, AN-16 on a running window.
+
+> **Settings polish (desktop-settings-polish-test-plan.md):** the `Always off` and `On`/`Off`/`Included` chips are plain text now (`Never collected`, and the stored state), so nothing static looks like a control. The feedback explanation and the storage explanation are behind a "?" beside their titles; their text is still in the page.