switchroom 0.15.0 → 0.15.2

package/telegram-plugin/quota-watch.ts

@@ -73,6 +73,76 @@ export function emptyAccountState(): QuotaWatchAccountState {
   return { lastNotifiedHealth: null, lastNotifiedAt: 0 };
 }
 
+// ─── Tuning (env knobs) ───────────────────────────────────────────────────────
+
+/**
+ * Operational tuning for the watch loop, resolved once from env by the
+ * gateway. All three hardening behaviours are individually
+ * kill-switchable (incident 2026-06-09: a fleet bounce released
+ * days-stale recovery latches on all 11 agents at once → 26 duplicate
+ * 🟢 messages in 16 minutes):
+ *
+ *   SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS      0 disables the staleness gate
+ *                                            (default 60 min)
+ *   SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS  0 disables silent late-recovery
+ *                                            reconciliation (default 6 h)
+ *   SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP       "0" disables the broker claim
+ *                                            (every agent sends, pre-incident
+ *                                            behaviour)
+ *   SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL "1" restores sending from
+ *                                            cached data when the pre-send
+ *                                            validation probe fails
+ */
+export interface QuotaWatchTuning {
+  /** Cached snapshots older than this are treated as unknown (no opinion). 0 = off. */
+  maxStaleMs: number;
+  /** Recovery edges whose 🟡 warning is older than this reconcile silently. 0 = off. */
+  lateRecoveryMs: number;
+  /** Route sends through the broker's claim-notification dedup. */
+  fleetDedup: boolean;
+  /** Legacy: send from cached data when the validation probe fails. */
+  sendOnProbeFail: boolean;
+}
+
+export const DEFAULT_QUOTA_WATCH_MAX_STALE_MS = 60 * 60_000;
+export const DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS = 6 * 60 * 60_000;
+
+/** Broker claim window. Must exceed one full poll cycle (15 min) plus the
+ *  boot-stagger spread so every agent's observation of the SAME edge lands
+ *  inside one window; an account genuinely re-crossing the same edge later
+ *  than this re-notifies. */
+export const QUOTA_WATCH_CLAIM_WINDOW_MS = 30 * 60_000;
+
+export function resolveQuotaWatchTuning(
+  env: Record<string, string | undefined>,
+): QuotaWatchTuning {
+  const num = (raw: string | undefined, fallback: number): number => {
+    if (raw === undefined || raw === "") return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+  };
+  return {
+    maxStaleMs: num(env.SWITCHROOM_QUOTA_WATCH_MAX_STALE_MS, DEFAULT_QUOTA_WATCH_MAX_STALE_MS),
+    lateRecoveryMs: num(env.SWITCHROOM_QUOTA_WATCH_LATE_RECOVERY_MS, DEFAULT_QUOTA_WATCH_LATE_RECOVERY_MS),
+    fleetDedup: env.SWITCHROOM_QUOTA_WATCH_FLEET_DEDUP !== "0",
+    sendOnProbeFail: env.SWITCHROOM_QUOTA_WATCH_SEND_ON_PROBE_FAIL === "1",
+  };
+}
+
+/**
+ * Broker dedup-claim key for one (account, transition, chat) cell.
+ * Per-CHAT keys keep the audience identical to pre-dedup behaviour:
+ * every chat that any agent would have notified still receives exactly
+ * one copy — from whichever agent claims it first.
+ */
+export function buildQuotaClaimKey(
+  accountLabel: string,
+  transition: string,
+  chatId: string | number,
+): string {
+  return `quota-watch:${accountLabel}:${transition}:${chatId}`;
+}
+
 // ─── Decision logic ───────────────────────────────────────────────────────────
 
 export type QuotaWatchTransition =
@@ -87,30 +157,73 @@ export type QuotaWatchDecision =
       newAccountState: QuotaWatchAccountState;
       transition: QuotaWatchTransition;
     }
