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

package/packages/server/src/spawn-register-watchdog.ts

@@ -32,6 +32,12 @@ export interface WatchdogArmOptions {
   mechanism: SpawnMechanism;
   logPath?: string;
   ws: WebSocket;
+  /**
+   * Server-minted spawn correlation token. When provided, the entry is
+   * indexed in `byToken` for strong-identity clearing via `clearByToken`.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
 }
 
 interface Entry {
@@ -42,12 +48,14 @@ interface Entry {
   logPath?: string;
   ws: WebSocket;
   timeoutMs: number;
+  spawnToken?: string;
 }
 
 interface RecentlyFiredEntry {
   firedAt: number;
   pid?: number;
   ws: WebSocket;
+  spawnToken?: string;
 }
 
 const RECENTLY_FIRED_TTL_MS = 60_000;
@@ -57,6 +65,7 @@ export class SpawnRegisterWatchdog {
   readonly timeoutMs: number;
   private readonly byPid = new Map<number, Entry>();
   private readonly byCwd = new Map<string, Entry>();
+  private readonly byToken = new Map<string, Entry>();
   private readonly recentlyFired = new Map<string, RecentlyFiredEntry>();
 
   constructor(timeoutMs: number) {
@@ -68,19 +77,21 @@ export class SpawnRegisterWatchdog {
     // takes effect on the next spawn without a server restart.
     // See change: spawn-failure-diagnostics (fix W1).
     const effectiveTimeout = clampSpawnRegisterTimeoutMs(opts.timeoutMs ?? this.timeoutMs);
-    const { pid, cwd, mechanism, logPath, ws } = opts;
+    const { pid, cwd, mechanism, logPath, ws, spawnToken } = opts;
     const entry: Entry = {
       timer: null as unknown as ReturnType<typeof setTimeout>,
       cwd, pid, mechanism, logPath, ws,
       timeoutMs: effectiveTimeout,
+      spawnToken,
     };
     entry.timer = setTimeout(() => this._fireEntry(entry), effectiveTimeout);
     // Always index by cwd so a `session_register` clears the watchdog even
     // when the bridge's reported pid differs from the spawner's pid (e.g.
     // Unix headless wraps pi in `sh -c "tail -f /dev/null | pi …"`, so
     // spawnResult.pid is the sh wrapper, not pi). Index by pid additionally
-    // for late-recovery lookup. Replace any prior entry for the same
-    // cwd/pid to avoid leaking timers.
+    // for late-recovery lookup. Index by token (when provided) for
+    // strong-identity clearing. See change: spawn-correlation-token.
+    // Replace any prior entry for the same cwd/pid/token to avoid leaking timers.
     const priorCwd = this.byCwd.get(cwd);
     if (priorCwd) clearTimeout(priorCwd.timer);
     this.byCwd.set(cwd, entry);
@@ -89,6 +100,38 @@ export class SpawnRegisterWatchdog {
       if (priorPid && priorPid !== priorCwd) clearTimeout(priorPid.timer);
       this.byPid.set(pid, entry);
     }
+    if (spawnToken) {
+      const priorTok = this.byToken.get(spawnToken);
+      if (priorTok && priorTok !== priorCwd && priorTok !== entry) clearTimeout(priorTok.timer);
+      this.byToken.set(spawnToken, entry);
+    }
+  }
+
+  /**
+   * Strong-identity clear: cancel watchdog for this exact spawn invocation.
+   * Tier 1 of the three-tier match in `event-wiring.ts`. Removes the entry
+   * from all three indices. See change: spawn-correlation-token.
+   */
+  clearByToken(spawnToken: string): void {
+    const entry = this.byToken.get(spawnToken);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.byToken.delete(spawnToken);
+      const cwdEntry = this.byCwd.get(entry.cwd);
+      if (cwdEntry === entry) this.byCwd.delete(entry.cwd);
+      if (entry.pid !== undefined) {
+        const pidEntry = this.byPid.get(entry.pid);
+        if (pidEntry === entry) this.byPid.delete(entry.pid);
+      }
+      return;
+    }
+    // Check for late recovery: scan recentlyFired for matching token.
+    for (const [cwd, fired] of this.recentlyFired) {
+      if (fired.spawnToken === spawnToken) {
+        this._emitRecovery(cwd, fired);
+        return;
+      }
+    }
   }
 
   clearByPid(pid: number): void {
@@ -96,9 +139,13 @@ export class SpawnRegisterWatchdog {
     if (entry) {
       clearTimeout(entry.timer);
       this.byPid.delete(pid);
-      // Also clear cwd entry if it points at the same arm.
+      // Also clear cwd / token entries if they point at the same arm.
       const cwdEntry = this.byCwd.get(entry.cwd);
       if (cwdEntry === entry) this.byCwd.delete(entry.cwd);
+      if (entry.spawnToken) {
+        const tokEntry = this.byToken.get(entry.spawnToken);
+        if (tokEntry === entry) this.byToken.delete(entry.spawnToken);
+      }
       return;
     }
     // Check for late recovery.
@@ -110,11 +157,15 @@ export class SpawnRegisterWatchdog {
     if (entry) {
       clearTimeout(entry.timer);
       this.byCwd.delete(cwd);
-      // Also clear pid entry if it points at the same arm.
+      // Also clear pid / token entries if they point at the same arm.
       if (entry.pid !== undefined) {
         const pidEntry = this.byPid.get(entry.pid);
         if (pidEntry === entry) this.byPid.delete(entry.pid);
       }
+      if (entry.spawnToken) {
+        const tokEntry = this.byToken.get(entry.spawnToken);
+        if (tokEntry === entry) this.byToken.delete(entry.spawnToken);
+      }
       return;
     }
     // Check for late recovery.
@@ -131,8 +182,12 @@ export class SpawnRegisterWatchdog {
     const cwdEntry = this.byCwd.get(cwd);
     if (cwdEntry === entry) this.byCwd.delete(cwd);
 
-    // Record in recentlyFired for late-recovery detection.
-    this.recentlyFired.set(cwd, { firedAt: Date.now(), pid, ws });
+    // Record in recentlyFired for late-recovery detection (also drop token entry).
+    if (entry.spawnToken) {
+      const tokEntry = this.byToken.get(entry.spawnToken);
+      if (tokEntry === entry) this.byToken.delete(entry.spawnToken);
+    }
+    this.recentlyFired.set(cwd, { firedAt: Date.now(), pid, ws, spawnToken: entry.spawnToken });
 
     // Read stderr tail if logPath available.
     let stderrTail: string | undefined;

package/packages/server/src/spawn-token.ts

@@ -0,0 +1,20 @@
+/**
+ * Spawn correlation token: server-minted UUIDv4 per `spawnPiSession` call.
+ *
+ * Flow: `mintSpawnToken()` → injected into spawned process env as
+ * `PI_DASHBOARD_SPAWN_TOKEN` → bridge reads it → bridge echoes back in
+ * `session_register.spawnToken` → server links via `linkByToken`.
+ *
+ * In-memory only; no persistence. TTL aligned to spawn-register-watchdog.
+ *
+ * See change: spawn-correlation-token.
+ */
+import { randomUUID } from "node:crypto";
+
+/** Mint a fresh UUIDv4 spawn correlation token. */
+export function mintSpawnToken(): string {
+  return randomUUID();
+}
+
+/** Env-var name used for the correlation token in spawned pi processes. */
+export const SPAWN_TOKEN_ENV_VAR = "PI_DASHBOARD_SPAWN_TOKEN";

package/packages/server/src/tunnel-watchdog.ts

@@ -0,0 +1,230 @@
+/**
+ * Tunnel watchdog: periodically probes the public tunnel URL through the
+ * zrok edge and recycles the tunnel when consecutive failures (5xx, network
+ * errors, timeouts) exceed a threshold.
+ *
+ * The zrok `share` subprocess can stay running for days while its connection
+ * to the zrok edge silently goes stale, returning HTTP 502 from the public
+ * URL even though the local upstream is healthy. The fix is a `deleteTunnel`
+ * + `createTunnel` cycle (preserves the reserved token, so the URL stays the
+ * same).
+ *
+ * Probe semantics: we treat ONLY 5xx and network/timeout failures as bad.
+ * Any 2xx/3xx/4xx response proves zrok edge ↔ local server connectivity is
+ * fine and counts as success — even if the local route is auth-gated.
+ */
+
+export interface TunnelWatchdogDeps {
+  /** Returns the active public tunnel URL, or null if no tunnel is up. */
+  getUrl: () => string | null;
+  /** Recycle the tunnel: delete and recreate. Returns the new URL or null. */
+  recycle: () => Promise<string | null>;
+  /** Optional fetch override for tests. */
+  fetchFn?: typeof fetch;
+  /** Optional logger; defaults to console. */
+  log?: (level: "info" | "warn" | "error", msg: string) => void;
+}
+
+export interface TunnelWatchdogConfig {
+  /** Master switch. Default: true. */
+  enabled: boolean;
+  /** Probe cadence. Default: 60_000. */
+  intervalMs: number;
+  /** Consecutive failures before recycling. Default: 2. */
+  failureThreshold: number;
+  /** Per-probe HTTP timeout. Default: 10_000. */
+  probeTimeoutMs: number;
+}
+
+export const DEFAULT_TUNNEL_WATCHDOG_CONFIG: TunnelWatchdogConfig = {
+  enabled: true,
+  intervalMs: 60_000,
+  failureThreshold: 2,
+  probeTimeoutMs: 10_000,
+};
+
+export interface TunnelWatchdogStatus {
+  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;
+}
+
+interface WatchdogState {
+  cfg: TunnelWatchdogConfig;
+  deps: TunnelWatchdogDeps;
+  timer: ReturnType<typeof setTimeout> | null;
+  inFlight: boolean;
+  recycling: boolean;
+  /** Current backoff multiplier applied after a recycle failure (1, 2, 4, …, capped). */
+  backoffMultiplier: number;
+  status: TunnelWatchdogStatus;
+}
+
+let state: WatchdogState | null = null;
+
+const MAX_BACKOFF_MULTIPLIER = 8;
+
+function defaultLog(level: "info" | "warn" | "error", msg: string): void {
+  const prefix = "[tunnel-watchdog]";
+  if (level === "warn") console.warn(prefix, msg);
+  else if (level === "error") console.error(prefix, msg);
+  else console.log(prefix, msg);
+}
+
+function makeInitialStatus(cfg: TunnelWatchdogConfig): TunnelWatchdogStatus {
+  return {
+    running: false,
+    intervalMs: cfg.intervalMs,
+    failureThreshold: cfg.failureThreshold,
+    probeTimeoutMs: cfg.probeTimeoutMs,
+    lastProbeAt: null,
+    lastSuccessAt: null,
+    lastFailureAt: null,
+    lastFailureReason: null,
+    consecutiveFailures: 0,
+    lastRecycleAt: null,
+    recycleCount: 0,
+  };
+}
+
+/** Probe outcome: ok=true on 2xx/3xx/4xx, false on 5xx/network/timeout. */
+export async function probeTunnel(
+  url: string,
+  timeoutMs: number,
+  fetchFn: typeof fetch = fetch,
+): Promise<{ ok: boolean; status?: number; reason?: string }> {
+  const probeUrl = url.replace(/\/+$/, "") + "/api/health";
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(probeUrl, { method: "GET", signal: ctrl.signal });
+    if (res.status >= 500) {
+      return { ok: false, status: res.status, reason: `http ${res.status}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err: any) {
+    const reason = err?.name === "AbortError" ? `timeout ${timeoutMs}ms` : (err?.message || "network error");
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+function scheduleNext(): void {
+  if (!state) return;
+  const delay = state.cfg.intervalMs * state.backoffMultiplier;
+  state.timer = setTimeout(() => { void tick(); }, delay);
+  // Don't keep the event loop alive for the watchdog alone.
+  if (typeof (state.timer as any).unref === "function") (state.timer as any).unref();
+}
+
+async function tick(): Promise<void> {
+  if (!state) return;
+  if (state.inFlight) { scheduleNext(); return; }
+  state.inFlight = true;
+  try {
+    const url = state.deps.getUrl();
+    if (!url) {
+      // No tunnel up — nothing to probe; keep ticking in case it comes up.
+      return;
+    }
+    const fetchFn = state.deps.fetchFn ?? fetch;
+    state.status.lastProbeAt = Date.now();
+    const result = await probeTunnel(url, state.cfg.probeTimeoutMs, fetchFn);
+    if (result.ok) {
+      state.status.lastSuccessAt = Date.now();
+      state.status.consecutiveFailures = 0;
+      state.backoffMultiplier = 1;
+      return;
+    }
+    state.status.lastFailureAt = Date.now();
+    state.status.lastFailureReason = result.reason ?? "unknown";
+    state.status.consecutiveFailures += 1;
+    (state.deps.log ?? defaultLog)(
+      "warn",
+      `probe failed (${state.status.consecutiveFailures}/${state.cfg.failureThreshold}): ${state.status.lastFailureReason}`,
+    );
+    if (state.status.consecutiveFailures >= state.cfg.failureThreshold && !state.recycling) {
+      await runRecycle();
+    }
+  } finally {
+    state.inFlight = false;
+    if (state) scheduleNext();
+  }
+}
+
+async function runRecycle(): Promise<void> {
+  if (!state) return;
+  state.recycling = true;
+  const log = state.deps.log ?? defaultLog;
+  log("warn", `recycling tunnel after ${state.status.consecutiveFailures} consecutive failures`);
+  try {
+    const newUrl = await state.deps.recycle();
+    state.status.lastRecycleAt = Date.now();
+    state.status.recycleCount += 1;
+    state.status.consecutiveFailures = 0;
+    if (newUrl) {
+      log("info", `tunnel recycled: ${newUrl}`);
+      state.backoffMultiplier = 1;
+    } else {
+      log("error", "tunnel recycle returned no URL — backing off");
+      state.backoffMultiplier = Math.min(state.backoffMultiplier * 2 || 2, MAX_BACKOFF_MULTIPLIER);
+    }
+  } catch (err: any) {
+    log("error", `tunnel recycle threw: ${err?.message ?? err}`);
+    state.backoffMultiplier = Math.min(state.backoffMultiplier * 2 || 2, MAX_BACKOFF_MULTIPLIER);
+  } finally {
+    state.recycling = false;
+  }
+}
+
+export function startTunnelWatchdog(
+  deps: TunnelWatchdogDeps,
+  cfg: Partial<TunnelWatchdogConfig> = {},
+): void {
+  if (state) return; // already running
+  const merged: TunnelWatchdogConfig = { ...DEFAULT_TUNNEL_WATCHDOG_CONFIG, ...cfg };
+  if (!merged.enabled) return;
+  state = {
+    cfg: merged,
+    deps,
+    timer: null,
+    inFlight: false,
+    recycling: false,
+    backoffMultiplier: 1,
+    status: makeInitialStatus(merged),
+  };
+  state.status.running = true;
+  scheduleNext();
+}
+
+export function stopTunnelWatchdog(): void {
+  if (!state) return;
+  if (state.timer) clearTimeout(state.timer);
+  state.status.running = false;
+  state = null;
+}
+
+export function getTunnelWatchdogStatus(): TunnelWatchdogStatus | null {
+  if (!state) return null;
+  return { ...state.status };
+}
+
+/** Test-only: force a tick now (returns when the tick completes). */
+export async function _runTickForTest(): Promise<void> {
+  await tick();
+}
+
+/** Test-only: reset module-level state. */
+export function _resetForTest(): void {
+  if (state?.timer) clearTimeout(state.timer);
+  state = null;
+}

package/packages/server/src/tunnel.ts

@@ -17,6 +17,7 @@ import {
 
 const zrokResolver = new ToolResolver({ processExecPath: process.execPath });
 import type { TunnelStatus } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { getTunnelWatchdogStatus } from "./tunnel-watchdog.js";
 import { CONFIG_FILE } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 
 export type { TunnelStatus };
@@ -458,7 +459,10 @@ export function getTunnelUrl(): string | null {
 export function getTunnelStatus(): TunnelStatus {
   const serverOs = process.platform;
   if (activeTunnelUrl) {
-    return { status: "active", url: activeTunnelUrl, serverOs };
+    const wd = getTunnelWatchdogStatus();
+    return wd
+      ? { status: "active", url: activeTunnelUrl, serverOs, watchdog: wd }
+      : { status: "active", url: activeTunnelUrl, serverOs };
   }
   if (detectZrokBinary()) {
     return { status: "inactive", serverOs };

package/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-shared",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Shared types and utilities for pi-dashboard",
   "type": "module",
   "repository": {

package/packages/shared/src/__tests__/binary-lookup-resolveJiti.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Tests for `ToolResolver.resolveJiti` — ported from the prior
+ * `resolve-jiti.test.ts`. Exercises every anchor in the resolution
+ * chain (managed-pi upstream/legacy, system-pi, anchor walk-up,
+ * argv fallback, all-miss) plus the URL-shape invariants
+ * (`file://` URL output, Windows drive-letter wrapping, upstream
+ * jiti chosen before legacy fork).
+ *
+ * Test seams (`_pathExists`, `_realpath`, `_whichPi`, `_argv1`,
+ * `_managedDir`, `resolver`) keep the test pure — no fs / process
+ * mutation, no managed-dir on disk.
+ */
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { ToolResolver, MANAGED_PI_PACKAGES, JITI_PACKAGES } from "../platform/binary-lookup.js";
+
+const MANAGED_DIR = "/fake/.pi-dashboard";
+
+function makeResolver(installed: Record<string, string>) {
+  return (spec: string): string => {
+    if (spec in installed) return installed[spec]!;
+    throw new Error(`Cannot find module '${spec}'`);
+  };
+}
+
+describe("MANAGED_PI_PACKAGES + JITI_PACKAGES contract", () => {
+  it("upstream pi pkg first, legacy fork fallback", () => {
+    expect(MANAGED_PI_PACKAGES).toEqual([
+      "@earendil-works/pi-coding-agent",
+      "@mariozechner/pi-coding-agent",
+    ]);
+  });
+
+  it("upstream jiti first, legacy fork fallback", () => {
+    expect(JITI_PACKAGES).toEqual(["jiti", "@mariozechner/jiti"]);
+  });
+});
+
+describe("ToolResolver.resolveJiti — managed pi", () => {
+  it("hits upstream managed pi (@earendil-works) when only it is present", () => {
+    const upstreamPkgJson = path.join(
+      MANAGED_DIR, "node_modules", "@earendil-works", "pi-coding-agent", "package.json",
+    );
+    const jitiPkgJson = "/managed/upstream/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === upstreamPkgJson || p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+  });
+
+  it("falls through to legacy managed pi (@mariozechner) when upstream is absent", () => {
+    const legacyPkgJson = path.join(
+      MANAGED_DIR, "node_modules", "@mariozechner", "pi-coding-agent", "package.json",
+    );
+    const jitiPkgJson = "/managed/legacy/node_modules/@mariozechner/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) =>
+        p === legacyPkgJson ||
+        p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({
+        "@mariozechner/jiti/package.json": jitiPkgJson,
+      }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!).toContain("@mariozechner/jiti");
+  });
+
+  it("prefers upstream pi over legacy when BOTH managed pkgs are present", () => {
+    const upstream = path.join(MANAGED_DIR, "node_modules", "@earendil-works", "pi-coding-agent", "package.json");
+    const legacy = path.join(MANAGED_DIR, "node_modules", "@mariozechner", "pi-coding-agent", "package.json");
+    const upstreamJiti = "/managed/upstream/jiti/package.json";
+    const legacyJiti = "/managed/legacy/@mariozechner/jiti/package.json";
+    const calls: string[] = [];
+    const resolver = (spec: string): string => {
+      calls.push(spec);
+      if (spec === "jiti/package.json") return upstreamJiti;
+      if (spec === "@mariozechner/jiti/package.json") return legacyJiti;
+      throw new Error(`nope ${spec}`);
+    };
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) =>
+        p === upstream || p === legacy ||
+        p === path.join(path.dirname(upstreamJiti), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver,
+    });
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+    expect(url!).not.toContain("@mariozechner");
+    // Upstream pi anchor produced upstream jiti — legacy pi anchor never tried.
+    expect(calls).toEqual(["jiti/package.json"]);
+  });
+});
+
+describe("ToolResolver.resolveJiti — system pi", () => {
+  it("uses which(\"pi\") when managed pi absent", () => {
+    const piBin = "/usr/local/bin/pi";
+    const piReal = "/usr/local/lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js";
+    const jitiPkgJson = "/usr/local/lib/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => piBin,
+      _realpath: (p) => (p === piBin ? piReal : p),
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+  });
+
+  it("realpaths a symlinked pi binary before resolving", () => {
+    const piSymlink = "/usr/local/bin/pi";
+    const piTarget = "/opt/pi/dist/cli.js";
+    const jitiPkgJson = "/opt/pi/node_modules/jiti/package.json";
+    let realpathArg: string | null = null;
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      // Managed-pi miss; only the symlinked register file exists.
+      _pathExists: (p) => p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => piSymlink,
+      _realpath: (p) => { realpathArg = p; return piTarget; },
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(realpathArg).toBe(piSymlink);
+    expect(url).not.toBeNull();
+  });
+});
+
+describe("ToolResolver.resolveJiti — anchor walk-up + argv fallback", () => {
+  it("uses caller-supplied anchor when prior layers miss", () => {
+    const anchor = "/custom/cli/path.js";
+    const jitiPkgJson = "/custom/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      anchor,
+      _managedDir: MANAGED_DIR,
+      _pathExists: (p) => p === anchor || p === path.join(path.dirname(jitiPkgJson), "lib", "jiti-register.mjs"),
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!).toMatch(/\/jiti\/lib\/jiti-register\.mjs$/);
+  });
+
+  it("returns null when caller-supplied anchor does not exist on disk", () => {
+    const url = new ToolResolver().resolveJiti({
+      anchor: "/missing/path.js",
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => false,
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: () => "/whatever/jiti/package.json",
+    });
+    expect(url).toBeNull();
+  });
+
+  it("falls back to process.argv[1] (test seam) when all earlier anchors miss", () => {
+    const argv = "/runtime/argv1/cli.js";
+    const jitiPkgJson = "/runtime/node_modules/jiti/package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _realpath: (p) => p,
+      _argv1: argv,
+      resolver: makeResolver({ "jiti/package.json": jitiPkgJson }),
+    });
+    expect(url).not.toBeNull();
+  });
+
+  it("returns null when every anchor misses", () => {
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => false,
+      _whichPi: () => null,
+      _argv1: undefined,
+      resolver: () => { throw new Error("nope"); },
+    });
+    expect(url).toBeNull();
+  });
+});
+
+describe("ToolResolver.resolveJiti — URL contract", () => {
+  it("returns a file:// URL parseable by new URL()", () => {
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _argv1: "/runtime/argv1/cli.js",
+      _realpath: (p) => p,
+      resolver: makeResolver({ "jiti/package.json": "/r/node_modules/jiti/package.json" }),
+    });
+    expect(url!.startsWith("file://")).toBe(true);
+    expect(() => new URL(url!)).not.toThrow();
+    expect(url!.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+
+  it("URL-wraps Windows drive-letter pkg.json paths (regression for ERR_UNSUPPORTED_ESM_URL_SCHEME)", () => {
+    const winPkgJson = "B:\\Dev\\Nodejs\\global\\node_modules\\@mariozechner\\jiti\\package.json";
+    const url = new ToolResolver().resolveJiti({
+      _managedDir: MANAGED_DIR,
+      _pathExists: () => true,
+      _whichPi: () => null,
+      _argv1: "C:\\runtime\\cli.js",
+      _realpath: (p) => p,
+      resolver: makeResolver({ "@mariozechner/jiti/package.json": winPkgJson }),
+    });
+    expect(url).not.toBeNull();
+    expect(url!.startsWith("file:///")).toBe(true);
+    expect(() => new URL(url!)).not.toThrow();
+    expect(new URL(url!).protocol).toBe("file:");
+    expect(url!.toLowerCase()).toContain("/b:/");
+    expect(url!.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+});