@blackbelt-technology/pi-agent-dashboard 0.4.0 → 0.4.1

package/docs/architecture.md

@@ -200,7 +200,18 @@ with `upgradeRecommended` / `upgradeDashboard` flags consumed by
 `BootstrapBanner`. Versions below `minimum` set a blocking `error`
 message that `session-api gateOrEnqueue` translates to 503 responses.
 
-See change: `unified-bootstrap-install`.
+The pinned range is `minimum: "0.70.0"`, `recommended: "0.70.0"`,
+`maximum: null` — deliberately in lockstep. The dashboard does NOT carry
+backward-compatibility shims for older pi releases; one supported pi
+means no conditional code paths in the bridge and no dual-import
+fallbacks (e.g. `@sinclair/typebox` vs `typebox`). Bumping `recommended`
+in a future change SHOULD be matched by an equal bump to `minimum` and a
+lockstep bump of the offline-bundled pi version in
+`packages/electron/offline-packages.json`.
+
+The CLI also surfaces skew on stderr at startup: `cli.ts::logCompatibilityWarning` emits a three-line red block on below-minimum (including the exact `pi-dashboard upgrade-pi` remediation command) and a single advisory line on below-recommended. Silent when in range. This is in addition to the browser banner and the 503 gating, so terminal-only users (headless servers, CI) don't miss the signal. Note: `readCurrentPiVersion` uses `fs.realpathSync` on the registry-resolved bin path so the common npm-global symlink layout (`~/.nvm/.../bin/pi` → `../lib/node_modules/@mariozechner/pi-coding-agent/dist/cli.js`) resolves to the real `package.json` — without this, `compatibility.current` was silently `undefined` in every response.
+
+See changes: `unified-bootstrap-install`, `pi-zero-seventy-compat`, `warn-pi-version-skew-in-cli`.
 
 ### Force Kill Escalation
 The Stop button supports two-click escalation for stuck sessions:
@@ -551,6 +562,18 @@ When a session sends `flows_list`, the server notifies other sessions in the sam
 ### Event Broadcast During Replay
 During bridge session replay (while `replayingSessions` set contains the session), `event_forward` messages are stored but NOT broadcast individually to browser subscribers. Instead, when `replay_complete` arrives (or the 5s safety timeout fires), the server sends all accumulated events as a single `event_replay` batch to subscribers. This prevents per-event serialization overhead during replay while still delivering the full history to browsers.
 
+### Per-message entry id stamping (live vs replay)
+
+The per-message ⤘ Fork button needs each chat bubble to carry the entry id of the entry it represents in the persisted JSONL. Two paths populate this:
+
+- **Replay path** (`packages/shared/src/state-replay.ts`): reads from the persisted JSONL directly, so each `message_start` / `message_end` event carries the stable `entryId` from the source entry. No back-fill needed.
+- **Live path** (`packages/extension/src/bridge.ts`): pi 0.69+ awaits extension handlers BEFORE calling `sessionManager.appendMessage`, which means an entry id does NOT exist at the bridge's emit time. The bridge instead:
+  1. Stamps a per-event `nonce` on `message_start` / `message_end` events so the client can correlate later.
+  2. Defers the `message_end` SEND via `setTimeout(0)` (a macrotask) so pi's awaited dispatcher unwinds and `appendMessage` runs in between — by the time the timeout fires, pi has mutated `event.message.id` in place.
+  3. Wraps `ctx.sessionManager.appendMessage` once per session at `session_start`. After a successful append, the wrapper emits an `entry_persisted { entryId, nonce }` event so the client reducer back-fills the matching ChatMessage's `entryId` (covers user messages, whose `message_start` fires before persistence).
+
+`queueMicrotask` was used previously but no longer works: on pi 0.69+ the microtask resolves *inside* the awaited `_emitExtensionEvent`, before persistence. See change `fix-per-message-fork`.
+
 ## Persistence
 
 | Data | Storage | Details |
