@blackbelt-technology/pi-agent-dashboard 0.2.8 → 0.3.0

package/docs/architecture.md

@@ -1,5 +1,12 @@
 # PI Dashboard Architecture
 
+> **Adjacent artifact:** the public marketing site lives at `/site` and is
+> product-adjacent, not part of the dashboard runtime. It has its own Astro
+> build, its own Playwright screenshot pipeline, and its own GitHub Pages
+> deploy workflow (`.github/workflows/deploy-site.yml`). See
+> `/site/README.md` for details.
+
+
 ## Overview
 
 The PI Dashboard is a web-based dashboard for monitoring and interacting with pi agent sessions. It consists of three components:
@@ -75,6 +82,7 @@ A React-based responsive web UI that:
 - Provides command autocomplete with `/` prefix
 - Supports bidirectional interaction (send prompts, run commands)
 - Works on mobile with responsive layout and swipe gestures
+- Shows an onboarding `LandingPage` whenever the main pane is empty, narrating the three steps needed to go from install → first running session (Setup credentials → Add folder → Start session). Each step is a card in **pending**, **done**, or **locked** state, derived purely from client state: `useProvidersReady()` (from `GET /api/providers`), `pinnedDirectories.length`, and `sessions.size`. Satisfied steps collapse to single-line ✔ rows, so returning users see a compact status strip rather than a full onboarding wall. The `PinDirectoryDialog` used by Step ② is mounted once at the app root in `App.tsx` and shared with the sidebar "Add folder" button via a single `onOpenPinDialog` callback.
 
 ### 4. Shared Types (`src/shared/`)
 TypeScript type definitions shared across all components:
@@ -226,10 +234,45 @@ When a user sends a prompt to an ended session, the server automatically resumes
 3. Changes are broadcast to all connected browsers via `openspec_update { cwd, data }`
 4. Browsers can request immediate refresh via `openspec_refresh { cwd }`
 5. New directories (pinned or from new sessions) trigger immediate discovery + polling
+6. Each `OpenSpecChange` carries an optional `isComplete?: boolean` field forwarded straight through from `openspec status --change <name> --json`. It indicates artifact-authoring completeness only — orthogonal to the task tally — and never feeds `deriveChangeState`. The dashboard uses it solely to gate the **Archive anyway** escape hatch (see “OpenSpec session card”).
+
+### OpenSpec session card UI
+
+The attached-change row on every session card has four affordances driven by the polled `OpenSpecChange`:
+
+- **State pill** — `StatePill.tsx` renders `deriveChangeState(change)` as a small color-coded pill (`PLANNING`=zinc, `READY`=blue, `IMPLEMENTING`=amber, `COMPLETE`=green) next to the `📋 <name>` badge. Hidden when the attached change isn't present in OpenSpec data (e.g. archived under another name).
+- **Tasks popover** — a `Tasks N/M` action button appears whenever the change has at least one parseable task. Clicking opens `TasksPopover.tsx`, a portal-rendered popover that lists every `- [ ] / - [x]` line in `tasks.md`, grouped by `## ` heading, with native checkboxes. Toggling a checkbox issues an optimistic `POST /api/openspec/tasks/toggle`; HTTP 409 (the file changed under us) refetches and surfaces a “File changed — please try again” banner. After every successful toggle the server re-polls openspec for that cwd and broadcasts the standard `openspec_update`, so card counts (`30/33` → `31/33`) refresh without a manual reload.
+- **Archive anyway** — when `state === IMPLEMENTING && change.isComplete === true && allArtifactsDone`, an overflow `⋯` button appears on the action row. The single menu item opens a `ConfirmDialog` reading `"<unchecked> of <total> tasks are unchecked. Archive anyway?"`. Confirming dispatches `/opsx:archive <name>` through the normal `onSendPrompt` path. The default Apply button is unaffected; this is purely an escape hatch for changes whose remaining tasks are manual-verification items the user owns.
+- **Bulk Archive relocation** — the Bulk Archive button now appears **only on unattached sessions** that have at least one folder change with `status === "complete"`. It is removed from the attached-session action row to free up space; the folder-level Bulk Archive in `FolderOpenSpecSection` is unchanged.
+
+**Server endpoints (localhost-guarded, registered alongside the existing openspec routes in `packages/server/src/routes/openspec-routes.ts`):**
+
+- `GET /api/openspec/tasks?cwd=<abs>&change=<name>` — parses `<cwd>/openspec/changes/<name>/tasks.md` via `parseTasksMarkdown` (top-level `- [ ] <id> <text>` / `- [x] <id> <text>` only; everything else is ignored). Returns `{ success: true, data: { tasks: OpenSpecTask[], groups: string[] } }`. 404 when the file is missing, 403 when the network guard denies.
+- `POST /api/openspec/tasks/toggle` — body `{ cwd, change, id, done, line }`. Reads the file, validates that `line` still contains the requested `id` and the *opposite* state (optimistic-concurrency check), rewrites only that one line's `[ ]`/`[x]` marker, and atomic-writes via `tmp + rename` so other lines are preserved byte-for-byte. Maps typed errors to HTTP: `NotFoundError` → 404, `LineMismatchError` → 409, `NotACheckboxError` → 400. On success, fires a fire-and-forget `directoryService.refreshOpenSpec(cwd)` followed by an `openspec_update` broadcast.
 
 ### File Read API
 The server exposes `GET /api/file?cwd=...&path=...` for reading files or listing directories from session working directories. Guards: localhost-only, cwd must match a known session, resolved path must stay inside cwd. Returns `{ type: "file", content }` or `{ type: "directory", entries }`.
 
