switchroom 0.18.12 → 0.18.14

package/telegram-plugin/tests/throttle-tier.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Unit tests for telegram-plugin/throttle-tier.ts — the 429 throttle tier.
+ *
+ * Pins the operator-approved decision matrix ("retry in place under 5 min,
+ * else mark + failover, honest reset messaging"):
+ *   - transient wording + reset ≤ threshold  → throttle (stay put)
+ *   - transient wording + reset > threshold  → failover (escalate)
+ *   - transient wording + unparseable reset  → throttle, now+60s default
+ *   - non-transient (wall) wording           → none (caller's existing path)
+ * plus the per-account notice cooldown and the notice text itself.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  decideThrottleTier,
+  evaluateThrottleNotice,
+  isAccountScopedThrottle,
+  renderThrottleEscalationNotice,
+  renderThrottleNotice,
+  throttleRetryInPlaceMaxMs,
+  THROTTLE_DEFAULT_WAIT_MS,
+  THROTTLE_NOTICE_COOLDOWN_MS,
+  THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT,
+  type ThrottleNoticeState,
+} from '../throttle-tier.js'
+import { formatModelUnavailableCard, parseResetTime } from '../model-unavailable.js'
+
+const NOW = Date.UTC(2026, 6, 12, 8, 0, 0) // 2026-07-12T08:00:00Z
+const THRESHOLD = THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT // 5 min
+
+// The canonical transient-negation wording (Anthropic burst-429 shape).
+const TRANSIENT = (suffix: string): string =>
+  `This request would exceed your account's rate limit (not your usage limit). ${suffix}`
+
+describe('decideThrottleTier — decision matrix', () => {
+  it('transient wording + reset within threshold → throttle at the parsed reset', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('Please retry after 90 seconds.'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + 90_000,
+      resetParsed: true,
+    })
+  })
+
+  it('transient wording + "resets in 3m" → throttle (≤ 5 min)', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('resets in 3m'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + 3 * 60_000,
+      resetParsed: true,
+    })
+  })
+
+  it('transient wording + reset beyond threshold → failover with the parsed reset', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('resets in 2h 15m'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'failover',
+      resetAtMs: NOW + (2 * 60 + 15) * 60_000,
+    })
+  })
+
+  it('transient wording + NO parseable reset → throttle for the 60s default', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('try again later.'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+    })
+  })
+
+  it('transient wording + reset in the PAST → throttle for the 60s default', () => {
+    const past = new Date(NOW - 60_000).toISOString()
+    const d = decideThrottleTier({
+      detail: TRANSIENT(`resets ${past}`),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+    })
+  })
+
+  it('genuine wall wording (no transient negation) → none (existing quota path owns it)', () => {
+    const d = decideThrottleTier({
+      detail: "You've hit your limit · resets 8:50am (Australia/Melbourne)",
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({ action: 'none' })
+  })
+
+  it('SERVER-side transient wording (529 shape) → none — never account-throttled', () => {
+    // This carries the transient NEGATION ("not your usage limit") but does
+    // NOT affirm the account's own rate limit — it is a server-wide
+    // condition; an account-scoped throttle + restart nudge would be the
+    // wrong action. It stays on the existing calm rate-limited path.
+    const d = decideThrottleTier({
+      detail: 'Server is temporarily limiting requests (not your usage limit). retry after 60 seconds',
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({ action: 'none' })
+  })
+
+  it('honours a custom threshold (boundary: exactly at threshold stays in place)', () => {
+    const atThreshold = decideThrottleTier({
+      detail: TRANSIENT('retry after 300 seconds'),
+      now: NOW,
+      thresholdMs: 5 * 60_000,
+    })
+    expect(atThreshold.action).toBe('throttle')
+    const beyond = decideThrottleTier({
+      detail: TRANSIENT('retry after 301 seconds'),
+      now: NOW,
+      thresholdMs: 5 * 60_000,
+    })
+    expect(beyond.action).toBe('failover')
+  })
+})
+
+describe('isAccountScopedThrottle — the tier gate', () => {
+  it("matches account-affirming wording (both apostrophe variants + 'not your account')", () => {
+    expect(isAccountScopedThrottle("would exceed your account's rate limit")).toBe(true)
+    expect(isAccountScopedThrottle('would exceed your account’s rate limit')).toBe(true)
+    expect(isAccountScopedThrottle("this is not your account's limit")).toBe(true)
+  })
+
+  it('rejects server-side transient / 529 wordings and walls', () => {
+    expect(isAccountScopedThrottle('Server is temporarily limiting requests (not your usage limit)')).toBe(false)
+    expect(isAccountScopedThrottle('temporarily rate limited, overloaded_error 529')).toBe(false)
+    expect(isAccountScopedThrottle("You've hit your limit · resets 8:50am")).toBe(false)
+    expect(isAccountScopedThrottle('')).toBe(false)
+  })
+})
+
+describe('throttleRetryInPlaceMaxMs — env resolution', () => {
+  it('defaults to 5 minutes', () => {
+    expect(throttleRetryInPlaceMaxMs({})).toBe(5 * 60_000)
+  })
+
+  it('reads SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS', () => {
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: '120000' }),
+    ).toBe(120_000)
+  })
+
+  it('falls back to the default on junk / non-positive values', () => {
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: 'soon' }),
+    ).toBe(THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT)
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: '-5' }),
+    ).toBe(THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT)
+  })
+})
+
+describe('evaluateThrottleNotice — per-account cooldown', () => {
+  it('sends the first notice and suppresses a repeat inside the window', () => {
+    let state: ThrottleNoticeState = { lastSentAtMsByAccount: {} }
+    const first = evaluateThrottleNotice(state, 'acct-a', NOW)
+    expect(first.send).toBe(true)
+    state = first.next
+    const repeat = evaluateThrottleNotice(state, 'acct-a', NOW + 60_000)
+    expect(repeat.send).toBe(false)
+  })
+
+  it('a DIFFERENT account is not suppressed by the first account\'s window', () => {
+    const first = evaluateThrottleNotice({ lastSentAtMsByAccount: {} }, 'acct-a', NOW)
+    const other = evaluateThrottleNotice(first.next, 'acct-b', NOW + 1)
+    expect(other.send).toBe(true)
+  })
+
+  it('sends again once the cooldown window has elapsed', () => {
+    const first = evaluateThrottleNotice({ lastSentAtMsByAccount: {} }, 'acct-a', NOW)
+    const later = evaluateThrottleNotice(
+      first.next,
+      'acct-a',
+      NOW + THROTTLE_NOTICE_COOLDOWN_MS,
+    )
+    expect(later.send).toBe(true)
+  })
+})
+
+describe('renderThrottleNotice — honest reset messaging', () => {
+  it('names the account, the agent, the reset, and that it is NOT a quota wall', () => {
+    const text = renderThrottleNotice({
+      account: 'alice',
+      agent: 'carrie',
+      throttledUntilMs: NOW + 3 * 60_000,
+      resetParsed: true,
+      now: new Date(NOW),
+    })
+    expect(text).toContain('alice')
+    expect(text).toContain('carrie')
+    expect(text).toContain('resets in 3m')
+    expect(text).toContain('not a quota wall')
+    expect(text).toContain('Staying on')
+    expect(text).toContain('no failover')
+  })
+
+  it('degrades honestly when the account is unknown (broker unreachable)', () => {
+    const text = renderThrottleNotice({
+      account: null,
+      agent: 'carrie',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+      now: new Date(NOW),
+    })
+    expect(text).toContain('the active account')
+    expect(text).toContain('retrying in ~60s')
+  })
+})
+
+describe('renderThrottleEscalationNotice — corroborated-wall announcement', () => {
+  it('names the account, the trigger agent, and the roll target', () => {
+    const text = renderThrottleEscalationNotice({
+      account: 'alice',
+      agent: 'carrie',
+      rolledTo: 'bob',
+    })
+    expect(text).toContain('alice')
+    expect(text).toContain('carrie')
+    expect(text).toContain('bob')
+    expect(text).toContain('actually a wall')
+  })
+
+  it('renders the all-blocked variant when no fallback had quota', () => {
+    const text = renderThrottleEscalationNotice({
+      account: 'alice',
+      agent: 'carrie',
+      rolledTo: null,
+    })
+    expect(text).toContain('all blocked')
+    expect(text).toContain('/auth add')
+  })
+})
+
+describe('rate_limited escalation card wording (model-unavailable integration)', () => {
+  it('formatModelUnavailableCard names the rate limit, not quota exhaustion', () => {
+    const card = formatModelUnavailableCard(
+      { kind: 'rate_limited', resetAt: new Date(NOW + 30 * 60_000), raw: 'x' },
+      'carrie',
+      { now: new Date(NOW), autoFallbackInFlight: true },
+    )
+    expect(card).toContain('account rate-limited')
+    expect(card).toContain('resets in 30m')
+    expect(card).not.toContain('quota exhausted')
+  })
+})
+
+describe('parseResetTime (exported for the throttle tier)', () => {
+  it('parses "retry after N seconds" relative to the injected clock', () => {
+    const d = parseResetTime('retry after 45 seconds', new Date(NOW))
+    expect(d?.getTime()).toBe(NOW + 45_000)
+  })
+
+  it('returns undefined for prose with no reset hint', () => {
+    expect(parseResetTime('temporarily limiting requests', new Date(NOW))).toBeUndefined()
+  })
+})

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);
+  });
+});