switchroom 0.18.11 → 0.18.13

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

package/telegram-plugin/typing-emitter.ts

@@ -0,0 +1,224 @@
+/**
+ * The single gate every `sendChatAction` in the gateway passes through (#3084).
+ *
+ * WHY THIS EXISTS — the 2026-07-11 flood ban
+ * ------------------------------------------
+ * The typing indicator used to be "a 4 s interval", which sounds rate-limited
+ * and is not. Both typing loops (`startTypingLoop` in gateway.ts and the
+ * turn-level `createTurnTypingLoop`) are restart-safe by design: a re-start
+ * clears the old interval and fires ONE action immediately so "typing…" lands
+ * instantly. The tool-use wrapper restarts the loop on every tool call, so the
+ * ping rate tracked the AGENT'S TOOL-CALL RATE, not the 4 s cadence — the
+ * interval was decorative. On 2026-07-11 `overlord` emitted 8,729
+ * sendChatAction calls (55% of all outbound volume, bursting at 200-300/min
+ * into ONE DM) to deliver 203 messages, and earned a per-bot-token flood ban:
+ * `429 retry_after=16739s` — 4.6 hours with every outbound reply rejected.
+ *
+ * The old code comment said the redundant pings were "harmless — same action,
+ * and sendChatAction is cheap." They are not cheap. They spend the per-bot
+ * flood budget the REPLIES need.
+ *
+ * WHAT THIS ENFORCES
+ * ------------------
+ *   1. A per-chat-key emission FLOOR. At most one chat action per key per
+ *      `floorMs` (~4 s refresh window), no matter how many loops restart, from
+ *      which caller, on which surface. Both loops share ONE emitter, so the
+ *      floor holds ACROSS them — they target the same chat key and neither can
+ *      out-shout the other. This is what structurally decouples ping rate from
+ *      tool-call rate.
+ *   2. The UX intent survives: a COLD start (no ping for this key inside the
+ *      floor) still fires immediately, so "typing…" lands the moment a turn
+ *      begins. Only the REDUNDANT restarts are dropped — and a dropped tick is
+ *      never silently lost: it arms a COALESCED catch-up at the instant the
+ *      window opens, so the worst-case gap between two emissions is `floorMs`
+ *      (3.5 s), comfortably inside Telegram's ~5 s action expiry. Without it,
+ *      an eaten tick on a fixed-cadence loop pushes the next emission out to
+ *      `floorMs + refreshMs` = 7.5 s and the chat goes DARK mid-turn — trading
+ *      a flood ban for a dead indicator, which is not a trade we make.
+ *   3. NON-ESSENTIAL by definition: while a flood-wait window is open
+ *      (`isSuppressed`, wired to the #2923 circuit breaker) no typing is
+ *      emitted at all. It cannot succeed, and sending into an open window can
+ *      extend the ban.
+ *
+ * The window is claimed on every attempt that PASSES the floor, including one
+ * suppressed by a flood window. That is deliberate: it bounds the flood-state
+ * read to once per floor per chat instead of once per tool call.
+ *
+ * Pure + injectable (clock, send, chat-key, suppression) so the whole gate is
+ * unit-testable on a fake clock without a bot — `tests/typing-emitter.test.ts`.
+ */
+
+/** Refresh cadence of the typing loops. Telegram's `typing` expires at ~5 s. */
+export const TYPING_REFRESH_MS = 4000
+
+/**
+ * Minimum gap between two chat actions on one chat key. Deliberately a hair
+ * UNDER `TYPING_REFRESH_MS` so a loop's own on-time refresh is never eaten by
+ * timer jitter (a 3999 ms tick would be dropped by a 4000 ms floor, and the
+ * indicator would go dark for a whole window). The gap between successive
+ * emissions therefore stays under Telegram's ~5 s action expiry, while the
+ * worst-case rate falls from the observed ~300/min to ~17/min per chat.
+ */
+export const TYPING_FLOOR_MS = 3500
+
+export interface TypingEmitterDeps {
+  /** Perform the actual chat action. Errors are the caller's concern — the
+   *  emitter never throws and never awaits. */
+  send: (chatId: string, threadId: number | null, action: string) => void
+  /** Canonical chat:thread key (the gateway's `chatKey`) — a supergroup topic
+   *  is its own lane and gets its own floor. */
+  chatKey: (chatId: string, threadId: number | null) => string
+  /** True while a flood-wait window is open. Typing is non-essential: while
+   *  this is true nothing is emitted. Defaults to "never suppressed". */
+  isSuppressed?: () => boolean
+  /** Injected clock (tests pass a fake). */
+  now?: () => number
+  /** Per-key emission floor in ms. */
+  floorMs?: number
+  /** Injected timer for the catch-up (tests pass fake timers). */
+  schedule?: (fn: () => void, ms: number) => unknown
+  /** Cancel a handle returned by `schedule`. */
+  cancel?: (handle: unknown) => void
+  /** Observability hook — fires for each dropped emission. */
+  onDrop?: (info: { key: string; reason: 'floor' | 'flood' }) => void
+}
+
+export interface TypingEmitter {
+  /**
+   * Emit one chat action for (chatId, threadId), subject to the floor and the
+   * flood gate. Returns true iff the action was actually handed to `send`.
+   * A floor-dropped emission arms a coalesced catch-up (see below), so the
+   * caller's cadence is never silently lost.
+   */
+  emit: (chatId: string, threadId?: number | null, action?: string) => boolean
+  /**
+   * Cancel any pending catch-up for a chat key. The canonical turn-end calls
+   * this so a dropped tick can't resurrect "typing…" after the turn is over.
+   * Does NOT clear the floor — the floor must survive loop stops, because the
+   * tool loop stops on every tool result and that is precisely the churn the
+   * floor exists to absorb.
+   */
+  cancelPending: (chatId: string, threadId?: number | null) => void
+  /** Test/observability: number of chat keys currently tracked. */
+  trackedKeys: () => number
+  /** Test/observability: number of catch-ups currently armed (0 ⇒ none leaked). */
+  pendingCatchUps: () => number
+  /** Drop all floor state and cancel every catch-up (shutdown / tests). */
+  reset: () => void
+}
+
+/** Keep the floor map from growing without bound in a long-lived gateway. */
+const PRUNE_AFTER_FACTOR = 10
+const PRUNE_SIZE_THRESHOLD = 64
+
+export function createTypingEmitter(deps: TypingEmitterDeps): TypingEmitter {
+  const floorMs = deps.floorMs ?? TYPING_FLOOR_MS
+  const now = deps.now ?? Date.now
+  const isSuppressed = deps.isSuppressed ?? (() => false)
+  const schedule =
+    deps.schedule ??
+    ((fn: () => void, ms: number) => {
+      const h = setTimeout(fn, ms)
+      ;(h as { unref?: () => void }).unref?.()
+      return h
+    })
+  const cancel =
+    deps.cancel ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>))
+
+  /** chat key → epoch ms at which the current emission window was claimed. */
+  const windowClaimedAt = new Map<string, number>()
+  /** chat key → the single armed catch-up timer (coalesced; never two). */
+  const catchUps = new Map<string, unknown>()
+
+  function prune(t: number): void {
+    if (windowClaimedAt.size <= PRUNE_SIZE_THRESHOLD) return
+    const cutoff = t - floorMs * PRUNE_AFTER_FACTOR
+    for (const [k, ts] of [...windowClaimedAt.entries()]) {
+      if (ts < cutoff && !catchUps.has(k)) windowClaimedAt.delete(k)
+    }
+  }
+
+  function clearCatchUp(key: string): void {
+    const h = catchUps.get(key)
+    if (h !== undefined) {
+      cancel(h)
+      catchUps.delete(key)
+    }
+  }
+
+  /**
+   * A dropped tick MUST NOT become silence. Both loops re-arm a FIXED-cadence
+   * interval, so a tick eaten by the floor is simply lost: the next emission
+   * for that key could land as late as `floorMs + refreshMs` (7.5 s) after the
+   * last one — past Telegram's ~5 s chat-action expiry, and the chat goes dark
+   * mid-turn. That would trade a flood ban for a dead "typing…" indicator,
+   * which breaches `know-what-my-agent-is-doing` ("stays present from receipt
+   * to turn end").
+   *
+   * So a floor drop arms ONE coalesced catch-up at the exact moment the window
+   * opens (`claimedAt + floorMs`). Effect: the worst-case gap between two
+   * emissions is bounded by `floorMs`, while the emission CAP is untouched (the
+   * catch-up fires only once the floor has expired, so it can never emit early).
+   * A second drop inside the same window must not arm a second timer — hence
+   * the coalesce.
+   */
+  function armCatchUp(
+    key: string,
+    chatId: string,
+    threadId: number | null,
+    action: string,
+    delayMs: number,
+  ): void {
+    if (catchUps.has(key)) return // coalesced — one timer per key, always
+    const h = schedule(() => {
+      catchUps.delete(key)
+      // Re-enters `emit`, which re-checks the floor (now expired) and the flood
+      // gate. A send here cancels nothing — there is nothing left to cancel.
+      emit(chatId, threadId, action)
+    }, Math.max(0, delayMs))
+    catchUps.set(key, h)
+  }
+
+  function emit(chatId: string, threadId: number | null = null, action = 'typing'): boolean {
+    const key = deps.chatKey(chatId, threadId ?? null)
+    const t = now()
+    const claimed = windowClaimedAt.get(key)
+    // `t >= claimed` guards a backwards clock step (NTP): a stale future
+    // timestamp must not wedge the indicator off, so treat it as expired.
+    if (claimed != null && t >= claimed && t - claimed < floorMs) {
+      armCatchUp(key, chatId, threadId ?? null, action, claimed + floorMs - t)
+      deps.onDrop?.({ key, reason: 'floor' })
+      return false
+    }
+    // Claim the window BEFORE the flood check so a burst of restarts costs
+    // one flood-state read per floor, not one per restart.
+    windowClaimedAt.set(key, t)
+    prune(t)
+    if (isSuppressed()) {
+      // A flood window is open. Don't arm a catch-up — the goal is silence, not
+      // a deferred ping into the ban.
+      clearCatchUp(key)
+      deps.onDrop?.({ key, reason: 'flood' })
+      return false
+    }
+    // This send satisfies whatever a pending catch-up was going to deliver.
+    // Cancelling it here is what keeps a catch-up from re-arming itself into a
+    // self-sustaining heartbeat after the loops have stopped.
+    clearCatchUp(key)
+    deps.send(chatId, threadId ?? null, action)
+    return true
+  }
+
+  return {
+    emit,
+    cancelPending(chatId, threadId = null) {
+      clearCatchUp(deps.chatKey(chatId, threadId ?? null))
+    },
+    trackedKeys: () => windowClaimedAt.size,
+    pendingCatchUps: () => catchUps.size,
+    reset: () => {
+      for (const key of [...catchUps.keys()]) clearCatchUp(key)
+      windowClaimedAt.clear()
+    },
+  }
+}