+### Filesystem Browser (PathPicker)
+
+The dashboard's reusable directory chooser (`PathPicker`) is backed by two localhost-only endpoints:
+
+- `GET /api/browse?path=<dir>&q=<query>` — lists subdirectories of `<dir>` (or `$HOME` when omitted), with `.git` / `.pi` detection. When `q` is non-empty, entries are case-insensitive substring-filtered and ranked:
+  - **Tier 0** exact match → **Tier 1** prefix → **Tier 2** word-boundary substring (after `-`, `_`, `.`, space, `/`) → **Tier 3** plain substring.
+  - Alphabetical within each tier. The 200-entry cap is applied **after** filter+rank so best matches always survive truncation.
+- `POST /api/browse/mkdir` body `{ parent, name }` — creates a new directory non-recursively (`fs.mkdir` without `recursive: true`). Name validation rejects `/`, `\`, `\0`, `.`, `..`, empty, and leading/trailing whitespace. Errors map to 400 (`invalid name`, `parent is not a directory`), 404 (`parent not found`), 409 (`already exists`).
+
+Client-side, `PathPicker` debounces the `q` request at 150ms and cancels in-flight requests via `AbortController`. Enter/Select follow a strict state machine instead of confirming arbitrary input:
+
+1. Exact case-insensitive match against a visible entry → `onSelect(<entry.path>)` + close.
+2. Input ends with `/` and its parsed parent equals the fetched directory → `onSelect(inputValue)` + close.
+3. Exactly one filtered candidate → complete to `<path>/` (do not close).
+4. Otherwise → no-op with a 300ms red-border flash.
+
+If a debounced query is still pending when Enter fires, the client flushes it synchronously before evaluating the rules so the freshest server result is considered.
+
+New folders can be created from two entry points — a footer **＋ New folder** button (inline name entry), or an inline **＋ Create "<name>" here** row shown when the typed partial has no exact match. The create-here row is suppressed if the parsed parent differs from the last-successfully-fetched directory (prevents creating inside a stale parent after a mid-path typo). On success the picker refetches and descends into the new directory.
+
 ### Pi Resources Browser
 
 The dashboard can display pi extensions, skills, and prompts installed for each workspace. The server-side scanner (`pi-resource-scanner.ts`) discovers resources from three sources:
@@ -255,6 +298,16 @@ Metadata is parsed from SKILL.md YAML frontmatter (`name`, `description`), promp
 
 Package operations use pi's `DefaultPackageManager` API on the server, serialized (one at a time, 409 on concurrent). Progress events are forwarded to browsers via `package_progress` WebSocket messages. After any successful operation, the server sends `/reload` to all connected pi sessions.
 
+**Pi Core Version Check (separate from extension management):**
+- `GET /api/pi-core/versions[?refresh=true]` — returns `PiCoreStatus` with all discovered pi ecosystem CLI packages (pi itself, pi-dashboard, pi-model-proxy, bare `pi-*` and scoped `@x/pi-*`), their installed version, latest npm-registry version, `updateAvailable` flag, and `installSource` (`"global"` via `npm list -g --depth=0 --json` vs `"managed"` in `~/.pi-dashboard/node_modules/`). Cached 5 min.
+- `POST /api/pi-core/update` with `{ packages?: string[] }` — updates the listed packages, or all packages with `updateAvailable` when omitted. Runs `npm update -g <pkg>` (global) or `npm update <pkg>` in `~/.pi-dashboard/` (managed). Shares the `PackageManagerWrapper.runExclusive()` busy-lock with extension operations — returns 409 on contention.
+
+Why a separate system? Pi's `DefaultPackageManager` only manages packages listed in `settings.json packages[]` (extensions/skills/prompts/themes). The pi CLI binary itself and the dashboard server package are installed directly via `npm -g` (or into `~/.pi-dashboard/` in the Electron case) and are invisible to pi's manager. `PiCoreChecker` + `PiCoreUpdater` (`pi-core-checker.ts` + `pi-core-updater.ts`) fill that gap.
+
+Progress for core updates is delivered via typed `pi_core_update_progress` / `pi_core_update_complete` browser-protocol messages (not the `package_progress` channel) and fanned out to `PiCoreVersionsSection` and `PiUpdateBadge` via a `pi-core-event` DOM event. After any successful core update the server sends `/reload` to connected pi sessions just like extension updates.
+
+**Header badge**: `PiUpdateBadge` polls `/api/pi-core/versions` on mount + every 30 min. When `updatesAvailable > 0` it renders a small pill-shaped button next to the `ServerSelector` that navigates to `/settings?tab=packages`.
+
 **Client navigation stack:**
 - Puzzle icon button in folder header → PiResourcesView (content area, "Installed" / "Packages" tabs)
 - "View" button on resource → MarkdownPreviewView (`.md` as markdown, `.ts` as code block)
@@ -429,18 +482,42 @@ The tunnel is **enabled by default** (`tunnel.enabled: true`). When the server s
 
 1. **Binary detection** — `detectZrokBinary()` checks if `zrok` is on PATH via `which`/`where`
 2. **Environment check** — `loadZrokEnv()` reads zrok's own config (`~/.zrok2/environment.json` or `~/.zrok/environment.json`) to verify enrollment. The dashboard never stores zrok API keys — they live entirely in zrok's config directory, created by `zrok enable <token>`.
-3. **Stale cleanup** — `cleanupStaleZrok()` reads `~/.pi/dashboard/zrok.pid`, kills orphaned zrok processes from previous crashes
-4. **Reserved share** — If `tunnel.reservedToken` is not set, `zrok reserve public` is called to create a persistent share token. The token is saved to config so the URL stays the same across restarts. If a saved token fails (e.g., expired), a new reservation is created automatically.
-5. **Subprocess spawn** — `createTunnel(port, reservedToken?)` spawns `zrok share reserved <token> --headless` (or `zrok share public --headless` as fallback) as a child process
-6. **URL parsing** — The public URL is parsed from stdout/stderr (30s timeout)
+3. **Stale cleanup** — Runs **unconditionally on startup** whenever the zrok binary is present (even in `--no-tunnel` mode) so leftovers from a previous run are always swept:
+   - `cleanupStaleZrok()` reads `~/.pi/dashboard/zrok.pid` and SIGTERMs the tracked process
+   - `scavengeOrphanZrokProcesses(port)` scans `ps -ax` for any `zrok share … --override-endpoint http://localhost:<port>` processes that escaped pid-file tracking (previous crashes, failed retries) and SIGTERMs them. Never kills the current process.
+4. **Reserved share** — If `tunnel.reservedToken` is not set, `zrok reserve public` is called to create a persistent share token. The token is saved to config so the URL stays the same across restarts. If a saved token fails (e.g., expired or orphaned on the zrok edge), `releaseShare(token)` explicitly releases it and a new reservation is created automatically (capped at 1 retry to prevent cascades).
+5. **Subprocess spawn** — `createTunnel(port, reservedToken?)` spawns `zrok share reserved <token> --headless` (or `zrok share public --headless` as fallback) as a child process. Concurrent calls are serialized via an in-flight promise (`pendingCreate`) so a UI double-click or a race between startup auto-connect and `/api/tunnel-connect` can’t create two parallel reservations.
+6. **URL parsing** — The public URL is parsed from stdout/stderr (30s timeout). On timeout: SIGTERM → SIGKILL after 2s grace, plus `releaseShare(token)` if the token was reserved just-in-time within the call (prevents leaking a dead reservation that would leave a "live but broken" URL on the zrok edge).
 7. **PID tracking** — The subprocess PID is written to `~/.pi/dashboard/zrok.pid`