@@ -658,13 +681,16 @@ The restart endpoint accepts `{ dev: boolean }` to switch between dev/production
 
 ### Cross-Platform Server Launch
 
-The dashboard server is spawned via `node --import <loader> <cli.ts>` from three call sites (`packages/server/src/cli.ts` `cmdStart`, `packages/extension/src/server-launcher.ts` `launchServer`, `packages/electron/src/lib/server-lifecycle.ts` `launchServer`). On Node ≥ 20, Windows rejects raw absolute paths passed to `--import` because it parses the drive-letter prefix (e.g. `B:`) as a URL scheme (`ERR_UNSUPPORTED_ESM_URL_SCHEME`). Every resolver therefore returns a `file://` URL, not a raw path:
+The dashboard server is spawned via `node --import <loader> <cli.ts>` from four call sites (`packages/server/src/cli.ts` `cmdStart`, `packages/extension/src/server-launcher.ts` `launchServer`, `packages/electron/src/lib/server-lifecycle.ts` `launchServer`, `packages/server/src/restart-helper.ts` `buildOrchestratorScript`). On Node ≥ 20, Windows's ESM loader parses **both** the `--import` loader position AND the entry-script position as URLs. A raw Windows path like `B:\Dev\cli.ts` parses with scheme `b:` (not in the ESM loader's `file`/`data`/`node` allowlist) and crashes with `ERR_UNSUPPORTED_ESM_URL_SCHEME`. Node has a drive-letter heuristic that auto-wraps common Windows paths with `file://` before the URL parse in the entry-script position, but the heuristic has known gaps for less-common drives (`A:`, `B:`, ...), so reliance on it is unsafe.
+
+Both positions are wrapped as `file://` URLs universally:
 