+  | {
+      /**
+       * A real transition was observed, but it is no longer NEWS — persist
+       * the new state so the edge-trigger latch clears, send nothing.
+       * Two producers: boot-tick recoveries (a just-booted gateway cannot
+       * distinguish "just recovered" from "recovered while we were down",
+       * and fleet bounces synchronize all agents' first ticks → flood) and
+       * late recoveries (the matching 🟡 is hours old; an "all clear" now
+       * is state reconciliation, not information).
+       */
+      kind: "reconcile";
+      accountLabel: string;
+      newAccountState: QuotaWatchAccountState;
+      transition: QuotaWatchTransition;
+      reason: "boot-tick-recovery" | "late-recovery";
+    }
   | { kind: "skip"; accountLabel: string; reason: string };
 
 /**
  * Evaluate one account's quota state against its last-notified health.
  *
- * Transition table:
+ * Transition table (after the staleness gate — a cached snapshot older
+ * than `maxStaleMs` is no opinion at all → skip "stale-snapshot"):
  *   healthy → healthy        skip (steady-state)
- *   healthy → throttling     notify (entered-throttling)
+ *   healthy → throttling     notify (entered-throttling) — warnings are
+ *                            level-state news, valid on any tick incl. boot
  *   healthy → blocked        skip (credits-watch covers this)
- *   throttling → healthy     notify (recovered-to-healthy)
+ *   throttling → healthy     notify (recovered-to-healthy), EXCEPT:
+ *                              boot tick           → reconcile silently
+ *                              warning > lateRecoveryMs old → reconcile silently
  *   throttling → throttling  skip (already notified)
  *   throttling → blocked     skip (credits-watch covers blocked)
  *   blocked → *              skip (credits-watch domain)
  *   unknown → *              skip (no quota data — don't spam)
  *   * → unknown              skip (probe failed — transient, don't alarm)
+ *
+ * `bootTick` / `tuning` are optional: omitted (legacy callers/tests) the
+ * behaviour is exactly the pre-hardening table (no stale gate, no
+ * reconciliation).
  */
 export function evaluateQuotaWatchAccount(args: {
   agentName: string;
   snap: AccountSnapshot;
   prev: QuotaWatchAccountState;
   now: number;
+  /** True on the gateway's first watch tick after boot. */
+  bootTick?: boolean;
+  /** Staleness / late-recovery thresholds; 0 disables each. */
+  tuning?: Pick<QuotaWatchTuning, "maxStaleMs" | "lateRecoveryMs">;
 }): QuotaWatchDecision {
   const { agentName, snap, prev, now } = args;
+  const bootTick = args.bootTick ?? false;
+  const maxStaleMs = args.tuning?.maxStaleMs ?? 0;
+  const lateRecoveryMs = args.tuning?.lateRecoveryMs ?? 0;
   const label = snap.label;
+
+  // Staleness gate: a CACHED snapshot (capturedAtMs set) past its shelf
+  // life carries no opinion about the present — neither latch nor release.
+  // Live-probe snapshots (capturedAtMs undefined) are fresh by construction.
+  if (
+    maxStaleMs > 0 &&
+    snap.capturedAtMs !== undefined &&
+    now - snap.capturedAtMs > maxStaleMs
+  ) {
+    return { kind: "skip", accountLabel: label, reason: "stale-snapshot" };
+  }
+
   const currentHealth = classifyHealth(snap);
 
   // Unknown (probe failed) or blocked — skip entirely.
@@ -147,6 +260,31 @@ export function evaluateQuotaWatchAccount(args: {
       lastNotifiedHealth: "healthy",
       lastNotifiedAt: now,
     };
+    // A recovery observed on the first post-boot tick is not attributable
+    // to "just now" — the account may have recovered any time while this
+    // gateway was down, and a fleet bounce synchronizes every agent's
+    // first tick (the 2026-06-09 26-message flood). Reconcile silently.
+    if (bootTick) {
+      return {
+        kind: "reconcile",
+        accountLabel: label,
+        newAccountState: newState,
+        transition: "recovered-to-healthy",
+        reason: "boot-tick-recovery",
+      };
+    }
+    // Recovery whose matching 🟡 warning is hours old: the "all clear" is
+    // no longer actionable news (the user has long moved on; /auth shows
+    // live state on demand). Clear the latch without a message.
+    if (lateRecoveryMs > 0 && now - prev.lastNotifiedAt > lateRecoveryMs) {
+      return {
+        kind: "reconcile",
+        accountLabel: label,
+        newAccountState: newState,
+        transition: "recovered-to-healthy",
+        reason: "late-recovery",
+      };
+    }
     return {
       kind: "notify",
       accountLabel: label,

package/telegram-plugin/tests/auth-quota-util-cell.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Telegram legacy accounts-table twin of the CLI honesty fix — the
+ * legacy table renders exactly when the live probe FAILED, i.e. when
+ * cached-data disclosure matters most.
+ */
+import { describe, it, expect } from "vitest";
+import { formatQuotaUtilCell } from "../gateway/auth-command.js";
+
+const NOW = 1_780_000_000_000;
+
+describe("formatQuotaUtilCell (Telegram legacy table)", () => {
+  it("no cached snapshot → 'no data'", () => {
+    expect(formatQuotaUtilCell({ last_quota: null }, NOW)).toBe("no data");
+  });
+
+  it("renders both windows with the snapshot age", () => {
+    const cell = formatQuotaUtilCell(
+      { last_quota: { fiveHourUtilizationPct: 84.6, sevenDayUtilizationPct: 12.1, capturedAt: NOW - 90_000 } },
+      NOW,
+    );
+    expect(cell).toBe("85%·12% (1m 30s ago)");
+  });
+});

package/telegram-plugin/tests/auto-fallback-fleet.test.ts

@@ -173,3 +173,74 @@ describe('runFleetAutoFallback', () => {
     }
   });
 });