-8. **Shutdown** — `deleteTunnel()` kills the subprocess and removes the PID file. The reserved token is preserved for next restart.
+8. **Shutdown** — `deleteTunnel(port?)` SIGTERMs the active subprocess, removes the PID file, and (when `port` is supplied) re-runs `scavengeOrphanZrokProcesses(port)` as belt-and-braces cleanup. The reserved token is preserved for next restart. Called from graceful shutdown, `/api/shutdown`, `/api/restart`, and `/api/tunnel-disconnect`.
 
-To disable: set `tunnel.enabled` to `false` in `~/.pi/dashboard/config.json` or pass `--no-tunnel` on the CLI.
+To disable: set `tunnel.enabled` to `false` in `~/.pi/dashboard/config.json` or pass `--no-tunnel` on the CLI. When disabled, step 3 still runs so orphan processes are cleaned up even if the tunnel is turned off.
 
 The client can query `GET /api/tunnel-status` which returns `{ status: "active"|"inactive"|"unavailable", url?, serverOs }`.
 The client can connect/disconnect the tunnel via `POST /api/tunnel-connect` and `POST /api/tunnel-disconnect`.
 
+
+
+### CORS
+
+The Fastify CORS callback in `server.ts` allows:
+
+- Same-origin navigations (no `Origin` header).
+- `localhost`, `127.0.0.1`, `[::1]` on any port.
+- The currently-active zrok tunnel URL (looked up dynamically via `getTunnelUrl()` so URL rotation picks up without a restart).
+- Any `*.share.zrok.io` host (covers stale tabs, new reservations, and the brief window before `activeTunnelUrl` is populated on startup).
+- Explicitly-configured `corsAllowedOrigins` from config.
+
+On a mismatch the callback returns `cb(null, false)` — **not** `cb(new Error(…), false)`. The `Error` form causes `@fastify/cors` to surface the error as HTTP 500 on every asset response, which is exactly what caused the long-running “zrok returns 500 on assets” debugging saga: Vite emits `<script type="module" crossorigin>` entry tags, which per HTML spec browsers always fetch in CORS mode (even same-origin), so the tunnel URL appearing in `Origin` is unavoidable. Returning `cb(null, false)` simply omits CORS headers; the browser enforces same-origin policy on its own.
+
+### HTTP Compression
+
+The Fastify server registers `@fastify/compress` globally with `gzip` + `deflate` encodings (threshold 1 KB). Brotli is intentionally **not** enabled — zrok’s free public proxy has been observed to truncate/stream-reset `content-encoding: br` responses under parallel browser load (curl succeeds, Chrome reports `ERR_ABORTED 500`). gzip round-trips cleanly through zrok and is universally supported.
+
+Additionally, the client build generates `.gz` sibling files (via `packages/client/scripts/precompress.mjs`, run from the `build` / `prepare` scripts) and `@fastify/static` is registered with `preCompressed: true`. This serves pre-compressed assets directly with a stable `Content-Length` header, avoiding any streaming-compression edge cases in intermediate HTTP/2 proxies. Dynamic compression via `@fastify/compress` still handles API responses and other non-file routes.
+
+Combined with client bundle splitting (see `packages/client/vite.config.ts` → `rollupOptions.output.manualChunks`), the main initial chunk ships at ~150 KB gzipped (down from 3.1 MB uncompressed), well under tunnel abort thresholds.
+
 ### PWA Support
 
 The dashboard is installable as a Progressive Web App on mobile devices:
