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

package/packages/server/src/__tests__/provider-catalogue-cache.test.ts

@@ -1,13 +1,14 @@
 /**
  * Tests for the provider-catalogue cache.
- * See change: replace-hardcoded-provider-lists.
+ *
+ * The cache is now a single global snapshot of the most-recent
+ * `providers_list` push. No per-session split, no `changed` signal —
+ * see change: simplify-model-selection-channels for why.
  */
 import { describe, it, expect, beforeEach } from "vitest";
 import {
   setCatalogueForSession,
-  getCatalogueForSession,
   getLatestCatalogue,
-  clearForSession,
   _resetForTests,
 } from "../provider-catalogue-cache.js";
 import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
@@ -18,37 +19,26 @@ const B: ProviderInfo = { id: "b", displayName: "B", hasOAuth: false, configured
 describe("provider-catalogue-cache", () => {
   beforeEach(() => _resetForTests());
 
-  it("starts empty", () => {
+  it("getLatestCatalogue returns [] before any push", () => {
     expect(getLatestCatalogue()).toEqual([]);
-    expect(getCatalogueForSession("s1")).toBeUndefined();
   });
 
-  it("set/get per session", () => {
-    setCatalogueForSession("s1", [A]);
-    expect(getCatalogueForSession("s1")).toEqual([A]);
-  });
-
-  it("latestSnapshot reflects most recent push across sessions", () => {
+  it("setCatalogueForSession overwrites the global snapshot", () => {
     setCatalogueForSession("s1", [A]);
     expect(getLatestCatalogue()).toEqual([A]);
-    setCatalogueForSession("s2", [A, B]);
-    expect(getLatestCatalogue()).toEqual([A, B]);
-  });
-
-  it("clearForSession removes that session and clears latest only when empty", () => {
-    setCatalogueForSession("s1", [A]);
     setCatalogueForSession("s2", [B]);
-    clearForSession("s1");
-    expect(getCatalogueForSession("s1")).toBeUndefined();
     expect(getLatestCatalogue()).toEqual([B]);
-    clearForSession("s2");
-    expect(getLatestCatalogue()).toEqual([]);
   });
 
-  it("_resetForTests wipes everything", () => {
+  it("last writer wins regardless of sessionId", () => {
+    setCatalogueForSession("s1", [A, B]);
+    setCatalogueForSession("s2", [A]);
+    expect(getLatestCatalogue()).toEqual([A]);
+  });
+
+  it("_resetForTests clears the snapshot", () => {
     setCatalogueForSession("s1", [A]);
     _resetForTests();
     expect(getLatestCatalogue()).toEqual([]);
-    expect(getCatalogueForSession("s1")).toBeUndefined();
   });
 });

package/packages/server/src/__tests__/provider-routes-recursion-guard.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Integration test for recursion guard wired into PUT /api/providers (task 10.4).
+ *
+ * Verifies:
+ * - Self-pointing baseUrl → 400 with code RECURSIVE_PROXY
+ * - Valid external baseUrl → accepted (2xx, written to disk)
+ * - Existing providers untouched on validation failure
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify from "fastify";
+import { writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { registerProviderRoutes } from "../routes/provider-routes.js";
+
+const PROVIDERS_PATH = join(homedir(), ".pi", "agent", "providers.json");
+const PROVIDERS_DIR = join(homedir(), ".pi", "agent");
+
+// Back up / restore providers.json around each test
+let backup: string | null = null;
+beforeEach(() => {
+  try { backup = require("fs").readFileSync(PROVIDERS_PATH, "utf-8"); } catch { backup = null; }
+});
+afterEach(() => {
+  try {
+    if (backup !== null) {
+      writeFileSync(PROVIDERS_PATH, backup);
+    } else {
+      rmSync(PROVIDERS_PATH, { force: true });
+    }
+  } catch {}
+});
+
+async function buildApp(port = 8000) {
+  const app = Fastify({ logger: false });
+  const networkGuard = async () => {};
+  mkdirSync(PROVIDERS_DIR, { recursive: true });
+  registerProviderRoutes(app, { networkGuard, port });
+  await app.ready();
+  return app;
+}
+
+describe("recursion guard on PUT /api/providers (task 10.4)", () => {
+  it("localhost self-pointing baseUrl → 400 RECURSIVE_PROXY", async () => {
+    const app = await buildApp(8000);
+
+    const res = await app.inject({
+      method: "PUT",
+      url: "/api/providers",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        providers: {
+          self: { baseUrl: "http://localhost:8000/v1", apiKey: "" },
+        },
+      }),
+    });
+
+    expect(res.statusCode).toBe(400);
+    const body = JSON.parse(res.body);
+    expect(body.code).toBe("RECURSIVE_PROXY");
+    expect(body.offendingBaseUrl).toBe("http://localhost:8000/v1");
+  });
+
+  it("127.0.0.1 variant also caught", async () => {
+    const app = await buildApp(8000);
+
+    const res = await app.inject({
+      method: "PUT",
+      url: "/api/providers",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        providers: {
+          self: { baseUrl: "http://127.0.0.1:8000/v1", apiKey: "" },
+        },
+      }),
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).code).toBe("RECURSIVE_PROXY");
+  });
+
+  it("external baseUrl passes validation", async () => {
+    const app = await buildApp(8000);
+
+    const res = await app.inject({
+      method: "PUT",
+      url: "/api/providers",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        providers: {
+          openai: { baseUrl: "https://api.openai.com/v1", apiKey: "sk-test" },
+        },
+      }),
+    });
+
+    // Should succeed (200/204) or return a non-400 error
+    expect(res.statusCode).not.toBe(400);
+    const body = JSON.parse(res.body);
+    expect(body.code).not.toBe("RECURSIVE_PROXY");
+  });
+
+  it("validation failure leaves existing providers untouched", async () => {
+    // Pre-populate providers.json with a valid provider
+    mkdirSync(PROVIDERS_DIR, { recursive: true });
+    writeFileSync(PROVIDERS_PATH, JSON.stringify({
+      providers: { openai: { baseUrl: "https://api.openai.com/v1", apiKey: "sk-existing" } },
+    }));
+
+    const app = await buildApp(8000);
+
+    // Attempt to add a recursive provider — should fail
+    const res = await app.inject({
+      method: "PUT",
+      url: "/api/providers",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        providers: {
+          openai: { baseUrl: "https://api.openai.com/v1", apiKey: "sk-existing" },
+          self: { baseUrl: "http://localhost:8000/v1", apiKey: "" },
+        },
+      }),
+    });
+
+    expect(res.statusCode).toBe(400);
+
+    // Read providers.json — existing provider should still be there
+    const stored = JSON.parse(require("fs").readFileSync(PROVIDERS_PATH, "utf-8"));
+    expect(stored.providers?.openai?.baseUrl).toBe("https://api.openai.com/v1");
+    expect(stored.providers?.self).toBeUndefined();
+  });
+});