-- `packages/shared/src/resolve-jiti.ts` — `resolveJitiImport()` (anchor = `process.argv[1]`) and `resolveJitiFromAnchor(anchorPath)` (anchor supplied explicitly) both return `pathToFileURL(registerPath).href`
-- `packages/electron/src/lib/server-lifecycle.ts` — `resolveJitiFromPi()` now imports `resolveJitiFromAnchor` from shared (previously duplicated; consolidated in the `consolidate-platform-handlers` change)
-- `packages/server/src/cli.ts` — the tsx fallback wraps `esm/index.mjs` the same way
+- `packages/shared/src/platform/node-spawn.ts` — `toFileUrl(pathOrUrl)` (idempotent path → file:// URL, handles Windows drive letters on POSIX hosts) and `spawnNodeScript(opts)` (wraps both loader and entry before delegating to `platform/exec.ts::spawn`). This is the canonical chokepoint.
+- `packages/shared/src/resolve-jiti.ts` — `resolveJitiImport()` and `resolveJitiFromAnchor(anchorPath)` return `pathToFileURL(registerPath).href` for the loader position.
+- `packages/server/src/cli.ts` — routes through `spawnNodeScript`.
+- `packages/extension/src/server-launcher.ts`, `packages/electron/src/lib/server-lifecycle.ts`, `packages/server/src/restart-helper.ts` — wrap the entry `cliPath` with `toFileUrl(cliPath)` before argv construction.
 
-The URL form is cross-platform safe (Linux/macOS accept both raw paths and `file://` URLs) so no platform gating is needed in the resolvers.
+The URL form is cross-platform safe (Linux/macOS accept `file://` URLs identically to raw paths), so no platform gating is needed. A repo-level lint test (`packages/shared/src/__tests__/no-raw-node-import.test.ts`) refuses any new call site that passes a raw identifier as argv after `--import` / `--loader`, preventing regression. Mirrors the `platform/exec.ts` + `no-direct-child-process.test.ts` pattern. See changes: `fix-windows-server-parity` (loader position), `fix-windows-entry-script-url` (entry-script position).
 
 #### stdout + stderr capture parity
 
@@ -798,9 +824,21 @@ The dashboard uses mDNS (via `bonjour-service`) for zero-config server discovery
 ### Server Selector UI
 - The header dropdown shows persisted known servers (from config) plus localhost, not raw mDNS results
 - Each entry shows label (or hostname), host:port, Local/Remote badge, and availability status
-- Non-current servers are probed via health check when the dropdown opens
-- Switching closes the current WebSocket and connects to the selected server
-- Last-used server persisted in `localStorage` (`pi-dashboard-last-server`)
+- **Probe lifecycle**: availability is probed via `/api/health` **only when the dropdown opens** — once per open. No mount probe, no timer, no probing while the dropdown is closed. Current-server status is derived from the live WebSocket state, not a separate probe.
+- **Unreachable entries** are rendered with `opacity-50`, `cursor-not-allowed`, and the `disabled` attribute set; clicks are no-ops. To re-probe, close and reopen the dropdown. The transactional switch (below) still protects against races between the last probe and a click on a reachable entry.
+- Last-used server persisted in `localStorage` (`pi-dashboard-last-server`) — **only after** a successful switch (see transactional switching below).
+
+### Transactional Server Switching
+Switching servers is a two-phase transaction that never destructs state before verifying the target is reachable. Implemented by `performServerSwitch` (`packages/client/src/lib/server-switch.ts`) + `openStagingSocket` (`packages/client/src/lib/staging-socket.ts`):
+
+1. **Stage**: open a second ("staging") WebSocket to the target URL with a 5-second timeout. The live WebSocket stays connected.
+2. **Commit (on staging `OPEN`)**: close the staging socket, clear in-memory session/command/flow/openspec/terminal state, call `setWsUrl(newUrl)` so `useWebSocket` reconnects, and **only then** write `localStorage["pi-dashboard-last-server"]`.
+3. **Abort (on staging error/timeout)**: close the staging socket, show a toast "Couldn't reach &lt;host&gt;", leave the live connection and state untouched. localStorage is not written — so a subsequent refresh still recovers the last-known-good server.
+
+An `inFlightSwitchKey` ref guards against duplicate clicks; the clicked dropdown entry renders a spinner while staging is in progress. The `POST /api/config { lastServer }` fire-and-forget call was removed as dead weight (no consumer read the field).
+
+### Connection Status Banner
+`ConnectionStatusBanner` (`packages/client/src/components/ConnectionStatusBanner.tsx`) mounts above `<MobileShell>`. It shows "Disconnected from &lt;host&gt;. Retrying…" when the active WebSocket has been non-`OPEN` for more than 3 seconds continuously. The threshold is implemented via `setTimeout` cleared on any return-to-`OPEN` or unmount, so brief reconnects (laptop sleep, wifi hiccup) never flash the banner. During an in-flight staging switch the banner is suppressed — the live socket is still open, so no disconnection has actually occurred.
 
 ### Server Management (Settings Panel)
 - **Known Servers section**: lists persisted servers with remove buttons and an inline add form (host, port, label)
@@ -1022,6 +1060,22 @@ Every external binary, module, and directory the dashboard depends on is resolve
 | `pi-coding-agent` | module | override → bare-import → managed (`MANAGED_DIR/node_modules/.../dist/index.js`) → npm-global; probes both `@mariozechner/*` and `@oh-my-pi/*` aliases |
 | `openspec`, `npm`, `node`, `tsx`, `git`, `zrok` | binary | override → managed → where |
 | `pi-dashboard` | module | override → managed → npm-global (presence of `package.json` is enough) |
+| `electron` | module | override → bare-import (`paths: ["packages/electron"]`) → managed; resolves the package directory containing `install.js`, hoist-aware. See change: register-build-time-tools |
+| `node-pty` | module | override → bare-import; resolves the package directory containing `prebuilds/`. See change: register-build-time-tools |
+
+### Build-time consumers (shell-callable wrapper)
+
+CI workflows, Dockerfiles, and root-level postinstall scripts cannot import the shared package's TypeScript directly — those run before any TS build has fired (or, for postinstall, before the shared package is even unpacked). For these consumers, `packages/shared/bin/pi-dashboard-resolve-tool.cjs` provides a CommonJS, dependency-free shell wrapper that mirrors the registry's `override` + `bare-import` strategies for the build-time tool subset (`electron`, `node-pty`):
+
+```bash
+# Resolve a build-time tool from any shell context
+ELECTRON_DIR=$(node packages/shared/bin/pi-dashboard-resolve-tool.cjs electron)
+cd "$ELECTRON_DIR" && node install.js
+```
+
+The wrapper is used by `.github/workflows/publish.yml` (linux/arm64 native rebuild) and `packages/electron/scripts/Dockerfile.build` (Docker cross-platform native rebuild). The root postinstall `scripts/fix-pty-permissions.cjs` reimplements the same `bare-import` semantics inline (it cannot shell out because it runs DURING `npm install`).
+
+Reintroduction of hardcoded `node_modules/<dep>` paths in any of these sites is blocked by the lint test at `packages/shared/src/__tests__/no-hardcoded-node-modules-paths.test.ts`.
 
 ### Resolution record
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-agent-dashboard",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Web dashboard for monitoring and interacting with pi agent sessions",
   "repository": {
     "type": "git",
@@ -66,9 +66,9 @@
     "screenshots": "npm --prefix site run screenshots"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-extension": "^0.4.0",
-    "@blackbelt-technology/pi-dashboard-server": "^0.4.0",
-    "@blackbelt-technology/pi-dashboard-web": "^0.4.0"
+    "@blackbelt-technology/pi-dashboard-extension": "^0.4.1",
+    "@blackbelt-technology/pi-dashboard-server": "^0.4.1",
+    "@blackbelt-technology/pi-dashboard-web": "^0.4.1"
   },
   "devDependencies": {
     "jsdom": "^29.0.2",
@@ -83,7 +83,7 @@
     "@oh-my-pi/pi-ai": "*",
     "@oh-my-pi/pi-coding-agent": "*",
     "@oh-my-pi/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": {
@@ -103,6 +103,9 @@
     },
     "@oh-my-pi/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   }
 }

package/packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-extension",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Pi bridge extension for pi-dashboard",
   "type": "module",
   "publishConfig": {
@@ -19,12 +19,13 @@
     ".pi/skills/pi-dashboard/"
   ],
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-shared": "^0.4.0",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.4.1",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*"
+    "@mariozechner/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": {
@@ -36,6 +37,7 @@
   },
   "devDependencies": {
     "@mariozechner/pi-tui": "*",
-    "@types/ws": "^8.18.1"
+    "@types/ws": "^8.18.1",
+    "typebox": "^1.1.33"
   }
 }

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

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 
 // Mock modules before importing
