switchroom 0.13.3 → 0.13.5

package/telegram-plugin/runtime-metrics.ts

@@ -19,6 +19,7 @@
 import { existsSync, mkdirSync, appendFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { captureEvent } from './analytics-posthog.js'
+import type { PokeLevel } from './silence-poke.js'
 
 export type RuntimeMetricEvent =
   /**
@@ -62,28 +63,33 @@ export type RuntimeMetricEvent =
       ended_via: 'reply' | 'stream_reply_done' | 'silent' | 'forced' | 'framework_fallback'
     }
   /**
-   * Framework safety-net: a silence-poke was armed at 75s (soft) or
-   * 180s (firm). The system-reminder appended to the next tool result
-   * nudges the model to send an update. Doubles as a design-health
-   * signal — if these fire frequently, the conversational-pacing
-   * prompt isn't doing its job.
+   * Framework safety-net: a silence-poke was armed. `ack` is the early
+   * (~10s) ack-budget poke — the model has sent NOTHING this turn and is
+   * leaving the user on a silent chat. `soft` (75s) / `firm` (180s) are
+   * the silence-since-last-outbound ladder. The system-reminder appended
+   * to the next tool result nudges the model to send an update. Doubles
+   * as a design-health signal — if these fire frequently, the
+   * conversational-pacing prompt isn't doing its job.
    */
   | {
       kind: 'silence_poke_fired'
       key: string
-      level: 'soft' | 'firm'
+      level: PokeLevel
       silence_ms: number
       subagent_wait: boolean
     }
   /**
    * The model sent an outbound message within the success window
    * (default 15s) after a poke fired. Pair with `silence_poke_fired`
-   * to compute success rate — the design target is >80%.
+   * to compute success rate — the design target is >80%. (`ack`-level
+   * success is not currently emitted — the ack poke sits outside the
+   * `pokesFired` ladder noteOutbound measures against; the type admits
+   * `ack` only so the silence-poke metric union stays assignable.)
    */
   | {
       kind: 'silence_poke_succeeded'
       key: string
-      level: 'soft' | 'firm'
+      level: PokeLevel
       latency_ms: number
     }
   /**

package/telegram-plugin/silence-poke.ts

@@ -43,7 +43,7 @@
  * pacing prompt still applies; only the framework safety net is off.
  */
 
-export type PokeLevel = 'soft' | 'firm'
+export type PokeLevel = 'ack' | 'soft' | 'firm'
 
 /** #1292: snapshot of an in-flight tool call, surfaced in the 300s
  * framework-fallback message so the user sees the actual observable
@@ -76,6 +76,10 @@ export interface SilencePokeState {
   lastThinkingAt: number | null
   /** True once the 300s framework fallback has fired this turn. */
   fallbackFired: boolean
+  /** True once the early ack-budget poke has fired this turn. One-shot:
+   *  the ack nudge is specifically about the *first* outbound, so it
+   *  never re-arms even after the model later goes quiet again. */
+  ackPokeFired: boolean
   /** Wall-clock ms of last poke fire — used for poke-success latency. */
   lastPokeFiredAt: number | null
   /** #1292: in-flight tool calls keyed by toolUseId. Populated by
@@ -91,6 +95,12 @@ export interface SilencePokeState {
 }
 
 export interface ThresholdsMs {
+  /** Ack budget: if NO outbound at all has landed this many ms after
+   *  turn start, arm an 'ack' poke. This is the framework enforcing the
+   *  human-baseline "acknowledge within a beat" — far tighter than the
+   *  75s `soft` threshold, which measures silence-since-last-outbound
+   *  and is the wrong instrument for "you never said hello." */
+  ack: number
   soft: number
   firm: number
   fallback: number
@@ -101,6 +111,7 @@ export interface ThresholdsMs {
 }
 
 export const DEFAULT_THRESHOLDS: ThresholdsMs = {
+  ack: 10_000,
   soft: 75_000,
   firm: 180_000,
   fallback: 300_000,
@@ -176,6 +187,7 @@ export function startTurn(key: string, now: number): void {
     subagentDispatchActive: false,
     lastThinkingAt: null,
     fallbackFired: false,
+    ackPokeFired: false,
     lastPokeFiredAt: null,
     inFlightTools: new Map(),
   })
@@ -340,6 +352,16 @@ export function endTurn(key: string): void {
 
 /** Verbatim poke text. Wording is load-bearing — see issue #1122 design. */
 export function formatPokeText(level: PokeLevel): string {
+  if (level === 'ack') {
+    return (
+      "[silence-poke] You haven't sent the user anything yet this turn — "
+      + 'they are looking at a silent chat. Send a short, human one-line '
+      + 'acknowledgement now via `reply` (e.g. "on it — checking"), in your '
+      + "persona's voice, before you do any more work. A good colleague "
+      + "answers in a beat; don't leave the message hanging while you think. "
+      + 'If the full answer is genuinely seconds away, send that instead.'
+    )
+  }
   if (level === 'soft') {
     return (
       "[silence-poke] You've been silent to the user for 75s. If you're "
@@ -437,6 +459,32 @@ function tick(now: number): void {
       ? thresholds.subagentSoft
       : thresholds.soft
 
+    // Ack budget — the framework enforcing the human-baseline "answer
+    // in a beat." Fires once, only when NOTHING has been sent this turn
+    // (`lastOutboundAt == null`), well before the 75s `soft` threshold.
+    // `soft` measures silence-since-last-outbound and is the wrong
+    // instrument for "you never acknowledged me." Independent of the
+    // soft/firm/fallback ladder: if the model never acks, it still
+    // escalates soft → firm → fallback on schedule after this.
+    if (
+      !s.ackPokeFired
+      && s.lastOutboundAt == null
+      && s.pokesFired === 0
+      && silence >= thresholds.ack
+    ) {
+      s.pokeArmed = { level: 'ack' }
+      s.ackPokeFired = true
+      s.lastPokeFiredAt = now
+      activeDeps.emitMetric({
+        kind: 'silence_poke_fired',
+        key,
+        level: 'ack',
+        silence_ms: silence,
+        subagent_wait: s.subagentDispatchActive,
+      })
+      continue
+    }
+
     if (s.pokesFired === 0 && silence >= softThreshold) {
       s.pokeArmed = { level: 'soft' }
       s.pokesFired = 1

package/telegram-plugin/tests/silence-poke.test.ts

@@ -33,7 +33,15 @@ function setupDeps(opts?: { thresholds?: Partial<typeof DEFAULT_THRESHOLDS> }):
   __setDepsForTests({
     emitMetric: (e) => fixtures.emitted.push(e),
     onFrameworkFallback: (ctx) => { fixtures.fallbacks.push(ctx) },
-    thresholdsMs: { ...DEFAULT_THRESHOLDS, ...(opts?.thresholds ?? {}) },
+    // The ack budget (a new poke that fires *earlier* than `soft`) is
+    // disabled by default in this fixture so the soft/firm/fallback
+    // ladder tests stay isolated from it. The 'ack budget' describe
+    // block opts back in with a real value.
+    thresholdsMs: {
+      ...DEFAULT_THRESHOLDS,
+      ack: Number.MAX_SAFE_INTEGER,
+      ...(opts?.thresholds ?? {}),
+    },
   })
   return fixtures
 }
@@ -139,6 +147,127 @@ describe('silence-poke — escalation ladder', () => {
   })
 })
 
+// PR1 (human-feel UX epic): the ack budget. A person you message
+// answers in a beat — the framework enforces that baseline by arming an
+// 'ack' poke if NOTHING has been sent within `thresholds.ack` of turn
+// start. It is a one-shot nudge (the model still authors every word),
+// deliberately OUTSIDE the soft/firm/fallback `pokesFired` ladder: if
+// the model never acks, the ladder still escalates on its own schedule.
+// See `reference/conversational-pacing.md` and the "Open with an
+// acknowledgement" bullet in `profiles/_shared/telegram-style.md.hbs`.
+//
+// NB: `setupDeps` disables the ack budget by default (ack = MAX_SAFE);
+// every test here opts back in with a real `ack` threshold.
+describe('silence-poke — ack budget (PR1 human-feel UX)', () => {
+  it('arms an ack poke at the ack threshold when nothing has been sent', () => {
+    const fx = setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('chat:0', 0)
+
+    __tickForTests(9_000) // before the ack budget
+    expect(consumeArmedPoke()).toBeNull()
+    expect(fx.emitted).toHaveLength(0)
+
+    __tickForTests(10_000) // at the ack budget
+    expect(fx.emitted).toEqual([
+      expect.objectContaining({ kind: 'silence_poke_fired', level: 'ack' }),
+    ])
+    const text = consumeArmedPoke()
+    expect(text).toContain('[silence-poke]')
+    expect(text).toContain('reply')
+  })
+
+  it('does NOT arm an ack poke if an outbound landed before the budget', () => {
+    const fx = setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('chat:0', 0)
+    noteOutbound('chat:0', 3_000) // model acked fast — inside the budget
+    __tickForTests(10_000)
+    __tickForTests(20_000)
+    expect(consumeArmedPoke()).toBeNull()
+    expect(
+      fx.emitted.filter((e) => e.kind === 'silence_poke_fired' && e.level === 'ack'),
+    ).toHaveLength(0)
+  })
+
+  it('is one-shot — never re-arms even if the model goes quiet again', () => {
+    const fx = setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('chat:0', 0)
+    __tickForTests(10_000)         // ack fires
+    consumeArmedPoke()             // drain it
+    noteOutbound('chat:0', 12_000) // model finally acks
+    // The model goes quiet again. The ack poke is specifically about the
+    // FIRST outbound — it must not fire twice. A later silence is the
+    // soft poke's job, not the ack budget's.
+    __tickForTests(40_000)
+    expect(
+      fx.emitted.filter((e) => e.kind === 'silence_poke_fired' && e.level === 'ack'),
+    ).toHaveLength(1)
+  })
+
+  it('ackPokeFired resets across turns even when endTurn was skipped (CC-5 invariant)', () => {
+    // Mirrors the subagentDispatchActive CC-5 guard: `ackPokeFired` is a
+    // turn-scoped one-shot flag, and the only thing that keeps it from
+    // leaking into the next turn (when an abnormal abort skips endTurn)
+    // is startTurn's unconditional state overwrite. Pin that here so a
+    // future read-modify-write refactor of startTurn fails loud.
+    setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('k', 0)
+    __tickForTests(10_000) // ack fires
+    expect(__getStateForTests('k')?.ackPokeFired).toBe(true)
+    // Turn 2 in the same key, no endTurn — startTurn MUST clear the flag.
+    startTurn('k', 1_000_000)
+    expect(__getStateForTests('k')?.ackPokeFired).toBe(false)
+  })
+
+  it('does not advance the ladder — soft still requires a full 75s of silence', () => {
+    // The ack poke is deliberately outside `pokesFired`. After it fires,
+    // a soft poke must still wait the normal 75s.
+    const fx = setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('chat:0', 0)
+    __tickForTests(10_000) // ack
+    consumeArmedPoke()
+    __tickForTests(70_000) // 70s total — under the 75s soft threshold
+    expect(
+      fx.emitted.filter((e) => e.kind === 'silence_poke_fired' && e.level === 'soft'),
+    ).toHaveLength(0)
+    __tickForTests(75_000)
+    expect(
+      fx.emitted.filter((e) => e.kind === 'silence_poke_fired' && e.level === 'soft'),
+    ).toHaveLength(1)
+  })
+
+  it('still escalates ack -> soft -> firm -> fallback on a turn that never acks', () => {
+    const fx = setupDeps({ thresholds: { ack: 10_000 } })
+    startTurn('chat:0', 0)
+    __tickForTests(10_000)  // ack
+    consumeArmedPoke()
+    __tickForTests(75_000)  // soft
+    consumeArmedPoke()
+    __tickForTests(180_000) // firm
+    consumeArmedPoke()
+    __tickForTests(300_000) // fallback
+    const trail = fx.emitted.map((e) =>
+      e.kind === 'silence_poke_fired'
+        ? `poke:${e.level}`
+        : e.kind === 'silence_fallback_sent'
+          ? `fallback:${e.fallback_kind}`
+          : e.kind,
+    )
+    expect(trail).toEqual([
+      'poke:ack',
+      'poke:soft',
+      'poke:firm',
+      'fallback:working',
+    ])
+  })
+
+  it('formatPokeText("ack") nudges for a human acknowledgement via reply', () => {
+    const text = formatPokeText('ack')
+    expect(text).toContain('[silence-poke]')
+    expect(text.toLowerCase()).toContain('acknowledg')
+    expect(text).toContain('reply')
+  })
+})
+
 describe('silence-poke — outbound resets clock + success measurement', () => {
   it('noteOutbound resets the silence clock', () => {
     setupDeps()
@@ -608,7 +737,9 @@ describe('silence-poke — fallback handler errors do not break timer', () => {
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => { throw new Error('oh no') },
-      thresholdsMs: DEFAULT_THRESHOLDS,
+      // ack budget out of the way — this test exercises the
+      // soft/firm/fallback ladder under a throwing fallback handler.
+      thresholdsMs: { ...DEFAULT_THRESHOLDS, ack: Number.MAX_SAFE_INTEGER },
     })
     startTurn('k', 0)
     expect(() => {
@@ -625,7 +756,8 @@ describe('silence-poke — fallback handler errors do not break timer', () => {
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => Promise.reject(new Error('async fail')),
-      thresholdsMs: DEFAULT_THRESHOLDS,
+      // ack budget out of the way — see the throwing-handler test above.
+      thresholdsMs: { ...DEFAULT_THRESHOLDS, ack: Number.MAX_SAFE_INTEGER },
     })
     startTurn('k', 0)
     __tickForTests(75_000)

package/telegram-plugin/uat/scenarios/bridge-flap-resilience-dm.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Bridge-flap resilience scenario — regression guard for #1613 / #1616.
+ *
+ * ## The bug this guards
+ *
+ * The handoff-briefing summarizer shells out to a headless `claude -p`
+ * once per turn (handoff Stop hook). Before #1616 it ran without
+ * `--strict-mcp-config`, so it auto-discovered the agent's project
+ * `.mcp.json` and started every MCP server in it — including
+ * `switchroom-telegram`. That spun up a *second* telegram bridge
+ * process which registered against the same gateway socket as the
+ * live agent's real bridge; the two collided under the gateway's
+ * register-race close, producing an A↔B "bridge reconnect race" flap
+ * every ~2s for the ~7-9s the `claude -p` lived. The handoff hook
+ * fires every turn, so did the flap. A turn whose completion landed
+ * inside a flap burst could have its `turn_end` signal eaten — the
+ * agent looked wedged for that turn.
+ *
+ * The fix (#1616): the summarizer passes `--strict-mcp-config`, so
+ * the headless `claude -p` loads zero MCP servers and never spawns a
+ * competing bridge. The structural guard against a new offending
+ * callsite is `tests/bridge-flap-regression-guard.test.ts`; this
+ * scenario is the behavioural backstop.
+ *
+ * ## What this scenario asserts (root-cause-agnostic by design)
+ *
+ * The checks are symptom-based, so they catch a flap reintroduced by
+ * ANY future change — not only a regression of #1616:
+ *
+ * 1. Send a handful of DMs in succession — each drives a turn (and a
+ *    handoff-hook fire). **Primary assertion:** every DM gets a reply
+ *    within budget. Directly catches both the flap (eats turn_end)
+ *    and the wedge (a zero-bridge gap strands the inbound).
+ * 2. **Forensic assertion:** inspect the agent's gateway-supervisor.log
+ *    over the test window and assert the `bridge disconnected` density
+ *    stays BELOW a flap threshold. One healthy persistent bridge
+ *    produces only a trickle of disconnects; a sustained reconnect
+ *    race produces dozens in tight ~2s bursts.
+ *
+ * ## Why the log inspection
+ *
+ * A flap is a server-side phenomenon that does not always surface as
+ * a missed reply (a burst can self-heal in ~20-30s). The `bridge
+ * disconnected` count is the transport-agnostic flap symptom. This
+ * scenario shells into the agent container via `docker exec` to read
+ * the gateway log; if docker is unavailable the log assertion is
+ * skipped with a warning and the responsiveness checks still run.
+ *
+ * ## Tolerances
+ *
+ * - `DISCONNECT_FLAP_THRESHOLD` is the max acceptable `bridge
+ *   disconnected` count over the window. Post-#1616 a healthy ~4-turn
+ *   run sits well under 16 (measured ~8-13, including anonymous
+ *   probe-connection churn); a sustained flap is 20-40+. 16 sits
+ *   comfortably in the gap.
+ */
+
+import { describe, expect, it } from "vitest";
+import { execSync } from "node:child_process";
+import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+const CONTAINER = `switchroom-${AGENT}`;
+const GATEWAY_LOG = "/var/log/switchroom/gateway-supervisor.log";
+
+const DM_COUNT = 4;
+const PER_DM_TIMEOUT_MS = 30_000;
+const OVERALL_DEADLINE_MS = 180_000;
+
+// Post-#1616 a healthy ~4-turn run logs ~8-13 `bridge disconnected`
+// lines (one persistent bridge + anonymous probe-connection churn).
+// A sustained A↔B flap produces 20-40+ in tight ~2s bursts. 16 sits
+// in the gap.
+const DISCONNECT_FLAP_THRESHOLD = 16;
+
+/** Total line count of the agent's gateway-supervisor.log, or null if
+ *  the container/log is unreachable (CI without the container). */
+function gatewayLogLineCount(): number | null {
+  try {
+    const out = execSync(
+      `docker exec ${CONTAINER} sh -lc 'wc -l < ${GATEWAY_LOG}'`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    return parseInt(out.trim(), 10);
+  } catch {
+    return null;
+  }
+}
+
+/** Count `bridge disconnected` lines after `sinceLine` in the log. */
+function disconnectCountSince(sinceLine: number): number | null {
+  try {
+    const out = execSync(
+      `docker exec ${CONTAINER} sh -lc ` +
+        `'awk "NR>${sinceLine}" ${GATEWAY_LOG} | grep -c "bridge disconnected" || true'`,
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    return parseInt(out.trim(), 10);
+  } catch {
+    return null;
+  }
+}
+
+describe("uat: bridge-flap resilience — agent stays responsive, gateway does not flap", () => {
+  it(
+    "every DM gets a reply and the gateway does not flap across turns",
+    async () => {
+      const baselineLine = gatewayLogLineCount();
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        const overallDeadline = Date.now() + OVERALL_DEADLINE_MS;
+
+        for (let i = 1; i <= DM_COUNT; i++) {
+          await sc.sendDM(`flap-resilience probe ${i}/${DM_COUNT}: reply with OK${i}`);
+
+          const remaining = Math.min(
+            PER_DM_TIMEOUT_MS,
+            overallDeadline - Date.now(),
+          );
+          expect(
+            remaining,
+            `overall deadline hit before DM ${i} — earlier turns were too slow`,
+          ).toBeGreaterThan(0);
+
+          const reply = await sc.expectMessage(
+            (m: ObservedMessage) => m.fromBot && !m.edited,
+            { from: "bot", timeout: remaining },
+          );
+          expect(
+            reply.text.length,
+            `DM ${i}/${DM_COUNT} produced an empty reply — a flap may have ` +
+              `eaten the turn_end signal`,
+          ).toBeGreaterThan(0);
+        }
+
+        // Responsiveness held for all DM_COUNT turns. Now check the
+        // server-side flap signal.
+        if (baselineLine == null) {
+          console.warn(
+            "[bridge-flap-resilience] docker exec unavailable — skipping " +
+              "the gateway-log flap assertion; responsiveness checks passed.",
+          );
+          return;
+        }
+
+        const disconnectCount = disconnectCountSince(baselineLine);
+        expect(
+          disconnectCount,
+          "could not read gateway log after the run — container went away",
+        ).not.toBeNull();
+        expect(
+          disconnectCount as number,
+          `gateway logged ${disconnectCount} "bridge disconnected" lines across ` +
+            `${DM_COUNT} turns — at/above the flap threshold ` +
+            `(${DISCONNECT_FLAP_THRESHOLD}). A parasitic bridge is racing the ` +
+            `live one — check for a headless 'claude -p' spawned without ` +
+            `--strict-mcp-config (#1613/#1616).`,
+        ).toBeLessThan(DISCONNECT_FLAP_THRESHOLD);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_DEADLINE_MS + 30_000,
+  );
+});