@@ -598,6 +675,16 @@ This is separate from the main JSON dashboard WebSocket (`/ws`).
 3. Browser opens binary WS to `/ws/terminal/:id`, attaches `xterm.js`
 4. Shell exit → PTY `onExit` → server broadcasts `terminal_removed` → card removed
 
+**Native binary permissions.** `node-pty`'s prebuilt `spawn-helper` (and `pty.node`) must be executable for `pty.spawn` to succeed on macOS/Linux. Three layers of defense ensure this:
+
+1. **Postinstall** — `packages/server/scripts/fix-pty-permissions.cjs` (wired at workspace-root `postinstall`) uses `require.resolve("node-pty/package.json")` to locate the dependency wherever npm placed it and sets mode `0o755` on every `prebuilds/*/spawn-helper` and `prebuilds/*/pty.node`.
+2. **Electron bundle** — `packages/electron/scripts/bundle-server.sh` runs `find … -name spawn-helper -exec chmod +x` after `npm install` and removes macOS quarantine flags (`xattr -d com.apple.quarantine`) from native binaries.
+3. **Runtime** — `packages/server/src/fix-pty-permissions.ts` runs once when `createTerminalManager()` is called. Uses `createRequire().resolve("node-pty")` to find the actual install location and fixes any non-executable `spawn-helper`.
+
+A regression test (`packages/server/src/__tests__/fix-pty-permissions.test.ts`) asserts the current platform's helper is executable after install.
+
+**Browser-gateway error visibility.** `browser-gateway.ts` distinguishes two failure modes when receiving a WebSocket frame: a `JSON.parse` error (silently dropped — garbage frames are normal on the open internet) and an exception thrown by an individual message handler (logged to stderr as `[browser-gw] handler error type=<msg.type>: <err>`). The connection stays open after handler errors so subsequent messages still flow. This stops failures like a broken `node-pty` `spawn` from manifesting as a silently dead UI button.
+
 ### Output Buffering
 
 Each terminal maintains a 256KB ring buffer of raw PTY output. When a new WebSocket connects (reconnect, new tab), the buffer is replayed before live streaming. Combined with client-side 10,000-line scrollback.
