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

package/packages/server/src/routes/system-routes.ts

@@ -13,7 +13,9 @@ import type { NetworkGuard } from "./route-deps.js";
 import { detectEditors, EDITORS } from "../editor-registry.js";
 import { detectCodeServerBinary, resetDetectionCache } from "../editor-detection.js";
 import { readConfigRedacted, writeConfigPartial } from "../config-api.js";
-import { createTunnel, deleteTunnel, getTunnelStatus } from "../tunnel.js";
+import { createTunnel, deleteTunnel, getTunnelStatus, getTunnelUrl } from "../tunnel.js";
+import { getModelProxyStatus } from "../model-proxy/registry-singleton.js";
+import { startTunnelWatchdog, stopTunnelWatchdog } from "../tunnel-watchdog.js";
 import { spawnRestart } from "../restart-helper.js";
 import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import path from "node:path";
@@ -152,6 +154,29 @@ export function registerSystemRoutes(
       if (partial.openspec !== undefined && directoryService) {
         directoryService.reconfigurePolling(reloaded.openspec);
       }
+      // Live-reload tunnel watchdog when its config changes (no restart needed).
+      // We always restart the watchdog when partial.tunnel is present and a
+      // tunnel is currently active — covers both watchdog flag changes and
+      // numeric tweaks. Cheap operation: stop + start with new config.
+      if (partial.tunnel !== undefined) {
+        config.tunnelWatchdog = reloaded.tunnel.watchdog;
+        if (getTunnelUrl()) {
+          stopTunnelWatchdog();
+          const wd = reloaded.tunnel.watchdog;
+          if (wd?.enabled !== false) {
+            startTunnelWatchdog(
+              {
+                getUrl: getTunnelUrl,
+                recycle: async () => {
+                  await deleteTunnel(config.port);
+                  return await createTunnel(config.port, config.tunnelReservedToken);
+                },
+              },
+              wd,
+            );
+          }
+        }
+      }
 
       return { success: true, restartRequired: result.restartRequired };
     },
@@ -167,13 +192,29 @@ export function registerSystemRoutes(
     if (status.status === "active") return { ok: true, url: status.url };
     if (status.status === "unavailable") return { ok: false, error: "zrok not installed" };
     const url = await createTunnel(config.port, config.tunnelReservedToken);
-    if (url) return { ok: true, url };
+    if (url) {
+      const wd = config.tunnelWatchdog;
+      if (wd?.enabled !== false) {
+        startTunnelWatchdog(
+          {
+            getUrl: getTunnelUrl,
+            recycle: async () => {
+              await deleteTunnel(config.port);
+              return await createTunnel(config.port, config.tunnelReservedToken);
+            },
+          },
+          wd,
+        );
+      }
+      return { ok: true, url };
+    }
     return { ok: false, error: "Failed to create tunnel" };
   });
 
   fastify.post("/api/tunnel-disconnect", async () => {
     // Pass port so orphan zrok processes bound to this endpoint are also
     // swept (not just the one we tracked via pid-file).
+    stopTunnelWatchdog();
     await deleteTunnel(config.port);
     return { ok: true };
   });
@@ -206,6 +247,7 @@ export function registerSystemRoutes(
       },
       agents: agentMetrics,
       plugins: getPluginStatusStore().listAll(),
+      proxy: getModelProxyStatus(),
     };
   });
 

package/packages/server/src/rpc-keeper/__tests__/fixtures/mock-pi-shim.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# PATH-shim used in keeper.test.ts to make `pi --mode rpc` invoke our
+# mock-pi.cjs instead of the real pi binary.
+#
+# The keeper spawns `pi --mode rpc` from PATH; we prepend the dir
+# containing this script (named `pi`) to PATH so this shim wins.
+# The path to mock-pi.cjs is passed via env var so the shim can be
+# placed anywhere without copying mock-pi.cjs alongside it.
+exec node "${MOCK_PI_CJS_PATH:?MOCK_PI_CJS_PATH env var required}" "$@"