-vi.mock("@sinclair/typebox", () => ({
+vi.mock("typebox", () => ({
   Type: {
     Object: vi.fn(() => ({})),
     String: vi.fn(() => ({})),
@@ -44,20 +44,37 @@ describe("registerAskUserTool", () => {
     expect(tool.promptGuidelines.length).toBeGreaterThan(0);
   });
 
+  it("description instructs agents not to add a Select all option", () => {
+    const pi = createMockPi();
+    registerAskUserTool(pi as any);
+    const tool = pi.registerTool.mock.calls[0][0];
+    expect(tool.description).toMatch(/UI provides a Select all/i);
+  });
+
   describe("message passthrough", () => {
     function getToolAndMockCtx() {
       const pi = createMockPi();
       registerAskUserTool(pi as any);
       const tool = pi.registerTool.mock.calls[0][0];
+      // `custom` stands in for the multiselect polyfill: it invokes the factory
+      // with a `done` callback; the factory-returned component exposes
+      // onConfirm/onCancel. We auto-confirm with ["A"] to preserve the legacy
+      // mock return value that the multiselect assertions expected.
+      const custom = vi.fn().mockImplementation(async (factory: any) => {
+        return await new Promise<unknown>((resolve) => {
+          const component: any = factory({}, {}, {}, (r: unknown) => resolve(r));
+          component?.onConfirm?.(["A"]);
+        });
+      });
       const ctx = {
         ui: {
           confirm: vi.fn().mockResolvedValue(true),
           select: vi.fn().mockResolvedValue("A"),
           input: vi.fn().mockResolvedValue("hello"),
-          multiselect: vi.fn().mockResolvedValue(["A"]),
+          custom,
         },
       };
-      return { tool, ctx };
+      return { tool, ctx, custom };
     }
 
     it("passes message through opts for input", async () => {
@@ -72,10 +89,19 @@ describe("registerAskUserTool", () => {
       expect(ctx.ui.select).toHaveBeenCalledWith("Pick", ["A", "B"], { message: "Context" });
     });
 
-    it("passes message through opts for multiselect", async () => {
+    it("dispatches multiselect through the polyfill via ctx.ui.custom", async () => {
       const { tool, ctx } = getToolAndMockCtx();
-      await tool.execute("id", { method: "multiselect", title: "Multi", message: "Info", options: ["A"] }, undefined, undefined, ctx);
-      expect(ctx.ui.multiselect).toHaveBeenCalledWith("Multi", ["A"], { message: "Info" });
+      const result = await tool.execute(
+        "id",
+        { method: "multiselect", title: "Multi", message: "Info", options: ["A"] },
+        undefined,
+        undefined,
+        ctx,
+      );
+      // Polyfill routes via custom(factory); multiselect is not called directly.
+      expect(ctx.ui.custom).toHaveBeenCalledTimes(1);
+      expect(result.details.method).toBe("multiselect");
+      expect(result.details.result).toEqual(["A"]);
     });
 
     it("does not pass opts when message is undefined", async () => {
@@ -123,7 +149,7 @@ describe("registerAskUserTool", () => {
       await expect(
         tool.execute("id", { method: "multiselect", title: "Pick" }, undefined, undefined, ctx),
       ).rejects.toThrow(/options/i);
-      expect(ctx.ui.multiselect).not.toHaveBeenCalled();
+      expect(ctx.ui.custom).not.toHaveBeenCalled();
     });
   });
 
@@ -311,12 +337,18 @@ describe("registerAskUserTool", () => {
       const pi = createMockPi();
       registerAskUserTool(pi as any);
       const tool = pi.registerTool.mock.calls[0][0];
+      const custom = vi.fn().mockImplementation(async (factory: any) => {
+        return await new Promise<unknown>((resolve) => {
+          const component: any = factory({}, {}, {}, (r: unknown) => resolve(r));
+          component?.onConfirm?.(["A"]);
+        });
+      });
       const ctx = {
         ui: {
           confirm: vi.fn().mockResolvedValue(true),
           select: vi.fn().mockResolvedValue("A"),
           input: vi.fn().mockResolvedValue("hello"),
-          multiselect: vi.fn().mockResolvedValue(["A"]),
+          custom,
         },
       };
       return { tool, ctx };

package/packages/extension/src/__tests__/bridge-entry-id-pi-070.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Tests for the bridge entryId stamping under pi 0.70.x's emit-then-await-then-append
+ * ordering. Pi 0.70.x's _processAgentEvent does (paraphrased):
+ *
+ *   await this._emitExtensionEvent(event);       // <-- bridge runs here, awaited
+ *   this._emit(event);                           // sync legacy listeners
+ *   if (event.type === "message_end") {
+ *     sessionManager.appendMessage(event.message); // <-- entry id GENERATED HERE
+ *   }
+ *
+ * The bridge's old `queueMicrotask` deferral resolves INSIDE the awaited dispatcher,
+ * before appendMessage runs — so getLeafId() still returns the previous leaf. The fix
+ * is `setTimeout(0)` (macrotask) so the entire await chain unwinds and appendMessage
+ * runs first; OR reading `event.message.id` after pi mutates it in-place.
+ *
+ * This test simulates that ordering and asserts the correct mechanisms.
+ */
+import { describe, it, expect } from "vitest";
+
+interface SimMessage {
+  role: string;
+  content: string;
+  id?: string;
+}
+
+/**
+ * Simulate pi 0.70.x's _processAgentEvent ordering. Returns a promise that
+ * resolves when the entire event has been processed (including appendMessage).
+ *
+ * The `bridgeHandler` is registered as an "extension handler" — runs awaited
+ * inside _emitExtensionEvent. It receives the event and a pseudo-ctx with
+ * sessionManager.getLeafId().
+ */
+async function simulatePi070Emit(opts: {
+  event: { type: string; message: SimMessage };
+  state: { leafId: string; nextId: string };
+  appendMessage: (msg: SimMessage) => string; // returns the new id
+  bridgeHandler: (event: any, ctx: any) => Promise<void> | void;
+}): Promise<void> {
+  const ctx = {
+    sessionManager: { getLeafId: () => opts.state.leafId },
+  };
+
+  // Step 1: await _emitExtensionEvent — runs the bridge handler awaited.
+  await opts.bridgeHandler(opts.event, ctx);
+
+  // Step 2: _emit (sync legacy listeners) — no-op in this simulation.
+
+  // Step 3: persistence on message_end.
+  if (opts.event.type === "message_end") {
+    const id = opts.appendMessage(opts.event.message);
+    opts.state.leafId = id;
+  }
+}
+
+describe("pi 0.70 emit/append ordering", () => {
+  it("queueMicrotask deferral DOES NOT capture the post-persist id (the bug)", async () => {
+    const state = { leafId: "prev", nextId: "new-id-42" };
+    let captured: string | undefined;
+
+    const buggyBridge = async (event: any, ctx: any) => {
+      // What the OLD bridge does today:
+      await new Promise<void>((resolve) => queueMicrotask(resolve));
+      captured = ctx.sessionManager.getLeafId();
+    };
+
+    await simulatePi070Emit({
+      event: { type: "message_end", message: { role: "assistant", content: "hi" } },
+      state,
+      appendMessage: (m) => {
+        m.id = state.nextId;
+        return state.nextId;
+      },
+      bridgeHandler: buggyBridge,
+    });
+
+    // Bug: captured is the previous leaf, NOT the just-appended id.
+    expect(captured).toBe("prev");
+    expect(captured).not.toBe("new-id-42");
+  });
+
+  it("setTimeout(0) deferral DOES capture the post-persist id (the fix)", async () => {
+    const state = { leafId: "prev", nextId: "new-id-42" };
+    let capturedFromGetLeafId: string | undefined;
+    let capturedFromMessageId: string | undefined;
+    let sendDone!: () => void;
+    const sendCompleted = new Promise<void>((r) => { sendDone = r; });
+
+    // The bridge schedules and returns synchronously — the only way the
+    // awaited dispatcher can unwind so appendMessage runs before the timeout.
+    const fixedBridge = (event: any, ctx: any) => {
+      setTimeout(() => {
+        capturedFromMessageId = (event.message as any).id;
+        capturedFromGetLeafId = ctx.sessionManager.getLeafId();
+        sendDone();
+      }, 0);
+    };
+
+    await simulatePi070Emit({
+      event: { type: "message_end", message: { role: "assistant", content: "hi" } },
+      state,
+      appendMessage: (m) => {
+        m.id = state.nextId;
+        return state.nextId;
+      },
+      bridgeHandler: fixedBridge,
+    });
+    await sendCompleted;
+
+    // Both signals should now point at the just-persisted entry.
+    expect(capturedFromMessageId).toBe("new-id-42");
+    expect(capturedFromGetLeafId).toBe("new-id-42");
+  });
+
+  it("WeakMap-on-appendMessage captures the id even before the macrotask", async () => {
+    const state = { leafId: "prev", nextId: "new-id-77" };
+    const idByMessage = new WeakMap<object, string>();
+    const wrappedAppend = (m: SimMessage): string => {
+      m.id = state.nextId;
+      idByMessage.set(m as object, m.id);
+      return m.id;
+    };
+
+    let viaWeakMap: string | undefined;
+    let viaMutation: string | undefined;
+    let sendDone!: () => void;
+    const sentP = new Promise<void>((r) => { sendDone = r; });
+
+    // CRITICAL: bridge SCHEDULES the send and RETURNS IMMEDIATELY.
+    // It does NOT await its own setTimeout — that would keep the
+    // outer dispatcher awaiting and we'd be back to the queueMicrotask
+    // bug (timeout fires before appendMessage).
+    const fixedBridge = (event: any) => {
+      setTimeout(() => {
+        viaMutation = (event.message as any).id;
+        viaWeakMap = idByMessage.get(event.message as object);
+        sendDone();
+      }, 0);
+      // Return synchronously — let the awaited dispatcher unwind.
+    };
+
+    await simulatePi070Emit({
+      event: { type: "message_end", message: { role: "assistant", content: "hi" } },
+      state,
+      appendMessage: wrappedAppend,
+      bridgeHandler: fixedBridge,
+    });
+    await sentP;
+
+    expect(viaMutation).toBe("new-id-77");
+    expect(viaWeakMap).toBe("new-id-77");
+  });
+
+  it("user message_start has NO id (pi defers user persistence to message_end)", async () => {
+    const state = { leafId: "prev-assistant", nextId: "new-user-id" };
+    let captured: string | undefined;
+
+    const fixedBridge = async (event: any) => {
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      captured = (event.message as any).id; // still undefined for message_start
+    };
+
+    await simulatePi070Emit({
+      event: { type: "message_start", message: { role: "user", content: "hello" } },
+      state,
+      appendMessage: () => state.nextId, // not called for message_start
+      bridgeHandler: fixedBridge,
+    });
+
+    // No id available at message_start time — must rely on entry_persisted
+    // back-fill (delivered when the message_end of the SAME message fires later).
+    expect(captured).toBeUndefined();
+  });
+});

package/packages/extension/src/__tests__/event-forwarder.test.ts

@@ -74,6 +74,36 @@ describe("mapEventToProtocol", () => {
     expect(result.event.data).toEqual(piEvent);
   });
 
+  it("should map an entry_persisted event (per fix-per-message-fork)", () => {
+    const piEvent = {
+      type: "entry_persisted",
+      entryId: "abc-123",
+      nonce: "n-7",
+    };
+    const result = mapEventToProtocol(sessionId, piEvent);
+    expect(result.type).toBe("event_forward");
+    expect(result.sessionId).toBe(sessionId);
+    expect(result.event.eventType).toBe("entry_persisted");
+    expect(result.event.data).toMatchObject({
+      type: "entry_persisted",
+      entryId: "abc-123",
+      nonce: "n-7",
+    });
+  });
+
+  it("should map a message_end event with nonce (per fix-per-message-fork)", () => {
+    const piEvent = {
+      type: "message_end",
+      message: { role: "assistant", content: "hi", id: "asst-9" },
+      entryId: "asst-9",
+      nonce: "n-7",
+    };
+    const result = mapEventToProtocol(sessionId, piEvent);
+    expect(result.event.eventType).toBe("message_end");
+    expect((result.event.data as any).nonce).toBe("n-7");
+    expect((result.event.data as any).entryId).toBe("asst-9");
+  });
+
   it("should strip non-serializable fields", () => {
     const piEvent = {
       type: "test_event",