@@ -608,7 +695,7 @@ Terminal xterm.js instances stay mounted in the DOM (CSS hidden/shown) for insta
 
 ### Folder-Scoped View
 
-Terminals are displayed in a tabbed `TerminalsView` per folder, accessed via the folder action bar's `Terminals(N)` button or `+Terminal` button. Terminal cards no longer appear in the sidebar — the sidebar shows only pi session cards. The tab bar supports switching, closing, renaming, and creating new terminals.
+Terminals are displayed in a tabbed `TerminalsView` per folder, accessed via the folder action bar's `Terminals(N)` button. Terminal cards no longer appear in the sidebar — the sidebar shows only pi session cards. The tab bar supports switching, closing, renaming, and creating new terminals.
 
 ## Embedded Editor (code-server)
 
@@ -638,6 +725,19 @@ Browser                     Dashboard Server              code-server
 
 All code-server traffic is proxied through `/editor/:id/*` on the dashboard server. This provides same-origin access (no CORS/iframe issues) and works transparently through zrok tunnels.
 
+### Orphan Cleanup
+
+`EditorManager` state is purely in-memory. On graceful shutdown, `editorManager.stopAll()` SIGTERMs every child. On non-graceful shutdown (SIGKILL, crash, OOM, force-quit), spawned code-server processes get reparented to init/launchd and continue holding their port and `--user-data-dir` lockfile.
+
+To recover, every spawn is recorded in `~/.pi/dashboard/editor-pids.json` (`editor-pid-registry.ts`). On the next server boot, `editorPidRegistry.cleanupOrphans()` runs at the top of `server.start()` (before `fastify.listen`) and:
+
+1. Reads the persisted PIDs.
+2. For each entry whose PID is alive AND whose OS-reported command line contains `--user-data-dir <~/.pi/dashboard/editors/...>`, sends `SIGTERM`.
+3. After a 1 second grace period, sends `SIGKILL` to any survivor.
+4. Rewrites the file empty.
+
+The cmdline ownership check prevents killing unrelated `code-server` instances the user may run themselves. Cleanup completes before any `POST /api/editor/start` request can be served, so a new spawn for the same folder cannot race with a surviving orphan on the same `--user-data-dir` lockfile.
+
 ### Configuration
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-agent-dashboard",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Web dashboard for monitoring and interacting with pi agent sessions",
   "repository": {
     "type": "git",
@@ -46,17 +46,22 @@
     "LICENSE"
   ],
   "scripts": {
+    "postinstall": "node packages/server/scripts/fix-pty-permissions.cjs",
     "dev": "npm run dev --workspace=@blackbelt-technology/pi-dashboard-web",
     "build": "npm run build --workspace=@blackbelt-technology/pi-dashboard-web",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "HOME=$(mktemp -d -t pi-test-XXXXXX) vitest run",
+    "test:watch": "HOME=$(mktemp -d -t pi-test-XXXXXX) vitest",
     "lint": "tsc --noEmit",
     "reload": "./scripts/reload-all.sh",
     "reload:check": "./scripts/reload-all.sh --check",
     "electron:dev": "npm run start:dev --workspace=@blackbelt-technology/pi-dashboard-electron",
     "electron:start": "npm run start --workspace=@blackbelt-technology/pi-dashboard-electron",
     "electron:make": "npm run make --workspace=@blackbelt-technology/pi-dashboard-electron",
-    "electron:build": "bash packages/electron/scripts/build-installer.sh"
+    "electron:build": "bash packages/electron/scripts/build-installer.sh",
+    "site:dev": "npm --prefix site run dev",
+    "site:build": "npm --prefix site run build",
+    "site:preview": "npm --prefix site run preview",
+    "screenshots": "npm --prefix site run screenshots"
   },
   "dependencies": {
     "@blackbelt-technology/pi-dashboard-extension": "*",

package/packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-extension",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Pi bridge extension for pi-dashboard",
   "type": "module",
   "pi": {

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

@@ -7,6 +7,8 @@ vi.mock("@sinclair/typebox", () => ({
     String: vi.fn(() => ({})),
     Optional: vi.fn((x: any) => x),
     Array: vi.fn(() => ({})),
+    Union: vi.fn(() => ({})),
+    Literal: vi.fn(() => ({})),
   },
 }));
 
@@ -100,10 +102,28 @@ describe("registerAskUserTool", () => {
       expect(ctx.ui.select).toHaveBeenCalledWith("Pick", ["A", "B"], undefined);
     });
 
-    it("handles malformed options string gracefully", async () => {
+    it("throws when select reaches execute with unparseable options string", async () => {
       const { tool, ctx } = getToolAndMockCtx();
-      await tool.execute("id", { method: "select", title: "Pick", options: "not json" }, undefined, undefined, ctx);
-      expect(ctx.ui.select).toHaveBeenCalledWith("Pick", [], undefined);
+      await expect(
+        tool.execute("id", { method: "select", title: "Pick", options: "not json" }, undefined, undefined, ctx),
+      ).rejects.toThrow(/options/i);
+      expect(ctx.ui.select).not.toHaveBeenCalled();
+    });
+
+    it("throws when select is invoked with empty options array", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      await expect(
+        tool.execute("id", { method: "select", title: "Pick", options: [] }, undefined, undefined, ctx),
+      ).rejects.toThrow(/options.*input/is);
+      expect(ctx.ui.select).not.toHaveBeenCalled();
+    });
+
+    it("throws when multiselect is invoked without options", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      await expect(
+        tool.execute("id", { method: "multiselect", title: "Pick" }, undefined, undefined, ctx),
+      ).rejects.toThrow(/options/i);
+      expect(ctx.ui.multiselect).not.toHaveBeenCalled();
     });
   });
 
