@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

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

@@ -9,7 +9,7 @@ import type {
   ExtensionToServerMessage,
 } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
 import { killProcessByPgid } from "./process-scanner.js";
-import type { FileEntry, PiSessionInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { FileEntry, ImageContent, PiSessionInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { filterHiddenCommands } from "./bridge-context.js";
 import { expandPromptTemplateFromDisk } from "./prompt-expander.js";
 import { tryDispatchExtensionCommand } from "./slash-dispatch.js";
@@ -169,7 +169,25 @@ export function createCommandHandler(
      * events emitted by the dispatch path arrive before this turn returns.
      * See change: fix-extension-slash-commands-in-dashboard.
      */
-    sessionPrompt?: (text: string) => void | Promise<void>;
+    sessionPrompt?: (text: string, delivery?: "steer" | "followUp") => void | Promise<void>;
+    /**
+     * Bridge-shadow-queue hooks: called AFTER pi accepts the user message,
+     * gated by `isStreaming()` captured BEFORE the send. The capture order
+     * matters — `pi.sendUserMessage` on an idle session synchronously
+     * triggers `agent_start`, which flips bridge state to streaming. Checking
+     * AFTER the send would mis-record idle sends as chip entries.
+     * Pi doesn't expose `queue_update` to extensions, so the bridge is the
+     * source of truth. See change: add-followup-edit-and-steer-cancel.
+     */
+    onSteerSent?: (text: string) => void;
+    onFollowupSent?: (text: string) => void;
+    /**
+     * Returns true iff the agent was streaming at the moment of the call.
+     * Used to capture pre-send streaming state before `pi.sendUserMessage`
+     * runs (which may flip the flag synchronously via agent_start).
+     * See change: add-followup-edit-and-steer-cancel.
+     */
+    isStreaming?: () => boolean;
   },
 ): CommandHandler {
   const getSessionId = typeof sessionIdOrGetter === "function" ? sessionIdOrGetter : () => sessionIdOrGetter;
@@ -304,7 +322,7 @@ export function createCommandHandler(
               // extension-command dispatch. Do NOT emit completed here — would
               // duplicate the dispatch path's terminal event.
               // See change: fix-extension-slash-commands-in-dashboard.
-              await options.sessionPrompt(parsed.text);
+              await options.sessionPrompt(parsed.text, msg.delivery);
             } else {
               // Test / non-bridge callers: apply the extension-command dispatch
               // branch inline before falling through to sendUserMessage. Keeps
@@ -314,12 +332,17 @@ export function createCommandHandler(
                 parsed.text,
                 sessionId,
                 options?.eventSink,
+                undefined, // connection — absent in non-bridge path
+                msg.delivery,
               );
               if (!handled) {
                 // sendUserMessage exempt from gating: only typed single-line
                 // slashes that are NOT extension commands reach this — i.e.
                 // skills, prompt templates, unrecognized slashes.
-                pi.sendUserMessage(parsed.text);
+                // Forward delivery so steering on slash fallback honors the
+                // dashboard's keyboard contract. See change: add-steering-message.
+                const deliverAs = msg.delivery ?? ("followUp" as const);
+                (pi.sendUserMessage as any)(parsed.text, { deliverAs });
               }
             }
             return undefined;
@@ -339,11 +362,27 @@ export function createCommandHandler(
           if (outgoing.startsWith("/")) {
             outgoing = expandPromptTemplateFromDisk(outgoing, process.cwd(), pi);
           }
-          sendUserMessageWithImages(pi, outgoing, msg.images);
+          // Pi owns the steering + follow-up queues natively. The helper enforces
+          // capacity-1 on follow-up by clearing pi's slot before sending. After
+          // pi accepts, notify the bridge so it updates its shadow queue — but
+          // only if the agent was already streaming BEFORE the send. Pi flips
+          // idle→streaming synchronously on the first user message, so checking
+          // after sendUserMessage gives false positives.
+          // See change: add-followup-edit-and-steer-cancel.
+          const wasStreaming = options?.isStreaming?.() ?? false;
+          sendUserMessageWithImages(pi, outgoing, msg.images, msg.delivery);
+          if (wasStreaming) {
+            const da = msg.delivery ?? "followUp";
+            if (da === "steer") options?.onSteerSent?.(outgoing);
+            else options?.onFollowupSent?.(outgoing);
+          }
           return undefined;
         }
 
         case "abort":
+          // Pi owns both queues now. abort() asks pi to halt the current turn;
+          // pi's native drain logic handles any remaining queue entries naturally.
+          // See change: add-followup-edit-and-steer-cancel.
           if (options?.abort) {
             options.abort();
           }
@@ -502,13 +541,20 @@ export function createCommandHandler(
 }
 
 /** Send a user message with optional image validation.
- * Uses deliverAs: "followUp" so messages queue properly when the agent is streaming. */
+ * Uses deliverAs: "followUp" by default so messages queue properly when the agent is streaming.
+ * Pass deliverAs: "steer" for steering messages (delivered after current turn).
+ * See change: add-steering-message. */
 function sendUserMessageWithImages(
   pi: ExtensionAPI,
   text: string,
   images?: Array<{ type: string; data: string; mimeType: string }>,
+  delivery?: "steer" | "followUp",
 ): void {
-  const sendOptions = { deliverAs: "followUp" as const };
+  const deliverAs = delivery ?? ("followUp" as const);
+  const sendOptions = { deliverAs };
+  // v2: follow-up is a multi-entry queue. Sends APPEND — the cap-1 invariant
+  // is gone. See change: add-followup-edit-and-steer-cancel design.md Decision 8.
+  // (The bridge's shadow queue records the append via onFollowupSent.)
   if (images && images.length > 0) {
     const validMimeTypes = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
     const validImages = images.filter((img) => {

package/packages/extension/src/dashboard-default-adapter.ts

@@ -10,6 +10,11 @@ import type { PromptAdapter, PromptRequest, PromptResponse, PromptClaim } from "
 
 export class DashboardDefaultAdapter implements PromptAdapter {
   readonly name = "dashboard-default";
+  /**
+   * Last-resort fallback. Any plugin adapter with default priority (1000)
+   * or lower beats this. See change: route-flow-asks-to-upper-slot.
+   */
+  readonly priority = 9999;
 
   onRequest(_prompt: PromptRequest): PromptClaim {
     return {

package/packages/extension/src/prompt-bus.ts

@@ -41,6 +41,14 @@ export interface PromptResponse {
 
 export interface PromptAdapter {
   name: string;
+  /**
+   * Routing priority. Lower numbers run first. Default 1000.
+   * `DashboardDefaultAdapter` uses 9999 so any plugin adapter with the
+   * default priority (1000) or lower beats it automatically.
+   *
+   * See change: route-flow-asks-to-upper-slot.
+   */
+  priority?: number;
   /**
    * Called when a new prompt arrives.
    * Return a PromptClaim to participate, or null/undefined to skip.
@@ -92,11 +100,18 @@ export class PromptBus {
   /**
    * Register an adapter. Returns an unsubscribe function.
    * Re-registering with the same name replaces the previous adapter.
+   *
+   * Adapters are kept sorted by `priority` (default 1000, lower first).
+   * `Array.prototype.sort` is stable in V8 ≥ ES2019 so equal priorities
+   * preserve insertion order. See change: route-flow-asks-to-upper-slot.
    */
   registerAdapter(adapter: PromptAdapter): () => void {
     // Replace existing adapter with same name
     this.adapters = this.adapters.filter(a => a.name !== adapter.name);
     this.adapters.push(adapter);
+    this.adapters.sort(
+      (a, b) => (a.priority ?? 1000) - (b.priority ?? 1000),
+    );
 
     return () => {
       this.adapters = this.adapters.filter(a => a !== adapter);

package/packages/extension/src/slash-dispatch.ts

@@ -8,10 +8,14 @@
  *     dashboard-spawned headless `pi --mode rpc` AND a `connection` is wired
  *     → emit `dispatch_extension_command` to the server (server forwards to
  *     the per-session RPC keeper UDS and emits the terminal command_feedback).
- *   - Path D (stopgap, last resort): `pi.dispatchCommand` absent AND the bridge
- *     is NOT headless (tmux / wt / unrecognized spawn shape) OR no `connection`
- *     was supplied → emit `command_feedback {status:"error"}` with a pi-version
- *     reminder.
+ *   - Path D: `pi.dispatchCommand` absent AND the bridge is NOT headless
+ *     (tmux / wt) OR no `connection` was supplied → emit
+ *     `command_feedback {status:"error"}` with a hint to enable
+ *     `useRpcKeeper: true` for headless sessions.
+ *     Note: pi.sendUserMessage() hardcodes expandPromptTemplates: false, which
+ *     skips _tryExecuteExtensionCommand; extension commands sent this way
+ *     become regular LLM messages. This is a pi limitation — the bridge has
+ *     no mechanism to dispatch extension commands outside the RPC path.
  *
  * If `text` is NOT an extension command, return `false` so the caller can
  * fall through to its existing template-expansion / sendUserMessage path.
@@ -21,7 +25,8 @@
  * Path C does NOT emit a terminal event — the server emits it.
  *
  * See change: fix-extension-slash-commands-in-dashboard,
- *             add-rpc-stdin-dispatch-with-keeper-sidecar.
+ *             add-rpc-stdin-dispatch-with-keeper-sidecar,
+ *             fix-slash-dispatch-delivery.
  */
 import crypto from "node:crypto";
 import type { ExtensionToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
@@ -38,9 +43,6 @@ export interface DispatchConnection {
   send(msg: ExtensionToServerMessage): void;
 }
 
-const PI_071_REQUIRED =
-  "Extension slash commands cannot be dispatched from the dashboard yet — requires pi 0.71+ (`pi.dispatchCommand`). Invoke from the pi TUI, or use the extension's tools directly.";
-
 function emitFeedback(
   sink: FeedbackSink | undefined,
   sessionId: string,
@@ -64,8 +66,8 @@ function emitFeedback(
  * Try to dispatch a slash command as an extension command.
  *
  * @returns `true` if the helper handled the text (extension command detected;
- *          dispatch attempted or stopgap emitted). The caller MUST NOT fall
- *          through to template expansion or `sendUserMessage`.
+ *          dispatch attempted or error feedback emitted). The caller MUST NOT
+ *          fall through to template expansion or `sendUserMessage`.
  * @returns `false` if `text` is not an extension slash command. The caller
  *          SHOULD continue with its existing fallback path.
  */
@@ -75,6 +77,7 @@ export async function tryDispatchExtensionCommand(
   sessionId: string,
   sink: FeedbackSink | undefined,
   connection?: DispatchConnection,
+  delivery?: "steer" | "followUp",
 ): Promise<boolean> {
   // Defensive: pi.getCommands() can throw on a stale ctx during dispose.
   let commands: Array<{ name: string; source?: string }> = [];
@@ -88,12 +91,13 @@ export async function tryDispatchExtensionCommand(
 
   if (!isExtensionSlashCommand(text, commands)) return false;
 
-  emitFeedback(sink, sessionId, text, "started");
-
   // Path B (preferred when available): pi 0.71+ exposes dispatchCommand.
+  // Note: as of pi 0.74.1, dispatchCommand does NOT exist in the ExtensionAPI.
+  // This path is dead code until pi ships the API; preserved for future use.
   if (hasDispatchCommand(pi)) {
+    emitFeedback(sink, sessionId, text, "started");
     try {
-      await (pi as any).dispatchCommand(text, { streamingBehavior: "followUp" });
+      await (pi as any).dispatchCommand(text, { streamingBehavior: delivery ?? "followUp" });
       emitFeedback(sink, sessionId, text, "completed");
     } catch (err: any) {
       const message = err instanceof Error ? err.message : String(err);
@@ -108,6 +112,7 @@ export async function tryDispatchExtensionCommand(
   // terminal event for this path — that would duplicate the reducer's
   // started→terminal upsert. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
   if (connection && isHeadlessRpcSession()) {
+    emitFeedback(sink, sessionId, text, "started");
     connection.send({
       type: "dispatch_extension_command",
       sessionId,
@@ -117,7 +122,17 @@ export async function tryDispatchExtensionCommand(
     return true;
   }
 
-  // Path D (stopgap): no dispatchCommand and not headless (tmux / wt / unrecognized).
-  emitFeedback(sink, sessionId, text, "error", PI_071_REQUIRED);
+  // Path D: No dispatchCommand, not headless (tmux / wt) or no connection.
+  // Extension commands can only be dispatched through the RPC keeper, which
+  // is available for headless sessions (`pi --mode rpc`). For tmux/wt sessions
+  // there is no injection channel — the command becomes a regular LLM message.
+  // To enable extension command dispatch for headless sessions:
+  //   { "spawnStrategy": "headless", "useRpcKeeper": true }
+  // See change: fix-slash-dispatch-delivery.
+  const RPC_KEEPER_HINT =
+    "Extension slash commands cannot be dispatched from the dashboard for " +
+    "non-headless (tmux/wt) sessions. If you're using headless mode, add " +
+    '"useRpcKeeper": true to your dashboard config (~/.pi/dashboard/config.json).';
+  emitFeedback(sink, sessionId, text, "error", RPC_KEEPER_HINT);
   return true;
 }

package/packages/extension/src/source-detector.ts

@@ -11,16 +11,24 @@ import { readSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/sessi
  *   a .meta.json sidecar with source information.
  */
 export function detectSessionSource(hasUI?: boolean, sessionFile?: string): SessionSource {
-  // Check for .meta.json sidecar written by the dashboard server
+  // A TUI is attached → the session is a CLI/TUI session, not headless,
+  // regardless of any .meta.json sidecar (which can be stamped "dashboard"
+  // by event-wiring's pendingDashboardSpawns by-cwd matcher when an
+  // unrelated dashboard Spawn for the same cwd happened around the same time).
+  if (hasUI) {
+    if (process.env.ZED_TERM) return "tui"; // pi TUI inside Zed's terminal
+    if (process.env.TMUX) return "tmux";
+    return "tui";
+  }
+
+  // No TUI attached → headless. Check for .meta.json sidecar written by
+  // the dashboard server when it spawned this session.
   if (sessionFile) {
     const meta = readSessionMeta(sessionFile);
     if (meta?.source === "dashboard") return "dashboard";
   }
 
-  if (process.env.ZED_TERM) {
-    if (hasUI) return "tui";
-    return "zed";
-  }
+  if (process.env.ZED_TERM) return "zed";
   if (process.env.TMUX) return "tmux";
   return "tui";
 }

package/packages/extension/src/usage-limit-orderer.ts

@@ -11,8 +11,25 @@
  * See change: fix-provider-retry-infinite-loop.
  */
 
+/**
+ * Matches terminal billing/quota error categories observed in production
+ * across providers. The orderer uses this to surface a synthesized
+ * `auto_retry_end{success:false}` BEFORE the bridge forwards `agent_end`,
+ * so the dashboard's `retryState` clears before `lastError` is set.
+ *
+ * Coverage (verified via fixture tests):
+ *   - Codex / Anthropic / generic: usage_limit_reached, usage_not_included,
+ *     quota_exceeded, credit_balance, insufficient_quota, monthly limit,
+ *     daily limit, hourly limit, "reset after Nh|Nm|Ns".
+ *   - Gemini / Google: "monthly spending cap", "spending cap",
+ *     RESOURCE_EXHAUSTED.
+ *   - Generic catch-all for "exceeded ... (quota|cap|spending)" within
+ *     ~40 chars (avoids a string with no terminal-meaning context).
+ *
+ * See change: fix-retry-banner-stuck-on-limit-exceeded.
+ */
 export const USAGE_LIMIT_PATTERN =
-  /usage[_ ]limit[_ ]reached|usage_not_included|quota[_ ]exceeded|monthly limit|hourly limit|reset after \d+[hms]/i;
+  /usage[_ ]limit[_ ]reached|usage_not_included|insufficient_quota|credit[_ ]balance|quota[_ ]exceeded|resource[_ ]exhausted|monthly[_ ]limit|monthly[_ ]spending[_ ]cap|hourly[_ ]limit|daily[_ ]limit|spending[_ ]cap|exceeded[^"]{0,40}(quota|cap|spending)|reset after \d+[hms]/i;
 
 export interface SyntheticEventEnvelope {
   eventType: "auto_retry_end";

package/packages/server/bin/pi-dashboard.mjs

@@ -4,18 +4,26 @@
  *
  * The actual CLI is `../src/cli.ts`. This wrapper exists because a
  * `#!/usr/bin/env` shebang cannot interpolate a dynamic `--import`
- * loader path. The wrapper resolves jiti from pi's tree at runtime
- * and re-execs Node with `--import <jiti-url> cli.ts <args>`.
+ * loader path. The wrapper resolves jiti from `process.argv[1]`'s
+ * module graph at runtime and re-execs Node with
+ * `--import <jiti-url> cli.ts <args>`.
  *
- * No tsx fallback: if jiti cannot be resolved, the wrapper exits 1
- * with an install-hint pointing at pi. Mirrors the resolution shape
- * in `packages/shared/src/resolve-jiti.ts` (cannot import the .ts
- * module before a TS loader is registered, so the lookup is inlined).
+ * Since `@blackbelt-technology/pi-dashboard-server` declares `jiti` as
+ * a direct runtime dependency, `createRequire(argv[1]).resolve("jiti/...")`
+ * SHALL succeed in any well-formed npm install layout (flat, scoped,
+ * hoisted, pnpm). A miss therefore indicates a corrupted install, not
+ * a missing prerequisite. The error message reflects that.
  *
- * See change: replace-tsx-with-jiti.
+ * No tsx fallback: jiti is the sole supported TypeScript loader.
+ * Mirrors the resolution shape in
+ * `packages/shared/src/platform/binary-lookup.ts::ToolResolver.resolveJiti`
+ * (cannot import the .ts module before a TS loader is registered, so
+ * the lookup is inlined).
+ *
+ * See change: replace-tsx-with-jiti, enable-standalone-npm-install.
  */
 import { createRequire } from "node:module";
-import { realpathSync } from "node:fs";
+import { realpathSync, readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
@@ -23,7 +31,35 @@ import { pathToFileURL, fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const cliPath = resolve(here, "..", "src", "cli.ts");
 
-// Mirrors packages/shared/src/resolve-jiti.ts JITI_PACKAGES.
+// Metadata short-circuit: --version / -v / version SHALL NOT require jiti.
+// See change: fix-electron-cold-launch-probe-cascade (Bug B).
+//
+// Why: every metadata-only consumer (npmGlobal probe, doctor, the user
+// asking "what's installed") was previously blocked when the wrapper
+// couldn't resolve jiti — even when the install was perfectly capable
+// of answering the query from its sibling package.json. Reading the
+// version is a pure metadata operation; gating it on a TS loader was
+// over-aggressive.
+//
+// Falls through (no exit) on read/parse error so the legacy install
+// hint still surfaces for genuinely corrupt installs.
+const metaArg = process.argv[2];
+if (metaArg === "--version" || metaArg === "-v" || metaArg === "version") {
+  try {
+    const pkgPath = resolve(here, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    if (pkg && typeof pkg.version === "string" && pkg.version.length > 0) {
+      process.stdout.write(pkg.version + "\n");
+      process.exit(0);
+    }
+  } catch {
+    /* fall through to jiti-resolve path so the legacy error still fires */
+  }
+}
+
+// Mirrors packages/shared/src/platform/binary-lookup.ts JITI_PACKAGES.
+// Kept in sync by repo-lint: packages/shared/src/__tests__/jiti-packages-parity.test.ts.
+// See change: enable-standalone-npm-install task 7.3.
 const JITI_PACKAGES = ["jiti", "@mariozechner/jiti"];
 
 /** Resolve pi's jiti register hook as a file:// URL. Returns null on miss. */
@@ -51,17 +87,29 @@ function resolveJitiUrl() {
 
 const loader = resolveJitiUrl();
 if (!loader) {
+  // jiti is a direct dep of @blackbelt-technology/pi-dashboard-server, so a
+  // miss here means the install is corrupted (deleted node_modules entry,
+  // partial extract, etc.). The legacy "install pi globally" hint is kept
+  // as a workaround for users who can't reinstall the dashboard cleanly.
   process.stderr.write(
-    "pi-dashboard: cannot find jiti. " +
-      "Install pi: 'npm install -g @earendil-works/pi-coding-agent'\n",
+    "pi-dashboard: cannot find jiti.\n" +
+      "This is unexpected: jiti ships as a direct dependency of pi-dashboard-server.\n" +
+      "Your install may be corrupted. Try:\n" +
+      "  npm install -g @blackbelt-technology/pi-agent-dashboard\n" +
+      "Workaround: install pi globally (provides a fallback jiti):\n" +
+      "  npm install -g @earendil-works/pi-coding-agent\n" +
+      "Please report at https://github.com/BlackBeltTechnology/pi-agent-dashboard/issues\n",
   );
   process.exit(1);
 }
 
 // Mirrors shouldUrlWrapEntry() in packages/shared/src/platform/node-spawn.ts:
-// jiti needs the entry URL-wrapped on Windows (Node rejects raw drive-letter
-// paths for --import). POSIX takes the raw path.
-const entry = process.platform === "win32" ? pathToFileURL(cliPath).href : cliPath;
+// jiti misnormalises file:/// URL entries on Windows (verified live on
+// Node 22.18.0 + jiti 2.7.0 in a standalone install — the entry gets
+// re-prepended with cwd as if it were a relative specifier). Pass the
+// RAW path on every platform; Node's drive-letter heuristic handles
+// `C:\…` entries directly. See change: fix-windows-standalone-spawn.
+const entry = cliPath;
 
 const child = spawn(
   process.execPath,

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "repository": {
@@ -32,9 +32,10 @@
     "postinstall": "node scripts/fix-pty-permissions.cjs"
   },
   "dependencies": {
-    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.3",
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.3",
-    "@blackbelt-technology/pi-dashboard-shared": "^0.5.3",
+    "@blackbelt-technology/dashboard-plugin-runtime": "^0.5.4",
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.4",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.4",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
     "@fastify/compress": "^8.3.1",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.0.0",
@@ -42,12 +43,15 @@
     "@fastify/reply-from": "^12.6.1",
     "@fastify/static": "^8.0.0",
     "@fastify/websocket": "^11.0.0",
+    "@fission-ai/openspec": "^1.3.0",
     "bonjour-service": "^1.3.0",
     "diff": "^8.0.3",
     "fastify": "^5.0.0",
+    "jiti": "^2.7.0",
     "jsonwebtoken": "^9.0.3",
-    "node-pty": "^1.1.0",
+    "node-pty": "1.2.0-beta.13",
     "proper-lockfile": "^4.1.2",
+    "tsx": "^4.21.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/packages/server/src/__tests__/browser-gateway-register-handler.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Tests for browserGateway.registerHandler — the reverse channel that
+ * plugins use to receive Browser→Server custom message types.
+ *
+ * See change: adopt-server-driven-intent-rendering.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { createBrowserGateway } from "../browser-gateway.js";
+
+function makeMockDeps() {
+  // Minimal mock dependencies for createBrowserGateway. We only need the
+  // gateway's registerHandler + the message dispatch loop, not session
+  // management.
+  return {
+    sessionManager: {
+      listActive: () => [],
+      listAll: () => [],
+      getSession: () => undefined,
+      registerSession: () => {},
+      unregisterSession: () => {},
+      updateSession: () => {},
+      detachAll: () => {},
+      attachExtension: () => {},
+      detachExtension: () => {},
+      markEnded: () => {},
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any,
+    eventStore: {
+      append: () => {},
+      getEvents: () => [],
+      getLatestEvent: () => undefined,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any,
+    piGateway: {
+      send: () => {},
+      sendToSession: () => {},
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any,
+  };
+}
+
+describe("browserGateway.registerHandler", () => {
+  it("stores and looks up handlers by type", () => {
+    const deps = makeMockDeps();
+    const gateway = createBrowserGateway(deps.sessionManager, deps.eventStore, deps.piGateway);
+
+    const handler = vi.fn();
+    gateway.registerHandler("plugin_action", handler);
+
+    // We can't easily invoke the WS message loop without a real WebSocket
+    // connection, so we verify only that registration succeeds without
+    // throwing. End-to-end dispatch is verified in section 19 manual smoke.
+    expect(typeof gateway.registerHandler).toBe("function");
+  });
+
+  it("multiple handlers for different types can be registered", () => {
+    const deps = makeMockDeps();
+    const gateway = createBrowserGateway(deps.sessionManager, deps.eventStore, deps.piGateway);
+
+    const handlerA = vi.fn();
+    const handlerB = vi.fn();
+    gateway.registerHandler("plugin_action", handlerA);
+    gateway.registerHandler("plugin_other", handlerB);
+
+    // No throw on registration. (Last-write-wins for the same type
+    // is implicit Map semantics; not validated here.)
+    expect(true).toBe(true);
+  });
+});

package/packages/server/src/__tests__/cli-env-no-clobber.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Regression-prevention lint: forbid the `env: { ...process.env }` anti-pattern
+ * in `packages/server/src/cli.ts`.
+ *
+ * Why this is forbidden:
+ *
+ * `launchDashboardServer` (the shared spawn primitive) internally computes the
+ * spawn env as `ToolResolver.buildSpawnEnv(process.env)`, which augments PATH
+ * with managed-dir, bundled-node, and pi-bin prepends. Caller-supplied `env`
+ * is then overlaid on top with caller-wins semantics.
+ *
+ * Passing `env: { ...process.env }` re-supplies the raw, un-augmented PATH
+ * back over the augmented base, silently defeating the entire purpose of
+ * `buildSpawnEnv` — the spawned daemon then cannot find `pi` (or any other
+ * tool resolved via PATH augmentation) in environments where the launching
+ * shell's PATH lacks those prepends (e.g. `.desktop` launchers, systemd-user
+ * units, non-interactive logins that don't init nvm).
+ *
+ * See: openspec/changes/fix-cli-env-clobber/proposal.md
+ * See: dashboard-server capability spec — constraint C22 (env merge contract)
+ */
+
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CLI_SOURCE = path.resolve(__dirname, "..", "cli.ts");
+
+describe("cli.ts env clobber lint", () => {
+  it("does not pass `env: { ...process.env }` to launchDashboardServer", () => {
+    const source = fs.readFileSync(CLI_SOURCE, "utf8");
+    const pattern = /env:\s*\{\s*\.\.\.process\.env\s*\}/;
+    const match = source.match(pattern);
+
+    expect(
+      match,
+      "packages/server/src/cli.ts must not contain `env: { ...process.env }`. " +
+        "This pattern clobbers the augmented PATH from ToolResolver.buildSpawnEnv. " +
+        "Omit `env` to let the shared primitive's resolver-merged env take effect. " +
+        "See openspec/changes/fix-cli-env-clobber/proposal.md.",
+    ).toBeNull();
+  });
+});

package/packages/server/src/__tests__/cli-no-bootstrap-references.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Repo-lint — guards Phase 3.0.a/3.0.b of change:
+ * eliminate-electron-runtime-install.
+ *
+ * Under R3, `packages/server/src/cli.ts::runForeground` MUST NOT reach into
+ * any of the deleted bootstrap modules. The tool-registry resolve is the
+ * sole point at which startup verifies pi is reachable; failure throws a
+ * hard error citing a corrupted node_modules/ tree (no degraded mode).
+ *
+ * This test asserts the cli.ts source text contains:
+ *   1. ZERO references to the deleted module names (`bootstrap-install`,
+ *      `bootstrap-install-from-list`, `installable-list`, `bootstrap-state`,
+ *      `bootstrap-queue`, `managed-workspace-materialize`,
+ *      `defaultInstallableList`, `writeInstallableList`,
+ *      `updateBootstrapCompatibility`, `BootstrapStateStore`).
+ *   2. The `[bootstrap] ready` log line, proving the tool-registry
+ *      resolve path is in place.
+ *   3. The hard-throw branch citing a "corrupted node_modules" message.
+ *
+ * If you intentionally rename / move the resolve step, update this lint
+ * to match — but reaching back into any of the forbidden symbols means
+ * runtime install has crept back into the standalone arm.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = path.resolve(HERE, "..", "cli.ts");
+
+const FORBIDDEN_SYMBOLS = [
+  "bootstrap-install",
+  "bootstrap-install-from-list",
+  "installable-list",
+  "bootstrap-state",
+  "bootstrap-queue",
+  "managed-workspace-materialize",
+  "defaultInstallableList",
+  "writeInstallableList",
+  "updateBootstrapCompatibility",
+  "BootstrapStateStore",
+  "bootstrapInstall",
+  "bootstrapInstallFromList",
+  "runDegradedModeBootstrap",
+  "maybeSeedDefaultInstallableList",
+];
+
+describe("cli.ts has no bootstrap-install references (Phase 3.0.b)", () => {
+  it("does not reference any deleted bootstrap modules or symbols", () => {
+    const src = fs.readFileSync(CLI_PATH, "utf-8");
+    const offenders = FORBIDDEN_SYMBOLS.filter((sym) => src.includes(sym));
+    expect(
+      offenders,
+      `cli.ts must not reference deleted bootstrap symbols under R3:\n  ${offenders.join(", ")}\n\nSee change: eliminate-electron-runtime-install (Phase 3.0).`,
+    ).toEqual([]);
+  });
+
+  it("contains the [bootstrap] ready log line proving tool-registry resolve is wired", () => {
+    const src = fs.readFileSync(CLI_PATH, "utf-8");
+    expect(src).toContain("[bootstrap] ready (pi resolved via");
+  });
+
+  it("throws hard on pi resolution failure (no degraded mode)", () => {
+    const src = fs.readFileSync(CLI_PATH, "utf-8");
+    // The hard-throw branch in runForeground cites "corrupted node_modules".
+    expect(src).toMatch(/corrupted node_modules/i);
+  });
+});