@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.1

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/@blackbelt-technology/pi-agent-dashboard)](https://www.npmjs.com/package/@blackbelt-technology/pi-agent-dashboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A web-based dashboard for monitoring and interacting with [pi](https://github.com/badlogic/pi-mono) agent sessions from any browser, including mobile.
+**One browser tab to command an army of [pi](https://github.com/badlogic/pi-mono) agents.** Spawn parallel sessions, watch reasoning live, attach OpenSpec changes, ship work — from your laptop or phone.
 
 🌐 **Website & demo:** [blackbelttechnology.github.io/pi-agent-dashboard](https://blackbelttechnology.github.io/pi-agent-dashboard) — animated tour, screenshots, and install guide.
 📝 **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)
@@ -13,6 +13,18 @@ A web-based dashboard for monitoring and interacting with [pi](https://github.co
 
 ---
 
+## Screenshots
+
+<table>
+<tr>
+<td width="33%" align="center"><a href="docs/screenshots/readme-overview.png"><img src="docs/screenshots/readme-overview.png" alt="Sessions overview — folders, branches, OpenSpec changes, live token spend" /></a><br/><sub><b>Overview</b> — sessions grouped by folder, branch & OpenSpec context, live cost</sub></td>
+<td width="33%" align="center"><a href="docs/screenshots/readme-session.png"><img src="docs/screenshots/readme-session.png" alt="Active session — chat, attached OpenSpec change, ask_user prompt, token gauge" /></a><br/><sub><b>Session</b> — chat, OpenSpec apply, interactive <code>ask_user</code>, context gauge</sub></td>
+<td width="33%" align="center"><a href="docs/screenshots/readme-settings.png"><img src="docs/screenshots/readme-settings.png" alt="Settings — ports, spawn strategy, tunnel, resolved tools table" /></a><br/><sub><b>Settings</b> — ports, spawn strategy, zrok tunnel, tool resolution</sub></td>
+</tr>
+</table>
+
+---
+
 ## Table of contents
 
 - [Quickstart](#quickstart)
@@ -44,7 +56,7 @@ Download a pre-built installer from [GitHub Releases](https://github.com/BlackBe
 |----------|----------|
 | **macOS** (Apple Silicon / Intel) | `.dmg` (arm64 / x64) |
 | **Linux** (x64 / ARM64) | `.deb` or `.AppImage` |
-| **Windows** (x64 / ARM64) | `.exe` (NSIS), `.zip`, or portable `.exe` |
+| **Windows** (x64 / ARM64) | `.zip` |
 
 On first launch a setup wizard walks you through mode selection (standalone vs. power-user), API key / OAuth sign-in, and [recommended extensions](#recommended-extensions). The standalone mode bundles Node.js and auto-installs pi + dashboard + openspec into `~/.pi-dashboard/` — **no terminal, npm, or Node.js required**.
 
@@ -640,7 +652,7 @@ Output by platform:
 |----------|--------|----------|
 | macOS | `.dmg` | `packages/electron/out/make/` |
 | Linux | `.deb` + `.AppImage` | `packages/electron/out/make/` |
-| Windows | `.exe` (NSIS) + `.zip` + portable `.exe` | `packages/electron/out/make/` |
+| Windows | `.zip` | `packages/electron/out/make/` |
 
 ### Cross-platform builds (Docker)
 
@@ -649,7 +661,7 @@ From macOS or Linux, build installers for all platforms:
 ```bash
 npm run electron:build -- --all              # macOS (native) + Linux + Windows (Docker)
 npm run electron:build -- --linux            # Linux .deb + .AppImage only
-npm run electron:build -- --windows          # Windows .exe (NSIS) only
+npm run electron:build -- --windows          # Windows .zip only
 npm run electron:build -- --linux --windows  # Both, skip native
 ```
 
@@ -663,7 +675,7 @@ npm run electron:build -- --mac-both
 
 Requires Rosetta 2 (`softwareupdate --install-rosetta --agree-to-license`) so node-pty's x64 prebuilt binary can be unpacked during the cross-arch run. The script wipes per-arch caches between the two builds (`resources/.last-arch` sentinel) so back-to-back runs don't accidentally ship arm64 binaries inside an x64 DMG. Intel macs cannot cross-build arm64 locally (Rosetta is one-way) — use CI for arm64 validation.
 
-Docker builds use a Node 22 Debian container with NSIS installed for Windows cross-compilation. Output goes to `packages/electron/out/make/`.
+Docker builds use a Node 22 Debian container for Windows cross-compilation. Output goes to `packages/electron/out/make/`.
 
 ### Electron dev mode
 
@@ -718,8 +730,8 @@ This runs CI, publishes to npm with `--provenance` for supply-chain transparency
 | `macos-15-intel` | macOS x64 | `.dmg` (Intel; last GitHub-hosted x86_64 image, EOL 2027-08) |
 | `ubuntu-latest` | Linux x64 | `.deb` + `.AppImage` |
 | `ubuntu-24.04-arm` | Linux arm64 | `.deb` |
-| `windows-latest` | Windows x64 | `.exe` (NSIS) + `.zip` + portable |
-| `windows-latest` | Windows arm64 | `.zip` + portable (x64 Node.js via WoW64) |
+| `windows-latest` | Windows x64 | `.zip` |
+| `windows-latest` | Windows arm64 | `.zip` (x64 Node.js via WoW64) |
 
 All artifacts are uploaded to a **draft GitHub Release**. Release notes are extracted automatically from the matching `## [<version>]` section of [`CHANGELOG.md`](CHANGELOG.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-agent-dashboard",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Web dashboard for monitoring and interacting with pi agent sessions",
   "repository": {
     "type": "git",
@@ -73,9 +73,9 @@
     "node": ">=22.12.0 <25"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.0",
-    "@blackbelt-technology/pi-dashboard-server": "^0.5.0",
-    "@blackbelt-technology/pi-dashboard-web": "^0.5.0"
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.1",
+    "@blackbelt-technology/pi-dashboard-server": "^0.5.1",
+    "@blackbelt-technology/pi-dashboard-web": "^0.5.1"
   },
   "optionalDependencies": {
     "appdmg": "^0.6.6"
@@ -87,31 +87,31 @@
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "@mariozechner/pi-ai": "*",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@oh-my-pi/pi-ai": "*",
-    "@oh-my-pi/pi-coding-agent": "*",
-    "@oh-my-pi/pi-tui": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@mariozechner/pi-coding-agent": {
+    "@earendil-works/pi-coding-agent": {
       "optional": true
     },
-    "@mariozechner/pi-ai": {
+    "@earendil-works/pi-ai": {
       "optional": true
     },
-    "@mariozechner/pi-tui": {
+    "@earendil-works/pi-tui": {
       "optional": true
     },
-    "@oh-my-pi/pi-coding-agent": {
+    "@mariozechner/pi-coding-agent": {
       "optional": true
     },
-    "@oh-my-pi/pi-ai": {
+    "@mariozechner/pi-ai": {
       "optional": true
     },
-    "@oh-my-pi/pi-tui": {
+    "@mariozechner/pi-tui": {
       "optional": true
     },
     "typebox": {

package/packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-extension",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Pi bridge extension for pi-dashboard",
   "type": "module",
   "repository": {
@@ -24,15 +24,23 @@
     ".pi/skills/pi-dashboard/"
   ],
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-shared": "^0.5.0",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.1",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "@mariozechner/pi-coding-agent": {
       "optional": true
     },
@@ -41,7 +49,7 @@
     }
   },
   "devDependencies": {
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-tui": "*",
     "@types/ws": "^8.18.1",
     "typebox": "^1.1.33"
   }

package/packages/extension/src/__tests__/ask-user-tool.test.ts

@@ -12,7 +12,7 @@ vi.mock("typebox", () => ({
   },
 }));
 
-vi.mock("@mariozechner/pi-ai", () => ({
+vi.mock("@earendil-works/pi-ai", () => ({
   StringEnum: vi.fn(() => ({})),
 }));
 

package/packages/extension/src/__tests__/command-handler.test.ts

@@ -201,6 +201,74 @@ describe("CommandHandler", () => {
     await handler.handle({ type: "abort", sessionId: "s1" } as ServerToExtensionMessage);
   });
 
+  it("abort schedules persistent-abort retries until isIdle returns true", async () => {
+    // See change: fix-provider-retry-infinite-loop.
+    vi.useFakeTimers();
+    const pi = createMockPi();
+    const abort = vi.fn();
+    let idleAfter = 3; // become idle after 3 polls
+    const isIdle = vi.fn(() => --idleAfter <= 0);
+    const handler = createCommandHandler(pi as any, "s1", { abort, isIdle, eventSink: vi.fn() });
+
+    await handler.handle({ type: "abort", sessionId: "s1" } as ServerToExtensionMessage);
+    expect(abort).toHaveBeenCalledOnce();
+
+    // Advance through the persistent-abort schedule. Each 200ms tick
+    // checks isIdle first, then calls abort if not idle.
+    vi.advanceTimersByTime(200); // tick 1: idleAfter 3→2, abort
+    vi.advanceTimersByTime(200); // tick 2: idleAfter 2→1, abort
+    vi.advanceTimersByTime(200); // tick 3: idleAfter 1→0, isIdle true, no abort, scheduler stops
+    vi.advanceTimersByTime(1000); // no more aborts
+
+    expect(abort.mock.calls.length).toBe(3); // initial + 2 retries
+    vi.useRealTimers();
+  });
+
+  it("persistent-abort scheduler stops after 2 seconds even if never idle", async () => {
+    vi.useFakeTimers();
+    const pi = createMockPi();
+    const abort = vi.fn();
+    const isIdle = vi.fn(() => false); // never idle
+    const handler = createCommandHandler(pi as any, "s1", { abort, isIdle, eventSink: vi.fn() });
+
+    await handler.handle({ type: "abort", sessionId: "s1" } as ServerToExtensionMessage);
+
+    vi.advanceTimersByTime(2500); // safely past 2s cap
+    // initial + ~10 retries (2000ms / 200ms)
+    const calls = abort.mock.calls.length;
+    expect(calls).toBeGreaterThanOrEqual(10);
+    expect(calls).toBeLessThanOrEqual(11);
+
+    // Past cap, no more calls
+    const before = abort.mock.calls.length;
+    vi.advanceTimersByTime(1000);
+    expect(abort.mock.calls.length).toBe(before);
+    vi.useRealTimers();
+  });
+
+  it("abort synthesizes auto_retry_end event after invoking abort callback (provider-retry-state)", async () => {
+    // See change: fix-provider-retry-infinite-loop.
+    const pi = createMockPi();
+    const calls: Array<{ name: string; arg?: unknown }> = [];
+    const abort = vi.fn(() => calls.push({ name: "abort" }));
+    const eventSink = vi.fn((m: unknown) => calls.push({ name: "eventSink", arg: m }));
+    const handler = createCommandHandler(pi as any, "s1", { abort, eventSink });
+
+    await handler.handle({ type: "abort", sessionId: "s1" } as ServerToExtensionMessage);
+
+    expect(abort).toHaveBeenCalledOnce();
+    expect(eventSink).toHaveBeenCalledOnce();
+    // Order: abort() first, then synthesized event
+    expect(calls[0]!.name).toBe("abort");
+    expect(calls[1]!.name).toBe("eventSink");
+    const evt = (calls[1]!.arg as any);
+    expect(evt.type).toBe("event_forward");
+    expect(evt.sessionId).toBe("s1");
+    expect(evt.event.eventType).toBe("auto_retry_end");
+    expect(evt.event.data).toEqual({ success: false, attempt: -1, finalError: "Aborted by user" });
+    expect(typeof evt.event.timestamp).toBe("number");
+  });
+
   it("should handle request_commands message", async () => {
     const pi = createMockPi();
     const handler = createCommandHandler(pi as any, "s1");

package/packages/extension/src/__tests__/enrich-model-metadata.test.ts

@@ -5,7 +5,7 @@
  * defaults when the probe has no match.
  *
  * The helper takes an optional `probe` parameter so unit tests can supply a
- * fake catalog without needing `@mariozechner/pi-ai` installed — in
+ * fake catalog without needing `@earendil-works/pi-ai` installed — in
  * production, registerEntry() injects `modelRegistry.find` as the probe.
  *
  * Spec: openspec/changes/enrich-custom-provider-model-metadata/specs/provider-auth-bridge/spec.md

package/packages/extension/src/__tests__/no-tui-multiselect-arm-regression.test.ts

@@ -11,7 +11,7 @@
  * pi 0.70's RPC mode (the only mode dashboard headless sessions run
  * under) defines `ExtensionUIContext.custom` as an unconditional no-op
  * (`async custom() { return undefined; }`, see
- * `~/.nvm/.../@mariozechner/pi-coding-agent/dist/modes/rpc/rpc-mode.js`
+ * `~/.nvm/.../@earendil-works/pi-coding-agent/dist/modes/rpc/rpc-mode.js`
  * lines 150-153). Awaiting that primitive resolves to `undefined`
  * synchronously, and the TUI arm's `bus.respond({ cancelled: true,
  * source: "tui" })` triggers the PromptBus's first-response-wins

package/packages/extension/src/__tests__/provider-register-reload.test.ts

@@ -367,6 +367,80 @@ describe("reloadProviders", () => {
     expect(opus.input).toEqual(["text", "image"]);
   });
 
+  // ── custom-flag race regression (see change: fix-custom-provider-flag-race) ──
+  // The bridge's first `providers_list` push fires from `session_start`
+  // shortly after `activate()` kicked off async `registerEntry()` calls.
+  // The catalogue's `custom: true` flag MUST be set on that first push,
+  // even when each provider's `/v1/models` endpoint hasn't responded yet —
+  // otherwise custom providers from `~/.pi/agent/providers.json` leak into
+  // Settings → Provider Authentication → API Keys (where they don't belong;
+  // the LLM Providers section already manages them).
+
+  it("custom flag is set on first providers_list push, before discoverModels resolves (regression)", async () => {
+    const mod = await importFresh();
+    const { pi } = makeMockPi();
+
+    // Capture event handlers so we can fire model_select to set modelRegistryRef.
+    const handlers = new Map<string, (event: any, ctx: any) => Promise<void> | void>();
+    pi.on = vi.fn((event: string, handler: any) => { handlers.set(event, handler); });
+
+    // Stub fetch with a never-resolving promise — simulates a slow or
+    // unreachable /v1/models endpoint. The fix's correctness does NOT depend
+    // on this resolving; the synchronous `lastRegistered.set` runs before the
+    // await.
+    let resolveFetch: ((value: Response) => void) | null = null;
+    globalThis.fetch = vi.fn(
+      () => new Promise<Response>((r) => { resolveFetch = r; }),
+    ) as any;
+
+    // Two custom providers. With the fix, both end up in lastRegistered
+    // synchronously when activate() iterates them.
+    writeProvidersJson(tmpHome, {
+      proxy: { baseUrl: "https://example.com/v1", apiKey: "sk-test", api: "openai-completions" },
+      "your-llmproxy": { baseUrl: "https://example2.com/v1", apiKey: "sk-test", api: "openai-completions" },
+    });
+
+    // activate() fires registerEntry async (.catch(() => {})). The synchronous
+    // body runs to the first await before yielding.
+    mod.activate(pi);
+
+    // Capture modelRegistry via a model_select event — buildProviderCatalogue()
+    // returns [] when modelRegistryRef is null. We use model_select rather
+    // than session_start because session_start would re-register every entry
+    // (also stalling on the never-resolving fetch).
+    const fakeRegistry = {
+      find: () => null,
+      getAll: () => [
+        { provider: "proxy", id: "some-model" },
+        { provider: "your-llmproxy", id: "some-model" },
+        { provider: "deepseek", id: "deepseek-chat" },
+      ],
+      getProviderDisplayName: (id: string) => id,
+      authStorage: {
+        getOAuthProviders: () => [],
+        getAuthStatus: () => ({ configured: false }),
+        get: () => undefined,
+      },
+    };
+    const modelSelectHandler = handlers.get("model_select");
+    expect(modelSelectHandler).toBeDefined();
+    await modelSelectHandler!({}, { modelRegistry: fakeRegistry, model: undefined });
+
+    // Build the catalogue while discovery is still in flight. With the fix,
+    // both custom providers are flagged custom: true. Without it, lastRegistered
+    // is still empty (the post-await `lastRegistered.set` never runs because
+    // fetch never resolves) and the flags are missing.
+    const cat = mod.buildProviderCatalogue();
+
+    expect(cat.find((c) => c.id === "proxy")?.custom).toBe(true);
+    expect(cat.find((c) => c.id === "your-llmproxy")?.custom).toBe(true);
+    // Built-in pi-ai providers must remain unflagged.
+    expect(cat.find((c) => c.id === "deepseek")?.custom).toBeUndefined();
+
+    // Cleanup: settle the dangling fetches so the test process doesn't leak.
+    if (resolveFetch) (resolveFetch as (value: Response) => void)(new Response(JSON.stringify({ data: [] }), { status: 200 }));
+  });
+
   it("discovered unknown model falls back to api-appropriate defaults (openai-completions → 128k)", async () => {
     const mod = await importFresh();
     const { pi, registerProvider } = makeMockPi();

package/packages/extension/src/__tests__/retry-tracker.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { RetryTracker, RETRYABLE_PATTERN } from "../retry-tracker.js";
+
+describe("RetryTracker", () => {
+  it("synthesizes auto_retry_start on retryable assistant error", () => {
+    const t = new RetryTracker();
+    const ev = t.observeMessageEnd("s1", {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "rate limit exceeded",
+    });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_start");
+    expect(ev!.data).toEqual({
+      attempt: 1,
+      maxAttempts: -1,
+      delayMs: -1,
+      errorMessage: "rate limit exceeded",
+    });
+    expect(t.isRetrying("s1")).toBe(true);
+  });
+
+  it("does not synthesize for non-retryable error (e.g. context overflow)", () => {
+    const t = new RetryTracker();
+    const ev = t.observeMessageEnd("s1", {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "prompt is too long: 300000 tokens > 200000 maximum",
+    });
+    expect(ev).toBeNull();
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("does not synthesize for non-assistant messages", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "user" })).toBeNull();
+    expect(t.observeMessageEnd("s1", { role: "toolResult", stopReason: "error" })).toBeNull();
+  });
+
+  it("does not synthesize for missing or empty errorMessage", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "assistant", stopReason: "error" })).toBeNull();
+    expect(
+      t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "" }),
+    ).toBeNull();
+  });
+
+  it("increments attempt counter across multiple retryable errors", () => {
+    const t = new RetryTracker();
+    const a = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const b = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const c = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    expect((a!.data as any).attempt).toBe(1);
+    expect((b!.data as any).attempt).toBe(2);
+    expect((c!.data as any).attempt).toBe(3);
+  });
+
+  it("synthesizes auto_retry_end success on successful assistant message_end after retry", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const ev = t.observeMessageEnd("s1", { role: "assistant", stopReason: "end_turn" });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_end");
+    expect(ev!.data).toEqual({ success: true, attempt: 1 });
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("does not synthesize auto_retry_end when no retry was tracked", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "assistant", stopReason: "end_turn" })).toBeNull();
+  });
+
+  it("synthesizes auto_retry_end failure on agent_end with terminal error", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "rate limit" });
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "rate limit" });
+    const ev = t.observeAgentEnd("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "Rate limit exceeded permanently" }],
+    });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_end");
+    expect(ev!.data).toEqual({
+      success: false,
+      attempt: 2,
+      finalError: "Rate limit exceeded permanently",
+    });
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("synthesizes auto_retry_end success on agent_end with non-error terminal message", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const ev = t.observeAgentEnd("s1", {
+      messages: [{ role: "assistant", stopReason: "end_turn" }],
+    });
+    expect(ev).not.toBeNull();
+    expect((ev!.data as any).success).toBe(true);
+  });
+
+  it("agent_end without prior retry returns null", () => {
+    const t = new RetryTracker();
+    expect(t.observeAgentEnd("s1", { messages: [] })).toBeNull();
+  });
+
+  it("noteAbort clears tracker so subsequent agent_end does not double-emit", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    t.noteAbort("s1");
+    expect(t.isRetrying("s1")).toBe(false);
+    expect(t.observeAgentEnd("s1", { messages: [] })).toBeNull();
+  });
+
+  it("scopes retry state per-session", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    expect(t.isRetrying("s1")).toBe(true);
+    expect(t.isRetrying("s2")).toBe(false);
+  });
+
+  it.each([
+    "rate limit exceeded",
+    "Rate Limit hit",
+    "overloaded_error",
+    "too many requests",
+    "HTTP 429",
+    "HTTP 500 Internal Server Error",
+    "service unavailable",
+    "fetch failed",
+    "socket hang up",
+    "connection refused",
+    "connection lost",
+    "request timed out",
+    "terminated",
+    "retry delay exceeded",
+  ])("RETRYABLE_PATTERN matches: %s", (msg) => {
+    expect(RETRYABLE_PATTERN.test(msg)).toBe(true);
+  });
+
+  it.each([
+    "prompt is too long: 300000 tokens > 200000 maximum",
+    "tool execution failed",
+    "invalid input",
+    "",
+  ])("RETRYABLE_PATTERN does NOT match: %s", (msg) => {
+    expect(RETRYABLE_PATTERN.test(msg)).toBe(false);
+  });
+});

package/packages/extension/src/__tests__/session-sync.test.ts

@@ -133,3 +133,75 @@ describe("handleSessionChange", () => {
     expect(registerMsg.registerReason).toBe("spawn");
   });
 });
+
+// See change: spawn-correlation-token — bridge token inclusion contract.
+describe("sendStateSync: spawnToken from env", () => {
+  const ENV_VAR = "PI_DASHBOARD_SPAWN_TOKEN";
+
+  function withEnvVar<T>(value: string | undefined, fn: () => T): T {
+    const prior = process.env[ENV_VAR];
+    if (value === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = value;
+    try {
+      return fn();
+    } finally {
+      if (prior === undefined) delete process.env[ENV_VAR];
+      else process.env[ENV_VAR] = prior;
+    }
+  }
+
+  it("first register includes spawnToken from env", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: false } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBe("tok_first");
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+
+  it("reattach register omits spawnToken (even when env still set)", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: true } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("reattach");
+    });
+  });
+
+  it("first register without env var omits spawnToken", () => {
+    withEnvVar(undefined, () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: false } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+
+  it("handleSessionChange register omits spawnToken (in-process new/fork/resume)", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: true } as any);
+      const ctx = {
+        cwd: "/proj",
+        sessionManager: {
+          getSessionId: () => "sess-fork",
+          getSessionFile: () => "/path/new.json",
+          getSessionDir: () => "/path",
+          getBranch: () => [],
+          getEntries: () => [],
+        },
+      };
+      handleSessionChange(bc, ctx as any, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register" && m.sessionId === "sess-fork");
+      expect(registerMsg).toBeDefined();
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+});