@@ -131,5 +151,282 @@ describe("registerAskUserTool", () => {
       const result = tool.prepareArguments({ method: "select", title: "Pick", options: "not json" });
       expect(result.options).toBe("not json");
     });
+
+    it("unwraps stringified params wrapper", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "select",
+        params: '{"title":"X","options":["a","b"]}',
+      });
+      expect(result.method).toBe("select");
+      expect(result.title).toBe("X");
+      expect(result.options).toEqual(["a", "b"]);
+      expect(result.params).toBeUndefined();
+    });
+
+    it("unwraps object-form params wrapper", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "select",
+        params: { title: "X", options: ["a", "b"] },
+      });
+      expect(result.method).toBe("select");
+      expect(result.title).toBe("X");
+      expect(result.options).toEqual(["a", "b"]);
+      expect(result.params).toBeUndefined();
+    });
+
+    it("copies question into title when title is absent", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({ method: "input", question: "Your name?" });
+      expect(result.title).toBe("Your name?");
+    });
+
+    it("does not overwrite explicit title with question", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({ method: "input", title: "T", question: "Q" });
+      expect(result.title).toBe("T");
+    });
+
+    it("top-level fields win over params wrapper", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "select",
+        title: "OuterTitle",
+        params: { title: "InnerTitle", options: ["a", "b"] },
+      });
+      expect(result.title).toBe("OuterTitle");
+      expect(result.options).toEqual(["a", "b"]);
+    });
+
+    it("rescues options JSON string inside params wrapper", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "select",
+        params: '{"title":"X","options":"[\\"a\\",\\"b\\"]"}',
+      });
+      expect(result.options).toEqual(["a", "b"]);
+    });
+
+    // ── batch rescue ────────────────────────────────────────────────
+
+    it("parses stringified questions array and synthesizes method=batch", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        questions:
+          '[{"title":"Pick","method":"select","options":["a","b"]}]',
+      });
+      expect(result.method).toBe("batch");
+      expect(Array.isArray(result.questions)).toBe(true);
+      expect(result.questions).toHaveLength(1);
+      expect(result.title).toBe("Pick");
+    });
+
+    it("backfills missing outer title on explicit method=batch call", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "batch",
+        questions: [
+          { method: "confirm", question: "Proceed?" },
+          { method: "select", question: "Scope?", options: ["A", "B"] },
+        ],
+      });
+      expect(result.title).toBe("Proceed?");
+      expect(result.questions[0].title).toBe("Proceed?"); // sub-question rename also fired
+      expect(result.questions[1].title).toBe("Scope?");
+    });
+
+    it("bare questions array with no method synthesizes method=batch and pulls title", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        questions: [{ method: "confirm", title: "Proceed?" }],
+      });
+      expect(result.method).toBe("batch");
+      expect(result.title).toBe("Proceed?");
+    });
+
+    it("pulls title from question or header if sub-question lacks title", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        questions: [{ method: "input", question: "Your name?" }],
+      });
+      expect(result.method).toBe("batch");
+      expect(result.title).toBe("Your name?");
+    });
+
+    it("flattens input_type wrapper inside a sub-question", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "batch",
+        title: "T",
+        questions: [
+          {
+            title: "Pick",
+            input_type: { method: "select", options: ["a", "b"] },
+          },
+        ],
+      });
+      const sq = result.questions[0];
+      expect(sq.method).toBe("select");
+      expect(sq.options).toEqual(["a", "b"]);
+      expect(sq.input_type).toBeUndefined();
+    });
+
+    it("converts {label, value} options to labels and records a warning", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "batch",
+        title: "T",
+        questions: [
+          {
+            method: "select",
+            title: "Pick",
+            options: [
+              { label: "Sync now", value: "sync" },
+              { label: "Skip", value: "skip" },
+            ],
+          },
+        ],
+      });
+      expect(result.questions[0].options).toEqual(["Sync now", "Skip"]);
+      const warnings = (result as any).__normalizations as string[];
+      expect(warnings).toBeDefined();
+      expect(warnings.length).toBeGreaterThan(0);
+      expect(warnings[0]).toMatch(/label.*value/);
+    });
+
+    it("renames sub-question header to title", () => {
+      const tool = getTool();
+      const result = tool.prepareArguments({
+        method: "batch",
+        title: "T",
+        questions: [{ method: "input", header: "Enter name" }],
+      });
+      expect(result.questions[0].title).toBe("Enter name");
+    });
+  });
+
+  describe("batch execution", () => {
+    function getToolAndMockCtx() {
+      const pi = createMockPi();
+      registerAskUserTool(pi as any);
+      const tool = pi.registerTool.mock.calls[0][0];
+      const ctx = {
+        ui: {
+          confirm: vi.fn().mockResolvedValue(true),
+          select: vi.fn().mockResolvedValue("A"),
+          input: vi.fn().mockResolvedValue("hello"),
+          multiselect: vi.fn().mockResolvedValue(["A"]),
+        },
+      };
+      return { tool, ctx };
+    }
+
+    it("invokes ctx.ui primitives sequentially for each sub-question", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      const result = await tool.execute(
+        "id",
+        {
+          method: "batch",
+          title: "Setup",
+          questions: [
+            { method: "input", title: "Name?" },
+            { method: "select", title: "Lang?", options: ["TS", "Py"] },
+            { method: "confirm", title: "Init git?" },
+          ],
+        },
+        undefined,
+        undefined,
+        ctx,
+      );
+      expect(ctx.ui.input).toHaveBeenCalledTimes(1);
+      expect(ctx.ui.select).toHaveBeenCalledTimes(1);
+      expect(ctx.ui.confirm).toHaveBeenCalledTimes(1);
+      expect(result.details.method).toBe("batch");
+      expect(result.details.results).toEqual(["hello", "A", true]);
+      expect(result.details.cancelled).toBe(false);
+    });
+
+    it("prepends batch title to sub-question titles", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      await tool.execute(
+        "id",
+        {
+          method: "batch",
+          title: "Setup",
+          questions: [{ method: "input", title: "Name?" }],
+        },
+        undefined,
+        undefined,
+        ctx,
+      );
+      const firstCallTitle = ctx.ui.input.mock.calls[0][0];
+      expect(firstCallTitle).toContain("Setup");
+      expect(firstCallTitle).toContain("Name?");
+    });
+
+    it("stops on cancellation and returns partial results with cancelled=true", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      // First sub-question returns a value; second cancels (undefined); third should not be called.
+      ctx.ui.input.mockResolvedValueOnce("first");
+      ctx.ui.select.mockResolvedValueOnce(undefined); // cancel
+      const result = await tool.execute(
+        "id",
+        {
+          method: "batch",
+          title: "T",
+          questions: [
+            { method: "input", title: "Q1" },
+            { method: "select", title: "Q2", options: ["a", "b"] },
+            { method: "confirm", title: "Q3" },
+          ],
+        },
+        undefined,
+        undefined,
+        ctx,
+      );
+      expect(result.details.cancelled).toBe(true);
+      expect(result.details.results).toEqual(["first", null]);
+      expect(ctx.ui.confirm).not.toHaveBeenCalled();
+    });
+
+    it("surfaces __normalizations warnings in details.warnings", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      const prepared = tool.prepareArguments({
+        method: "batch",
+        title: "T",
+        questions: [
+          {
+            method: "select",
+            title: "Pick",
+            options: [
+              { label: "A", value: "a" },
+              { label: "B", value: "b" },
+            ],
+          },
+        ],
+      });
+      const result = await tool.execute("id", prepared, undefined, undefined, ctx);
+      expect(result.details.warnings).toBeDefined();
+      expect(result.details.warnings.length).toBeGreaterThan(0);
+      expect(result.details.warnings[0]).toMatch(/label.*value/);
+    });
+
+    it("throws if a batch sub-question is select with empty options", async () => {
+      const { tool, ctx } = getToolAndMockCtx();
+      await expect(
+        tool.execute(
+          "id",
+          {
+            method: "batch",
+            title: "T",
+            questions: [{ method: "select", title: "Pick", options: [] }],
+          },
+          undefined,
+          undefined,
+          ctx,
+        ),
+      ).rejects.toThrow(/options/i);
+    });
   });
 });