package/packages/server/src/rpc-keeper/__tests__/fixtures/mock-pi.cjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Mock pi for keeper integration tests.
+ *
+ * Reads JSON-line input from stdin and appends each line to the file at
+ * `process.env.MOCK_PI_LOG`. Exits 0 on stdin EOF.
+ *
+ * Behavior modes (via env):
+ *   MOCK_PI_MODE=normal (default) — read until EOF, log lines, exit 0
+ *   MOCK_PI_MODE=crash             — exit non-zero immediately (tests
+ *                                    keeper crash-detection window)
+ *
+ * CommonJS-pure, only Node built-ins.
+ */
+"use strict";
+
+const fs = require("fs");
+
+const mode = process.env.MOCK_PI_MODE || "normal";
+const logPath = process.env.MOCK_PI_LOG;
+
+if (mode === "crash") {
+  process.stderr.write("[mock-pi] crash mode: exiting 1 immediately\n");
+  process.exit(1);
+}
+
+if (!logPath) {
+  process.stderr.write("[mock-pi] FATAL: MOCK_PI_LOG env var required\n");
+  process.exit(2);
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  // eslint-disable-next-line no-cond-assign
+  while ((nl = buf.indexOf("\n")) !== -1) {
+    const line = buf.slice(0, nl);
+    buf = buf.slice(nl + 1);
+    fs.appendFileSync(logPath, line + "\n");
+  }
+});
+process.stdin.on("end", () => {
+  if (buf.length > 0) {
+    fs.appendFileSync(logPath, buf + "\n");
+  }
+  process.exit(0);
+});
+process.stdin.on("error", () => process.exit(0));