+
+// ── failure notice (broken-promise fix, 2026-06-09 incident follow-up) ──────
+
+import { renderFallbackFailureNotice } from "../auto-fallback-fleet.js";
+
+describe("renderFallbackFailureNotice", () => {
+  it("names the trigger agent, the reason, and the manual recovery verbs", () => {
+    const html = renderFallbackFailureNotice("marko", "auth-broker unreachable (no client).");
+    expect(html).toContain("Auto-failover could not run");
+    expect(html).toContain("<b>marko</b>");
+    expect(html).toContain("auth-broker unreachable");
+    expect(html).toContain("/auth use");
+    expect(html).toContain("/auth</code>");
+  });
+
+  it("escapes HTML in the error reason (broker errors can contain angle brackets)", () => {
+    const html = renderFallbackFailureNotice("a<b", 'request <probe-quota> failed & "timed out"');
+    expect(html).toContain("a&lt;b");
+    expect(html).toContain("&lt;probe-quota&gt;");
+    expect(html).toContain("&amp;");
+    expect(html).not.toMatch(/<probe-quota>/);
+  });
+});
+
+// ── failure-notice cooldown (reviewer blocker: gate window never arms on
+//    failure; quota_wall_detected re-fires ~60s → unbounded notice spam) ─────
+
+import {
+  evaluateFallbackFailureNotice,
+  FALLBACK_FAILURE_NOTICE_COOLDOWN_MS,
+} from "../auto-fallback-fleet.js";
+
+describe("evaluateFallbackFailureNotice", () => {
+  const T0 = 1_780_000_000_000;
+
+  it("first failure always sends and arms the cooldown", () => {
+    const r = evaluateFallbackFailureNotice({ lastSentAtMs: 0 }, T0);
+    expect(r.send).toBe(true);
+    expect(r.next.lastSentAtMs).toBe(T0);
+  });
+
+  it("a repeat failure inside the cooldown is suppressed and does NOT extend the window", () => {
+    const armed = { lastSentAtMs: T0 };
+    const r = evaluateFallbackFailureNotice(armed, T0 + 60_000);
+    expect(r.send).toBe(false);
+    expect(r.next).toBe(armed); // unchanged — window not extended by suppressed attempts
+  });
+
+  it("sends again once the cooldown elapses", () => {
+    const r = evaluateFallbackFailureNotice(
+      { lastSentAtMs: T0 },
+      T0 + FALLBACK_FAILURE_NOTICE_COOLDOWN_MS,
+    );
+    expect(r.send).toBe(true);
+    expect(r.next.lastSentAtMs).toBe(T0 + FALLBACK_FAILURE_NOTICE_COOLDOWN_MS);
+  });
+
+  it("bounds the 60s quota_wall_detected re-fire storm to ≤2 notices/hour", () => {
+    // Simulate a wedged agent re-signalling every 60s for one hour with a
+    // dead broker — the incident shape the reviewer flagged.
+    let state = { lastSentAtMs: 0 };
+    let sent = 0;
+    for (let t = T0; t < T0 + 3_600_000; t += 60_000) {
+      const r = evaluateFallbackFailureNotice(state, t);
+      if (r.send) sent++;
+      state = r.next;
+    }
+    expect(sent).toBeLessThanOrEqual(2);
+    expect(sent).toBeGreaterThanOrEqual(1);
+  });
+});

