@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.0

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

@@ -0,0 +1,277 @@
+/**
+ * Tests for /api/tools REST routes.
+ *
+ * Covers: list, get single, rescan (all / one), set override, clear
+ * override, unknown-tool 404, bad-body 400, diagnostics text format.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  ToolRegistry,
+  OverridesStore,
+  registerDefaultTools,
+  type Strategy,
+} from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { registerToolRoutes, formatDiagnostics } from "../routes/tool-routes.js";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function noGuard() {
+  return async () => { /* allow all */ };
+}
+
+function tmpOverridesPath(): string {
+  return path.join(
+    os.tmpdir(),
+    `tool-routes-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+}
+
+/**
+ * Build a registry with two fake tools: `pi` (resolves) and `ghost`
+ * (never resolves). The `override` strategy honors ctx.overrides so
+ * set/clear flows are observable.
+ */
+function buildRegistry(opts?: { existsPath?: string }): ToolRegistry {
+  const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+  const r = new ToolRegistry({ overrides, platform: "linux" });
+
+  const piStrategies: Strategy[] = [
+    {
+      name: "override",
+      run: (ctx) => ctx.overrides["pi"]
+        ? { ok: true, path: ctx.overrides["pi"] }
+        : { ok: false, reason: "no override set" },
+    },
+    { name: "where", run: () => ({ ok: true, path: opts?.existsPath ?? "/usr/bin/pi" }) },
+  ];
+  const ghostStrategies: Strategy[] = [
+    { name: "override", run: (ctx) => ctx.overrides["ghost"]
+      ? { ok: true, path: ctx.overrides["ghost"] }
+      : { ok: false, reason: "no override set" } },
+    { name: "where", run: () => ({ ok: false, reason: "not found on PATH" }) },
+  ];
+  r.register({ name: "pi", kind: "binary", strategies: piStrategies });
+  r.register({ name: "ghost", kind: "binary", strategies: ghostStrategies });
+  return r;
+}
+
+function buildServer(registry: ToolRegistry): FastifyInstance {
+  const fastify = Fastify();
+  registerToolRoutes(fastify, { registry, networkGuard: noGuard() });
+  return fastify;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe("GET /api/tools", () => {
+  let fastify: FastifyInstance;
+  beforeEach(() => { fastify = buildServer(buildRegistry()); });
+  afterEach(async () => { await fastify.close(); });
+
+  it("returns all registered tools", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    const names = body.data.tools.map((t: any) => t.name).sort();
+    expect(names).toEqual(["ghost", "pi"]);
+  });
+});
+
+describe("GET /api/tools/:name", () => {
+  let fastify: FastifyInstance;
+  beforeEach(() => { fastify = buildServer(buildRegistry()); });
+  afterEach(async () => { await fastify.close(); });
+
+  it("returns the resolution for a known tool", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools/pi" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.name).toBe("pi");
+    expect(body.data.ok).toBe(true);
+    expect(body.data.path).toBe("/usr/bin/pi");
+  });
+
+  it("404s for an unregistered tool", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools/bogus" });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toMatch(/Unknown tool/);
+  });
+});
+
+describe("POST /api/tools/rescan", () => {
+  it("rescan() without body clears all caches", async () => {
+    let calls = 0;
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    r.register({
+      name: "pi",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/pi${++calls}` }) }],
+    });
+    const fastify = buildServer(r);
+
+    await fastify.inject({ method: "GET", url: "/api/tools/pi" });
+    expect(r.resolve("pi").path).toBe("/pi1");
+
+    const res = await fastify.inject({ method: "POST", url: "/api/tools/rescan", payload: {} });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.tools[0].path).toBe("/pi2");
+    await fastify.close();
+  });
+
+  it("rescan({ name }) only clears that tool's cache", async () => {
+    let piCalls = 0, ghostCalls = 0;
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    r.register({
+      name: "pi",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/pi${++piCalls}` }) }],
+    });
+    r.register({
+      name: "ghost",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/ghost${++ghostCalls}` }) }],
+    });
+    const fastify = buildServer(r);
+
+    r.resolve("pi"); r.resolve("ghost");
+    await fastify.inject({
+      method: "POST", url: "/api/tools/rescan", payload: { name: "pi" },
+    });
+    expect(r.resolve("pi").path).toBe("/pi2");
+    expect(r.resolve("ghost").path).toBe("/ghost1"); // unchanged
+    await fastify.close();
+  });
+
+  it("404s when rescanning an unknown name", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "POST", url: "/api/tools/rescan", payload: { name: "bogus" },
+    });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("PUT /api/tools/:name (set override)", () => {
+  it("sets the override and returns refreshed Resolution", async () => {
+    const r = buildRegistry();
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/pi",
+      payload: { path: "/custom/pi" },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.source).toBe("override");
+    expect(body.data.path).toBe("/custom/pi");
+    await fastify.close();
+  });
+
+  it("400s on missing path body", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/pi", payload: {},
+    });
+    expect(res.statusCode).toBe(400);
+    await fastify.close();
+  });
+
+  it("404s for unknown tool name", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/bogus", payload: { path: "/x" },
+    });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("DELETE /api/tools/:name (clear override)", () => {
+  it("clears the override and returns refreshed Resolution", async () => {
+    const r = buildRegistry();
+    r.setOverride("pi", "/custom/pi");
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({ method: "DELETE", url: "/api/tools/pi" });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.path).toBe("/usr/bin/pi");
+    await fastify.close();
+  });
+
+  it("404s for unknown tool", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({ method: "DELETE", url: "/api/tools/bogus" });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("POST /api/tools/diagnostics", () => {
+  it("returns text/plain with per-tool headers and trail lines", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({ method: "POST", url: "/api/tools/diagnostics" });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toMatch(/text\/plain/);
+    const body = res.body;
+    // Header line per tool
+    expect(body).toMatch(/^\[ok\] +pi /m);
+    expect(body).toMatch(/^\[miss\] +ghost /m);
+    // Each attempted strategy appears with a leading dash
+    expect(body).toMatch(/- where: ok/);
+    expect(body).toMatch(/- where: not found on PATH/);
+    await fastify.close();
+  });
+
+  it("formatDiagnostics is stable for unit testing", () => {
+    const text = formatDiagnostics([
+      {
+        name: "pi", ok: true, path: "/usr/bin/pi", source: "system",
+        tried: [{ strategy: "where", result: "ok" }],
+        resolvedAt: 0,
+      },
+    ]);
+    expect(text).toMatch(/\[ok\] +pi \(system\) → \/usr\/bin\/pi/);
+    expect(text).toMatch(/- where: ok/);
+  });
+});
+
+describe("integration with default tool definitions", () => {
+  it("the standard registry exposes pi, openspec, git, npm etc. via GET /api/tools", async () => {
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    registerDefaultTools(r, {
+      exists: () => false,
+      which: () => null,
+      npmRootGlobal: () => "",
+    });
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({ method: "GET", url: "/api/tools" });
+    expect(res.statusCode).toBe(200);
+    const names = res.json().data.tools.map((t: any) => t.name).sort();
+    expect(names).toEqual(expect.arrayContaining(["git", "node", "npm", "openspec", "pi", "pi-coding-agent", "zrok"]));
+    expect(names).not.toContain("tsx");
+    expect(names).not.toContain("pi-dashboard");
+    await fastify.close();
+  });
+});
+
+// Clean up tmp overrides files
+afterAll();
+function afterAll() {
+  try {
+    for (const f of fs.readdirSync(os.tmpdir())) {
+      if (f.startsWith("tool-routes-test-")) {
+        try { fs.unlinkSync(path.join(os.tmpdir(), f)); } catch {}
+      }
+    }
+  } catch {}
+}

package/packages/server/src/__tests__/trusted-networks-config.test.ts

@@ -52,6 +52,25 @@ describe("trustedNetworks config", () => {
     expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
   });
 
+  // Companion to the test above. The archived trusted-networks spec scenario
+  // "trustedNetworks merged with auth.bypassHosts" as written did NOT include
+  // a `providers` field; the test above silently adds one to make it pass.
+  // This second test exercises the literal spec scenario — it would have
+  // failed pre-fix (parseAuthConfig nuked the whole auth block when
+  // providers was absent) and demonstrates the scenario as written now holds.
+  // See openspec/changes/fix-trusted-networks-no-oauth.
+  it("should merge trustedNetworks with auth.bypassHosts (no providers configured)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: {
+        bypassHosts: ["10.0.0.0/8"],
+      },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
   it("should deduplicate entries", () => {
     fs.writeFileSync(configFile, JSON.stringify({
       trustedNetworks: ["192.168.1.0/24"],

package/packages/server/src/__tests__/trusted-networks-no-oauth-roundtrip.test.ts

@@ -0,0 +1,126 @@
+/**
+ * End-to-end regression test for fix-trusted-networks-no-oauth.
+ *
+ * Round-trips a bypassHosts-only auth config through the full
+ * write → disk → loadConfig → resolvedTrustedNetworks path.
+ *
+ * This is the test that would have caught the bug activated by
+ * eb24780 (consolidate-trusted-networks). The archived tasks.md
+ * section 5.4 claimed this case was "covered by unit test" — but
+ * the cited unit test only checked the React onChange handler's
+ * return value in memory, never writing to disk or reloading.
+ *
+ * This test asserts the end state: after the UI's PUT /api/config
+ * equivalent fires, a subsequent loadConfig() sees the entry in
+ * resolvedTrustedNetworks.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { writeConfigPartial } from "../config-api.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+describe("fix-trusted-networks-no-oauth: round-trip", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-no-oauth-rt-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("UI add → save → reload → resolvedTrustedNetworks contains entry", () => {
+    // Simulate fresh config (no auth section).
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+
+    // Simulate the UI PUT /api/config from Settings → Security → Add
+    // with no OAuth configured (the case that broke users).
+    const writeResult = writeConfigPartial({
+      auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    // Disk assertion — the bypassHosts must actually land on disk.
+    const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+    expect(written.auth).toBeDefined();
+    expect(written.auth.bypassHosts).toEqual(["192.168.1.0/24"]);
+
+    // Reload assertion — loadConfig must surface the entry in
+    // resolvedTrustedNetworks, which is what the network guard
+    // and the WS upgrade handler consult.
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.auth!.bypassHosts).toEqual(["192.168.1.0/24"]);
+    expect(loaded.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+  });
+
+  it("UI add with existing OAuth → round-trip preserves both", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        port: 8000,
+        auth: {
+          secret: "s",
+          providers: { github: { clientId: "abc", clientSecret: "xyz" } },
+        },
+      }),
+    );
+
+    const writeResult = writeConfigPartial({
+      auth: { bypassHosts: ["10.0.0.0/8"] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.auth!.providers.github).toBeDefined();
+    expect(loaded.auth!.bypassHosts).toEqual(["10.0.0.0/8"]);
+    expect(loaded.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
+  it("UI clear → save → reload → entry gone from resolvedTrustedNetworks", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+      }),
+    );
+
+    const writeResult = writeConfigPartial({
+      auth: { bypassHosts: [] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    const loaded = loadConfig();
+    // Loader returns auth === undefined when nothing auth-relevant remains.
+    // Either way, the trusted entry must not survive.
+    expect(loaded.resolvedTrustedNetworks).not.toContain("192.168.1.0/24");
+    expect(loaded.resolvedTrustedNetworks).toEqual([]);
+  });
+
+  it("hand-edited config (no UI write) with bypassHosts only → loads correctly", () => {
+    // This path simulates a user who edited config.json by hand
+    // rather than through the UI. The fix must make loadConfig
+    // honor this shape.
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        auth: { providers: {}, bypassHosts: ["192.168.0.0/24"] },
+      }),
+    );
+
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.resolvedTrustedNetworks).toContain("192.168.0.0/24");
+  });
+});

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

@@ -0,0 +1,90 @@
+/**
+ * Tests that `cleanupStaleZrok` routes liveness + termination through the
+ * shared platform module rather than raw `process.kill`.
+ *
+ * See change: route-kill-paths-through-platform.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const killProcessSpy = vi.fn(async (_pid: number, _opts?: any) => ({ ok: true, forced: false }));
+const isProcessAliveSpy = vi.fn((_pid: number) => true);
+
+vi.mock("@blackbelt-technology/pi-dashboard-shared/platform/process.js", async () => {
+  const actual = await vi.importActual<typeof import("@blackbelt-technology/pi-dashboard-shared/platform/process.js")>(
+    "@blackbelt-technology/pi-dashboard-shared/platform/process.js",
+  );
+  return {
+    ...actual,
+    killProcess: (pid: number, opts?: any) => killProcessSpy(pid, opts),
+    isProcessAlive: (pid: number) => isProcessAliveSpy(pid),
+  };
+});
+
+const { cleanupStaleZrok, writeZrokPid, readZrokPid } = await import("../tunnel.js");
+
+function pidFile(): string {
+  return path.join(os.homedir(), ".pi", "dashboard", "zrok.pid");
+}
+
+describe("cleanupStaleZrok uses platform helpers", () => {
+  const original = readZrokPid();
+
+  beforeEach(() => {
+    killProcessSpy.mockClear();
+    killProcessSpy.mockImplementation(async () => ({ ok: true, forced: false }));
+    isProcessAliveSpy.mockClear();
+    isProcessAliveSpy.mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    // Restore prior PID file content if any.
+    try {
+      if (original !== null) writeZrokPid(original);
+      else fs.unlinkSync(pidFile());
+    } catch { /* ignore */ }
+  });
+
+  it("calls platform killProcess when a live stale PID exists", async () => {
+    writeZrokPid(654321);
+    isProcessAliveSpy.mockReturnValue(true);
+
+    await cleanupStaleZrok();
+
+    expect(isProcessAliveSpy).toHaveBeenCalledWith(654321);
+    expect(killProcessSpy).toHaveBeenCalledOnce();
+    expect(killProcessSpy).toHaveBeenCalledWith(654321, expect.any(Object));
+    // PID file removed after cleanup
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("skips killProcess when PID is already dead but still removes PID file", async () => {
+    writeZrokPid(654322);
+    isProcessAliveSpy.mockReturnValue(false);
+
+    await cleanupStaleZrok();
+
+    expect(killProcessSpy).not.toHaveBeenCalled();
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("no-ops when no PID file exists", async () => {
+    try { fs.unlinkSync(pidFile()); } catch { /* ignore */ }
+    await cleanupStaleZrok();
+    expect(killProcessSpy).not.toHaveBeenCalled();
+    expect(isProcessAliveSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not invoke process.kill directly", async () => {
+    writeZrokPid(654323);
+    isProcessAliveSpy.mockReturnValue(true);
+    const processKillSpy = vi.spyOn(process, "kill");
+
+    await cleanupStaleZrok();
+
+    expect(processKillSpy).not.toHaveBeenCalled();
+    processKillSpy.mockRestore();
+  });
+});

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

@@ -160,30 +160,32 @@ describe("PID file helpers", () => {
 });
 
 describe("cleanupStaleZrok", () => {
-  it("should do nothing when no PID file exists", () => {
+  it("should do nothing when no PID file exists", async () => {
     vi.mocked(fs.readFileSync).mockImplementation(() => {
       throw new Error("ENOENT");
     });
     const killSpy = vi.spyOn(process, "kill");
 
-    cleanupStaleZrok();
+    await cleanupStaleZrok();
 
     expect(killSpy).not.toHaveBeenCalled();
   });
 
-  it("should kill running stale process and remove PID file", () => {
+  it("should kill running stale process and remove PID file", async () => {
     vi.mocked(fs.readFileSync).mockReturnValue("99999\n");
     const killSpy = vi.spyOn(process, "kill").mockReturnValue(true);
     vi.mocked(fs.unlinkSync).mockReturnValue(undefined);
 
-    cleanupStaleZrok();
+    // cleanupStaleZrok became async when it moved to platform/process's
+    // killProcess (SIGTERM+grace+SIGKILL orchestration).
+    await cleanupStaleZrok();
 
     expect(killSpy).toHaveBeenCalledWith(99999, 0);
     expect(killSpy).toHaveBeenCalledWith(99999, "SIGTERM");
     expect(fs.unlinkSync).toHaveBeenCalled();
   });
 
-  it("should just remove PID file if process is not running", () => {
+  it("should just remove PID file if process is not running", async () => {
     vi.mocked(fs.readFileSync).mockReturnValue("99999\n");
     const killSpy = vi.spyOn(process, "kill").mockImplementation((_pid: number, signal?: string | number) => {
       if (signal === 0) throw new Error("ESRCH");
@@ -191,7 +193,7 @@ describe("cleanupStaleZrok", () => {
     });
     vi.mocked(fs.unlinkSync).mockReturnValue(undefined);
 
-    cleanupStaleZrok();
+    await cleanupStaleZrok();
 
     expect(killSpy).toHaveBeenCalledTimes(1);
     expect(fs.unlinkSync).toHaveBeenCalled();
@@ -254,8 +256,12 @@ describe("scavengeOrphanZrokProcesses", () => {
     const killed = scavengeOrphanZrokProcesses(8000);
 
     expect(killed).toEqual([12345]);
-    expect(killSpy).toHaveBeenCalledWith(12345, "SIGTERM");
+    // Negative PID targets the whole process group on Unix (killPidWithGroup's
+    // contract); positive PID on Windows. Match whichever platform we're on.
+    const expectedPid = process.platform === "win32" ? 12345 : -12345;
+    expect(killSpy).toHaveBeenCalledWith(expectedPid, "SIGTERM");
     expect(killSpy).not.toHaveBeenCalledWith(12346, expect.anything());
+    expect(killSpy).not.toHaveBeenCalledWith(-12346, expect.anything());
   });
 
   it("should return empty array on ps failure", () => {

package/packages/server/src/__tests__/wsl-tmux-probe-cache.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { _resetWslTmuxCacheForTests } from "../process-manager.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Structural test: the WSL-tmux probe MUST have a module-scoped cache so it's
+ * invoked at most once per server lifetime. Without this cache, users on
+ * Windows without `wt.exe` pay the full WSL VM cold-start cost (1.5–30 s) on
+ * every + Session click.
+ *
+ * We assert the cache exists by source inspection (tight, deterministic) and
+ * that a reset helper is exported for tests.
+ */
+describe("WSL-tmux probe cache invariant", () => {
+  const src = readFileSync(
+    path.resolve(__dirname, "../process-manager.ts"),
+    "utf-8",
+  );
+
+  it("process-manager.ts declares _wslTmuxAvailabilityCache", () => {
+    expect(src).toMatch(/let\s+_wslTmuxAvailabilityCache\s*:\s*boolean\s*\|\s*null\s*=\s*null/);
+  });
+
+  it("isWslTmuxAvailable() returns the cached value when non-null", () => {
+    expect(src).toMatch(/if\s*\(\s*_wslTmuxAvailabilityCache\s*!==\s*null\s*\)\s*return\s+_wslTmuxAvailabilityCache/);
+  });
+
+  it("fallback-log fires at most once per server run", () => {
+    expect(src).toMatch(/_wslFallbackLogged\s*=\s*true/);
+    expect(src).toMatch(/if\s*\(\s*!_wslTmuxAvailabilityCache\s*&&\s*!_wslFallbackLogged\s*\)/);
+  });
+
+  it("exports a cache-reset helper for tests", () => {
+    expect(typeof _resetWslTmuxCacheForTests).toBe("function");
+    // reset is idempotent — safe to call repeatedly
+    _resetWslTmuxCacheForTests();
+    _resetWslTmuxCacheForTests();
+  });
+});