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

package/packages/shared/src/config.ts

@@ -57,6 +57,8 @@ export interface AuthConfig {
   allowedUsers?: string[];
   bypassUrls?: string[];
   bypassHosts?: string[];
+  /** Admin email override — can list/revoke every user's proxy API keys. */
+  admin?: string;
 }
 
 export interface MemoryLimitsConfig {
@@ -75,6 +77,16 @@ export const DEFAULT_MEMORY_LIMITS: MemoryLimitsConfig = {
 };
 
 export interface OpenSpecPollConfig {
+  /**
+   * Master gate. When `false`, the dashboard treats OpenSpec as fully disabled
+   * across the dashboard — no polling, the OPENSPEC session-card subcard hides
+   * everywhere, and `openspec_refresh` is a no-op. Other tuning fields below
+   * retain their meaning but are ignored at runtime when this is `false`.
+   *
+   * Default `true` for backwards compatibility. Existing configs without this
+   * field behave exactly as before. See change: auto-hide-empty-session-subcards.
+   */
+  enabled: boolean;
   /** Poll interval in seconds. Default 30. Clamped to [5, 3600]. */
   pollIntervalSeconds: number;
   /** Max concurrent `openspec` CLI invocations across all dirs. Default 3. Clamped to [1, 16]. */
@@ -86,6 +98,7 @@ export interface OpenSpecPollConfig {
 }
 
 export const DEFAULT_OPENSPEC_POLL: OpenSpecPollConfig = {
+  enabled: true,
   pollIntervalSeconds: 30,
   maxConcurrentSpawns: 3,
   changeDetection: "mtime",
@@ -113,6 +126,47 @@ export interface KnownServer {
   addedAt: string; // ISO timestamp
 }
 
+// ── Model Proxy ─────────────────────────────────────────────────────
+
+export interface ProxyApiKey {
+  id: string;
+  label: string;
+  createdBy?: string;
+  scopes?: string[];
+  createdAt: number;
+  lastUsedAt?: number;
+  expiresAt?: number;
+  revokedAt?: number;
+  hash: string;
+}
+
+export interface ModelProxyConfig {
+  /** Master toggle. Default true. */
+  enabled: boolean;
+  /** Default model for requests that omit it. */
+  defaultModel?: string;
+  /** Optional second port for /v1/* routes (for SDKs that hardcode path-prefix-less base URLs). */
+  secondPort?: number;
+  /** Server-wide max concurrent streams. Default 16. Clamped [1, 256]. */
+  maxConcurrentStreams: number;
+  /** Per-API-key max concurrent streams. Default 4. Clamped [1, 64]. */
+  perKeyConcurrentStreams: number;
+  /** Per-provider concurrency caps. Keys are provider names. */
+  perProviderCaps?: Record<string, number>;
+  /** Enable JSONL request logging. Default false. */
+  logRequests: boolean;
+  /** Proxy API keys (stored hashed). */
+  apiKeys: ProxyApiKey[];
+}
+
+export const DEFAULT_MODEL_PROXY: ModelProxyConfig = {
+  enabled: true,
+  maxConcurrentStreams: 16,
+  perKeyConcurrentStreams: 4,
+  logRequests: false,
+  apiKeys: [],
+};
+
 /**
  * Plugin-specific config namespace.
  * Lives at ~/.pi/dashboard/config.json#plugins.<id>.*
@@ -126,7 +180,16 @@ export interface DashboardConfig {
   autoShutdown: boolean;
   shutdownIdleSeconds: number;
   spawnStrategy: SpawnStrategy;
-  tunnel: { enabled: boolean; reservedToken?: string };
+  tunnel: {
+    enabled: boolean;
+    reservedToken?: string;
+    watchdog?: {
+      enabled: boolean;
+      intervalMs: number;
+      failureThreshold: number;
+      probeTimeoutMs: number;
+    };
+  };
   devBuildOnReload: boolean;
   auth?: AuthConfig;
   defaultModel: string;
@@ -165,6 +228,17 @@ export interface DashboardConfig {
    * See change: spawn-failure-diagnostics.
    */
   spawnRegisterTimeoutMs: number;
+  /**
+   * EXPERIMENTAL: when true, headless pi sessions are spawned through the
+   * RPC keeper sidecar instead of the legacy `sh -c "tail -f /dev/null | pi"`
+   * (Unix) or direct-pipe (Windows) paths. The keeper owns pi's stdin and
+   * exposes a per-session UDS / named pipe the server writes RPC `prompt`
+   * lines to. Enables typed extension slash commands (`/ctx-stats`,
+   * `/curator`, `/agents`, `/flows:*`) to dispatch in headless sessions
+   * against pi versions that do not yet expose `pi.dispatchCommand`.
+   * Default `false`. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+   */
+  useRpcKeeper: boolean;
   /**
    * Per-plugin config namespaces. Reserved top-level key.
    * Each plugin's config lives at plugins.<id>.*
@@ -172,6 +246,8 @@ export interface DashboardConfig {
    * until each extract-*-as-plugin change migrates them.
    */
   plugins: PluginsConfig;
+  /** Model proxy configuration (OpenAI/Anthropic-compatible /v1/* endpoints). */
+  modelProxy: ModelProxyConfig;
 }
 
 export interface CorsConfig {
@@ -193,13 +269,22 @@ export function clampSpawnRegisterTimeoutMs(v: unknown): number {
 
 const DEFAULTS: DashboardConfig = {
   plugins: {},
+  modelProxy: { ...DEFAULT_MODEL_PROXY },
   port: 8000,
   piPort: 9999,
   autoStart: true,
   autoShutdown: false,
   shutdownIdleSeconds: 300,
   spawnStrategy: "headless",
-  tunnel: { enabled: true },
+  tunnel: {
+    enabled: true,
+    watchdog: {
+      enabled: true,
+      intervalMs: 60000,
+      failureThreshold: 2,
+      probeTimeoutMs: 10000,
+    },
+  },
   devBuildOnReload: false,
   defaultModel: "",
   memoryLimits: { ...DEFAULT_MEMORY_LIMITS },
@@ -213,6 +298,7 @@ const DEFAULTS: DashboardConfig = {
   askUserPromptTimeoutSeconds: DEFAULT_ASK_USER_PROMPT_TIMEOUT_SECONDS,
   reattachPlacement: DEFAULT_REATTACH_PLACEMENT,
   spawnRegisterTimeoutMs: 30000,
+  useRpcKeeper: false,
 };
 
 /**
@@ -274,6 +360,7 @@ function parseAuthConfig(raw: any): AuthConfig | undefined {
     ...(Array.isArray(raw.allowedUsers) ? { allowedUsers: raw.allowedUsers } : Array.isArray(raw.allowedEmails) ? { allowedUsers: raw.allowedEmails } : {}),
     bypassUrls: Array.isArray(raw.bypassUrls) ? raw.bypassUrls.filter((u: unknown) => typeof u === "string") : [],
     bypassHosts: Array.isArray(raw.bypassHosts) ? raw.bypassHosts.filter((u: unknown) => typeof u === "string") : [],
+    ...(typeof raw.admin === "string" && raw.admin ? { admin: raw.admin } : {}),
   };
 }
 
@@ -300,6 +387,8 @@ function parseOpenSpecPollConfig(raw: any): OpenSpecPollConfig {
       ? raw.changeDetection
       : DEFAULT_OPENSPEC_POLL.changeDetection;
   return {
+    enabled:
+      typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_OPENSPEC_POLL.enabled,
     pollIntervalSeconds: clampNumber(raw.pollIntervalSeconds, DEFAULT_OPENSPEC_POLL.pollIntervalSeconds, 5, 3600),
     maxConcurrentSpawns: clampNumber(raw.maxConcurrentSpawns, DEFAULT_OPENSPEC_POLL.maxConcurrentSpawns, 1, 16),
     changeDetection,
@@ -346,6 +435,70 @@ export function getPluginConfig(
   return config.plugins?.[pluginId] ?? {};
 }
 
+export function parseModelProxyConfig(raw: any): ModelProxyConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_MODEL_PROXY };
+
+  const apiKeys: ProxyApiKey[] = [];
+  if (Array.isArray(raw.apiKeys)) {
+    for (const entry of raw.apiKeys) {
+      if (
+        entry &&
+        typeof entry === "object" &&
+        typeof entry.id === "string" &&
+        typeof entry.label === "string" &&
+        typeof entry.hash === "string" &&
+        typeof entry.createdAt === "number"
+      ) {
+        apiKeys.push({
+          id: entry.id,
+          label: entry.label,
+          hash: entry.hash,
+          createdAt: entry.createdAt,
+          ...(typeof entry.createdBy === "string" ? { createdBy: entry.createdBy } : {}),
+          ...(Array.isArray(entry.scopes) ? { scopes: entry.scopes.filter((s: unknown) => typeof s === "string") } : {}),
+          ...(typeof entry.lastUsedAt === "number" ? { lastUsedAt: entry.lastUsedAt } : {}),
+          ...(typeof entry.expiresAt === "number" ? { expiresAt: entry.expiresAt } : {}),
+          ...(typeof entry.revokedAt === "number" ? { revokedAt: entry.revokedAt } : {}),
+        });
+      }
+    }
+  }
+
+  let perProviderCaps: Record<string, number> | undefined;
+  if (raw.perProviderCaps && typeof raw.perProviderCaps === "object" && !Array.isArray(raw.perProviderCaps)) {
+    perProviderCaps = {};
+    for (const [key, val] of Object.entries(raw.perProviderCaps)) {
+      if (typeof val === "number" && Number.isFinite(val) && val >= 1) {
+        perProviderCaps[key] = Math.min(val, 256);
+      }
+    }
+  }
+
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_MODEL_PROXY.enabled,
+    ...(typeof raw.defaultModel === "string" ? { defaultModel: raw.defaultModel } : {}),
+    ...(typeof raw.secondPort === "number" && raw.secondPort >= 1024 && raw.secondPort <= 65535
+      ? { secondPort: raw.secondPort }
+      : {}),
+    maxConcurrentStreams: clampNumber(
+      raw.maxConcurrentStreams,
+      DEFAULT_MODEL_PROXY.maxConcurrentStreams,
+      1,
+      256,
+    ),
+    perKeyConcurrentStreams: clampNumber(
+      raw.perKeyConcurrentStreams,
+      DEFAULT_MODEL_PROXY.perKeyConcurrentStreams,
+      1,
+      64,
+    ),
+    ...(perProviderCaps ? { perProviderCaps } : {}),
+    logRequests:
+      typeof raw.logRequests === "boolean" ? raw.logRequests : DEFAULT_MODEL_PROXY.logRequests,
+    apiKeys,
+  };
+}
+
 function parseKnownServers(raw: any): KnownServer[] {
   if (!Array.isArray(raw)) return [];
   return raw
@@ -391,6 +544,21 @@ export function loadConfig(): DashboardConfig {
       tunnel: {
         enabled: parsed.tunnel?.enabled ?? defaults.tunnel.enabled,
         ...(parsed.tunnel?.reservedToken ? { reservedToken: parsed.tunnel.reservedToken } : {}),
+        watchdog: {
+          enabled: parsed.tunnel?.watchdog?.enabled ?? defaults.tunnel.watchdog!.enabled,
+          intervalMs:
+            typeof parsed.tunnel?.watchdog?.intervalMs === "number" && parsed.tunnel.watchdog.intervalMs > 0
+              ? parsed.tunnel.watchdog.intervalMs
+              : defaults.tunnel.watchdog!.intervalMs,
+          failureThreshold:
+            typeof parsed.tunnel?.watchdog?.failureThreshold === "number" && parsed.tunnel.watchdog.failureThreshold > 0
+              ? Math.floor(parsed.tunnel.watchdog.failureThreshold)
+              : defaults.tunnel.watchdog!.failureThreshold,
+          probeTimeoutMs:
+            typeof parsed.tunnel?.watchdog?.probeTimeoutMs === "number" && parsed.tunnel.watchdog.probeTimeoutMs > 0
+              ? parsed.tunnel.watchdog.probeTimeoutMs
+              : defaults.tunnel.watchdog!.probeTimeoutMs,
+        },
       },
       devBuildOnReload: parsed.devBuildOnReload ?? defaults.devBuildOnReload,
       defaultModel: typeof parsed.defaultModel === "string" ? parsed.defaultModel : defaults.defaultModel,
@@ -414,6 +582,8 @@ export function loadConfig(): DashboardConfig {
         ? parsed.askUserPromptTimeoutSeconds
         : defaults.askUserPromptTimeoutSeconds,
       spawnRegisterTimeoutMs: clampSpawnRegisterTimeoutMs(parsed.spawnRegisterTimeoutMs),
+      useRpcKeeper: parsed.useRpcKeeper === true,
+      modelProxy: parseModelProxyConfig(parsed.modelProxy),
     };
 
     // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts

package/packages/shared/src/dashboard-plugin/manifest-types.ts

@@ -21,8 +21,23 @@ export interface PluginClaim {
   tab?: SettingsTab;
   /** Slot-specific extra config. */
   config?: Record<string, unknown>;
-  /** Optional exported predicate function name for filtering contributions. */
+  /**
+   * Optional exported predicate function name for filtering contributions.
+   * Answers "does this claim apply to this target?" — a claim failing its
+   * predicate is removed from the slot's claim list entirely.
+   */
   predicate?: string;
+  /**
+   * Optional exported sync function name. Answers "will this claim's component
+   * produce visible output for this target?" — a claim whose shouldRender
+   * returns false is NOT mounted and counts as absent for the wrapper-gate
+   * helpers (e.g. `useSlotHasClaimsForSession`), so parent subcards hide
+   * cleanly. Use when the component conditionally returns `null` based on
+   * dynamic state (e.g. "extension not installed"). MUST be synchronous.
+   *
+   * See change: auto-hide-empty-session-subcards.
+   */
+  shouldRender?: string;
 }
 
 /**

package/packages/shared/src/dashboard-plugin/slot-props.ts

@@ -38,6 +38,14 @@ export interface SlotPropsMap {
     session: DashboardSession;
     pluginContext: AnyPluginContext;
   };
+  "session-card-memory": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
+  "workspace-action-bar": {
+    session: DashboardSession;
+    pluginContext: AnyPluginContext;
+  };
   "content-view": {
     session: DashboardSession;
     routeParams: Record<string, string>;

package/packages/shared/src/dashboard-plugin/slot-types.ts

@@ -6,17 +6,22 @@
  * Adding a slot: minor (non-breaking).
  * Removing or renaming a slot: major (breaking).
  */
+import type { DashboardSession } from "../types.js";
+import type { FolderDescriptor } from "./slot-props.js";
 
 /** All valid slot ids (frozen for v0.x). */
 export type SlotId =
   // React-only slots
   | "sidebar-folder-section"
   | "session-card-action-bar"
+  | "workspace-action-bar"
+  // (session-card-memory is also react-only; declared below for ordering)
   | "content-inline-footer"
   | "anchored-popover"
   | "command-route"
   | "tool-renderer"
   // React-or-descriptor slots
+  | "session-card-memory"
   | "session-card-badge"
   | "content-view"
   | "content-header-sticky"
@@ -59,6 +64,16 @@ export const SLOT_DEFINITIONS: Record<SlotId, SlotDefinition> = {
     payloadTier: "react-only",
     description: "Action buttons on a session card",
   },
+  "session-card-memory": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Memory/Honcho contributions inside the MEMORY subcard of a session card",
+  },
+  "workspace-action-bar": {
+    multiplicity: "many",
+    payloadTier: "react-only",
+    description: "Action buttons inside the WORKSPACE subcard of a session card (jj/git workspace tooling)",
+  },
   "content-view": {
     multiplicity: "one-active",
     payloadTier: "react-or-descriptor",
@@ -149,3 +164,45 @@ export const VALID_SETTINGS_TABS: SettingsTab[] = [
   "security",
   "advanced",
 ];
+
+// ── Predicate input classification ──────────────────────────────────────────
+//
+// `ClaimEntry.predicate` / `.shouldRender` are invoked by exactly two filter
+// helpers in the runtime (`forSession`, `forFolder`). The argument shape is
+// therefore determined by the slot id. `SlotPredicateInput<S>` exposes that
+// classification at the type level so the registry contract can be tightened.
+//
+// See change: slot-generic-claim-entry.
+
+/** Slot ids whose predicates receive a session. */
+type SessionScopedSlot =
+  | "session-card-badge"
+  | "session-card-action-bar"
+  | "session-card-memory"
+  | "workspace-action-bar"
+  | "content-view"
+  | "content-header-sticky"
+  | "content-inline-footer"
+  | "command-route";
+
+/** Slot ids whose predicates receive a folder descriptor. */
+type FolderScopedSlot = "sidebar-folder-section";
+
+/**
+ * Map of slot id → predicate input shape. Resolves to `never` for slots that
+ * are not filtered by predicate (settings-section, tool-renderer, anchored-
+ * popover, every descriptor-only slot). Registering a predicate on a `never`-
+ * input slot is therefore a compile-time error.
+ */
+export type SlotPredicateInput<S extends SlotId> =
+  S extends SessionScopedSlot ? DashboardSession | null | undefined
+  : S extends FolderScopedSlot ? FolderDescriptor
+  : never;
+
+// Type-level test: assert every SlotId is reachable through SlotPredicateInput,
+// either by mapping to a concrete input or explicitly to `never`. This forces a
+// build failure when a new slot id is added without classifying it.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type _AssertAllSlotsPredicateClassified = {
+  [K in SlotId]: SlotPredicateInput<K>;
+};

package/packages/shared/src/platform/binary-lookup.ts

@@ -5,10 +5,117 @@
  */
 import { execSync, spawnSync, buildSafeArgv } from "./exec.js";
 import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 import path from "node:path";
 import os from "node:os";
 import { MANAGED_BIN, MANAGED_DIR } from "../managed-paths.js";
 
+// ── jiti loader resolution constants ──────────────────────────────────────
+
+/**
+ * Pi-coding-agent package names searched for a managed-install jiti.
+ * Upstream first, legacy fork second. Mirrors the prior
+ * `resolveJitiFromPi` wrapper that lived in two electron files.
+ */
+export const MANAGED_PI_PACKAGES = [
+  "@earendil-works/pi-coding-agent",
+  "@mariozechner/pi-coding-agent",
+] as const;
+
+/**
+ * jiti provider package names tried inside every anchor's resolution
+ * chain. Upstream `jiti` first; legacy `@mariozechner/jiti` fallback.
+ * Carried over verbatim from `resolve-jiti.ts`.
+ */
+export const JITI_PACKAGES = ["jiti", "@mariozechner/jiti"] as const;
+
+/**
+ * Test seam: a function that takes a package specifier (e.g.
+ * `"jiti/package.json"`) and returns the resolved path. Production
+ * supplies `createRequire(<anchor>).resolve`; tests supply a stub.
+ * Carried over verbatim from `resolve-jiti.ts`.
+ */
+export type JitiResolver = (specifier: string) => string;
+
+/**
+ * Pure helper: given a jiti package.json path, return the file:// URL
+ * of its register hook. Handles Windows-style drive letters regardless
+ * of host OS (`pathToFileURL` on POSIX URL-encodes backslashes).
+ *
+ * Mirrors the prior helper from the deleted `resolve-jiti.ts`.
+ */
+function jitiRegisterUrl(pkgJsonPath: string): string {
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pkgJsonPath);
+  if (isWindowsStyle) {
+    const registerPath = path.win32.join(
+      path.win32.dirname(pkgJsonPath),
+      "lib",
+      "jiti-register.mjs",
+    );
+    return `file:///${registerPath.replace(/\\/g, "/")}`;
+  }
+  const registerPath = path.join(path.dirname(pkgJsonPath), "lib", "jiti-register.mjs");
+  return pathToFileURL(registerPath).href;
+}
+
+/**
+ * Walk JITI_PACKAGES with the supplied resolver and return the first
+ * hit's register URL. Optional `pathExists` guard rejects hits whose
+ * `lib/jiti-register.mjs` is absent on disk (corrupt installs). When
+ * `pathExists` is omitted, the package.json hit alone is sufficient
+ * — used by the argv/system-pi anchors which already realpath'd a
+ * trustworthy node_modules tree.
+ */
+function walkJiti(
+  resolver: JitiResolver,
+  pathExists?: (p: string) => boolean,
+): string | null {
+  for (const jiti of JITI_PACKAGES) {
+    try {
+      const pkgJson = resolver(`${jiti}/package.json`);
+      if (pathExists) {
+        const registerPath = path.join(path.dirname(pkgJson), "lib", "jiti-register.mjs");
+        if (!pathExists(registerPath)) continue;
+      }
+      return jitiRegisterUrl(pkgJson);
+    } catch { /* next */ }
+  }
+  return null;
+}
+
+/**
+ * Internal deps for `ToolResolver.resolveJiti`. Underscore-prefixed
+ * fields are test seams — production callers pass only `anchor` /
+ * `resolver`.
+ */
+export interface ResolveJitiOpts {
+  /** Caller-supplied anchor inside a node_modules tree (e.g. cliPath). */
+  anchor?: string;
+  /**
+   * When true, skip the managed-pi / system-pi / argv anchors and try
+   * ONLY `opts.anchor`. Used for health-probing a specific extracted
+   * tree where finding jiti elsewhere does not prove the tree itself
+   * is healthy.
+   */
+  anchorOnly?: boolean;
+  /**
+   * Test seam: replaces `createRequire(<anchor>).resolve` at every
+   * probe site. Production omits — actual `createRequire` is used.
+   */
+  resolver?: JitiResolver;
+  /** Test seam: replaces `existsSync` for managed-pi pkg.json + register guards. */
+  _pathExists?: (p: string) => boolean;
+  /** Test seam: replaces `realpathSync` for system-pi + argv anchors. */
+  _realpath?: (p: string) => string;
+  /** Test seam: replaces this resolver's `which("pi")` call. */
+  _whichPi?: () => string | null;
+  /** Test seam: replaces `process.argv[1]`. */
+  _argv1?: string | undefined;
+  /** Test seam: replaces `~/.pi-dashboard` root used to probe managed-pi. */
+  _managedDir?: string;
+}
+
 // ── AppImage self-hit guard (Linux power-user mode safety) ────────────────
 
 /**
@@ -235,6 +342,103 @@ export class ToolResolver {
     return this.which("node");
   }
 
+  /**
+   * Resolve pi's jiti register hook as a `file://` URL.
+   *
+   * Resolution order (first hit wins):
+   *   1. Managed pi install — `~/.pi-dashboard/node_modules/<pkg>` for
+   *      every entry of `MANAGED_PI_PACKAGES` (upstream first, legacy
+   *      fallback). Each candidate's pkg.json is the createRequire
+   *      anchor; walk `JITI_PACKAGES` from there.
+   *   2. System pi via `this.which("pi")` (realpathed to escape
+   *      symlinks like `/usr/local/bin/pi → .../dist/cli.js`).
+   *   3. Caller-supplied `opts.anchor` (e.g. an electron `cliPath`).
+   *   4. `process.argv[1]` (the running pi/node entry; populated for
+   *      bridge-extension callers).
+   *
+   * Returns null when none yield a jiti install. Preserves the
+   * Windows drive-letter URL-wrapping contract that previously lived
+   * on the prior `buildJitiRegisterUrl` helper in `resolve-jiti.ts`.
+   *
+   * Tests inject `_pathExists` / `_realpath` / `_whichPi` / `_argv1`
+   * / `_managedDir` and a flat `resolver` to exercise individual
+   * anchors deterministically.
+   *
+   * Subsumes the previous `resolveJitiImport`, `resolveJitiFromAnchor`,
+   * `pickJitiRegisterUrl`, `pickJitiFromAnchor`, `buildJitiRegisterUrl`,
+   * and the duplicate `resolveJitiFromPi` wrappers in electron.
+   */
+  resolveJiti(opts: ResolveJitiOpts = {}): string | null {
+    const pathExists = opts._pathExists ?? existsSync;
+    const realpath = opts._realpath ?? realpathSync;
+    const whichPi = opts._whichPi ?? (() => this.which("pi"));
+    const argv1 = "_argv1" in opts ? opts._argv1 : process.argv[1];
+    const managedDir = opts._managedDir ?? MANAGED_DIR;
+
+    const makeResolver = (anchor: string): JitiResolver | null => {
+      if (opts.resolver) return opts.resolver;
+      try {
+        const req = createRequire(anchor);
+        return (spec) => req.resolve(spec);
+      } catch {
+        return null;
+      }
+    };
+
+    // anchor-only short-circuit: skip every anchor except opts.anchor.
+    if (opts.anchorOnly) {
+      if (!opts.anchor) return null;
+      if (!pathExists(opts.anchor)) return null;
+      const r = makeResolver(opts.anchor);
+      if (!r) return null;
+      return walkJiti(r, pathExists);
+    }
+
+    // 1. Managed pi installs.
+    for (const pkg of MANAGED_PI_PACKAGES) {
+      const pkgJson = path.join(managedDir, "node_modules", pkg, "package.json");
+      if (!pathExists(pkgJson)) continue;
+      const resolver = makeResolver(pkgJson);
+      if (!resolver) continue;
+      const url = walkJiti(resolver, pathExists);
+      if (url) return url;
+    }
+
+    // 2. System pi.
+    const piPath = whichPi();
+    if (piPath) {
+      let realPi: string;
+      try { realPi = realpath(piPath); } catch { realPi = piPath; }
+      const resolver = makeResolver(realPi);
+      if (resolver) {
+        const url = walkJiti(resolver, pathExists);
+        if (url) return url;
+      }
+    }
+
+    // 3. Caller-supplied anchor.
+    if (opts.anchor && pathExists(opts.anchor)) {
+      const resolver = makeResolver(opts.anchor);
+      if (resolver) {
+        const url = walkJiti(resolver, pathExists);
+        if (url) return url;
+      }
+    }
+
+    // 4. process.argv[1] (or test override).
+    if (argv1) {
+      let realArgv: string;
+      try { realArgv = realpath(argv1); } catch { realArgv = argv1; }
+      const resolver = makeResolver(realArgv);
+      if (resolver) {
+        const url = walkJiti(resolver, pathExists);
+        if (url) return url;
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Build a spawn environment with managed bin, node bin, extra dirs,
    * and common user bin dirs prepended to PATH.