package/telegram-plugin/uat/scenarios/jtbd-feel-like-a-colleague-dm.test.ts

@@ -0,0 +1,136 @@
+/**
+ * JTBD scenario — feel like a colleague, not a chatbot (DM).
+ *
+ * Serves: `reference/jobs/feel-like-a-colleague.md`. The colleague posture
+ * is shipped fleet-wide as lane-2 model-visible text (`~/.switchroom/fleet/
+ * CLAUDE.md`, seeded by `renderFleetDefaultsClaudeMd()` in
+ * `src/agents/fleet-defaults.ts`, epic #1850 / issue #1855). One bullet of
+ * "Good looks like" reads:
+ *
+ *   "The agent asks at most one good clarifying question, and skips it when
+ *    intent is clear, stating its assumption inline as it acts."
+ *
+ * This scenario sends a genuinely ambiguous request and asserts the agent
+ * asks EXACTLY ONE clarifying question rather than a question avalanche
+ * (the "Bad looks like" failure) or a confident guess that ignores the
+ * ambiguity.
+ *
+ * Gating: like every file under `telegram-plugin/uat/scenarios/`, this hits
+ * real Telegram + real Claude and only runs under `vitest.uat.config.ts`
+ * (`bun run test:uat`). The default vitest config excludes this directory,
+ * so CI stays green without live credentials.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+
+// Ambiguous on purpose: "the report" has no referent, no format, no
+// destination. A colleague asks which report / what for; it does not
+// silently invent one, and it does not fire three questions.
+const AMBIGUOUS_PROMPT = "can you send over the report when you get a sec?";
+
+/**
+ * Count clarifying questions the agent itself asks. We count sentences
+ * ending in a question mark AFTER stripping spans where a `?` is not a
+ * question the agent is asking: URLs (query strings), inline/fenced code,
+ * and quoted echoes of the user's own words. Rhetorical framing
+ * ("sure, which one?") counts as one question; the invariant is at most one.
+ */
+function countQuestions(text: string): number {
+  const stripped = text
+    // Fenced code blocks, then inline code spans.
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`\n]*`/g, " ")
+    // URLs — `?` here is a query string, not a question.
+    .replace(/\bhttps?:\/\/\S+/gi, " ")
+    .replace(/\bwww\.\S+/gi, " ")
+    // Quoted spans — the agent echoing the user ("you said 'which report?'")
+    // is not the agent asking a question.
+    .replace(/"[^"\n]*"/g, " ")
+    // Single-quoted spans must OPEN at a word boundary so apostrophes in
+    // contractions ("don't", "user's") are not misread as quote delimiters.
+    .replace(/(^|[\s([{])'[^'\n]*'/g, "$1 ")
+    .replace(/[“”][^“”\n]*[“”]/g, " ")
+    // Markdown blockquote lines are quoted material, not the agent's voice.
+    .replace(/^\s*>.*$/gm, " ");
+  const matches = stripped.match(/[^.!?\n]*\?/g);
+  if (matches == null) return 0;
+  // Filter out trivial fragments (a lone "?" or whitespace) that are not
+  // real questions.
+  return matches.filter((m) => m.replace(/[^a-z0-9]/gi, "").length >= 3).length;
+}
+
+/**
+ * `true` for bot messages that are infrastructure cards rather than a
+ * conversational reply: the boot/greeting card (always delivered with the
+ * Telegram `silent` flag — see boot-card.ts "Boot cards are ALWAYS
+ * delivered silently"), edits of earlier messages, and anything matching
+ * the known boot-card header shape (`✅ <agent> back up · <version>`).
+ */
+function isInfrastructureCard(m: {
+  text: string;
+  silent: boolean;
+  edited: boolean;
+}): boolean {
+  if (m.silent || m.edited) return true;
+  return /back up ·|^✅ /u.test(m.text.trim());
+}
+
+describe("uat: feel like a colleague — one clarifying question when ambiguous", () => {
+  it(
+    "ambiguous ask → agent asks exactly one clarifying question",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        await sc.sendDM(AMBIGUOUS_PROMPT);
+
+        // Substantive replies only: skip the boot/greeting card and any
+        // silent interim edits so the assertion runs against the agent's
+        // actual conversational answer to the prompt.
+        const reply = await sc.expectMessage(
+          (m) => /\S/.test(m.text) && !isInfrastructureCard(m),
+          {
+            from: "bot",
+            timeout: 90_000,
+          },
+        );
+
+        expect(reply.text.length).toBeGreaterThan(0);
+
+        const questionCount = countQuestions(reply.text);
+
+        // Invariant: at least one clarifying question (it did not guess
+        // blindly) and at most one (no question avalanche).
+        if (questionCount === 0) {
+          throw new Error(
+            `[colleague] ambiguous ask got no clarifying question — the ` +
+            `agent either guessed a referent or ignored the ambiguity. ` +
+            `Reply: ${JSON.stringify(reply.text.slice(0, 300))}`,
+          );
+        }
+        if (questionCount > 1) {
+          throw new Error(
+            `[colleague] question avalanche: ${questionCount} questions ` +
+            `where one would do. Reply: ${JSON.stringify(reply.text.slice(0, 300))}`,
+          );
+        }
+        expect(questionCount).toBe(1);
+
+        // Posture bonus: no sycophantic preamble. A soft forensic warn,
+        // not a hard fail (voice specifics are audited in
+        // fuzz-voice-scrub-dm).
+        if (/^(great question|i'?d be happy to|absolutely!|of course!)/i.test(reply.text.trim())) {
+          console.warn(
+            `[colleague] reply opens with sycophantic preamble: ` +
+            `${JSON.stringify(reply.text.slice(0, 120))}`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    120_000,
+  );
+});

package/telegram-plugin/welcome-text.ts

@@ -93,6 +93,27 @@ export type AgentMetadata = {
    * asked for current state, so terseness loses to completeness here.
    */
   live?: StatusProbeRow[];
+  /**
+   * Send-gate state (#3084 PR 3, part3-design §6). Present only when the gate
+   * feature flag is ON; omitted entirely when off so `/status` looks exactly
+   * as it did before the gate existed.
+   */
+  sendGate?: SendGateStatus;
+};
+
+/**
+ * `/status` view of the deterministic send gate (#3084). Queued / shed totals
+ * plus any open flood windows with their expiry. Only populated when the gate
+ * is enabled.
+ */
+export type SendGateStatus = {
+  queued: number;
+  shed: number;
+  expired: number;
+  failedFast: number;
+  dropped: number;
+  /** Currently-open flood windows (expired already pruned). */
+  openWindows: { scopeKey: string; untilTs: number }[];
 };
 
 // Markdown escaper for dynamic values interpolated into bold/plain card
@@ -231,6 +252,27 @@ export function statusPairedText(params: {
     }
   }
 
+  // Send-gate block (#3084 PR 3) — only when the gate flag is on, so a fleet
+  // running with the gate OFF sees the identical pre-gate /status.
+  if (meta.sendGate) {
+    const sg = meta.sendGate;
+    lines.push("");
+    lines.push("**Send gate**");
+    lines.push(
+      `queued ${sg.queued} · shed ${sg.shed} · expired ${sg.expired} · ` +
+        `fail-fast ${sg.failedFast} · dropped ${sg.dropped}`,
+    );
+    if (sg.openWindows.length > 0) {
+      const now = Date.now();
+      for (const w of sg.openWindows) {
+        const secs = Math.max(0, Math.round((w.untilTs - now) / 1000));
+        lines.push(`⏳ flood window \`${escapeHtml(w.scopeKey)}\` — clears in ${secs}s`);
+      }
+    } else {
+      lines.push("no open flood windows");
+    }
+  }
+
   const audit = meta.audit;
   if (audit) {
     // Blank separator before the audit block so the reply reads as two