package/packages/server/src/rpc-keeper/__tests__/keeper.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Keeper integration tests.
+ *
+ * Spawns `node packages/server/src/rpc-keeper/keeper.cjs <sessionId>` as a
+ * real subprocess (NOT via jiti / tsx — the whole point is that keeper.cjs
+ * runs under bare node). A `pi` PATH shim invokes a `mock-pi.cjs` fixture
+ * so we exercise the spawn path without needing a real pi binary.
+ *
+ * Note re tasks.md 3.1: spec says ".test.cjs". We write the driver in TS
+ * (existing vitest glob is `*.test.ts`); the BINARY-under-test is still
+ * pure CJS. The CJS contract is what we verify — the test runner is irrelevant.
+ *
+ * Tasks covered: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, unlinkSync, rmSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const KEEPER_PATH = path.resolve(__dirname, "..", "keeper.cjs");
+const FIXTURES_DIR = path.resolve(__dirname, "fixtures");
+const SHIM_DIR = FIXTURES_DIR;
+
+// macOS UDS sun_path is 104 bytes. The root `npm test` HOME under
+// /var/folders/.../pi-test-XXXXXX is ~73 chars before any further nesting,
+// which exceeds the limit once we append `.pi/dashboard/sessions/<uuid>.rpc.sock`.
+// Each test mints its OWN short HOME under /tmp/p... (≤ 12 chars), passed to
+// the keeper subprocess via env. The npm-test HOME isolation tripwire is
+// unaffected — we only override HOME for the spawned child, not the test
+// runner itself. We still create the per-test HOME under /tmp (not the npm-test
+// HOME) because /tmp is short, AND we keep the test isolated from production paths.
+function sessionsDirIn(home: string): string {
+  return path.join(home, ".pi", "dashboard", "sessions");
+}
+function sockPathIn(home: string, sid: string): string {
+  return process.platform === "win32"
+    ? `\\\\.\\pipe\\pi-rpc-${sid}`
+    : path.join(sessionsDirIn(home), `${sid}.rpc.sock`);
+}
+function pidPathIn(home: string, sid: string): string {
+  return process.platform === "win32"
+    ? path.join(sessionsDirIn(home), `pi-rpc-${sid}.pid`)
+    : `${sockPathIn(home, sid)}.pid`;
+}
+function keeperLogIn(home: string, sid: string): string {
+  return path.join(sessionsDirIn(home), `keeper-${sid}.log`);
+}
+
+function makeSessionId(): string {
+  // Short ID to keep total UDS path comfortably under 104 bytes even on
+  // edge-case test environments.
+  return `t${Math.floor(Math.random() * 1e9).toString(36)}`;
+}
+
+function makeShortHome(): string {
+  // /tmp resolves to /private/tmp on macOS but Node uses the path as-given
+  // for UDS bind; either resolved form fits well under 104 bytes.
+  // mkdtempSync('/tmp/p') yields '/tmp/pXXXXXX' (≈12 chars).
+  return mkdtempSync(path.join("/tmp", "p"));
+}
+
+interface SpawnedKeeper {
+  child: ChildProcess;
+  sessionId: string;
+  home: string;
+  mockPiLog: string;
+  exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+}
+
+// Convenience accessors that route through the keeper's own home.
+function sockPathFor(s: SpawnedKeeper): string { return sockPathIn(s.home, s.sessionId); }
+function pidPathFor(s: SpawnedKeeper): string { return pidPathIn(s.home, s.sessionId); }
+function keeperLogFor(s: SpawnedKeeper): string { return keeperLogIn(s.home, s.sessionId); }
+
+interface SpawnKeeperOpts {
+  /** "normal" (default) or "crash" (mock-pi exits 1 immediately) */
+  mode?: "normal" | "crash";
+  /** Override sessionId; otherwise auto-generated */
+  sessionId?: string;
+}
+
+interface SpawnKeeperOptsExt extends SpawnKeeperOpts {
+  /** Override HOME (default: short tmp dir under /tmp/p...). */
+  home?: string;
+  /** If true, do NOT pre-create sessionsDir (tests stale-socket scenarios). */
+  skipMkdir?: boolean;
+}
+
+async function spawnKeeper(opts: SpawnKeeperOptsExt = {}): Promise<SpawnedKeeper> {
+  const sessionId = opts.sessionId ?? makeSessionId();
+  const home = opts.home ?? makeShortHome();
+  if (!opts.skipMkdir) mkdirSync(sessionsDirIn(home), { recursive: true });
+
+  const mockPiLog = path.join(sessionsDirIn(home), `mock-pi-${sessionId}.log`);
+
+  // PATH shim: prepend a dir containing a `pi` script that execs our mock.
+  const tmpBin = path.join(home, "bin");
+  mkdirSync(tmpBin, { recursive: true });
+  const piShimDest = path.join(tmpBin, "pi");
+  const shimSrc = path.join(SHIM_DIR, "mock-pi-shim.sh");
+  writeFileSync(piShimDest, readFileSync(shimSrc, "utf8"), { mode: 0o755 });
+
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    HOME: home,
+    PATH: `${tmpBin}${path.delimiter}${process.env.PATH ?? ""}`,
+    MOCK_PI_CJS_PATH: path.join(SHIM_DIR, "mock-pi.cjs"),
+    MOCK_PI_LOG: mockPiLog,
+    MOCK_PI_MODE: opts.mode ?? "normal",
+  };
+
+  const child = spawn(process.execPath, [KEEPER_PATH, sessionId], {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  // Capture stderr for diagnostics on test failure.
+  child.stderr?.on("data", (b) => {
+    if (process.env.KEEPER_TEST_DEBUG) process.stderr.write(`[keeper:${sessionId}] ${b}`);
+  });
+
+  const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+    (resolve) => {
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    },
+  );
+
+  return { child, sessionId, home, mockPiLog, exited };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 3000, intervalMs = 25): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`waitFor timed out after ${timeoutMs}ms`);
+}
+
+async function readyKeeper(s: SpawnedKeeper): Promise<void> {
+  // "Ready" = (a) socket bound, (b) pid sidecar written, (c) past 300ms
+  // crash window AND keeper still running.
+  await waitFor(() => existsSync(pidPathFor(s)));
+  if (process.platform !== "win32") {
+    await waitFor(() => existsSync(sockPathFor(s)));
+  }
+  // Past the crash window
+  await new Promise((r) => setTimeout(r, 350));
+  if (s.child.exitCode !== null) {
+    const log = existsSync(keeperLogFor(s))
+      ? readFileSync(keeperLogFor(s), "utf8")
+      : "(no log)";
+    throw new Error(`keeper exited prematurely (code=${s.child.exitCode}). Log:\n${log}`);
+  }
+}
+
+async function writeLineToKeeper(s: SpawnedKeeper, line: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const sock = net.createConnection(sockPathFor(s));
+    sock.once("connect", () => {
+      sock.end(line + "\n", "utf8", () => resolve());
+    });
+    sock.once("error", reject);
+  });
+}
+
+async function killAndAwait(s: SpawnedKeeper, signal: NodeJS.Signals = "SIGTERM"): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {
+  if (s.child.exitCode === null) s.child.kill(signal);
+  return s.exited;
+}
+
+// ---------------------------------------------------------------------------
+// Cleanup state across tests
+// ---------------------------------------------------------------------------
+
+const trackedKeepers: SpawnedKeeper[] = [];
+beforeEach(() => {
+  trackedKeepers.length = 0;
+});
+afterEach(async () => {
+  for (const k of trackedKeepers) {
+    if (k.child.exitCode === null) {
+      k.child.kill("SIGKILL");
+      await k.exited.catch(() => undefined);
+    }
+    try { rmSync(k.home, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+});
+
+function track(s: SpawnedKeeper): SpawnedKeeper {
+  trackedKeepers.push(s);
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe.skipIf(process.platform === "win32")("rpc-keeper (Unix UDS)", () => {
+  it("3.2 forwards a JSON line from UDS connection to mock-pi stdin", async () => {
+    const k = track(await spawnKeeper());
+    await readyKeeper(k);
+
+    const line = '{"type":"prompt","message":"hello","id":"1"}';
+    await writeLineToKeeper(k, line);
+
+    // Mock pi appends each line to MOCK_PI_LOG. Wait for it.
+    await waitFor(() => existsSync(k.mockPiLog) && readFileSync(k.mockPiLog, "utf8").includes("hello"));
+
+    const contents = readFileSync(k.mockPiLog, "utf8");
+    expect(contents.trimEnd()).toBe(line);
+
+    // The keeper still has pi alive — clean up.
+    await killAndAwait(k);
+  }, 10_000);
+
+  it("3.3 keeper exits 0 and unlinks files when pi exits", async () => {
+    const k = track(await spawnKeeper());
+    await readyKeeper(k);
+
+    expect(existsSync(sockPathFor(k))).toBe(true);
+    expect(existsSync(pidPathFor(k))).toBe(true);
+
+    // Read the keeper's pi child PID via lsof? Simpler: kill the keeper's
+    // parent's pi child by PGID-equivalent strategy — but that's racy.
+    // Instead, use the shutdown path that's the same code: send SIGTERM
+    // to the keeper, which closes pi's stdin → mock-pi sees EOF → exit 0.
+    // This test exercises the shared shutdown handler path that ALSO
+    // fires on pi-exit (via child.on("exit") → shutdown(0)).
+    const result = await killAndAwait(k, "SIGTERM");
+
+    expect(result.code).toBe(0);
+    expect(existsSync(sockPathFor(k))).toBe(false);
+    expect(existsSync(pidPathFor(k))).toBe(false);
+  }, 10_000);
+
+  it("3.3b keeper exits 0 and unlinks files when pi child exits naturally", async () => {
+    // Stronger version of 3.3: trigger pi's exit (not keeper's signal).
+    // We connect, send EOF to mock-pi indirectly by closing all input
+    // routes. Easiest path: write a line and end the conn — mock-pi will
+    // log the line but won't exit (it waits for stdin EOF, which only
+    // closes when keeper closes pi.stdin, which only happens on keeper
+    // shutdown). So instead: send SIGTERM to the mock-pi child PID by
+    // searching its process tree.
+    const k = track(await spawnKeeper());
+    await readyKeeper(k);
+
+    // Find mock-pi children of the keeper (best-effort via /proc on Linux,
+    // ps on macOS).
+    const mockPids = await findChildPids(k.child.pid!);
+    expect(mockPids.length).toBeGreaterThan(0);
+
+    for (const pid of mockPids) {
+      try { process.kill(pid, "SIGTERM"); } catch { /* gone */ }
+    }
+
+    const result = await k.exited;
+    expect(result.code).toBe(0);
+    expect(existsSync(sockPathFor(k))).toBe(false);
+    expect(existsSync(pidPathFor(k))).toBe(false);
+  }, 10_000);
+
+  it("3.4 stale-socket recovery (pre-create socket file, keeper unlinks + retries)", async () => {
+    const sessionId = makeSessionId();
+    const home = makeShortHome();
+    mkdirSync(sessionsDirIn(home), { recursive: true });
+    // Pre-create a regular file at the socket path. Bind fails with EADDRINUSE.
+    writeFileSync(sockPathIn(home, sessionId), "", { mode: 0o600 });
+
+    const k = track(await spawnKeeper({ sessionId, home }));
+    await readyKeeper(k);
+
+    // Recovery succeeded: the path is now bound (existsSync returns true for sockets too).
+    expect(existsSync(sockPathFor(k))).toBe(true);
+
+    await killAndAwait(k);
+  }, 10_000);
+
+  it("3.5 crash-detection: mock-pi exits immediately, keeper exits non-zero within 1s", async () => {
+    const k = track(await spawnKeeper({ mode: "crash" }));
+
+    // Should NOT reach readyKeeper — wait for exit instead, with a tight bound.
+    const result = await Promise.race([
+      k.exited,
+      new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((_, reject) =>
+        setTimeout(() => reject(new Error("keeper did not exit within 2s")), 2000),
+      ),
+    ]);
+    expect(result.code).not.toBe(0);
+
+    // Files cleaned up
+    expect(existsSync(sockPathFor(k))).toBe(false);
+    expect(existsSync(pidPathFor(k))).toBe(false);
+  }, 5_000);
+
+  it("3.6 concurrent connections — 3 simultaneous UDS connections, all 3 lines forwarded", async () => {
+    const k = track(await spawnKeeper());
+    await readyKeeper(k);
+
+    const lines = [
+      '{"type":"prompt","message":"line-A","id":"a"}',
+      '{"type":"prompt","message":"line-B","id":"b"}',
+      '{"type":"prompt","message":"line-C","id":"c"}',
+    ];
+
+    await Promise.all(lines.map((line) => writeLineToKeeper(k, line)));
+
+    await waitFor(() => {
+      if (!existsSync(k.mockPiLog)) return false;
+      const c = readFileSync(k.mockPiLog, "utf8");
+      return lines.every((l) => c.includes(l));
+    });
+
+    const out = readFileSync(k.mockPiLog, "utf8")
+      .split("\n")
+      .filter((l) => l.length > 0)
+      .sort();
+    expect(out).toEqual([...lines].sort());
+
+    await killAndAwait(k);
+  }, 10_000);
+});
+
+describe.skipIf(process.platform !== "win32")("rpc-keeper (Windows named pipe)", () => {
+  // Task 3.7: same scenarios as Unix, gated by platform.
+  // Windows path uses `\\.\pipe\pi-rpc-<sid>` and `<sessionsDir>/pi-rpc-<sid>.pid`.
+  // Leaving as a single smoke test for now — full coverage of all 3.x cases
+  // requires a Windows CI runner. The spec scenarios apply identically; the
+  // helper functions above already path-switch by platform.
+
+  it("3.7 keeper bound named pipe, forwards a line, exits cleanly on signal", async () => {
+    const k = track(await spawnKeeper());
+    await readyKeeper(k);
+
+    const line = '{"type":"prompt","message":"hello","id":"1"}';
+    await writeLineToKeeper(k, line);
+
+    await waitFor(() => existsSync(k.mockPiLog) && readFileSync(k.mockPiLog, "utf8").includes("hello"));
+
+    const result = await killAndAwait(k);
+    expect(result.code).toBe(0);
+    // Named pipe path is virtual on Windows — only the PID sidecar is unlinked.
+    expect(existsSync(pidPathFor(k))).toBe(false);
+  }, 15_000);
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function findChildPids(parentPid: number): Promise<number[]> {
+  // macOS / Linux: `ps -o pid= --ppid <pid>`
+  return new Promise((resolve) => {
+    // -A is required to see processes outside the calling terminal session;
+    // vitest workers don't have a controlling tty, so without -A the keeper's
+    // child node process is invisible.
+    const ps = spawn("ps", ["-A", "-o", "pid=", "-o", "ppid="], { stdio: ["ignore", "pipe", "ignore"] });
+    let out = "";
+    ps.stdout.on("data", (b) => { out += b; });
+    ps.once("exit", () => {
+      const pids: number[] = [];
+      for (const raw of out.split("\n")) {
+        const m = raw.trim().match(/^(\d+)\s+(\d+)$/);
+        if (m && Number(m[2]) === parentPid) pids.push(Number(m[1]));
+      }
+      resolve(pids);
+    });
+    ps.once("error", () => resolve([]));
+  });
+}

package/packages/server/src/rpc-keeper/dispatch-router.ts

@@ -0,0 +1,85 @@
+/**
+ * Dispatch router for the bridge→server `dispatch_extension_command`
+ * message. Forwards the slash command to the per-session RPC keeper UDS
+ * and emits the terminal `command_feedback` event to browser subscribers
+ * (the bridge already emitted `started`).
+ *
+ * Optimistic completion (design.md Decision 7): a successful UDS write
+ * means pi RECEIVED the line; if pi rejects it, an `extension_error`
+ * event flows back over the bridge WS path and is rendered as a separate
+ * chat row by the existing event-reducer.
+ *
+ * The terminal `completed` / `error` event MUST be persisted in the
+ * dashboard's `eventStore` (same path the bridge's `event_forward` takes)
+ * — otherwise the chat pill renders the bridge's persisted `started`
+ * but the server's optimistic terminal is ephemeral and the upsert never
+ * fires on browser reattach. Stuck-on-"in progress" was the visible
+ * symptom of routing the broadcast directly via `sendToSubscribers`
+ * without storing first.
+ *
+ * See change: add-rpc-stdin-dispatch-with-keeper-sidecar (Phase 8).
+ */
+import type { DispatchExtensionCommandMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+import type { HeadlessPidRegistry } from "../headless-pid-registry.js";
+
+export interface DispatchRouterContext {
+  headlessPidRegistry: HeadlessPidRegistry;
+  /**
+   * Persist + broadcast a `command_feedback` event for `sessionId`.
+   * Wired by `event-wiring.ts` to `eventStore.insertEvent` +
+   * `browserGateway.broadcastEvent` so the event survives browser
+   * reattach via the existing replay path.
+   */
+  emitCommandFeedback(
+    sessionId: string,
+    command: string,
+    status: "completed" | "error",
+    message?: string,
+  ): void;
+}
+
+/**
+ * Build the pi RPC line forwarded over the keeper UDS. Pure helper so
+ * unit tests don't have to JSON-parse to assert the shape.
+ */
+export function buildPiRpcLine(command: string, requestId: string): string {
+  return JSON.stringify({ type: "prompt", message: command, id: requestId });
+}
+
+const ERR_NO_KEEPER = "RPC keeper unavailable for this session";
+const ERR_WRITE_PREFIX = "Failed to write RPC line";
+
+/**
+ * Handle `dispatch_extension_command`: write the pi RPC line to the
+ * session's keeper UDS, then persist + broadcast the optimistic terminal
+ * `command_feedback`. Never throws; failures surface as
+ * `command_feedback {status:"error"}` via `emitCommandFeedback`.
+ */
+export async function handleDispatchExtensionCommand(
+  msg: DispatchExtensionCommandMessage,
+  ctx: DispatchRouterContext,
+): Promise<void> {
+  const { sessionId, command, requestId } = msg;
+  const line = buildPiRpcLine(command, requestId);
+  console.error(
+    `[dispatch-router] dispatch_extension_command sid=${sessionId} cmd=${command} reqId=${requestId.slice(0, 8)}`,
+  );
+
+  let ok = false;
+  try {
+    ok = await ctx.headlessPidRegistry.writeRpc(sessionId, line);
+  } catch (err: any) {
+    const reason = err instanceof Error ? err.message : String(err);
+    ctx.emitCommandFeedback(sessionId, command, "error", `${ERR_WRITE_PREFIX}: ${reason}`);
+    return;
+  }
+
+  if (!ok) {
+    console.error(`[dispatch-router] writeRpc returned false for sid=${sessionId} (no keeper or socket gone)`);
+    ctx.emitCommandFeedback(sessionId, command, "error", ERR_NO_KEEPER);
+    return;
+  }
+
+  console.error(`[dispatch-router] writeRpc OK for sid=${sessionId}, emitting optimistic completed`);
+  ctx.emitCommandFeedback(sessionId, command, "completed");
+}