switchroom 0.18.12 → 0.18.13

package/telegram-plugin/tests/subagent-watcher-fd-leak.test.ts

@@ -0,0 +1,275 @@
+/**
+ * FD-leak regression tests for the subagent-watcher (review findings H1 + H2).
+ *
+ * H1 — directory FSWatchers were only ever closed in the global stop(). When a
+ *      Claude session's `subagents/` dir was reaped, the rescan loop skipped
+ *      the vanished path without closing its watcher, so every session leaked
+ *      one inotify FD for the gateway's lifetime.
+ *
+ * H2 — every boot-scanned file opened a per-file FSWatcher unconditionally,
+ *      including stale historical `running` entries that `checkStalls` skips
+ *      and that therefore never reach terminal cleanup — leaking their FD until
+ *      the file happened to vanish.
+ *
+ * Each test FAILS on pre-fix code (an unclosed / never-opened-guarded watcher)
+ * and PASSES with the runtime-close / open-gating fix.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type * as fs from 'fs'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+interface FakeWatcher {
+  path: string
+  close: ReturnType<typeof vi.fn>
+  closed: boolean
+}
+
+/**
+ * Minimal watcher harness with a MUTABLE fake filesystem (so a test can make a
+ * directory or file vanish mid-run) and per-watcher path tracking (so we can
+ * assert exactly which watchers were opened / closed).
+ */
+function makeHarness(opts: {
+  agentDir?: string
+  dirs: Record<string, string[]>
+  fileSizes?: Record<string, number>
+  rescanMs?: number
+}) {
+  const agentDir = opts.agentDir ?? '/home/user/.switchroom/agents/myagent'
+  const rescanMs = opts.rescanMs ?? 500
+  const dirs = new Map<string, string[]>(Object.entries(opts.dirs))
+  const fileSizes = new Map<string, number>(Object.entries(opts.fileSizes ?? {}))
+  const logs: string[] = []
+  const watchers: FakeWatcher[] = []
+  let currentTime = 1_000_000
+
+  const existsSync = ((p: fs.PathLike) => {
+    const ps = String(p)
+    return dirs.has(ps) || fileSizes.has(ps)
+  }) as typeof fs.existsSync
+
+  const mockFs = {
+    existsSync,
+    readdirSync: ((p: fs.PathLike) => dirs.get(String(p)) ?? []) as unknown as typeof fs.readdirSync,
+    // No mtimeMs → boot-promotion freshness gate treats a running file as
+    // stale (dead prior-session worker), so it stays historical + unpromoted.
+    statSync: ((p: fs.PathLike) => ({ size: fileSizes.get(String(p)) ?? 0 }) as fs.Stats) as typeof fs.statSync,
+    openSync: (() => 42) as unknown as typeof fs.openSync,
+    closeSync: (() => undefined) as typeof fs.closeSync,
+    readSync: (() => 0) as unknown as typeof fs.readSync,
+    watch: ((p: fs.PathLike) => {
+      const w: FakeWatcher = {
+        path: String(p),
+        closed: false,
+        close: vi.fn(() => { w.closed = true }),
+      }
+      watchers.push(w)
+      return w as unknown as fs.FSWatcher
+    }) as unknown as typeof fs.watch,
+  }
+
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  const timeouts: Array<{ fn: () => void; ref: number; fireAt: number }> = []
+  let nextRef = 1
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    onFinish: () => {},
+    stallThresholdMs: 60_000,
+    silentSynthesisStallThresholdMs: 60_000,
+    rescanMs,
+    now: () => currentTime,
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = intervals.findIndex((i) => i.ref === ref)
+      if (idx !== -1) intervals.splice(idx, 1)
+    },
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timeouts.push({ fn, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = timeouts.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timeouts.splice(idx, 1)
+    },
+    fs: mockFs,
+    log: (msg: string) => { logs.push(msg) },
+  })
+
+  const poll = (): void => {
+    // intervals[0] is the poll loop (registered first — see startSubagentWatcher).
+    intervals[0]?.fn()
+  }
+
+  return {
+    watcher,
+    watchers,
+    logs,
+    dirs,
+    fileSizes,
+    poll,
+    fileWatchers: () => watchers.filter((w) => w.path.endsWith('.jsonl')),
+    dirWatchersFor: (p: string) => watchers.filter((w) => w.path === p),
+  }
+}
+
+const PROJECTS = '/home/user/.switchroom/agents/myagent/.claude/projects'
+
+describe('subagent-watcher FD-leak (H1): dir watchers close when their session dir vanishes', () => {
+  it('closes and forgets the subagents-dir FSWatcher after the session dir is reaped', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // empty subagents dir — still gets a dir watcher
+      },
+    })
+
+    // Boot scan already ran in the constructor; poll once to be certain the
+    // dir watcher for the subagents dir has been opened.
+    h.poll()
+    const dw = h.dirWatchersFor(subagentsDir)
+    expect(dw).toHaveLength(1)
+    expect(dw[0].closed).toBe(false)
+
+    // Claude Code reaps the whole session directory (session rotation).
+    h.dirs.delete(sessionDir)
+    h.dirs.delete(subagentsDir)
+    h.dirs.set(projectDir, []) // session-A gone from the project listing
+
+    // Next rescan tick must release the now-dangling dir watcher.
+    h.poll()
+
+    expect(dw[0].close).toHaveBeenCalledTimes(1)
+    expect(dw[0].closed).toBe(true)
+
+    h.watcher.stop()
+  })
+})
+
+describe('subagent-watcher FD-leak (H2): no per-file watcher for stale historical running entries', () => {
+  it('does not open an FSWatcher for a boot-discovered stale running JSONL', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+    const staleFile = `${subagentsDir}/agent-deadbeef.jsonl`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: ['agent-deadbeef.jsonl'],
+      },
+      // size 0 + no mtimeMs → registers as a stale historical `running` entry
+      // that will never be promoted and never reach terminal cleanup.
+      fileSizes: { [staleFile]: 0 },
+    })
+
+    h.poll()
+
+    // A dir watcher for the subagents dir is fine. What must NOT happen is a
+    // per-file (.jsonl) watcher for a stale historical running entry that
+    // would leak forever.
+    const fileWatchersForStale = h.fileWatchers().filter((w) => w.path === staleFile)
+    expect(fileWatchersForStale).toHaveLength(0)
+
+    h.watcher.stop()
+  })
+
+  // Positive direction of the H2 gate: the open-guard is `!entry.historical ||
+  // entry.bootPromotionPending != null`, so the negative test above (no watcher
+  // for a stale boot entry) must be balanced by proof the guard does NOT
+  // over-prune a genuinely LIVE worker. A file that first appears AFTER the boot
+  // scan is non-historical (`bootScanInProgress` is already false), so it is a
+  // live worker the user is awaiting and MUST get its own per-file FSWatcher —
+  // otherwise its tool-call / turn_end transitions would be invisible until the
+  // 1s defensive poll happened to catch them. Reviewer verified this by code-
+  // reading only; this test locks it in.
+  it('opens a per-file FSWatcher for a live (post-boot, non-historical) worker JSONL', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+    const liveFile = `${subagentsDir}/agent-live01.jsonl`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // empty at boot → nothing marked historical
+      },
+    })
+
+    // Boot scan already ran (constructor) over the empty dir; poll once so the
+    // dir watcher for the subagents dir is definitely established.
+    h.poll()
+    expect(h.fileWatchers()).toHaveLength(0) // nothing to watch yet
+
+    // A brand-new worker dispatches AFTER boot: its JSONL appears now. Because
+    // bootScanInProgress is already false, scanSubagentsDir does NOT mark it
+    // historical → it registers as a live running entry.
+    h.dirs.set(subagentsDir, ['agent-live01.jsonl'])
+    h.fileSizes.set(liveFile, 24)
+
+    h.poll()
+
+    const fileWatchersForLive = h.fileWatchers().filter((w) => w.path === liveFile)
+    expect(fileWatchersForLive).toHaveLength(1)
+    expect(fileWatchersForLive[0].closed).toBe(false)
+
+    h.watcher.stop()
+    // stop() must close the live watcher it opened (no leak on shutdown).
+    expect(fileWatchersForLive[0].closed).toBe(true)
+  })
+})
+
+describe('subagent-watcher FD-leak (H1): a still-present session dir keeps its watcher across rescans', () => {
+  it('does NOT prune the dir watcher for a directory that is still present', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // present + empty — gets a dir watcher, stays present
+      },
+    })
+
+    h.poll()
+    const dw = h.dirWatchersFor(subagentsDir)
+    expect(dw).toHaveLength(1)
+    expect(dw[0].closed).toBe(false)
+
+    // The session dir never vanishes. Several rescan ticks pass. The complement
+    // of the H1 close-on-vanish test: pruneVanishedDirWatchers must leave a
+    // still-existing dir's watcher untouched, and the `if (!dirWatchers.has(...))`
+    // guard must NOT open a duplicate watcher for the same dir on each rescan.
+    h.poll()
+    h.poll()
+    h.poll()
+
+    expect(dw[0].close).not.toHaveBeenCalled()
+    expect(dw[0].closed).toBe(false)
+    // Exactly one dir watcher for this path across all the rescans — no churn.
+    expect(h.dirWatchersFor(subagentsDir)).toHaveLength(1)
+
+    h.watcher.stop()
+  })
+})

