switchroom 0.15.45 → 0.16.5

package/telegram-plugin/tests/permission-title.test.ts

@@ -15,6 +15,7 @@ import {
   formatPermissionResumeMessage,
 } from '../permission-title.js'
 import type { ScopeOption } from '../permission-rule.js'
+import { resolveScopedAllowChoices } from '../permission-rule.js'
 
 const opt = (rule: string): ScopeOption => ({ rule, buttonLabel: 'x', broad: false })
 
@@ -119,11 +120,11 @@ describe('naturalAction — MCP tools', () => {
 })
 
 describe('formatPermissionCardBody', () => {
-  test('renders "<Agent> wants to <action>" + why line', () => {
+  test('renders "<Agent> wants to <action>" + why line (why = caller reason)', () => {
     const body = formatPermissionCardBody({
       toolName: 'Edit',
-      inputPreview: JSON.stringify({ file_path: '/work/supplement-log.md' }),
-      description: 'logging today\'s lifts',
+      inputPreview: JSON.stringify({ file_path: '/work/supplement-log.md', reason: 'logging today\'s lifts' }),
+      description: 'Edit a file on disk.',
       agentName: 'gymbro',
     })
     expect(body).toBe(
@@ -131,11 +132,46 @@ describe('formatPermissionCardBody', () => {
     )
   })
 
-  test('shows "not provided" when description is missing or whitespace', () => {
+  // #2469: the `why:` line is the CALLER's reason, never the tool's static
+  // schema description (which can contain literal $SWITCHROOM_* tokens).
+  test('why is the caller-supplied reason, NOT the schema description (#2469)', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'mcp__hostd__agent_restart',
+      inputPreview: JSON.stringify({ name: 'carrie', reason: 'gateway is wedged, bouncing it' }),
+      description: 'Restart an agent via the host-control daemon. cross-agent (`name` ≠ $SWITCHROOM_AGENT_NAME) …',
+      agentName: 'carrie',
+    })
+    expect(body).toContain('why: <i>gateway is wedged, bouncing it</i>')
+    expect(body).not.toContain('$SWITCHROOM_AGENT_NAME')
+    expect(body).not.toContain('host-control daemon')
+  })
+
+  test('why accepts a `why` arg as well as `reason`', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Bash',
+      inputPreview: JSON.stringify({ command: 'ls /tmp', why: 'listing temp files' }),
+      description: 'Run a shell command.',
+      agentName: 'gymbro',
+    })
+    expect(body).toContain('why: <i>listing temp files</i>')
+  })
+
+  test('shows "not provided" when no caller reason is present (never the description)', () => {
     const body = formatPermissionCardBody({
       toolName: 'Bash',
       inputPreview: JSON.stringify({ command: 'ls /tmp' }),
-      description: '   \n ',
+      description: 'Run a shell command on the host.',
+      agentName: 'gymbro',
+    })
+    expect(body).toContain('why: <i>not provided</i>')
+    expect(body).not.toContain('Run a shell command')
+  })
+
+  test('shows "not provided" when caller reason is whitespace only', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Bash',
+      inputPreview: JSON.stringify({ command: 'ls /tmp', reason: '   \n ' }),
+      description: 'Run a shell command.',
       agentName: 'gymbro',
     })
     expect(body).toContain('why: <i>not provided</i>')
@@ -144,18 +180,18 @@ describe('formatPermissionCardBody', () => {
   test('drops the agent prefix when agentName is null (early-boot edge)', () => {
     const body = formatPermissionCardBody({
       toolName: 'Skill',
-      inputPreview: JSON.stringify({ skill: 'mail' }),
-      description: 'do the thing',
+      inputPreview: JSON.stringify({ skill: 'mail', reason: 'do the thing' }),
+      description: 'Use a skill.',
       agentName: null,
     })
     expect(body).toBe(['🔐 Use the mail skill', 'why: <i>do the thing</i>'].join('\n'))
   })
 
-  test('HTML-escapes <, >, & in agentName / action / description', () => {
+  test('HTML-escapes <, >, & in agentName / action / reason', () => {
     const body = formatPermissionCardBody({
       toolName: 'Bash',
-      inputPreview: JSON.stringify({ command: 'echo "a < b && c > d"' }),
-      description: 'compare a < b & c > d',
+      inputPreview: JSON.stringify({ command: 'echo "a < b && c > d"', reason: 'compare a < b & c > d' }),
+      description: 'Run a shell command.',
       agentName: 'agent<test>',
     })
     expect(body).toContain('&lt;test&gt;')
@@ -165,27 +201,119 @@ describe('formatPermissionCardBody', () => {
     expect(body).toContain('<i>')
   })
 
-  test('truncates a very long description with an ellipsis', () => {
+  test('truncates a very long caller reason with an ellipsis', () => {
     const body = formatPermissionCardBody({
       toolName: 'Skill',
-      inputPreview: JSON.stringify({ skill: 'mail' }),
-      description: 'x'.repeat(500),
+      inputPreview: JSON.stringify({ skill: 'mail', reason: 'x'.repeat(500) }),
+      description: 'Use a skill.',
       agentName: 'clerk',
     })
     expect(body).toContain('xxxx…</i>')
     expect(body.split('\n')[0]).toBe('🔐 <b>Clerk</b> wants to use the mail skill')
   })
 
-  test('collapses internal whitespace in the description', () => {
+  test('collapses internal whitespace in the caller reason', () => {
     const body = formatPermissionCardBody({
       toolName: 'Skill',
-      inputPreview: JSON.stringify({ skill: 'mail' }),
-      description: 'first\n\nsecond\t\t paragraph',
+      inputPreview: JSON.stringify({ skill: 'mail', reason: 'first\n\nsecond\t\t paragraph' }),
+      description: 'Use a skill.',
       agentName: 'clerk',
     })
     expect(body).toContain('why: <i>first second paragraph</i>')
   })
 
+  // config-edit-hardening: upstream Claude Code truncates `inputPreview`
+  // to ~200 chars. For config_propose_edit the (NEW-ordered) reason lands
+  // inside the surviving prefix, but the truncated JSON is unparseable —
+  // the lenient `extractReasonFromRaw` regex fallback must still recover it
+  // so the card no longer renders "why: not provided".
+  test('recovers reason from a >200-char truncated config_propose_edit input', () => {
+    // reason FIRST (the reordered schema), then a huge unified_diff that
+    // gets cut by the 200-char truncation → invalid JSON, no closing brace.
+    const reason = 'widen klanker tools.allow for the new skill'
+    const fullDiff =
+      '--- a/switchroom.yaml\n+++ b/switchroom.yaml\n' +
+      Array.from({ length: 40 }, (_, i) => `+    - "Bash(tool-${i}:*)"`).join('\n')
+    const full = JSON.stringify({
+      reason,
+      target_path: '/state/config/switchroom.yaml',
+      unified_diff: fullDiff,
+    })
+    const truncated = full.slice(0, 200) // mirror the upstream cut
+    expect(() => JSON.parse(truncated)).toThrow() // precondition: unparseable
+    const body = formatPermissionCardBody({
+      toolName: 'config_propose_edit',
+      inputPreview: truncated,
+      description: 'Propose a unified-diff patch against switchroom.yaml.',
+      agentName: 'klanker',
+    })
+    expect(body).toContain(`why: <i>${reason}</i>`)
+    expect(body).not.toContain('not provided')
+  })
+
+  test('recovers reason even when unified_diff precedes it (legacy order)', () => {
+    // Even with the OLD key order (diff first), the regex finds reason if it
+    // survives the cut — proving the fallback is order-independent.
+    const reason = 'self-scope allow rule add'
+    const raw =
+      '{"unified_diff":"--- a/x\\n+++ b/x\\n+ small","reason":"' + reason + '"}'
+    const body = formatPermissionCardBody({
+      toolName: 'config_propose_edit',
+      inputPreview: raw,
+      description: 'desc',
+      agentName: 'klanker',
+    })
+    expect(body).toContain(`why: <i>${reason}</i>`)
+  })
+
+  // #2469: hostd agent_* cards must name WHICH agent is targeted, pulled
+  // from the `name` input arg — not the static curated phrase.
+  test('hostd agent_restart names the target agent in the title (#2469)', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'mcp__hostd__agent_restart',
+      inputPreview: JSON.stringify({ name: 'carrie', reason: 'wedged' }),
+      description: 'Restart an agent via the host-control daemon. $SWITCHROOM_AGENT_NAME …',
+      agentName: 'klanker',
+    })
+    expect(body.split('\n')[0]).toBe('🔐 <b>Klanker</b> wants to restart agent `carrie` in the fleet')
+  })
+
+  test('hostd start/stop/logs/exec each name the target agent (#2469)', () => {
+    const mk = (tool: string) =>
+      formatPermissionCardBody({
+        toolName: tool,
+        inputPreview: JSON.stringify({ name: 'pixel' }),
+        description: 'static schema doc',
+        agentName: 'klanker',
+      }).split('\n')[0]
+    expect(mk('mcp__hostd__agent_start')).toBe('🔐 <b>Klanker</b> wants to start agent `pixel` in the fleet')
+    expect(mk('mcp__hostd__agent_stop')).toBe('🔐 <b>Klanker</b> wants to stop agent `pixel` in the fleet')
+    expect(mk('mcp__hostd__agent_logs')).toBe("🔐 <b>Klanker</b> wants to read agent `pixel`'s container logs")
+    expect(mk('mcp__hostd__agent_exec')).toBe('🔐 <b>Klanker</b> wants to run a read-only inspection inside agent `pixel`')
+  })
+
+  test('hostd agent verb without a name arg falls back to the generic phrase (no crash) (#2469)', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'mcp__hostd__agent_restart',
+      inputPreview: JSON.stringify({ reason: 'bouncing the fleet' }),
+      description: 'static schema doc',
+      agentName: 'klanker',
+    })
+    expect(body.split('\n')[0]).toBe('🔐 <b>Klanker</b> wants to restart an agent in the fleet')
+    expect(body).toContain('why: <i>bouncing the fleet</i>')
+  })
+
+  test('non-name-arg gated verb (update_apply) stays generic and does not break (#2469)', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'mcp__hostd__update_apply',
+      inputPreview: JSON.stringify({ reason: 'rolling out v0.16' }),
+      description: 'static schema doc',
+      agentName: 'klanker',
+    })
+    expect(body.split('\n')[0]).toBe('🔐 <b>Klanker</b> wants to apply a fleet-wide update (pull + recreate)')
+    expect(body).toContain('why: <i>rolling out v0.16</i>')
+  })
+
   // Clarity fix: the card gains a third "↳" line summarizing the REST
   // payload so the operator can see WHAT is being written, not just the
   // endpoint. Values are redaction-passed + truncated; nested objects show
@@ -195,6 +323,7 @@ describe('formatPermissionCardBody', () => {
       toolName: 'mcp__brevo__post',
       inputPreview: JSON.stringify({
         path: '/smtp/email',
+        reason: 'sending the priority-access invite',
         body: { subject: 'Priority access', templateId: 12, to: [{ email: 'lisa@example.com' }] },
       }),
       description: 'HIGH RISK: write to the brevo API (POST).',
@@ -202,7 +331,7 @@ describe('formatPermissionCardBody', () => {
     })
     const lines = body.split('\n')
     expect(lines[0]).toBe('🔐 <b>Marko</b> wants to POST /smtp/email (Brevo)')
-    expect(lines[1]).toBe('why: <i>HIGH RISK: write to the brevo API (POST).</i>')
+    expect(lines[1]).toBe('why: <i>sending the priority-access invite</i>')
     // Third line: scalar keys show value; the nested `to` array shows key-only.
     expect(lines[2]).toContain('↳')
     expect(lines[2]).toContain('subject: Priority access')
@@ -340,3 +469,63 @@ describe('formatPermissionResumeMessage — agent-voiced verdict ack', () => {
     ).toBe('▶️ <b>Agent</b> — got it, continuing: <i>edit: x.md</i>')
   })
 })
+
+describe('truncated inputPreview recovery — Edit/Write file_path extraction', () => {
+  /**
+   * Claude Code produces `input_preview = JSON.stringify(displayInput).slice(0, 200)`.
+   * For Edit/Write the serialised form is:
+   *   {"file_path":"...","old_string":"<hundreds of chars>","new_string":"..."}
+   * which almost always exceeds 200 chars, leaving invalid (truncated) JSON.
+   * "file_path" is the first key so its value is intact within 200 chars.
+   * The lenient regex fallback must recover it so cards read "edit: module.ts"
+   * instead of the generic "edit files".
+   */
+  function truncatedPreview(filePath: string): string {
+    const full = JSON.stringify({
+      file_path: filePath,
+      old_string:
+        'function oldFn() {\n  // many lines of old code that push the JSON way past 200 chars\n  const x = doSomething();\n  return x;\n}',
+      new_string: 'function newFn() { return doSomethingElse(); }',
+    })
+    return full.slice(0, 200)
+  }
+
+  test('naturalAction recovers file basename from truncated Edit inputPreview', () => {
+    const filePath = '/home/user/project/src/some/long/module.ts'
+    const preview = truncatedPreview(filePath)
+
+    // The truncated preview must be invalid JSON (precondition of the bug).
+    expect(() => JSON.parse(preview)).toThrow()
+
+    // After fix: basename is recovered via regex fallback.
+    expect(naturalAction('Edit', preview)).toBe('edit: module.ts')
+  })
+
+  test('naturalAction recovers file basename from truncated Write inputPreview', () => {
+    const filePath = '/home/user/project/src/config/settings.json'
+    const full = JSON.stringify({
+      file_path: filePath,
+      content: 'x'.repeat(300),
+    })
+    const preview = full.slice(0, 200)
+    expect(() => JSON.parse(preview)).toThrow()
+    expect(naturalAction('Write', preview)).toBe('write: settings.json')
+  })
+
+  test('resolveScopedAllowChoices includes a per-file "This file" choice for truncated Edit inputPreview', () => {
+    const filePath = '/home/user/project/src/some/long/module.ts'
+    const preview = truncatedPreview(filePath)
+
+    // The truncated preview must be invalid JSON (precondition of the bug).
+    expect(() => JSON.parse(preview)).toThrow()
+
+    const choices = resolveScopedAllowChoices('Edit', preview)
+    expect(choices).not.toBeNull()
+    // After fix: specific "This file" choice present with the full path.
+    expect(choices!.specific).toBeDefined()
+    expect(choices!.specific!.buttonLabel).toBe('This file')
+    expect(choices!.specific!.rule).toBe(`Edit(${filePath})`)
+    // Broad option also present.
+    expect(choices!.broad.buttonLabel).toBe('Any file')
+  })
+})

package/telegram-plugin/tests/quota-watch.test.ts

@@ -18,6 +18,8 @@ import {
   patchQuotaWatchState,
   emptyQuotaWatchState,
   emptyAccountState,
+  isLiveCorroboration,
+  type CorroborationProbe,
 } from "../quota-watch.js";
 import type { AccountSnapshot } from "../auth-snapshot-format.js";
 import type { QuotaUtilization } from "../quota-check.js";
@@ -217,6 +219,22 @@ describe("evaluateQuotaWatchAccount — message content", () => {
     expect(d.message).toContain("5-hour");
   });
 
+  it("#2495 Change 3 — throttling alarm advertises live-probe corroboration, not a raw cache read", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    // The alarm body's source-of-truth footnote must reflect that the gateway
+    // corroborates the alarm with a forceLive probe (the broker re-probe at
+    // gateway.ts runQuotaWatch), not "Source: broker quota cache".
+    expect(d.message).toContain("Live-probe corroborated");
+    expect(d.message).not.toContain("Source: broker quota cache");
+  });
+
   it("recovery message contains account label and percentages", () => {
     const d = evaluateQuotaWatchAccount({
       agentName: "lawgpt",
@@ -272,6 +290,79 @@ describe("evaluateQuotaWatchAccount — message content", () => {
   });
 });
 
+// ── corroboration gate (#2495 BLOCKER) ───────────────────────────────────────
+
+describe("isLiveCorroboration — only a genuine live probe corroborates (#2495 BLOCKER)", () => {
+  // A successful upstream live probe.
+  const LIVE_OK: CorroborationProbe = { result: { ok: true }, served: "live" };
+  // The trap: under forceLive, when the upstream probe FAILS but the broker
+  // holds a prior snapshot, opProbeQuota returns cachedSnapshotToResult →
+  // result.ok === true but served === "cache". Vacuous corroboration.
+  const CACHE_FALLBACK_AFTER_PROBE_FAIL: CorroborationProbe = {
+    result: { ok: true },
+    served: "cache",
+  };
+  // A hard probe failure with no prior snapshot to fall back on.
+  const PROBE_FAILED: CorroborationProbe = { result: { ok: false }, served: "live" };
+
+  it("a genuine live probe (ok:true, served:'live') corroborates", () => {
+    expect(isLiveCorroboration(LIVE_OK)).toBe(true);
+  });
+
+  it("a failed-probe cache fallback (ok:true, served:'cache') does NOT corroborate", () => {
+    // This is the BLOCKER: a stale cache read must NOT be mistaken for a live
+    // corroboration, even though result.ok is true.
+    expect(isLiveCorroboration(CACHE_FALLBACK_AFTER_PROBE_FAIL)).toBe(false);
+  });
+
+  it("a failed probe (ok:false) does NOT corroborate", () => {
+    expect(isLiveCorroboration(PROBE_FAILED)).toBe(false);
+  });
+
+  it("a missing entry (probe absent from batch result) does NOT corroborate", () => {
+    expect(isLiveCorroboration(undefined)).toBe(false);
+  });
+
+  it("a legacy entry with no `served` tag does NOT corroborate (fail-closed)", () => {
+    expect(isLiveCorroboration({ result: { ok: true } })).toBe(false);
+  });
+
+  // Simulate the gateway gate (runQuotaWatch). The gate fires the alarm and
+  // stamps the "Live-probe corroborated" footnote ONLY when
+  // isLiveCorroboration is true; otherwise it DEFERS (state untouched).
+  function gateDecision(entry: CorroborationProbe | undefined): {
+    fired: boolean;
+    message: string | null;
+  } {
+    if (isLiveCorroboration(entry)) {
+      // Genuine corroboration → re-evaluate and notify with the live numbers.
+      const d = evaluateQuotaWatchAccount({
+        agentName: "lawgpt",
+        snap: THROTTLING_5H,
+        prev: PREV_NEVER_NOTIFIED,
+        now: NOW,
+      });
+      return { fired: true, message: d.kind === "notify" ? d.message : null };
+    }
+    // Not corroborated → defer. No alarm, no footnote.
+    return { fired: false, message: null };
+  }
+
+  it("failed-probe cache fallback → alarm DEFERRED, no false 'Live-probe corroborated' footnote", () => {
+    const decision = gateDecision(CACHE_FALLBACK_AFTER_PROBE_FAIL);
+    expect(decision.fired).toBe(false);
+    expect(decision.message).toBeNull();
+    // The false footnote must NOT be produced on this path.
+    expect(decision.message ?? "").not.toContain("Live-probe corroborated");
+  });
+
+  it("genuine live probe → alarm FIRES and stamps the 'Live-probe corroborated' footnote", () => {
+    const decision = gateDecision(LIVE_OK);
+    expect(decision.fired).toBe(true);
+    expect(decision.message).toContain("Live-probe corroborated");
+  });
+});
+
 // ── state persistence tests ──────────────────────────────────────────────────
 
 describe("loadQuotaWatchState / saveQuotaWatchState — round-trip", () => {
@@ -369,40 +460,161 @@ describe("patchQuotaWatchState", () => {
 describe("evaluateFleetAllExhausted", () => {
   const notAlerting = { lastNotifiedHealth: null, lastNotifiedAt: 0 };
   const alerting = { lastNotifiedHealth: "throttling" as const, lastNotifiedAt: 1000 };
-
-  it("notifies (entered) when every account is exhausted and we weren't alerting", () => {
+  // Use a realistic "now" so a fresh probe (capturedAt near NOW) and a stale
+  // probe (capturedAt older than maxStaleMs) are unambiguous.
+  const NOW = 10_000_000_000;
+  const STALE = DEFAULT_QUOTA_WATCH_MAX_STALE_MS;
+  const gate = { maxStaleMs: STALE };
+  /** A fresh live snapshot captured `ageMs` ago (default: just now). */
+  const freshProbe = (ageMs = 0) => ({ capturedAt: NOW - ageMs });
+  /** A stale snapshot, captured just past the staleness ceiling. */
+  const staleProbe = () => ({ capturedAt: NOW - STALE - 1 });
+
+  it("notifies (entered) when every exhausted account is backed by a FRESH probe", () => {
     const d = evaluateFleetAllExhausted({
       accounts: [
-        { label: "a", exhausted: true, exhausted_until: 5_000 },
-        { label: "b", exhausted: true, exhausted_until: 9_000 },
+        { label: "a", exhausted: true, exhausted_until: NOW + 5_000, last_quota: freshProbe() },
+        { label: "b", exhausted: true, exhausted_until: NOW + 9_000, last_quota: freshProbe(60_000) },
       ],
       prev: notAlerting,
-      now: 1_000,
+      now: NOW,
+      tuning: gate,
     });
     expect(d.kind).toBe("notify");
     if (d.kind === "notify") {
       expect(d.transition).toBe("entered");
       expect(d.newState.lastNotifiedHealth).toBe("throttling");
       expect(d.message).toContain("All accounts exhausted");
-      // earliest reset is the 5_000 one
+      // earliest reset is the +5_000 one
       expect(d.message).toContain("Earliest reset");
     }
   });
 
+  it("skips (probe-blind) when all exhausted rests on STALE marks with no fresh probe (#2478)", () => {
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: true, exhausted_until: NOW + 5_000, last_quota: staleProbe() },
+        { label: "b", exhausted: true, exhausted_until: NOW + 9_000, last_quota: null },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind === "skip") expect(d.reason).toBe("probe-blind");
+  });
+
+  it("skips (probe-blind) on MIXED freshness — one stale-mark-only account is enough (#2478)", () => {
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: true, exhausted_until: NOW + 5_000, last_quota: freshProbe() },
+        { label: "b", exhausted: true, exhausted_until: NOW + 9_000, last_quota: staleProbe() },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind === "skip") expect(d.reason).toBe("probe-blind");
+  });
+
+  it("skips (probe-blind) when a probe is FUTURE-dated beyond the clock-skew tolerance (#2479 nit)", () => {
+    // A future-dated capturedAt makes `now - capturedAt` negative, which would
+    // slip under the staleness ceiling and read as fresh. The clock-skew guard
+    // (mirrored from broker `snapshotFresh`: capturedAt <= now + 60_000) must
+    // reject it so a skewed snapshot does NOT corroborate exhaustion.
+    const futureProbe = () => ({ capturedAt: NOW + 60_000 + 1 }); // 1ms past tolerance
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: true, exhausted_until: NOW + 5_000, last_quota: futureProbe() },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind === "skip") expect(d.reason).toBe("probe-blind");
+  });
+
+  it("notifies (entered) when a probe is future-dated WITHIN the skew tolerance (boundary)", () => {
+    // Exactly +60_000 ms is within tolerance and still negative-age fresh — it
+    // must count as a fresh live probe (proves the guard is a future-dating
+    // skew allowance, not an outright rejection of any future timestamp).
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: true, exhausted_until: NOW + 5_000, last_quota: { capturedAt: NOW + 60_000 } },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind === "notify") expect(d.transition).toBe("entered");
+  });
+
+  it("notifies (entered) when out_of_credits account has a FRESH probe (freshness drives corroboration, not the credits flag)", () => {
+    // NEW CONTRACT (fix/out-of-credits-serve-block): out_of_credits is
+    // informational — it does NOT corroborate exhaustion on its own. But a
+    // genuinely fresh probe (capturedAt within maxStaleMs) still corroborates.
+    // Result: still notifies — for the right reason (fresh snapshot), not the
+    // credits reason.
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        {
+          label: "a",
+          exhausted: true,
+          last_quota: { capturedAt: NOW, overageDisabledReason: "out_of_credits" },
+        },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind === "notify") expect(d.transition).toBe("entered");
+  });
+
+  it("out_of_credits does NOT corroborate exhaustion when the snapshot is past the staleness ceiling (probe-blind)", () => {
+    // NEW CONTRACT (fix/out-of-credits-serve-block): out_of_credits is
+    // informational, NOT exhaustion in its own right at any util. A stale
+    // snapshot with only out_of_credits provides no live corroboration →
+    // probe-blind → skip (no false fleet alert). Contrast with the test above:
+    // a FRESH probe with out_of_credits still notifies via freshness, not the
+    // credits flag.
+    const d = evaluateFleetAllExhausted({
+      accounts: [
+        {
+          label: "a",
+          exhausted: true,
+          last_quota: { capturedAt: NOW - STALE - 1, overageDisabledReason: "out_of_credits" },
+        },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind === "skip") expect(d.reason).toBe("probe-blind");
+  });
+
   it("skips (still) when all exhausted and already alerting — no re-spam", () => {
     const d = evaluateFleetAllExhausted({
       accounts: [{ label: "a", exhausted: true }, { label: "b", exhausted: true }],
       prev: alerting,
       now: 2_000,
+      tuning: gate,
     });
     expect(d.kind).toBe("skip");
   });
 
-  it("notifies (recovered) when one account frees after we were alerting", () => {
+  it("notifies (recovered) when one account frees after we were alerting — UNGUARDED by probe-blind", () => {
+    // Recovery must fire even when freshness data is absent, so a legitimately
+    // fired alert is never stranded (#2478 scope: gate only the `entered` edge).
     const d = evaluateFleetAllExhausted({
       accounts: [{ label: "a", exhausted: false }, { label: "b", exhausted: true }],
       prev: alerting,
       now: 3_000,
+      tuning: gate,
     });
     expect(d.kind).toBe("notify");
     if (d.kind === "notify") {
@@ -413,20 +625,51 @@ describe("evaluateFleetAllExhausted", () => {
     }
   });
 
+  it("entered then recovered: a legit fire (fresh probes) is followed by a working recovery edge", () => {
+    const entered = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: true, last_quota: freshProbe() },
+        { label: "b", exhausted: true, last_quota: freshProbe() },
+      ],
+      prev: notAlerting,
+      now: NOW,
+      tuning: gate,
+    });
+    expect(entered.kind).toBe("notify");
+    if (entered.kind !== "notify") return;
+    expect(entered.transition).toBe("entered");
+    // Feed the persisted state forward; one account frees.
+    const recovered = evaluateFleetAllExhausted({
+      accounts: [
+        { label: "a", exhausted: false, last_quota: freshProbe() },
+        { label: "b", exhausted: true, last_quota: freshProbe() },
+      ],
+      prev: entered.newState,
+      now: NOW + 60_000,
+      tuning: gate,
+    });
+    expect(recovered.kind).toBe("notify");
+    if (recovered.kind === "notify") expect(recovered.transition).toBe("recovered");
+  });
+
   it("skips (not-all) when some account is healthy and we weren't alerting", () => {
     const d = evaluateFleetAllExhausted({
       accounts: [{ label: "a", exhausted: false }, { label: "b", exhausted: true }],
       prev: notAlerting,
       now: 4_000,
+      tuning: gate,
     });
     expect(d.kind).toBe("skip");
   });
 
   it("never alerts on an empty fleet", () => {
-    expect(evaluateFleetAllExhausted({ accounts: [], prev: notAlerting, now: 1 }).kind).toBe("skip");
+    expect(
+      evaluateFleetAllExhausted({ accounts: [], prev: notAlerting, now: 1, tuning: gate }).kind,
+    ).toBe("skip");
   });
 
-  it("shows reset-unknown when no exhausted_until is present", () => {
+  it("with the gate disabled (maxStaleMs 0) the legacy bare-mark behaviour is preserved", () => {
+    // Kill-switch parity: tuning omitted / 0 → fire on bare marks (pre-#2478).
     const d = evaluateFleetAllExhausted({
       accounts: [{ label: "a", exhausted: true }],
       prev: notAlerting,

package/telegram-plugin/tests/reply-terminal-reaction.test.ts

@@ -81,7 +81,12 @@ describe('#1713 + #1728 — reply tool reaction contract', () => {
     )
     const anchor = src.indexOf("fresh sendMessage from reply tool is a user-visible")
     expect(anchor).toBeGreaterThan(-1)
-    const slice = src.slice(anchor, anchor + 3000)
+    // Window widened 3000 → 4000 (#2556): the deterministic-emission lever-1
+    // sticky-latch set + comment lives inside the post-send isFinalAnswerReply
+    // branch between this anchor and finalizeStatusReaction, growing the block
+    // past the old 3000-char window. The assertion's INTENT is unchanged —
+    // finalize present, gated by isFinalAnswerReply, and after the gate.
+    const slice = src.slice(anchor, anchor + 4000)
     // The finalize MUST appear in the post-send block.
     expect(slice).toMatch(/finalizeStatusReaction\(/)
     // It MUST be gated by isFinalAnswerReply (the classifier prevents