package/packages/server/src/__tests__/recommended-routes.test.ts

@@ -8,7 +8,7 @@ import os from "node:os";
 import path from "node:path";
 
 // Mock pi dependency (pulled transitively by package-manager-wrapper)
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
 	DefaultPackageManager: function () {
 		return {};
 	},
@@ -195,7 +195,7 @@ describe("GET /api/packages/recommended", () => {
 		return fastify;
 	}
 
-	it("returns the 5 manifest entries with default (offline) descriptions", async () => {
+	it("returns the 6 manifest entries with default (offline) descriptions", async () => {
 		vi.mocked(fetchPackageMeta).mockResolvedValue(null);
 		vi.mocked(fetchGithubPackageJson).mockResolvedValue(null);
 		await setupRoute();
@@ -208,7 +208,7 @@ describe("GET /api/packages/recommended", () => {
 		const body = JSON.parse(res.payload);
 		expect(body.success).toBe(true);
 		const entries = body.data.recommended;
-		expect(entries).toHaveLength(5);
+		expect(entries).toHaveLength(6);
 		// Every entry falls back to fallbackDescription and has no version.
 		for (const e of entries) {
 			expect(typeof e.description).toBe("string");

package/packages/server/src/__tests__/spawn-correlation-token-integration.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Integration: verify the kill-fork-kills-parent bug stays fixed.
+ *
+ * Simulates the race window where parent + fork are both registered in the
+ * same cwd and bridges connect in arbitrary order. Asserts the registry
+ * resolves each sessionId to its OWN PID via the three-tier link.
+ *
+ * See change: spawn-correlation-token.
+ */
+import { describe, it, expect } from "vitest";
+import { EventEmitter } from "node:events";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createHeadlessPidRegistry } from "../headless-pid-registry.js";
+import { createPendingForkRegistry } from "../pending-fork-registry.js";
+import { mintSpawnToken } from "../spawn-token.js";
+
+function mockProc() {
+  return new EventEmitter() as any;
+}
+
+function tmpPidFile() {
+  return join(mkdtempSync(join(tmpdir(), "spawn-corr-")), "pids.json");
+}
+
+describe("spawn-correlation-token: kill-fork-doesn't-kill-parent regression", () => {
+  it("two same-cwd spawns: each session resolves to its OWN pid via token", () => {
+    // Setup: simulate dashboard spawning parent, then fork, in the same cwd.
+    // Each spawn mints a token; registry stores entries by pid + token.
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    const tokenParent = mintSpawnToken();
+    const tokenFork = mintSpawnToken();
+    expect(tokenParent).not.toBe(tokenFork);
+
+    registry.register(1000, "/proj", mockProc(), tokenParent);
+    registry.register(1234, "/proj", mockProc(), tokenFork);
+
+    // Bridge connect order is reversed (fork first, parent second) — the
+    // worst-case race that produced the original bug.
+    expect(registry.linkByToken(tokenFork, "S_fork")).toBe(true);
+    expect(registry.linkByToken(tokenParent, "S_parent")).toBe(true);
+
+    // Critical: each session resolves to its OWN pid. Pre-fix this would
+    // have given S_fork → 1000 (parent) and S_parent → 1234 (fork) due to
+    // cwd-FIFO ordering.
+    expect(registry.getPid("S_fork")).toBe(1234);
+    expect(registry.getPid("S_parent")).toBe(1000);
+  });
+
+  it("legacy bridge fallback: linkByPid is exact even without tokens", () => {
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    // Legacy bridges don't send spawnToken; only pid.
+    registry.register(1000, "/proj", mockProc()); // no token
+    registry.register(1234, "/proj", mockProc()); // no token
+
+    // Race-order register messages, but pid-link is direct lookup.
+    expect(registry.linkByPid("S_fork", 1234)).toBe(true);
+    expect(registry.linkByPid("S_parent", 1000)).toBe(true);
+
+    expect(registry.getPid("S_fork")).toBe(1234);
+    expect(registry.getPid("S_parent")).toBe(1000);
+  });
+
+  it("fork registry: per-token keying separates two forks in same cwd", () => {
+    const forkRegistry = createPendingForkRegistry();
+    const tokenA = mintSpawnToken();
+    const tokenB = mintSpawnToken();
+
+    // Two forks issued in the same cwd, each with its own token. Pre-fix
+    // (cwd-keyed registry) the second recordFork would overwrite the first.
+    forkRegistry.recordFork(tokenA, "parent-A");
+    forkRegistry.recordFork(tokenB, "parent-B");
+
+    // Bridge connect order arbitrary; each token resolves to its OWN parent.
+    expect(forkRegistry.consumeFork(tokenB)).toBe("parent-B");
+    expect(forkRegistry.consumeFork(tokenA)).toBe("parent-A");
+  });
+
+  it("stale token (server-restart-mid-spawn) degrades to lower-tier match", () => {
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    // Bridge holds an env-var token from before server restart; the new
+    // server has no entry for that token. linkByToken returns false; the
+    // event-wiring caller falls through to linkByPid.
+    registry.register(1000, "/proj", mockProc()); // post-restart entry, no token
+    expect(registry.linkByToken("stale_tok_from_old_server", "S")).toBe(false);
+    // Caller falls back:
+    expect(registry.linkByPid("S", 1000)).toBe(true);
+    expect(registry.getPid("S")).toBe(1000);
+  });
+});

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

@@ -164,3 +164,87 @@ describe("SpawnRegisterWatchdog", () => {
     expect(recoveries).toHaveLength(0);
   });
 });
+
+// See change: spawn-correlation-token — third index by token.
+describe("SpawnRegisterWatchdog: byToken index", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("clearByToken cancels the watchdog", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByToken("tok_a");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("clearByToken removes entry from cwd and pid indices too", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByToken("tok_a");
+    // Subsequent clearByPid / clearByCwd are no-ops (entry already removed).
+    w.clearByPid(100);
+    w.clearByCwd("/p");
+    // No exception, no double-clear.
+    expect(true).toBe(true);
+  });
+
+  it("clearByPid also clears the token index", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByPid(100);
+    // Token-keyed clear is now a no-op (already cleaned up).
+    w.clearByToken("tok_a");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("tmux arm without pid: token clears watchdog", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ cwd: "/p", mechanism: "tmux", ws, spawnToken: "tok_b" });
+    w.clearByToken("tok_b");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("late clearByToken after timeout emits recovered", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_c" });
+    vi.advanceTimersByTime(31_000); // timeout fires
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+    w.clearByToken("tok_c");
+    expect(messages.filter((m) => m.includes("spawn_register_recovered"))).toHaveLength(1);
+  });
+
+  it("two simultaneous arms with distinct tokens, distinct cwds: token-clears each independently", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws: ws1, messages: m1 } = makeMockWs();
+    const { ws: ws2, messages: m2 } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p1", mechanism: "headless", ws: ws1, spawnToken: "tok_x" });
+    w.arm({ pid: 200, cwd: "/p2", mechanism: "headless", ws: ws2, spawnToken: "tok_y" });
+    w.clearByToken("tok_y");
+    vi.advanceTimersByTime(31_000);
+    // Only the first arm's timeout fired (second was cleared).
+    expect(m1.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+    expect(m2.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("arm without spawnToken behaves as before", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws });
+    // Token-clear with empty / unknown token is a no-op.
+    w.clearByToken("tok_unknown");
+    vi.advanceTimersByTime(31_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,57 @@
+/**
+ * Tests for spawn correlation token primitives.
+ *
+ * Covers:
+ *   - `mintSpawnToken()` returns distinct UUIDv4 strings.
+ *   - `buildSpawnEnv(env, { spawnToken })` injects `PI_DASHBOARD_SPAWN_TOKEN`.
+ *   - Without `spawnToken`, env is unchanged (no leakage).
+ *
+ * See change: spawn-correlation-token.
+ */
+import { describe, expect, it } from "vitest";
+import { mintSpawnToken, SPAWN_TOKEN_ENV_VAR } from "../spawn-token.js";
+import { buildSpawnEnv } from "../process-manager.js";
+
+describe("mintSpawnToken", () => {
+	it("returns a UUIDv4 string", () => {
+		const t = mintSpawnToken();
+		expect(typeof t).toBe("string");
+		// UUIDv4: 8-4-4-4-12 hex with version=4 nibble
+		expect(t).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+	});
+
+	it("returns distinct tokens on each call", () => {
+		const tokens = new Set<string>();
+		for (let i = 0; i < 50; i++) tokens.add(mintSpawnToken());
+		expect(tokens.size).toBe(50);
+	});
+});
+
+describe("buildSpawnEnv: spawnToken injection", () => {
+	it("sets PI_DASHBOARD_SPAWN_TOKEN when spawnToken is provided", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" }, { spawnToken: "tok_test_123" });
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBe("tok_test_123");
+	});
+
+	it("does not set PI_DASHBOARD_SPAWN_TOKEN when spawnToken is omitted", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" });
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBeUndefined();
+	});
+
+	it("does not set PI_DASHBOARD_SPAWN_TOKEN when opts is empty", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" }, {});
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBeUndefined();
+	});
+
+	it("preserves baseEnv variables unchanged when injecting", () => {
+		const env = buildSpawnEnv(
+			{ HOME: "/tmp", FOO: "bar", PATH: "/usr/bin" },
+			{ spawnToken: "tok_xyz" },
+		);
+		expect(env.HOME).toBe("/tmp");
+		expect(env.FOO).toBe("bar");
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBe("tok_xyz");
+		// PATH may be mutated by managed-node prepend, but the raw value should still appear in it.
+		expect(env.PATH).toContain("/usr/bin");
+	});
+});

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

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  probeTunnel,
+  startTunnelWatchdog,
+  stopTunnelWatchdog,
+  getTunnelWatchdogStatus,
+  _runTickForTest,
+  _resetForTest,
+} from "../tunnel-watchdog.js";
+
+const URL = "https://abc.share.zrok.io";
+
+function makeFetch(responses: Array<Response | Error>): typeof fetch {
+  let i = 0;
+  return (async () => {
+    const r = responses[Math.min(i, responses.length - 1)];
+    i += 1;
+    if (r instanceof Error) throw r;
+    return r;
+  }) as unknown as typeof fetch;
+}
+
+describe("probeTunnel", () => {
+  it("returns ok on 2xx", async () => {
+    const f = makeFetch([new Response("{}", { status: 200 })]);
+    expect(await probeTunnel(URL, 1000, f)).toEqual({ ok: true, status: 200 });
+  });
+
+  it("returns ok on 4xx (auth gate proves edge↔local works)", async () => {
+    const f = makeFetch([new Response("", { status: 401 })]);
+    expect(await probeTunnel(URL, 1000, f)).toEqual({ ok: true, status: 401 });
+  });
+
+  it("returns NOT ok on 5xx", async () => {
+    const f = makeFetch([new Response("bad gateway", { status: 502 })]);
+    const r = await probeTunnel(URL, 1000, f);
+    expect(r.ok).toBe(false);
+    expect(r.status).toBe(502);
+    expect(r.reason).toMatch(/502/);
+  });
+
+  it("returns NOT ok on network error", async () => {
+    const f = makeFetch([new Error("ENOTFOUND")]);
+    const r = await probeTunnel(URL, 1000, f);
+    expect(r.ok).toBe(false);
+    expect(r.reason).toMatch(/ENOTFOUND/);
+  });
+});
+
+describe("watchdog lifecycle", () => {
+  beforeEach(() => { _resetForTest(); });
+  afterEach(() => { _resetForTest(); });
+
+  it("does not start when disabled", () => {
+    startTunnelWatchdog(
+      { getUrl: () => URL, recycle: vi.fn(async () => URL) },
+      { enabled: false },
+    );
+    expect(getTunnelWatchdogStatus()).toBeNull();
+  });
+
+  it("recycles after threshold consecutive 5xx", async () => {
+    const recycle = vi.fn(async () => URL);
+    const fetchFn = makeFetch([
+      new Response("", { status: 502 }),
+      new Response("", { status: 502 }),
+    ]);
+    startTunnelWatchdog(
+      { getUrl: () => URL, recycle, fetchFn, log: () => {} },
+      { intervalMs: 1000, failureThreshold: 2, probeTimeoutMs: 500 },
+    );
+    await _runTickForTest();
+    expect(recycle).not.toHaveBeenCalled();
+    expect(getTunnelWatchdogStatus()?.consecutiveFailures).toBe(1);
+
+    await _runTickForTest();
+    expect(recycle).toHaveBeenCalledTimes(1);
+    const s = getTunnelWatchdogStatus()!;
+    expect(s.consecutiveFailures).toBe(0);
+    expect(s.recycleCount).toBe(1);
+    expect(s.lastRecycleAt).toBeGreaterThan(0);
+  });
+
+  it("does not recycle on a single failure surrounded by success", async () => {
+    const recycle = vi.fn(async () => URL);
+    const fetchFn = makeFetch([
+      new Response("", { status: 200 }),
+      new Response("", { status: 502 }),
+      new Response("", { status: 200 }),
+    ]);
+    startTunnelWatchdog(
+      { getUrl: () => URL, recycle, fetchFn, log: () => {} },
+      { intervalMs: 1000, failureThreshold: 2, probeTimeoutMs: 500 },
+    );
+    await _runTickForTest();
+    await _runTickForTest();
+    await _runTickForTest();
+    expect(recycle).not.toHaveBeenCalled();
+    expect(getTunnelWatchdogStatus()?.consecutiveFailures).toBe(0);
+  });
+
+  it("treats recycle failure as a no-op for stats but flags it for backoff", async () => {
+    const recycle = vi.fn(async () => null); // recycle returned no URL
+    const fetchFn = makeFetch([
+      new Response("", { status: 502 }),
+      new Response("", { status: 502 }),
+    ]);
+    startTunnelWatchdog(
+      { getUrl: () => URL, recycle, fetchFn, log: () => {} },
+      { intervalMs: 1000, failureThreshold: 2, probeTimeoutMs: 500 },
+    );
+    await _runTickForTest();
+    await _runTickForTest();
+    expect(recycle).toHaveBeenCalledTimes(1);
+    expect(getTunnelWatchdogStatus()?.recycleCount).toBe(1);
+  });
+
+  it("skips probing when no tunnel URL", async () => {
+    const recycle = vi.fn(async () => URL);
+    const fetchFn = vi.fn();
+    startTunnelWatchdog(
+      { getUrl: () => null, recycle, fetchFn: fetchFn as any, log: () => {} },
+      { intervalMs: 1000, failureThreshold: 2, probeTimeoutMs: 500 },
+    );
+    await _runTickForTest();
+    expect(fetchFn).not.toHaveBeenCalled();
+    expect(recycle).not.toHaveBeenCalled();
+  });
+
+  it("stop clears state", () => {
+    startTunnelWatchdog(
+      { getUrl: () => URL, recycle: vi.fn(async () => URL), log: () => {} },
+      { intervalMs: 1000 },
+    );
+    expect(getTunnelWatchdogStatus()).not.toBeNull();
+    stopTunnelWatchdog();
+    expect(getTunnelWatchdogStatus()).toBeNull();
+  });
+});

package/packages/server/src/auth-plugin.ts

@@ -253,6 +253,9 @@ export async function registerAuthPlugin(
     // Skip health endpoint
     if (request.url === "/api/health") return;
 
+    // Skip /v1/* — proxy auth gate handles those
+    if (request.url.startsWith("/v1/")) return;
+
     // Skip configured bypass URL prefixes
     if (isBypassed(request.url, authState.bypassUrls)) return;
 

package/packages/server/src/bootstrap-state.ts

@@ -69,6 +69,16 @@ export interface BootstrapState {
     /** Package names that failed to install. */
     failed: string[];
   };
+  /**
+   * Legacy `@mariozechner/pi-coding-agent` installs detected on disk.
+   * Populated at server start and after every cleanup POST. See
+   * `legacy-pi-cleanup.ts`.
+   */
+  legacyPiInstalls?: Array<{
+    scope: "npm-global" | "npx-cache" | "managed";
+    path: string;
+    version: string | null;
+  }>;
 }
 
 export type BootstrapListener = (state: BootstrapState) => void;