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

package/packages/shared/src/protocol.ts

@@ -289,6 +289,23 @@ export interface UiDataListMessage {
   items: unknown[];
 }
 
+// ── RPC keeper: bridge → server slash dispatch ──
+// See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+//
+// Emitted by `slash-dispatch.ts::tryDispatchExtensionCommand` when the
+// active pi build does NOT expose `pi.dispatchCommand` AND the bridge
+// detects a headless RPC pi (per `isHeadlessRpcSession()`). The server's
+// dispatch-router writes `{type:"prompt", message: command, id: requestId}`
+// to the session's keeper UDS / named pipe and emits the optimistic
+// `command_feedback {status:"completed"}` (or error) to browser subscribers.
+export interface DispatchExtensionCommandMessage {
+  type: "dispatch_extension_command";
+  sessionId: string;
+  command: string;
+  /** UUID minted by the bridge so pi's RPC response can be correlated. */
+  requestId: string;
+}
+
 // ── Extension UI System (Phase 2: live in-page decorations) ──
 // See change: add-extension-ui-decorations.
 
@@ -354,7 +371,8 @@ export type ExtensionToServerMessage =
   | UiModulesListMessage
   | UiDataListMessage
   | ExtUiDecoratorMessage
-  | AssetRegisterMessage;
+  | AssetRegisterMessage
+  | DispatchExtensionCommandMessage;
 
 // ── Server → Extension ──────────────────────────────────────────────
 

package/packages/shared/src/recommended-extensions.ts

@@ -165,6 +165,24 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 		unlocks: ["browser tool (open, snapshot, click, screenshot)"],
 		toolsRegistered: ["browser"],
 	},
