@darwinium/portal-mcp 0.0.1 → 0.0.2

package/TESTING.md

@@ -0,0 +1,478 @@
+# portal-mcp — Manual Verification (Phase 1)
+
+The two automated smoke tests (`yarn smoke-test`, `yarn smoke-test:eaddrinuse`) cover
+Phase 1 Success Criteria 3 and 4. Success Criteria 1, 2, and 5 require a running
+portal session and the loaded extension; document the manual steps here.
+
+## Prerequisites
+
+- Built binary: `yarn workspace @darwinium/portal-mcp build`
+- Built extension (Plan 05): `yarn workspace @jfrog/portal-extension build`
+  then load `dwn_aphex/packages/portal-extension/.output/chrome-mv3/` via
+  `chrome://extensions` → Developer Mode → Load Unpacked
+- `wscat` installed: `npm i -g wscat`
+- Logged-in `*.darwinium.com` portal tab open in Chrome
+
+## Success Criterion 5 — bridge round-trip (page-side end-to-end via DevTools)
+
+**Phase 1 boundary:** the SW WS client is deferred to Phase 2 (BRIDGE-04). The
+page-side bridge (Plan 05) is fully reachable from the journey page's DevTools
+console. The portal-mcp binary's WS server (Plan 02) is reachable via wscat.
+Phase 1 verifies them INDEPENDENTLY; Phase 2 connects them.
+
+### Path A — Page-side end-to-end (Plan 04 + Plan 05)
+
+1. Build the extension and load it unpacked:
+   ```sh
+   yarn workspace @jfrog/portal-extension build
+   # Then: chrome://extensions → Developer Mode → Load Unpacked
+   # → select dwn_aphex/packages/portal-extension/.output/chrome-mv3/
+   ```
+
+2. Build aphex-frontend and start the dev server (per CLAUDE.md project guide):
+   ```sh
+   yarn rebuild
+   # Dev server: https://localhost:8000 (or your local portal URL on *.darwinium.com)
+   ```
+
+3. Open a journey page in the portal. Open DevTools console.
+
+4. Verify the symbol-keyed registry is alive (Plan 04 output):
+   ```js
+   window[Symbol.for('darwinium.pageCommands')]().map(c => `${c.name} (_pageId=${c._pageId})`);
+   // Expected: includes 'getDarwiniumInstructions (_pageId=global)' and
+   // 'getCurrentNodeContext (_pageId=InvestigationsJourney)'
+   ```
+
+5. After Plan 02-04 (Phase 2): the DevTools `window.__darwinium-Bridge-Request`
+   affordance is REMOVED (T-05-08 — literal hyphenated only here so the removal-check
+   greps still pass). Drive commands via the Phase 2 SW path instead — open the popup,
+   paste the token printed by the binary on stderr, click **Save & Connect**, then drive
+   a `listCommands` request through the binary from a wscat client (the binary forwards
+   binary → SW → ISOLATED → MAIN → registry):
+   ```sh
+   # Substitute <hex> with the contents of ~/.config/darwinium-portal-mcp/token
+   wscat -c ws://127.0.0.1:9224 -s darwinium.v1 -s tok.<hex>
+   > {"type":"hello","token":"<hex>","version":"0.1.0"}
+   > {"type":"req","id":"test-1","op":"listCommands"}
+   # Expected response (with the popup connected to a *.darwinium.com tab):
+   # {"type":"resp","id":"test-1","result":[{"name":"...","description":"...","args":[...],"_pageId":"..."}]}
+   ```
+
+6. Run a command via the SW path:
+   ```sh
+   > {"type":"req","id":"test-2","op":"runCommand","args":{"name":"getDarwiniumInstructions","args":{}}}
+   # Expected: {"type":"resp","id":"test-2","result":{"instructions":"...long static prompt string..."}}
+   ```
+
+7. Optional: drive the bridge directly via raw CustomEvents in the page DevTools console (no helper):
+   ```js
+   const id = crypto.randomUUID();
+   document.addEventListener('dwn-mcp-resp', (e) => {
+     if (e.detail.id === id) console.log('resp:', e.detail);
+   }, { once: true });
+   document.dispatchEvent(new CustomEvent('dwn-mcp-req', { detail: { id, op: 'listCommands' } }));
+   // Expected: a 'dwn-mcp-resp' fires with detail.result === the command list.
+   ```
+
+### Path B — Binary WS server reachability (Plan 02)
+
+(Phase 1 has no SW WS client; this verifies the WS server itself is alive.)
+
+1. Start the portal-mcp binary (with stdio piped to /dev/null so it doesn't block on initialize):
+   ```sh
+   node dwn_aphex/packages/portal-mcp/dist/bin/portal-mcp.js serve < /dev/null
+   # Stderr: "portal-mcp: WS server listening on ws://127.0.0.1:9224"
+   ```
+
+2. From another terminal, connect via wscat. Phase 2 token-handshake (BRIDGE-02)
+   requires the `darwinium.v1` and `tok.<hex>` subprotocols; without them the WS
+   upgrade fails (Pitfall 1 — `handleProtocols` rejection). Substitute `<hex>` with
+   the contents of `~/.config/darwinium-portal-mcp/token`:
+   ```sh
+   wscat -c ws://127.0.0.1:9224 -s darwinium.v1 -s tok.<hex>
+   > {"type":"hello","token":"<hex>","version":"0.1.0"}
+   > {"type":"req","id":"test-1","op":"listCommands"}
+   ```
+   Expected response when the popup is connected to a `*.darwinium.com` tab:
+   ```json
+   {"type":"resp","id":"test-1","result":[{"name":"...","description":"...","args":[...],"_pageId":"..."}]}
+   ```
+   With NO popup-connected tab, the response is the verbatim D-C2 string:
+   ```json
+   {"type":"resp","id":"test-1","error":"Not connected. Click Connect in the Darwinium MCP extension popup on the *.darwinium.com tab you want to use."}
+   ```
+
+### Phase 2 closes the loop
+
+Phase 2's SW WS client connects Path B's WS server to Path A's `bridgeRequest`,
+making `wscat → binary → SW → ISOLATED → MAIN → registry → response` work
+end-to-end. The page-side and binary-side are verified INDEPENDENTLY in Phase 1.
+
+## Success Criterion 1 — DevTools console: symbol-keyed registry
+
+After Plan 04 lands the PageContextProvider migration:
+
+1. Open the portal in Chrome on a journey page; open DevTools console.
+2. Run: `window[Symbol.for('darwinium.pageCommands')]()`
+3. Verify the returned array includes:
+   - The existing per-page commands (e.g. `getEventDetail`)
+   - `getDarwiniumInstructions` (global)
+   - `getCurrentNodeContext` (global with journey-page override)
+4. Verify each entry has a `_pageId` field.
+
+## Success Criterion 2 — In-portal ChatModal regression check
+
+After Plan 04 atomically migrates ChatModal:
+
+1. Open the in-portal chat modal on a journey page.
+2. Click "List page commands" (or whatever the existing UI affordance is for
+   `getPageCommands`).
+3. Verify the listed commands match what the symbol-keyed registry returns
+   (Success Criterion 1).
+4. Run a known-safe page command (e.g. `getEventDetail` from the sidebar context).
+5. Verify the command executes and returns its result without errors.
+
+## Phase 2 Manual Matrix
+
+These scenarios verify Phase 2 end-to-end behavior. Run each after building the binary
+(`yarn workspace @darwinium/portal-mcp build`), building the extension
+(`yarn workspace @jfrog/portal-extension build`), loading the extension via
+`chrome://extensions → Developer Mode → Load Unpacked → .output/chrome-mv3/`, and
+opening a logged-in `*.darwinium.com` tab.
+
+For each scenario, record PASS or FAIL with details.
+
+### Scenario (a) — Cold start with no tab connected (MCP-03 / D-B1 timeout path)
+
+1. Start the binary in a fresh terminal: `node dwn_aphex/packages/portal-mcp/dist/bin/portal-mcp.js serve`
+2. Without clicking Connect in the popup, send an `initialize` JSON-RPC frame to the
+   binary's stdin (or simulate via Claude Desktop config that points at the binary).
+3. **Expected:** `initialize.instructions` is `""` (empty string) — the 5s WS-readiness
+   wait expires per D-B1.
+
+### Scenario (b) — Connected tab returns live commands (MCP-04)
+
+1. With the binary running, open the extension popup on a `*.darwinium.com` journey page.
+2. Paste the token printed on binary stderr; click **Save & Connect**.
+3. Popup transitions to `Connected: <tab URL>`.
+4. Run a `tools/call get_page_commands` against the binary (stdin or via an MCP host).
+5. **Expected:** the response includes the live command list with `_pageId` field on each
+   entry, matching what `window[Symbol.for('darwinium.pageCommands')]()` returns in DevTools.
+
+### Scenario (c) — 5-minute idle keepalive (BRIDGE-03)
+
+1. With the popup in `Connected:` state, leave the browser idle (no clicks anywhere) for 5 minutes.
+2. Background Claude Desktop / Code (the MCP host); background Chrome.
+3. After 5 minutes, run a `tools/call run_page_command` against the binary.
+4. **Expected:** the call succeeds without the user having to re-Connect. The 20s WS ping
+   has kept the SW alive (Chrome 116+ idle-timer reset).
+
+### Scenario (d) — Navigate mid-call returns mode-3 error (MCP-05 / D-C4)
+
+1. With the popup in `Connected:` state on a journey page, set up a `tools/call run_page_command`
+   with `expected_page_id` matching the current page (visible in `get_page_commands` response).
+2. Have a colleague (or use a script) navigate the connected tab to a different journey
+   IMMEDIATELY before issuing the call.
+3. **Expected:** the binary returns mode-3 PAGE_NAVIGATED error: `Page navigated. Current page is
+   <new-pageId>. Re-call get_page_commands and retry against the new page.`
+4. Verify `<new-pageId>` matches the actual new page (the MAIN-world `setupPageIdObserver`'s
+   `dwn-mcp-pageid-changed` event has propagated through ISOLATED → SW → binary).
+
+### Scenario (e) — Bad token returns mode-4 error + popup state (MCP-07 / D-C5)
+
+1. Stop the binary. Edit `~/.config/darwinium-portal-mcp/token` to a different 64-char hex
+   string. Restart the binary.
+2. The popup's still-running SW will retry; on the next attempt the WS upgrade succeeds
+   (handleProtocols shape gate accepts) but the post-upgrade hello-frame check fails →
+   `ws.close(4401, 'invalid token')`.
+3. **Expected:** the popup transitions to `Token mismatch` state (red dot) within ~30s
+   (next chrome.alarms tick or sooner if backoff has fired). Error row appears with the
+   verbatim D-C5 popup string.
+4. From the host side, run a `tools/call get_page_commands` — the binary returns the verbatim
+   D-C5 host string: `Extension token does not match the binary's token. Re-run install or rotate-token.`
+5. Click **Re-pair** in the popup; paste the new token; click Save & Connect.
+6. **Expected:** popup transitions back to `Connected:`; subsequent `tools/call` succeeds.
+
+### Scenario (f) — Chrome backgrounded for 30+ seconds (BRIDGE-03 SW keepalive)
+
+1. With the popup in `Connected:` state, close all Chrome windows EXCEPT the one with the
+   connected tab. Move focus away from Chrome (cmd-tab to another app) for at least 30 seconds.
+2. Return focus to Chrome and run a `tools/call run_page_command`.
+3. **Expected:** the call succeeds — the 20s WS ping kept the SW alive past the 30s idle threshold.
+
+### Scenario (g) — Extension reload survives without manual tab refresh (Plan 02-08 / Plan F gap)
+
+**Requirements covered:** EXT-02, EXT-03, EXT-06, BRIDGE-03 (lifecycle robustness)
+
+1. Cold-start the binary (`node dist/bin/portal-mcp.js serve`) and the extension (Load Unpacked from `.output/chrome-mv3/`).
+2. Open a `*.darwinium.com` (or `https://localhost:8000`) tab; click Connect in the popup; verify Connected pill.
+3. Run `tools/call get_page_commands` from Claude Desktop — confirm a successful response with the live command list.
+4. Visit `chrome://extensions`. Click the **Reload** icon on the "Darwinium Portal MCP" entry. (This is the exact gesture that previously bricked open tabs until manual refresh.)
+5. WITHOUT touching the tab, immediately run `tools/call get_page_commands` from Claude Desktop again.
+6. Inspect the tab's DevTools Console (F12 → Console). Filter for `Darwinium`.
+
+**Expected:**
+   - **Step 5 outcome:** the call succeeds (the SW's `chrome.runtime.onInstalled` re-injection completed; the new content scripts forward to the new SW; the binary keeps no page-id state, so the fresh `listCommands` round-trip is all it needs). Acceptable alternative: the call returns the new TAB_STALE error verbatim — `Extension was reloaded; refresh the connected portal tab to restore the bridge. Re-injection is being attempted automatically.` — in which case a SECOND `tools/call get_page_commands` issued ~1 second later succeeds.
+   - **Step 6 outcome:** at most ONE `Darwinium extension was reloaded — refresh this tab to restore the MCP bridge.` warning line in the console (NOT spammed; if the warning appears, it's because the OLD content script's listener fired before the NEW re-injected one took over — both legitimate). NO `Uncaught Error: Extension context invalidated.` from `portal-isolated.js`.
+   - **Popup state:** transitions through `Connecting...` → `Connected:` (no false `Disconnected` flash; Plan 02-06's debounce holds).
+   - **SW console** (chrome://extensions → "Inspect views: service worker"): one log line of the form `[portal-extension] re-injected content scripts into N open Darwinium tab(s) (reason: update)`.
+
+**Failure modes:**
+   - If Step 5 returns `Not connected. Click Connect...` (NO_TAB) instead of TAB_STALE or success: command-router.ts substring detection failed to match the Chrome version's wording. Inspect the actual `(err as Error).message` in the SW console; widen the regex in command-router.ts.
+   - If Step 6 shows `Uncaught Error: Extension context invalidated.`: the Layer 1 guards in portal-isolated.content.ts didn't catch a chrome.* call site. Re-audit every chrome.* in the file.
+   - If the SW console shows `chrome.scripting.executeScript ... permission denied`: the 'scripting' permission did not bake into the manifest — Task 1 fix needed.
+
+### D-A2 ChatModal Regression Check (PAGE-05)
+
+This verifies that Phase 2's external-MCP path does NOT change the in-portal ChatModal's
+existing per-command approval UX (D-A2 lock).
+
+1. With the binary stopped (or just don't connect via the popup), open the in-portal chat
+   modal on a journey page (the existing `ChatModal` component, NOT the extension popup).
+2. Issue a chat message that triggers the LLM to call a non-auto-accept page command
+   (per the existing `autoAcceptRPCFunctions` list).
+3. **Expected:** the in-portal chat shows the existing approval UX (per
+   `EnhancedChat.tsx` `showRPCConfirmation`) — same behavior as before Phase 2.
+4. Verify by scrolling through the chat history that no Phase 2 changes (popup, SW connection
+   state, etc.) affect the in-portal flow.
+
+---
+
+If any scenario FAILs, file a gap-closure ticket; `/gsd-plan-phase --gaps 02-end-to-end-round-trip`
+generates a Phase 2 Wave 3 plan to address it.
+
+## Phase 3 Manual Test Matrix
+
+These scenarios verify the Phase 3 customer install flow end-to-end. Each row in
+the cross-platform matrix should be run by a human operator on a fresh / dirty
+state per the pre-state column. Capture stderr transcripts (so they can be
+diffed against the locked UI-SPEC §Surface 2 expected lines) and on-disk state
+(token file mode, claude_desktop_config.json contents, env-paths data dir).
+
+### Cross-platform install end-to-end
+
+| Platform | Pre-state              | Command                         | Expected stderr lines (UI-SPEC §Surface 2)                                                                                                              | Token file                                                                            | claude_desktop_config.json                                                       | Pair flow                                                              |
+| -------- | ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| macOS    | clean (no env-paths)   | `npx @darwinium/portal-mcp install` | `install starting...`, `✓ token (added at ~/Library/Application Support/darwinium-portal-mcp/token, mode 0600)`, `✓ extension (extracted ...)`, `✓ config (added ...)`, boxed pairing prompt, `waiting for popup...` | `~/Library/Application Support/darwinium-portal-mcp/token` mode 0600                  | `~/Library/Application Support/Claude/claude_desktop_config.json` with `.bak`    | popup paste → `✓ paired with extension`, exit 0                        |
+| macOS    | re-install (unchanged) | `npx @darwinium/portal-mcp install` | `✓ token (existing at ..., mode 0600)`, `✓ config (existing match)`, `✓ extension (existing v...)`                                                                                                                  | unchanged                                                                              | unchanged (no `.bak` written)                                                    | popup paste → exit 0                                                   |
+| macOS    | rotate-token           | `npx @darwinium/portal-mcp rotate-token` | `rotate-token starting...`, `✓ token (regenerated at ..., mode 0600)`, boxed pairing prompt with "click \"Re-pair\"" verb                                                                                          | new 64-hex value at same path, mode 0600                                              | unchanged                                                                        | popup Re-pair → `rotate complete. The old token is no longer accepted.` |
+| Windows  | clean                  | `npx @darwinium/portal-mcp install` | as macOS but with `, ACL locked` suffix on the token line; LOCALAPPDATA path used                                                                                                                                  | `%LOCALAPPDATA%\darwinium-portal-mcp\Data\token` icacls inheritance:r, user:F         | `%APPDATA%\Claude\claude_desktop_config.json` with `.bak`                        | as macOS                                                               |
+| Linux    | clean                  | `npx @darwinium/portal-mcp install` | as macOS, no migration line (Linux silently skips Phase 2 → Phase 3 migration)                                                                                                                                     | `~/.local/share/darwinium-portal-mcp/token` mode 0600                                 | `~/.config/Claude/claude_desktop_config.json` with `.bak`                        | as macOS                                                               |
+
+### First-launch migration test (D-F1, macOS / Windows)
+
+1. Pre-state: `printf '%s' "<random 64-hex>" > ~/.config/darwinium-portal-mcp/token; chmod 0600 ~/.config/darwinium-portal-mcp/token` on macOS (or the Windows equivalent path).
+2. `npx @darwinium/portal-mcp install`.
+3. Expected stderr line: `portal-mcp: ✓ migrated token from ~/.config/darwinium-portal-mcp/token to <new env-paths path>`.
+4. Verify on-disk: token now at the env-paths data dir; Phase 2 path no longer exists.
+
+### Malformed claude_desktop_config.json test (D-F2)
+
+1. Pre-state: write `not json` to the platform-correct config path.
+2. `npx @darwinium/portal-mcp install`.
+3. Expected stderr line (verbatim): `portal-mcp: ✗ config (refusing to write — <path> is not valid JSON; please fix or delete and re-run)`.
+4. Verify exit code is 1; the malformed file is unchanged on disk (no overwrite).
+
+### Re-arm test (D-E3)
+
+1. `npx @darwinium/portal-mcp install`.
+2. Wait 60s without entering the code into the popup.
+3. Expected stderr: `portal-mcp: code expired. 0 successful pairings.\nportal-mcp: press Enter to generate a new one, or Ctrl+C to abort.`.
+4. Press Enter; verify a fresh boxed pairing-code prompt is reprinted with a different 6-digit code.
+
+### 3-attempt lockout test (D-E3)
+
+1. `npx @darwinium/portal-mcp install`.
+2. From a separate terminal, send three deliberately-wrong codes via wscat:
+   ```sh
+   wscat -c ws://127.0.0.1:9224 -s darwinium.v1 -s pair.000000
+   wscat -c ws://127.0.0.1:9224 -s darwinium.v1 -s pair.000001
+   wscat -c ws://127.0.0.1:9224 -s darwinium.v1 -s pair.000002
+   ```
+3. Expected stderr (in order): `⚠ wrong code (attempt 1 of 3).` → `⚠ wrong code (attempt 2 of 3).` → `⚠ wrong code (attempt 3 of 3).` followed by the re-arm prompt.
+
+### Doctor pass/fail/warn matrix
+
+Run `npx @darwinium/portal-mcp doctor --json | jq` in each of:
+
+1. **Clean install** — all 9 checks pass except `git.token-tree-warning` (warn if TOKEN_DIR is inside a git work tree).
+2. **Missing token** — `token.mode` and `token.parent.mode` fail; `extension.reachable` fails (no token to handshake with).
+3. **Malformed config** — `config.desktop.entry` fails with detail `not valid JSON`.
+4. **Port 9224 held** — start `serve` in another terminal first; `port.9224.bindable` fails with EADDRINUSE detail.
+5. **Token inside git tree** — `git.token-tree-warning` warns with the repo root in the detail.
+6. **Claude Desktop absent** — `config.desktop.entry` is `level:'warn'` (not fail), so exit code is still 0 if everything else passes.
+
+For each, verify: stdout is a single JSON line, stderr is empty (`--json` mode), `result.checks.length === 9`, exit code matches `summary.fail > 0 ? 1 : 0`.
+
+### Marketplace install path (DIST-02)
+
+1. From inside Claude Code: `/plugin marketplace add darwinium-com/portal-mcp-marketplace` (waiting on plan 03-03).
+2. `/plugin install portal-mcp`.
+3. `npx @darwinium/portal-mcp doctor --json | jq '.checks[] | select(.id == "config.code.marketplace")'`.
+4. Verify the check passes with detail set to the resolved plugin path.
+5. Run a tool call from inside Claude Code (e.g. `get_page_commands`) — verify response contains the live page commands.
+
+### D-A2 ChatModal regression check
+
+This verifies that Phase 3's external customer install flow does NOT change the
+in-portal ChatModal's existing per-command approval UX (D-A2 lock — Phase 1
+lineage).
+
+1. With the binary stopped (or the popup not connected), open the in-portal
+   chat modal on a journey page.
+2. Issue a chat message that triggers a non-auto-accept page command.
+3. Expected: the existing approval UX appears (per `EnhancedChat.tsx`
+   `showRPCConfirmation`) — same behavior as Phase 1 + Phase 2.
+4. Verify by scrolling chat history that no Phase 3 changes (install flow,
+   pairing, OOB code) affect the in-portal flow.
+
+---
+
+## CI Matrix (recommended — Wave 2 task)
+
+End-to-end install + popup pair is necessarily manual on the dev OS (Chrome
+extension popup interaction). What CAN be automated cross-platform is the
+structured-output contract. RESEARCH §Open Question 15 recommends:
+
+```yaml
+# .github/workflows/portal-mcp-doctor-matrix.yml (Wave 2 — not in this plan)
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+runs-on: ${{ matrix.os }}
+steps:
+  - uses: actions/checkout@v4
+  - uses: actions/setup-node@v4
+    with: { node-version: 20 }
+  - run: yarn install --immutable
+  - run: yarn workspace @darwinium/portal-mcp build
+  - run: yarn workspace @darwinium/portal-mcp smoke-test
+  - run: |
+      node dwn_aphex/packages/portal-mcp/dist/bin/portal-mcp.js doctor --json > doctor.json
+      # Assert the structured-output contract:
+      jq -e '.checks | length == 9' doctor.json
+      jq -e '.platform | IN("darwin", "win32", "linux")' doctor.json
+      jq -e '.checks | map(.id) | sort' doctor.json
+```
+
+The 9-check count + locked check IDs + platform-correct env-paths resolution
+are the most important cross-platform invariants; a failed CI matrix here
+indicates a stable-API regression that customers would hit.
+
+---
+
+## Unaided-walkthrough protocol (DIST-05 SC-4 gate)
+
+This is the truth-of-the-pudding test for whether the customer-facing setup docs
+actually work. Per RESEARCH §Pitfall 9, the docs are only "done" if someone who
+has not seen the project can complete setup using only the public URLs.
+
+**Recruit ONE Darwinium engineer who has NOT been on standup or planning sessions
+for portal-mcp.** Ideal verifier: a backend or infra engineer unfamiliar with the
+portal frontend.
+
+Provide them ONLY:
+
+- The public setup URL: <https://darwinium.com/portal-mcp/setup>
+- The npm install command: `npx -y @darwinium/portal-mcp install`
+- A blank notepad and a stopwatch.
+
+Do NOT answer questions during the walkthrough. Sit silently and observe.
+Capture:
+
+- **Time-to-first-Connected-state** (target: < 5 minutes from start to popup
+  showing `Connected: <tab URL>`).
+- **Every confusion point.** "What does this mean?" / "Where is this option?" /
+  any moment they hesitate or backtrack — record verbatim.
+- **Every command they ran that wasn't in the docs.** This is the strongest
+  signal that a step is under-documented.
+- **Every error they hit and how (or whether) they recovered.** Errors the docs
+  didn't preempt are doc bugs.
+
+Capture results in
+`.planning/phases/03-install-flow-customer-docs/UNAIDED-WALKTHROUGH-RESULT.md`
+using the template in plan 03-04 Task 6 — verifier name + role + exposure level,
+time-to-paired, confusion points, commands run, errors hit, doc revisions
+required, three sign-off boxes.
+
+**Pass criteria:** the walkthrough completes WITHOUT external help. If the
+verifier needs help, the docs need revision; iterate (preferably with a
+different verifier on the second pass — first-time-eyes is the test) before
+Phase 3 close.
+
+---
+
+## Cross-platform CI matrix expectations
+
+`.github/workflows/portal-mcp-cross-platform.yml` runs `doctor --json` on each
+platform (`ubuntu-latest`, `macos-latest`, `windows-latest`) and asserts the
+locked **structural** contract:
+
+- `result.version` is a non-empty string (the binary's semver).
+- `result.platform` matches `process.platform` of the runner
+  (`linux` / `darwin` / `win32`).
+- `result.checks.length === 9`.
+- The 9 check IDs match the locked set: `binary.present`, `token.mode`,
+  `token.parent.mode`, `token.acl`, `config.desktop.entry`,
+  `config.code.marketplace`, `extension.reachable`, `port.9224.bindable`,
+  `git.token-tree-warning`.
+- `result.summary` has numeric `pass` / `fail` / `warn` fields.
+
+**Individual check pass/fail is NOT asserted by CI.** Reason: Claude Desktop /
+Claude Code are not installed on the GitHub-hosted runners, and the Chrome
+extension is not loaded. The `extension.reachable` check will fail every time;
+the `config.desktop.entry` and `config.code.marketplace` checks will warn. That
+is the expected runner state. The structural contract — which IDs exist, the
+platform field, the version string — is what CI gates.
+
+**Why a structural-only gate is sufficient:** drift in the locked check IDs or
+platform field is a customer-impacting stable-API regression. Drift in
+individual pass/fail is environment-dependent and would produce false alarms.
+End-to-end install + popup pair is necessarily manual on the dev OS; the
+developer signs off on the manual matrix in the Phase 3 close gate.
+
+The workflow has a second job, `wxt-zip-artifact`, that runs only on
+`ubuntu-latest` (sufficient for the artifact build) and asserts the production
+`wxt zip` artifact's manifest excludes `localhost` host_permissions (WR-07
+enforcement at the Web-Store-shippable artifact level). The uploaded
+`portal-extension-zip` artifact becomes the source of truth for Phase 4 Web
+Store submission.
+
+---
+
+## Four-error-mode regression matrix (DIST-06)
+
+For each of the four MCP error modes (D-C2..D-C5), walk through the
+customer-facing UX before Phase 3 close. The customer troubleshooting doc
+(DIST-06, staged at
+`.planning/phases/03-install-flow-customer-docs/customer-docs/troubleshooting.md`)
+covers all four; this matrix verifies the doc + the binary + the extension are
+consistent.
+
+| Error mode               | Trigger                                                                                  | Expected popup state                                          | Expected `doctor` check                                     |
+|--------------------------|------------------------------------------------------------------------------------------|---------------------------------------------------------------|-------------------------------------------------------------|
+| No tab connected         | Close all `*.darwinium.com` tabs; ask Claude to call `get_page_commands`                  | `Disconnected` (paired) — pill text matches D-C2 verbatim     | `extension.reachable: fail (timeout)`                        |
+| Connection lost mid-call | Stop the SW mid-command (chrome://extensions → Inspect → close DevTools); immediately retry | `Connecting...` then auto-recovers within ≤30 s                | `extension.reachable: pass after the recover`                |
+| Page navigated mid-call  | Start a long page command; navigate the connected tab during; observe rejection           | `Connected: <new tab URL>` (popup updates after navigation)   | `extension.reachable: pass`                                  |
+| Token mismatch           | Run `npx -y @darwinium/portal-mcp rotate-token`; observe popup transition                 | `Token mismatch` → after Re-pair flow → `Connected: <tab URL>` | `extension.reachable: 4401` (transient) then `pass`         |
+
+Each row should be tested manually before Phase 3 close. Record PASS / FAIL
+inline. If any row fails, the bug is in one of three places: the
+troubleshooting doc copy is wrong, the binary's error message is wrong, or the
+popup's state machine is wrong. The doctor check is the tie-breaker — if doctor
+agrees with the popup but the troubleshooting doc says otherwise, fix the doc.
+
+---
+
+## Troubleshooting
+
+- If the binary's first stdout line isn't JSON-RPC, a transitive dependency is
+  logging on import. Run `node --trace-warnings dist/bin/portal-mcp.js serve` and
+  look for `console.log` calls. See PITFALLS.md Pitfall 1.
+- If port 9224 is held: `lsof -i:9224` shows the holding process.
+- If the second instance prints a stack trace instead of the user-readable message,
+  file a bug — the smoke-test-eaddrinuse should have caught this.
+- If the wscat upgrade fails with `Unexpected server response: 400` on the SW path
+  (Phase 2), confirm both subprotocols are passed: `-s darwinium.v1 -s tok.<hex>`.
+  Without them `handleProtocols` rejects (Pitfall 1).

package/dist/bin/bundlePaths-CSftU0OK.js

@@ -0,0 +1,59 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/install/bundlePaths.ts
+/**
+* Path resolution that survives single-file compilation.
+*
+* The npm distribution runs `dist/bin/*.js` under Node, where `import.meta.url`
+* points at a real file and bundled resources sit at `<package-root>/`. The
+* macOS distribution (`scripts/build-macos-bundle.mjs`) instead compiles this
+* source into one executable with `bun build --compile`, where every module is
+* served from a virtual filesystem:
+*
+*   import.meta.url   file:///$bunfs/root/portal-mcp     ← NOT on disk
+*   process.argv[1]   /$bunfs/root/portal-mcp            ← NOT on disk
+*   process.execPath  /path/to/portal-mcp                ← the real binary
+*
+* So anything that resolves a sibling file from `import.meta.url` silently
+* resolves inside `/$bunfs/` and fails `existsSync`. Both call sites that care
+* — the bundled extension zip in `install.ts` and `binary.present` in
+* `doctor.ts` — go through this module instead.
+*/
+/** Prefix bun mounts compiled modules under. Not a real filesystem path. */
+const COMPILED_VFS_PREFIX = "/$bunfs/";
+/** True when running from a `bun build --compile` single-file executable. */
+function isCompiledBinary() {
+	return fileURLToPath(import.meta.url).startsWith(COMPILED_VFS_PREFIX);
+}
+/**
+* On-disk path of the running program.
+*
+* Under a compiled binary `argv[1]` is a virtual path, so `doctor`'s
+* `binary.present` check must stat `process.execPath` instead. Under Node
+* `execPath` is the node runtime itself, so `argv[1]` remains correct there.
+*/
+function selfPath() {
+	return isCompiledBinary() ? process.execPath : process.argv[1] ?? "";
+}
+/**
+* Directory containing bundled resources (currently just `extension-bundle/`).
+*
+* - Compiled binary: resources ship beside the executable, so this is the
+*   executable's own directory. In the `.mcpb` layout that is
+*   `<extension-dir>/server/`, holding `portal-mcp` and `extension-bundle/`.
+* - Node/npm: chunks land in `<package-root>/dist/bin/`, so the package root —
+*   holding `extension-bundle/` per package.json `files` — is two levels up.
+*/
+function bundleResourceRoot() {
+	if (isCompiledBinary()) return path.dirname(process.execPath);
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+/** Absolute path to the bundled Chrome extension zip. */
+function bundledExtensionZipPath() {
+	return path.join(bundleResourceRoot(), "extension-bundle", "extension.zip");
+}
+
+//#endregion
+export { selfPath as n, bundledExtensionZipPath as t };
+//# sourceMappingURL=bundlePaths-CSftU0OK.js.map

package/dist/bin/bundlePaths-CSftU0OK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundlePaths-CSftU0OK.js","names":[],"sources":["../../src/install/bundlePaths.ts"],"sourcesContent":["/**\n * Path resolution that survives single-file compilation.\n *\n * The npm distribution runs `dist/bin/*.js` under Node, where `import.meta.url`\n * points at a real file and bundled resources sit at `<package-root>/`. The\n * macOS distribution (`scripts/build-macos-bundle.mjs`) instead compiles this\n * source into one executable with `bun build --compile`, where every module is\n * served from a virtual filesystem:\n *\n *   import.meta.url   file:///$bunfs/root/portal-mcp     ← NOT on disk\n *   process.argv[1]   /$bunfs/root/portal-mcp            ← NOT on disk\n *   process.execPath  /path/to/portal-mcp                ← the real binary\n *\n * So anything that resolves a sibling file from `import.meta.url` silently\n * resolves inside `/$bunfs/` and fails `existsSync`. Both call sites that care\n * — the bundled extension zip in `install.ts` and `binary.present` in\n * `doctor.ts` — go through this module instead.\n */\nimport * as path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Prefix bun mounts compiled modules under. Not a real filesystem path. */\nconst COMPILED_VFS_PREFIX = '/$bunfs/';\n\n/** True when running from a `bun build --compile` single-file executable. */\nexport function isCompiledBinary(): boolean {\n  return fileURLToPath(import.meta.url).startsWith(COMPILED_VFS_PREFIX);\n}\n\n/**\n * On-disk path of the running program.\n *\n * Under a compiled binary `argv[1]` is a virtual path, so `doctor`'s\n * `binary.present` check must stat `process.execPath` instead. Under Node\n * `execPath` is the node runtime itself, so `argv[1]` remains correct there.\n */\nexport function selfPath(): string {\n  return isCompiledBinary() ? process.execPath : (process.argv[1] ?? '');\n}\n\n/**\n * Directory containing bundled resources (currently just `extension-bundle/`).\n *\n * - Compiled binary: resources ship beside the executable, so this is the\n *   executable's own directory. In the `.mcpb` layout that is\n *   `<extension-dir>/server/`, holding `portal-mcp` and `extension-bundle/`.\n * - Node/npm: chunks land in `<package-root>/dist/bin/`, so the package root —\n *   holding `extension-bundle/` per package.json `files` — is two levels up.\n */\nexport function bundleResourceRoot(): string {\n  if (isCompiledBinary()) {\n    return path.dirname(process.execPath);\n  }\n  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');\n}\n\n/** Absolute path to the bundled Chrome extension zip. */\nexport function bundledExtensionZipPath(): string {\n  return path.join(bundleResourceRoot(), 'extension-bundle', 'extension.zip');\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAM,sBAAsB;;AAG5B,SAAgB,mBAA4B;AAC1C,QAAO,cAAc,OAAO,KAAK,IAAI,CAAC,WAAW,oBAAoB;;;;;;;;;AAUvE,SAAgB,WAAmB;AACjC,QAAO,kBAAkB,GAAG,QAAQ,WAAY,QAAQ,KAAK,MAAM;;;;;;;;;;;AAYrE,SAAgB,qBAA6B;AAC3C,KAAI,kBAAkB,CACpB,QAAO,KAAK,QAAQ,QAAQ,SAAS;AAEvC,QAAO,KAAK,QAAQ,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EAAE,MAAM,KAAK;;;AAI/E,SAAgB,0BAAkC;AAChD,QAAO,KAAK,KAAK,oBAAoB,EAAE,oBAAoB,gBAAgB"}