package/telegram-plugin/tests/worktree-watch-cwds.test.ts

@@ -9,12 +9,26 @@
  * Run with:
  *   bun test telegram-plugin/tests/worktree-watch-cwds.test.ts
  */
-import { describe, it, expect, beforeEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 import {
   ownedWorktreeCwds,
+  refreshOwnedWorktreeHeartbeats,
+  makeWorktreeWatchProvider,
   __resetIdentityEscalationForTests,
   type WorktreeOwnershipRecord,
+  type WorktreeHeartbeatRecord,
 } from "../worktree-watch-cwds.js";
+import {
+  writeRecord,
+  readRecord,
+  listRecords as registryListRecords,
+  touchHeartbeat as registryTouchHeartbeat,
+} from "../../src/worktree/registry.js";
+import type { WorktreeRecord } from "../../src/worktree/types.js";
 
 const idPath = (p: string) => p; // identity realpath for deterministic tests
 
@@ -196,3 +210,203 @@ describe("ownedWorktreeCwds", () => {
     expect(provider()).toEqual(["/wt/b"]);
   });
 });
+
+describe("refreshOwnedWorktreeHeartbeats", () => {
+  const records: WorktreeHeartbeatRecord[] = [
+    { id: "mine-1", ownerAgent: "klanker" },
+    { id: "mine-2", ownerAgent: "klanker" },
+    { id: "theirs", ownerAgent: "reggie" },
+    { id: "ownerless" }, // ownerAgent undefined
+  ];
+
+  it("touches ONLY this agent's records, never ownerless or foreign ones", () => {
+    const touched: string[] = [];
+    const n = refreshOwnedWorktreeHeartbeats({
+      self: "klanker",
+      listRecords: () => records,
+      touchHeartbeat: (id) => touched.push(id),
+      minRefreshIntervalMs: 0, // always touch
+    });
+    expect(touched.sort()).toEqual(["mine-1", "mine-2"]);
+    expect(touched).not.toContain("theirs");
+    expect(touched).not.toContain("ownerless");
+    expect(n).toBe(2);
+  });
+
+  it("fail-closed: unresolved identity touches NOTHING (no #1116 leak)", () => {
+    const touched: string[] = [];
+    const n = refreshOwnedWorktreeHeartbeats({
+      self: undefined,
+      listRecords: () => records,
+      touchHeartbeat: (id) => touched.push(id),
+      minRefreshIntervalMs: 0,
+    });
+    expect(touched).toEqual([]);
+    expect(n).toBe(0);
+  });
+
+  it("resolves identity from agentDir when env is unset (durable fallback)", () => {
+    const touched: string[] = [];
+    refreshOwnedWorktreeHeartbeats({
+      self: undefined,
+      agentDir: "/home/x/.switchroom/agents/klanker",
+      listRecords: () => records,
+      touchHeartbeat: (id) => touched.push(id),
+      minRefreshIntervalMs: 0,
+    });
+    expect(touched.sort()).toEqual(["mine-1", "mine-2"]);
+  });
+
+  it("throttles: skips a record whose heartbeat is younger than the interval", () => {
+    const now = 1_000_000;
+    const fresh = new Date(now - 30_000).toISOString(); // 30s ago
+    const aged = new Date(now - 5 * 60_000).toISOString(); // 5min ago
+    const touched: string[] = [];
+    refreshOwnedWorktreeHeartbeats({
+      self: "klanker",
+      listRecords: () => [
+        { id: "fresh", ownerAgent: "klanker", heartbeatAt: fresh },
+        { id: "aged", ownerAgent: "klanker", heartbeatAt: aged },
+      ],
+      touchHeartbeat: (id) => touched.push(id),
+      minRefreshIntervalMs: 2 * 60_000, // 2 min
+      now: () => now,
+    });
+    // Only the aged one crosses the throttle window.
+    expect(touched).toEqual(["aged"]);
+  });
+
+  it("a registry read failure is swallowed (never throws on the hot loop)", () => {
+    expect(() =>
+      refreshOwnedWorktreeHeartbeats({
+        self: "klanker",
+        listRecords: () => {
+          throw new Error("registry gone");
+        },
+        touchHeartbeat: () => {},
+      }),
+    ).not.toThrow();
+  });
+
+  it("a per-record touch failure does not abort the remaining records", () => {
+    const touched: string[] = [];
+    const n = refreshOwnedWorktreeHeartbeats({
+      self: "klanker",
+      listRecords: () => records,
+      touchHeartbeat: (id) => {
+        if (id === "mine-1") throw new Error("write failed");
+        touched.push(id);
+      },
+      minRefreshIntervalMs: 0,
+    });
+    // mine-2 still touched despite mine-1 throwing.
+    expect(touched).toEqual(["mine-2"]);
+    expect(n).toBe(1);
+  });
+});
+
+// ─── M1: the gateway's extraWatchCwds provider ──────────────────────────────
+//
+// The gateway wires a single closure (`makeWorktreeWatchProvider`) as the
+// subagent-watcher's extraWatchCwdsProvider. The whole point of this PR is
+// that that closure ALSO advances heartbeats on every tick — deleting the
+// refresh call would leave the cwd behaviour (and every ownership test above)
+// green while silently reintroducing the zero-caller `touchHeartbeat` bug.
+// These tests are the deterministic guard: they assert the provider returns
+// owned cwds AND advances a real registry record's heartbeatAt on the same
+// call, and that the gateway actually installs it.
+describe("makeWorktreeWatchProvider (gateway wiring)", () => {
+  const idPathLocal = (p: string) => p; // deterministic realpath
+
+  it("both returns owned cwds AND advances the claim's heartbeat (in-memory)", () => {
+    const now = 10_000_000;
+    const before = new Date(now - 60 * 60_000).toISOString(); // 1h ago (stale)
+    const store: (WorktreeOwnershipRecord & WorktreeHeartbeatRecord)[] = [
+      { id: "mine", path: "/wt/mine", ownerAgent: "klanker", heartbeatAt: before },
+      { id: "theirs", path: "/wt/theirs", ownerAgent: "reggie", heartbeatAt: before },
+    ];
+    const touched: string[] = [];
+    const provider = makeWorktreeWatchProvider({
+      self: "klanker",
+      listRecords: () => store,
+      touchHeartbeat: (id) => touched.push(id),
+      realpath: idPathLocal,
+      minRefreshIntervalMs: 0,
+      now: () => now,
+    });
+
+    const cwds = provider();
+
+    // (1) returns exactly this agent's owned cwds
+    expect(cwds).toEqual(["/wt/mine"]);
+    // (2) AND advanced the heartbeat of the owned record only — never foreign
+    expect(touched).toEqual(["mine"]);
+  });
+
+  describe("against a real temp registry", () => {
+    let tmpDir: string;
+    const origEnv = process.env.SWITCHROOM_WORKTREE_DIR;
+
+    beforeEach(() => {
+      tmpDir = mkdtempSync(join(tmpdir(), "sw-provider-test-"));
+      process.env.SWITCHROOM_WORKTREE_DIR = tmpDir;
+    });
+
+    afterEach(() => {
+      rmSync(tmpDir, { recursive: true, force: true });
+      if (origEnv === undefined) delete process.env.SWITCHROOM_WORKTREE_DIR;
+      else process.env.SWITCHROOM_WORKTREE_DIR = origEnv;
+    });
+
+    function makeRecord(overrides: Partial<WorktreeRecord> = {}): WorktreeRecord {
+      const iso = new Date().toISOString();
+      return {
+        id: "prov001",
+        repo: "/fake/repo",
+        repoName: "fake",
+        branch: "task/prov001",
+        path: "/wt/prov001",
+        createdAt: iso,
+        heartbeatAt: iso,
+        ownerAgent: "klanker",
+        ...overrides,
+      };
+    }
+
+    it("provider drives the REAL registry: returns cwd AND advances heartbeatAt on disk", async () => {
+      const past = new Date(Date.now() - 5 * 60_000).toISOString(); // 5min ago
+      writeRecord(makeRecord({ heartbeatAt: past }));
+      const before = new Date(readRecord("prov001")!.heartbeatAt).getTime();
+
+      const provider = makeWorktreeWatchProvider({
+        self: "klanker",
+        listRecords: registryListRecords,
+        touchHeartbeat: registryTouchHeartbeat,
+        realpath: idPathLocal,
+        minRefreshIntervalMs: 0, // always touch
+      });
+
+      await new Promise((r) => setTimeout(r, 5)); // ensure a strictly newer ts
+      const cwds = provider();
+
+      // (1) returns the owned cwd from the real registry
+      expect(cwds).toEqual(["/wt/prov001"]);
+      // (2) AND the on-disk heartbeat actually advanced (the zero-caller guard)
+      const after = new Date(readRecord("prov001")!.heartbeatAt).getTime();
+      expect(after).toBeGreaterThan(before);
+    });
+  });
+
+  it("gateway.ts installs makeWorktreeWatchProvider as extraWatchCwdsProvider", () => {
+    // Grep-pin (anchor MUST resolve so it can never pass vacuously — repo test
+    // convention, PR #3126): proves the gateway actually wires the extracted
+    // provider, so a behaviour test on the provider is not testing dead code.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const gatewaySrc = readFileSync(
+      join(here, "..", "gateway", "gateway.ts"),
+      "utf8",
+    );
+    const anchor = "extraWatchCwdsProvider: makeWorktreeWatchProvider(";
+    expect(gatewaySrc.indexOf(anchor)).toBeGreaterThan(-1);
+  });
+});