+	{
+		id: "pi-memory-honcho",
+		source: "npm:pi-memory-honcho",
+		displayName: "pi-memory-honcho",
+		fallbackDescription:
+			"Persistent cross-session memory backed by Honcho. Pairs with " +
+			"the @blackbelt-technology/pi-dashboard-honcho-plugin dashboard " +
+			"plugin which adds a settings panel, per-card actions, and " +
+			"optional self-hosted Honcho server lifecycle.",
+		status: "optional",
+		unlocks: [
+			"Honcho memory tools (honcho_search, honcho_context, honcho_profile)",
+			"Honcho settings panel (when honcho-plugin is loaded)",
+			"Per-card 🧠 status badge + interview/sync/map actions",
+		],
+		toolsRegistered: ["honcho_search", "honcho_context", "honcho_profile"],
+		autowired: true,
+	},
 ];
 
 /**

package/packages/shared/src/rest-api.ts

@@ -5,6 +5,8 @@ import type {
   DashboardSession,
   DashboardEvent,
   ApiResponse,
+  OpenSpecGroup,
+  OpenSpecGroupsFile,
 } from "./types.js";
 
 export type { ApiResponse } from "./types.js";
@@ -163,8 +165,22 @@ export type MkdirResponse = ApiResponse<MkdirResult>;
 
 // ── Tunnel Status ───────────────────────────────────────────────────
 
+export interface TunnelWatchdogPublicStatus {
+  running: boolean;
+  intervalMs: number;
+  failureThreshold: number;
+  probeTimeoutMs: number;
+  lastProbeAt: number | null;
+  lastSuccessAt: number | null;
+  lastFailureAt: number | null;
+  lastFailureReason: string | null;
+  consecutiveFailures: number;
+  lastRecycleAt: number | null;
+  recycleCount: number;
+}
+
 export type TunnelStatus =
-  | { status: "active"; url: string; serverOs: string }
+  | { status: "active"; url: string; serverOs: string; watchdog?: TunnelWatchdogPublicStatus }
   | { status: "inactive"; serverOs: string }
   | { status: "unavailable"; serverOs: string };
 
@@ -447,3 +463,205 @@ export interface RescanToolsRequest {
 export interface SetToolOverrideRequest {
   path: string;
 }
+
+// ── Model Proxy: wire-protocol types ────────────────────────────────
+
+/** OpenAI Chat Completions request shape (subset relevant to the proxy). */
+export interface OpenAIChatCompletionRequest {
+  model: string;
+  messages: OpenAIChatMessage[];
+  stream?: boolean;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  tools?: OpenAITool[];
+  tool_choice?: string | { type: string; function?: { name: string } };
+  stop?: string | string[];
+}
+
+export interface OpenAIChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content?: string | OpenAIContentPart[];
+  name?: string;
+  tool_calls?: OpenAIToolCall[];
+  tool_call_id?: string;
+}
+
+export interface OpenAIContentPart {
+  type: "text" | "image_url";
+  text?: string;
+  image_url?: { url: string; detail?: string };
+}
+
+export interface OpenAITool {
+  type: "function";
+  function: { name: string; description?: string; parameters?: Record<string, unknown> };
+}
+
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+export interface OpenAIChatCompletionResponse {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: {
+    index: number;
+    message: { role: "assistant"; content?: string | null; tool_calls?: OpenAIToolCall[] };
+    finish_reason: string | null;
+  }[];
+  usage?: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+}
+
+export interface OpenAIChatCompletionStreamChunk {
+  id: string;
+  object: "chat.completion.chunk";
+  created: number;
+  model: string;
+  choices: {
+    index: number;
+    delta: {
+      role?: "assistant";
+      content?: string | null;
+      reasoning_content?: string | null;
+      tool_calls?: { index: number; id?: string; type?: "function"; function?: { name?: string; arguments?: string } }[];
+    };
+    finish_reason: string | null;
+  }[];
+}
+
+export interface OpenAIModelEntry {
+  id: string;
+  object: "model";
+  created: number;
+  owned_by: string;
+  "x-pi"?: {
+    contextWindow?: number;
+    maxTokens?: number;
+    reasoning?: boolean;
+    cost?: { input?: number; output?: number };
+    input?: string[];
+  };
+}
+
+export interface OpenAIModelsResponse {
+  object: "list";
+  data: OpenAIModelEntry[];
+}
+
+/** Anthropic Messages request shape (subset relevant to the proxy). */
+export interface AnthropicMessagesRequest {
+  model: string;
+  messages: AnthropicMessage[];
+  system?: string | AnthropicContentBlock[];
+  max_tokens: number;
+  stream?: boolean;
+  temperature?: number;
+  top_p?: number;
+  tools?: AnthropicTool[];
+  stop_sequences?: string[];
+}
+
+export interface AnthropicMessage {
+  role: "user" | "assistant";
+  content: string | AnthropicContentBlock[];
+}
+
+export interface AnthropicContentBlock {
+  type: string;
+  text?: string;
+  source?: { type: "base64"; media_type: string; data: string };
+  [key: string]: unknown;
+}
+
+export interface AnthropicTool {
+  name: string;
+  description?: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface AnthropicMessagesResponse {
+  id: string;
+  type: "message";
+  role: "assistant";
+  content: AnthropicContentBlock[];
+  model: string;
+  stop_reason: string | null;
+  usage: { input_tokens: number; output_tokens: number };
+}
+
+export interface AnthropicMessagesStreamEvent {
+  type: string;
+  message?: AnthropicMessagesResponse;
+  index?: number;
+  content_block?: AnthropicContentBlock;
+  delta?: { type: string; text?: string; partial_json?: string; thinking?: string; [key: string]: unknown };
+  usage?: { output_tokens: number };
+}
+
+// ── Model Proxy: API key management ─────────────────────────────────
+
+export interface ModelProxyApiKeysCreateRequest {
+  label: string;
+  scopes?: string[];
+  expiresAt?: number;
+}
+
+export interface ModelProxyApiKeyEntry {
+  id: string;
+  label: string;
+  createdBy?: string;
+  scopes: string[];
+  createdAt: number;
+  lastUsedAt?: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  hash: string; // redacted to "***" in list responses
+}
+
+export type ModelProxyApiKeysListResponse = ApiResponse<{
+  keys: ModelProxyApiKeyEntry[];
+  revoked: ModelProxyApiKeyEntry[];
+}>;
+
+export type ModelProxyApiKeysCreateResponse = ApiResponse<{
+  id: string;
+  label: string;
+  createdBy?: string;
+  scopes: string[];
+  createdAt: number;
+  expiresAt?: number;
+  key: string; // cleartext, revealed ONCE
+}>;
+
+// ── OpenSpec Change Grouping ────────────────────────────────────────
+// See change: add-openspec-change-grouping (tasks 1.6, 5.x).
+// Endpoints under `/api/openspec/groups[?cwd=…]`.
+
+export type GetOpenSpecGroupsResponse = ApiResponse<OpenSpecGroupsFile>;
+
+export interface CreateOpenSpecGroupRequest {
+  name: string;
+  color?: string;
+}
+export type CreateOpenSpecGroupResponse = ApiResponse<OpenSpecGroup>;
+
+export interface UpdateOpenSpecGroupRequest {
+  name?: string;
+  color?: string;
+  order?: number;
+}
+export type UpdateOpenSpecGroupResponse = ApiResponse<OpenSpecGroup>;
+
+export type DeleteOpenSpecGroupResponse = ApiResponse<void>;
+
+export interface SetOpenSpecGroupAssignmentRequest {
+  changeName: string;
+  /** `null` removes the assignment (change becomes Ungrouped). */
+  groupId: string | null;
+}
+export type SetOpenSpecGroupAssignmentResponse = ApiResponse<void>;

package/packages/shared/src/server-launcher.ts

@@ -0,0 +1,277 @@
+/**
+ * `launchDashboardServer` — single shared spawn primitive for the
+ * dashboard server. Used by every starter (Bridge, Standalone CLI,
+ * Electron). Owns:
+ *
+ *   - jiti loader resolution via `ToolResolver.resolveJiti({ anchor })`
+ *   - argv construction via `spawnNodeScript` (which delegates to
+ *     `buildNodeImportArgvParts` for the `--import` chunk)
+ *   - env merge: `ToolResolver.buildSpawnEnv()` ∪ caller `env`
+ *     (caller wins on conflict, e.g. `DASHBOARD_STARTER`)
+ *   - log-file policy: caller-owned absolute path; we mkdir, open in
+ *     append mode, write a header line, pass the fd, then close the
+ *     parent's copy after spawn.
+ *   - readiness policy: poll `isDashboardRunning(port)` and resolve /
+ *     reject on the first of: health-ok, port-conflict, child early
+ *     exit, or `healthTimeoutMs` elapsed.
+ *
+ * Does NOT own the log-file PATH — that's caller policy. Conventions:
+ *   - extension: `stdio: "ignore"`
+ *   - cli (`cmdStart`): `~/.pi/dashboard/server.log`
+ *   - electron: existing electron log path
+ *
+ * See change: unify-server-launch-ts-loader.
+ */
+import { dirname } from "node:path";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  writeSync,
+} from "node:fs";
+import type { ChildProcess, SpawnOptions } from "node:child_process"; // ban:child_process-ok — types only
+import { spawnNodeScript } from "./platform/node-spawn.js";
+import { ToolResolver } from "./platform/binary-lookup.js";
+import { isDashboardRunning } from "./server-identity.js";
+
+// ── Errors ──────────────────────────────────────────────────────────────────
+
+/** No jiti install resolved at any anchor. */
+export class JitiNotFoundError extends Error {
+  constructor(message =
+    "Cannot find pi's TypeScript loader (jiti). " +
+    "Is @earendil-works/pi-coding-agent or @mariozechner/pi-coding-agent installed?",
+  ) {
+    super(message);
+    this.name = "JitiNotFoundError";
+  }
+}
+
+/** Target port is occupied by a non-dashboard service. */
+export class PortConflictError extends Error {
+  readonly port: number;
+  constructor(port: number) {
+    super(`Port ${port} is occupied by a non-dashboard service`);
+    this.name = "PortConflictError";
+    this.port = port;
+  }
+}
+
+/** Spawned child exited before reaching health-ok. */
+export class EarlyExitError extends Error {
+  readonly code: number | null;
+  readonly signal: NodeJS.Signals | null;
+  constructor(code: number | null, signal: NodeJS.Signals | null = null) {
+    super(`Server child exited (code=${code}, signal=${signal}) before reaching health`);
+    this.name = "EarlyExitError";
+    this.code = code;
+    this.signal = signal;
+  }
+}
+
+// ── Options + result ────────────────────────────────────────────────────────
+
+export interface LaunchOpts {
+  /** Path to node binary. Defaults to `process.execPath`. */
+  nodeBin?: string;
+  /** Path to the dashboard server CLI script. */
+  cliPath: string;
+  /** Args appended after the entry script (e.g. `--port`, `--pi-port`, `start`). */
+  extraArgs?: readonly string[];
+  /** Caller-supplied jiti-resolution anchor (e.g. cliPath inside a node_modules tree). */
+  anchor?: string;
+  /**
+   * Caller env overrides merged ON TOP of `ToolResolver.buildSpawnEnv()`.
+   * Conflicting keys: caller wins. Pass `DASHBOARD_STARTER` here.
+   * Omit to fall back to the resolver-merged process env.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Stdio routing. `"ignore"` for fire-and-forget (extension); a
+   * `{ logFile }` object for caller-owned append-mode log capture.
+   */
+  stdio: "ignore" | { logFile: string };
+  /**
+   * Optional starter label written to the log header line and (when
+   * present) injected as `DASHBOARD_STARTER` env var if `env` does not
+   * already supply it. Plain string ("Bridge", "Standalone", "Electron").
+   */
+  starter?: string;
+  /** Health-check timeout in milliseconds. */
+  healthTimeoutMs: number;
+  /** Port to probe via `isDashboardRunning(port)`. */
+  port: number;
+  /**
+   * Whether the spawned server detaches from the parent's process
+   * group / Windows Job Object. Default: `true` (server outlives the
+   * launcher — correct for Bridge auto-spawn and Standalone CLI).
+   *
+   * Pass `false` when the caller deliberately ties the server's
+   * lifecycle to its own (Electron — server should die when Electron
+   * quits unless Electron explicitly decides to keep it).
+   */
+  detach?: boolean;
+  /**
+   * Working directory for the spawned process. Defaults to the
+   * launcher's own cwd. Electron passes the project directory.
+   */
+  cwd?: string;
+  // ── Test seams (production omits) ────────────────────────────────────────
+  /** Replace `ToolResolver.resolveJiti` (returns loader URL or null). */
+  _resolveJiti?: () => string | null;
+  /** Replace `spawnNodeScript` (returns ChildProcess). */
+  _spawnNodeScript?: typeof spawnNodeScript;
+  /** Replace `isDashboardRunning`. */
+  _isDashboardRunning?: typeof isDashboardRunning;
+  /** Replace fs primitives used for log-file handling. */
+  _fs?: {
+    mkdirSync?: typeof mkdirSync;
+    openSync?: typeof openSync;
+    closeSync?: typeof closeSync;
+    writeSync?: typeof writeSync;
+  };
+  /** Override poll interval (ms). Default 300. */
+  _pollIntervalMs?: number;
+  /** Override `Date.now` for deterministic timeout testing. */
+  _now?: () => number;
+  /** Override the sleep function used between polls. */
+  _sleep?: (ms: number) => Promise<void>;
+}
+
+export interface LaunchResult {
+  /** Spawned process pid (always present once spawn succeeded). */
+  childPid: number;
+  /** PID reported by `/api/health` (matches `dashboard.pid`); null if unavailable. */
+  reportedPid: number | null;
+  /** Always true when this resolves — readiness was confirmed. */
+  healthOk: true;
+}
+
+// ── Implementation ──────────────────────────────────────────────────────────
+
+const DEFAULT_POLL_MS = 300;
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Filter out `undefined` values from an env-record (NodeJS.ProcessEnv
+ * tolerates undefined; child_process.spawn does not).
+ */
+function compactEnv(base: NodeJS.ProcessEnv): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(base)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Spawn the dashboard server and wait for `/api/health` to confirm
+ * identity. Resolves with `{ childPid, reportedPid, healthOk: true }`
+ * on success; rejects with `JitiNotFoundError` / `PortConflictError`
+ * / `EarlyExitError` / readiness-timeout `Error` per the spec.
+ */
+export async function launchDashboardServer(opts: LaunchOpts): Promise<LaunchResult> {
+  const nodeBin = opts.nodeBin ?? process.execPath;
+  const resolveJiti = opts._resolveJiti ?? (() => new ToolResolver({ processExecPath: nodeBin }).resolveJiti({ anchor: opts.anchor }));
+  const spawn = opts._spawnNodeScript ?? spawnNodeScript;
+  const probe = opts._isDashboardRunning ?? isDashboardRunning;
+  const pollIntervalMs = opts._pollIntervalMs ?? DEFAULT_POLL_MS;
+  const now = opts._now ?? Date.now;
+  const sleep = opts._sleep ?? defaultSleep;
+  const fsMkdir = opts._fs?.mkdirSync ?? mkdirSync;
+  const fsOpen = opts._fs?.openSync ?? openSync;
+  const fsClose = opts._fs?.closeSync ?? closeSync;
+  const fsWrite = opts._fs?.writeSync ?? writeSync;
+
+  // 1. Loader resolution.
+  const loader = resolveJiti();
+  if (!loader) throw new JitiNotFoundError();
+
+  // 2. Env: ToolResolver.buildSpawnEnv() merged with caller env (caller wins).
+  const baseEnv = new ToolResolver({ processExecPath: nodeBin }).buildSpawnEnv(process.env);
+  const env: Record<string, string> = compactEnv(baseEnv);
+  if (opts.starter && !(opts.env && "DASHBOARD_STARTER" in opts.env)) {
+    env["DASHBOARD_STARTER"] = opts.starter;
+  }
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) {
+      if (typeof v === "string") env[k] = v;
+      else if (v === undefined) delete env[k];
+    }
+  }
+
+  // 3. Stdio + log header.
+  let logFd: number | undefined;
+  let stdio: SpawnOptions["stdio"];
+  if (opts.stdio === "ignore") {
+    stdio = "ignore";
+  } else {
+    const { logFile } = opts.stdio;
+    fsMkdir(dirname(logFile), { recursive: true });
+    logFd = fsOpen(logFile, "a");
+    const header = `[${new Date().toISOString()}] ${opts.starter ?? "dashboard"} launch (parent pid ${process.pid}, port ${opts.port}, cli ${opts.cliPath})\n`;
+    try { fsWrite(logFd, header); } catch { /* best-effort */ }
+    stdio = ["ignore", logFd, logFd];
+  }
+
+  // 4. Spawn. spawnNodeScript handles --import URL-wrapping + entry rule.
+  let child: ChildProcess;
+  try {
+    child = spawn({
+      nodeBin,
+      loader,
+      entry: opts.cliPath,
+      args: opts.extraArgs ? [...opts.extraArgs] : undefined,
+      spawnOptions: {
+        detached: opts.detach ?? true,
+        stdio,
+        env,
+        cwd: opts.cwd,
+        windowsHide: true,
+      },
+    });
+  } finally {
+    // Always close the parent's copy of the log fd; the child has its own.
+    if (logFd !== undefined) {
+      try { fsClose(logFd); } catch { /* ignore */ }
+    }
+  }
+
+  try { child.unref(); } catch { /* ignore */ }
+
+  if (!child.pid) {
+    throw new EarlyExitError(child.exitCode ?? null, child.signalCode ?? null);
+  }
+
+  // 5. Readiness loop.
+  const deadline = now() + opts.healthTimeoutMs;
+  while (true) {
+    // Early-exit detection (beats timeout per spec).
+    if (child.exitCode !== null) {
+      throw new EarlyExitError(child.exitCode, child.signalCode ?? null);
+    }
+    let status;
+    try {
+      status = await probe(opts.port);
+    } catch {
+      status = { running: false } as const;
+    }
+    if (status.running) {
+      return {
+        childPid: child.pid,
+        reportedPid: status.pid ?? null,
+        healthOk: true,
+      };
+    }
+    if (status.portConflict) {
+      throw new PortConflictError(opts.port);
+    }
+    if (now() >= deadline) {
+      throw new Error("readiness timeout");
+    }
+    await sleep(pollIntervalMs);
+  }
+}