package/telegram-plugin/tests/model-command.test.ts

@@ -0,0 +1,205 @@
+/**
+ * `/model` Telegram command — parser + handler coverage.
+ *
+ * The headline guarantees:
+ *
+ *   1. The bare `/model` form NEVER reaches the inject primitive —
+ *      with no argument claude renders an interactive picker modal
+ *      that Telegram can't drive (no arrows, no Esc), so injecting it
+ *      would wedge the pane (the /rate-limit-options class of wedge).
+ *   2. The argument is shape-gated before it's typed into the tmux
+ *      pane: one token, no whitespace, no shell/control smuggling.
+ *   3. The set path injects exactly `/model <name>` (claude's own
+ *      REPL verb — already on the inject allowlist) and relays the
+ *      captured output, with the session-only persistence caveat.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  parseModelCommand,
+  handleModelCommand,
+  isValidModelArg,
+  MODEL_ALIASES,
+  type ModelCommandDeps,
+} from "../gateway/model-command.js";
+import type { InjectResult } from "../../src/agents/inject.js";
+
+function okResult(output: string): InjectResult {
+  return {
+    outcome: "ok",
+    output,
+    truncated: false,
+    command: "/model",
+    meta: { description: "Open model picker", expectsOutput: true },
+  };
+}
+
+function makeDeps(overrides: Partial<ModelCommandDeps> = {}) {
+  const calls: Array<{ agent: string; command: string }> = [];
+  const deps: ModelCommandDeps = {
+    inject: async (agent, command) => {
+      calls.push({ agent, command });
+      return okResult("⏺ Set model to sonnet");
+    },
+    getAgentName: () => "klanker",
+    getConfiguredModel: () => "claude-sonnet-4-6",
+    escapeHtml: (s) =>
+      s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"),
+    preBlock: (s) => `<pre>${s}</pre>`,
+    ...overrides,
+  };
+  return { deps, calls };
+}
+
+describe("parseModelCommand", () => {
+  it("returns null for non-/model text", () => {
+    expect(parseModelCommand("/auth list")).toBeNull();
+    expect(parseModelCommand("model sonnet")).toBeNull();
+    expect(parseModelCommand("/modelx sonnet")).toBeNull();
+  });
+
+  it("bare /model (and @botname form) parses as show", () => {
+    expect(parseModelCommand("/model")).toEqual({ kind: "show" });
+    expect(parseModelCommand("/model@klanker_bot")).toEqual({ kind: "show" });
+    expect(parseModelCommand("/model   ")).toEqual({ kind: "show" });
+  });
+
+  it("single valid token parses as set", () => {
+    expect(parseModelCommand("/model sonnet")).toEqual({ kind: "set", model: "sonnet" });
+    expect(parseModelCommand("/model@bot claude-opus-4-8")).toEqual({
+      kind: "set",
+      model: "claude-opus-4-8",
+    });
+    // 1m-context variant ids carry brackets
+    expect(parseModelCommand("/model claude-sonnet-4-6[1m]")).toEqual({
+      kind: "set",
+      model: "claude-sonnet-4-6[1m]",
+    });
+  });
+
+  it("/model help parses as help", () => {
+    expect(parseModelCommand("/model help")).toEqual({ kind: "help" });
+  });
+
+  it("rejects multi-token args (no second token can ride into the pane)", () => {
+    const p = parseModelCommand("/model sonnet; rm -rf /");
+    expect(p?.kind).toBe("help");
+  });
+
+  it("rejects shell/control smuggling shapes", () => {
+    for (const bad of [
+      "/model $(reboot)",
+      "/model `id`",
+      "/model -opus", // leading dash — looks like a flag
+      "/model sonnet\nEnter",
+      "/model ../../etc/passwd",
+      "/model a|b",
+    ]) {
+      const p = parseModelCommand(bad);
+      expect(p?.kind, `should reject: ${bad}`).toBe("help");
+    }
+  });
+});
+
+describe("isValidModelArg", () => {
+  it("accepts aliases and full ids", () => {
+    for (const good of [...MODEL_ALIASES, "claude-opus-4-8", "claude-haiku-4-5-20251001", "claude-sonnet-4-6[1m]"]) {
+      expect(isValidModelArg(good), good).toBe(true);
+    }
+  });
+  it("rejects whitespace, metacharacters, and over-long strings", () => {
+    for (const bad of ["", " ", "a b", "a;b", "a/b", "-x", "a".repeat(120), "a\tb", "a\nb"]) {
+      expect(isValidModelArg(bad), JSON.stringify(bad)).toBe(false);
+    }
+  });
+});
+
+describe("handleModelCommand — show / help never inject (picker-wedge guard)", () => {
+  it("show renders configured model + switch options without injecting", async () => {
+    const { deps, calls } = makeDeps();
+    const reply = await handleModelCommand({ kind: "show" }, deps);
+    expect(calls.length).toBe(0);
+    expect(reply.text).toContain("claude-sonnet-4-6");
+    expect(reply.text).toContain("/model opus");
+    expect(reply.text).toContain("switchroom.yaml");
+  });
+
+  it("show falls back to 'default' when no model configured", async () => {
+    const { deps, calls } = makeDeps({ getConfiguredModel: () => null });
+    const reply = await handleModelCommand({ kind: "show" }, deps);
+    expect(calls.length).toBe(0);
+    expect(reply.text).toContain("<code>default</code>");
+  });
+
+  it("help never injects", async () => {
+    const { deps, calls } = makeDeps();
+    const reply = await handleModelCommand({ kind: "help", reason: "nope" }, deps);
+    expect(calls.length).toBe(0);
+    expect(reply.text).toContain("nope");
+  });
+});
+
+describe("handleModelCommand — set", () => {
+  it("injects exactly `/model <name>` once and relays output + persistence note", async () => {
+    const { deps, calls } = makeDeps();
+    const reply = await handleModelCommand({ kind: "set", model: "opus" }, deps);
+    expect(calls).toEqual([{ agent: "klanker", command: "/model opus" }]);
+    expect(reply.text).toContain("<pre>⏺ Set model to sonnet</pre>");
+    expect(reply.text).toContain("Session-only");
+    expect(reply.html).toBe(true);
+  });
+
+  it("re-gates the model arg at the seam (caller bypassing the parser)", async () => {
+    const { deps, calls } = makeDeps();
+    const reply = await handleModelCommand({ kind: "set", model: "a b; reboot" }, deps);
+    expect(calls.length).toBe(0);
+    expect(reply.text).toContain("not a valid model name");
+  });
+
+  it("ok_no_output explains the empty capture", async () => {
+    const { deps } = makeDeps({
+      inject: async () => ({
+        outcome: "ok_no_output",
+        output: "",
+        truncated: false,
+        command: "/model",
+        meta: { description: "Open model picker", expectsOutput: true },
+      }),
+    });
+    const reply = await handleModelCommand({ kind: "set", model: "sonnet" }, deps);
+    expect(reply.text).toContain("no response captured");
+  });
+
+  it("session_missing failure surfaces the tmux-supervisor hint", async () => {
+    const { deps } = makeDeps({
+      inject: async () => ({
+        outcome: "failed",
+        output: "",
+        truncated: false,
+        command: "/model",
+        meta: null,
+        errorCode: "session_missing",
+        errorMessage: "tmux session not found",
+      }),
+    });
+    const reply = await handleModelCommand({ kind: "set", model: "sonnet" }, deps);
+    expect(reply.text).toContain("tmux session not found");
+    expect(reply.text).toContain("tmux supervisor");
+  });
+
+  it("inject throwing is surfaced, not propagated", async () => {
+    const { deps } = makeDeps({
+      inject: async () => {
+        throw new Error("boom");
+      },
+    });
+    const reply = await handleModelCommand({ kind: "set", model: "sonnet" }, deps);
+    expect(reply.text).toContain("boom");
+  });
+});
+
+describe("inject allowlist contract", () => {
+  it("/model stays on the inject allowlist (the set path depends on it)", async () => {
+    const { INJECT_COMMANDS } = await import("../../src/agents/inject.js");
+    expect(INJECT_COMMANDS.has("/model")).toBe(true);
+  });
+});