package/packages/extension/src/__tests__/fork-entryid-timing.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for fork entryId timing fix.
+ *
+ * Verifies that the bridge's message_end entryId enrichment captures the
+ * correct leaf ID (after pi core persists the entry), not the stale one
+ * (before appendMessage runs).
+ *
+ * The bug: pi core emits message_end via _emit() BEFORE calling
+ * sessionManager.appendMessage(), so getLeafId() returns the previous leaf.
+ * The fix: the bridge defers getLeafId() for message_end using queueMicrotask,
+ * allowing appendMessage to run first.
+ */
+import { describe, it, expect, vi } from "vitest";
+
+/**
+ * Simulates the pi core + bridge interaction for entryId enrichment.
+ *
+ * Pi core's _processAgentEvent does:
+ *   1. _emit(event)          — bridge handler called (async, not awaited)
+ *   2. appendMessage(msg)    — updates leafId synchronously
+ *
+ * The bridge handler (async) should yield via queueMicrotask before reading
+ * getLeafId(), so that appendMessage has already run.
+ */
+describe("message_end entryId timing", () => {
+  it("deferred getLeafId() captures the post-persist entry ID", async () => {
+    // Simulate sessionManager with mutable leafId
+    let leafId = "user-entry-100"; // stale leaf before appendMessage
+    const sessionManager = {
+      getLeafId: () => leafId,
+    };
+
+    let capturedEntryId: string | undefined;
+
+    // Simulate the bridge handler (with the fix: defers via queueMicrotask)
+    const bridgeHandler = async () => {
+      // This is what the fixed bridge does for message_end:
+      await new Promise<void>(resolve => queueMicrotask(resolve));
+      capturedEntryId = sessionManager.getLeafId();
+    };
+
+    // Simulate pi core's _processAgentEvent:
+    // 1. _emit calls handler (async, NOT awaited)
+    const handlerPromise = bridgeHandler();
+    // 2. appendMessage runs synchronously, updating leafId
+    leafId = "assistant-entry-101";
+
+    // Wait for the deferred handler to complete
+    await handlerPromise;
+
+    expect(capturedEntryId).toBe("assistant-entry-101");
+  });
+
+  it("immediate getLeafId() would capture the stale entry ID (demonstrates the bug)", async () => {
+    let leafId = "user-entry-100";
+    const sessionManager = {
+      getLeafId: () => leafId,
+    };
+
+    let capturedEntryId: string | undefined;
+
+    // Simulate the OLD (buggy) bridge handler: reads getLeafId() immediately
+    const buggyBridgeHandler = async () => {
+      // No deferral — reads leafId before appendMessage runs
+      capturedEntryId = sessionManager.getLeafId();
+    };
+
+    // Simulate pi core's _processAgentEvent:
+    const handlerPromise = buggyBridgeHandler();
+    leafId = "assistant-entry-101"; // too late — handler already read it
+
+    await handlerPromise;
+
+    // Bug: captures the stale leaf, not the assistant's entry
+    expect(capturedEntryId).toBe("user-entry-100");
+  });
+
+  it("message_start should still capture entryId immediately (no deferral)", async () => {
+    let leafId = "previous-assistant-entry-99";
+    const sessionManager = {
+      getLeafId: () => leafId,
+    };
+
+    let capturedEntryId: string | undefined;
+
+    // Simulate bridge handler for message_start (immediate, no deferral)
+    const messageStartHandler = async () => {
+      capturedEntryId = sessionManager.getLeafId();
+    };
+
+    const handlerPromise = messageStartHandler();
+    // User entry gets written after message_start
+    leafId = "user-entry-100";
+
+    await handlerPromise;
+
+    // message_start should capture the leaf BEFORE the user entry is written
+    expect(capturedEntryId).toBe("previous-assistant-entry-99");
+  });
+});