package/packages/shared/src/tool-registry/__tests__/pi-ai-registration.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Registration and resolution tests for the `pi-ai` module-kind tool.
+ *
+ * Verifies:
+ * - Registry resolves pi-ai when ~/.pi-dashboard/node_modules/@mariozechner/pi-ai/dist/index.js exists (managed)
+ * - Falls back to npmGlobalStrategy when only globally installed
+ * - Returns failed resolution with diagnostic trail when none match
+ * - Override takes precedence
+ *
+ * Note: bareImportStrategy uses real module resolution (createRequire) and
+ * cannot be injected via StrategyDeps.resolveModule in moduleDefWithAliases.
+ * It is implicitly tested (fails gracefully when pi-ai isn't a project dep).
+ *
+ * See change: add-dashboard-model-proxy (task 2.1).
+ */
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ToolRegistry,
+  registerDefaultTools,
+  OverridesStore,
+} from "../index.js";
+
+const HOME = os.homedir();
+const MANAGED_PATH = path.join(
+  HOME,
+  ".pi-dashboard",
+  "node_modules",
+  "@mariozechner",
+  "pi-ai",
+  "dist",
+  "index.js",
+);
+
+function freshRegistry(opts: {
+  exists?: (p: string) => boolean;
+  which?: (name: string) => string | null;
+  npmRootGlobal?: () => string;
+  overrides?: Record<string, string>;
+}) {
+  const store = new OverridesStore({
+    filePath: path.join(os.tmpdir(), `pi-ai-test-${Math.random()}.json`),
+    warn: () => {},
+  });
+  for (const [k, v] of Object.entries(opts.overrides ?? {})) store.set(k, v);
+
+  const r = new ToolRegistry({
+    overrides: store,
+    platform: "linux",
+  });
+  registerDefaultTools(r, {
+    exists: opts.exists ?? (() => false),
+    which: opts.which ?? (() => null),
+    npmRootGlobal: opts.npmRootGlobal ?? (() => ""),
+  });
+  return r;
+}
+
+describe("pi-ai: module registration", () => {
+  it("resolves via managed path when ~/.pi-dashboard/node_modules/@mariozechner/pi-ai exists", () => {
+    const r = freshRegistry({
+      exists: (p) => p === MANAGED_PATH,
+    });
+    const result = r.resolve("pi-ai");
+    expect(result.ok).toBe(true);
+    expect(result.path).toBe(MANAGED_PATH);
+    expect(result.source).toBe("managed");
+  });
+
+  it("falls back to npm-global when only globally installed", () => {
+    const globalRoot = "/usr/lib/node_modules";
+    const globalPath = path.join(
+      globalRoot,
+      "@mariozechner",
+      "pi-ai",
+      "dist",
+      "index.js",
+    );
+    const r = freshRegistry({
+      exists: (p) => p === globalPath,
+      npmRootGlobal: () => globalRoot,
+    });
+    const result = r.resolve("pi-ai");
+    expect(result.ok).toBe(true);
+    expect(result.path).toBe(globalPath);
+    expect(result.source).toBe("npm-global");
+  });
+
+  it("returns failed resolution with diagnostic trail when none match", () => {
+    const r = freshRegistry({});
+    const result = r.resolve("pi-ai");
+    expect(result.ok).toBe(false);
+    expect(result.tried).toBeDefined();
+    expect(result.tried!.length).toBeGreaterThan(0);
+    // Should have tried override, bare-import, managed, npm-global
+    const strategyNames = result.tried!.map((t) => t.strategy);
+    expect(strategyNames).toContain("override");
+    expect(strategyNames).toContain("bare-import");
+    expect(strategyNames).toContain("managed");
+    expect(strategyNames).toContain("npm-global");
+  });
+
+  it("override takes precedence over managed", () => {
+    const overridePath = "/custom/pi-ai/dist/index.js";
+    const r = freshRegistry({
+      exists: (p) => p === overridePath || p === MANAGED_PATH,
+      overrides: { "pi-ai": overridePath },
+    });
+    const result = r.resolve("pi-ai");
+    expect(result.ok).toBe(true);
+    expect(result.path).toBe(overridePath);
+    expect(result.source).toBe("override");
+  });
+
+  it("is registered and resolvable by name", () => {
+    const r = freshRegistry({
+      exists: (p) => p === MANAGED_PATH,
+    });
+    const result = r.resolve("pi-ai");
+    expect(result.name).toBe("pi-ai");
+    expect(result.ok).toBe(true);
+  });
+});