switchroom 0.13.55 → 0.13.56

package/telegram-plugin/gateway/gateway.ts

@@ -80,6 +80,7 @@ import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
 import * as pendingProgress from '../pending-work-progress.js'
 import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd } from '../silent-end.js'
+import { markAckSent, clearAckSent } from '../ack-flag.js'
 import { isFinalAnswerReply } from '../final-answer-detect.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
 import { type SessionEvent } from '../session-tail.js'
@@ -3321,6 +3322,43 @@ silencePoke.startTimer({
     // Re-emit through the unified runtime-metrics fan-out (PostHog + JSONL).
     emitRuntimeMetric(event)
   },
+  onAwarenessPing: async (ctx) => {
+    // Early framework-owned awareness signal (~60s) so the user never
+    // faces a silent chat while the model is busy / held / thinking.
+    // Distinct from the 300s onFrameworkFallback: fires earlier, sends
+    // a SILENT message (disable_notification: true — ambient liveness,
+    // not a device buzz), and is bounded to ONE per turn by the silence-
+    // poke module's `awarenessPingFired` flag. Reuses
+    // `formatFrameworkFallbackText` so the wording stays consistent and
+    // in-flight tools are named when known. If the model has been
+    // silent long enough to cross 300s, the heavier framework_fallback
+    // escalates with a notification.
+    //
+    // Late-fire guard mirrors the framework_fallback handler: skip if
+    // the turn ended cleanly between the silence-poke arming and this
+    // timer-fired handler so we don't talk over a clean response.
+    if (activeTurnStartedAt.get(ctx.key) == null && currentTurn == null) {
+      return
+    }
+    const text = silencePoke.formatFrameworkFallbackText(
+      ctx.fallbackKind,
+      ctx.silenceMs,
+      ctx.inFlightTools,
+    )
+    try {
+      await robustApiCall(
+        () => bot.api.sendMessage(ctx.chatId, text, {
+          ...(ctx.threadId != null ? { message_thread_id: ctx.threadId } : {}),
+          disable_notification: true,
+        }),
+        { chat_id: ctx.chatId, ...(ctx.threadId != null ? { threadId: ctx.threadId } : {}) },
+      )
+    } catch (err) {
+      process.stderr.write(
+        `silence-poke awareness-ping sendMessage failed chat=${ctx.chatId} thread=${ctx.threadId}: ${err}\n`,
+      )
+    }
+  },
   onFrameworkFallback: async (ctx) => {
     // Late-fire short-circuit (2026-05-23 audit finding). The fallback
     // can race a clean turn-end: the model's actual reply lands inside
@@ -3429,7 +3467,18 @@ silencePoke.startTimer({
         longest_silent_gap_ms: outboundMetrics.longestOutboundGapMs,
         ended_via: 'framework_fallback',
       })
-      signalTracker.clear(fbKey)
+      // #1892-follow-up: do NOT clear signalTracker state here. When the
+      // model recovers post-fallback (the framework's user-visible
+      // "still working" message is the load-bearing unwedge primitive —
+      // see `project_silence_poke_broken_and_cross_turn_fix`), its late
+      // reply calls fire `signalTracker.noteOutbound(fbKey, ...)`. If
+      // state is already cleared, that's a silent no-op and the late
+      // reply is invisible to outbound_count + ttfo metrics — the
+      // canonical session-end path (silent-marker line 7407 or normal
+      // turn-end line 7502) emits turn_ended a second time, reading
+      // the empty state and reporting outbound_count=0 even though
+      // replies landed. Defer clear to the canonical paths so
+      // post-fallback recoveries are correctly counted.
     }
     // Stamp the turn-DB end row as `timeout` so the wedged turn doesn't
     // stay open until a SIGTERM/restart relabels it (false-negative for
@@ -4896,6 +4945,16 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // silence-poke clock so the next poke is measured from this send.
   signalTracker.noteOutbound(statusKey(chat_id, threadId), Date.now())
   silencePoke.noteOutbound(statusKey(chat_id, threadId), Date.now())
+  // Ack-first gate (`reference/conversational-pacing.md` beat 1):
+  // touch the state-dir flag so the ack-first-pretool hook lets
+  // subsequent non-reply tool calls through this turn. Cleared at
+  // turn_started. Best-effort — a write failure shouldn't break
+  // reply, and the hook is kill-switched anyway.
+  try {
+    markAckSent()
+  } catch (err) {
+    process.stderr.write(`telegram gateway: markAckSent failed: ${err}\n`)
+  }
   // #1741 — only clear silent-end state on a plausibly-final reply.
   // An interim ack (disable_notification:true, short text, no done)
   // must NOT clear the state file; otherwise a turn that ends with
@@ -5491,6 +5550,13 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       const sKey = statusKey(streamChatId, streamThreadId)
       signalTracker.noteOutbound(sKey, Date.now())
       silencePoke.noteOutbound(sKey, Date.now())
+      // Ack-first gate: stream_reply's first emit also unlocks subsequent
+      // tool calls. See ack-flag.ts + ack-first-pretool.ts.
+      try {
+        markAckSent()
+      } catch (err) {
+        process.stderr.write(`telegram gateway: markAckSent (stream_reply) failed: ${err}\n`)
+      }
       // #1741 — see executeReply for the rationale: only a plausibly-
       // final stream_reply clears the silent-end state. An interim
       // ack via stream_reply must NOT clear; the Stop hook needs
@@ -6725,6 +6791,14 @@ function handleSessionEvent(ev: SessionEvent): void {
           statusKey(ev.chatId, enqThreadId),
           'handback',
         )
+        // Ack-first gate (`reference/conversational-pacing.md` beat 1):
+        // wipe the prior turn's `ack-sent.flag` so the ack-first-
+        // pretool hook re-arms for this fresh turn. Centralised HERE
+        // (not in handleInbound) because `enqueue` is the single
+        // canonical fresh-turn atom — fires for real inbounds, cron
+        // fires, subagent-handback channel wakes, vault-grant resumes,
+        // and restart markers alike. Best-effort — see ack-flag.ts.
+        clearAckSent()
       }
       if (ev.chatId) {
         // Issue #195: if a previous turn left an answer-lane stream open
@@ -8985,6 +9059,11 @@ async function handleInbound(
         // the framework can nudge the model if it goes quiet past the
         // soft / firm thresholds.
         silencePoke.startTurn(statusKey(chat_id, messageThreadId), Date.now())
+        // Ack-first gate clear is centralised in handleSessionEvent's
+        // `enqueue` branch — that fires for EVERY fresh turn atom
+        // (real inbound, cron, subagent-handback, vault-grant wake,
+        // restart marker) so cron/handback turns also re-arm the gate.
+        // See the call site under `case 'enqueue'` (~line 6794).
         // #1445 cross-turn pending-async ambient. A new turn starting
         // (user inbound, synthesised wake, or handback channel) is the
         // signal that the model is about to re-engage — clear any

package/telegram-plugin/runtime-metrics.ts

@@ -104,6 +104,23 @@ export type RuntimeMetricEvent =
       fallback_kind: 'working' | 'thinking'
       silence_ms: number
     }
+  /**
+   * Awareness ping (~60s, default): framework-owned user-visible
+   * "still working… / still thinking…" message sent BEFORE the 300s
+   * fallback so the user never faces a silent chat for the full 5
+   * minutes. Silent (no device ping); one-shot per turn; suppressed
+   * by any outbound or sub-agent dispatch. A high rate is the
+   * diagnostic signal that frequent silences exist (held-inbound,
+   * extended-thinking, slow startup), and the rate of the heavier
+   * silence_fallback_sent that still follows tells us how many of
+   * those escalate all the way to 5 min.
+   */
+  | {
+      kind: 'awareness_ping_sent'
+      key: string
+      fallback_kind: 'working' | 'thinking'
+      silence_ms: number
+    }
   /**
    * #1445 cross-turn pending-async ambient lifecycle. `started` fires
    * when a turn ends with a captured anchor AND a pending Agent/Task/

package/telegram-plugin/silence-poke.ts

@@ -80,6 +80,13 @@ export interface SilencePokeState {
    *  the ack nudge is specifically about the *first* outbound, so it
    *  never re-arms even after the model later goes quiet again. */
   ackPokeFired: boolean
+  /** True once the early awareness-ping has fired this turn. One-shot:
+   *  the user only needs one "we know it's slow" cue before the heavier
+   *  300s fallback escalates. Independent of the ack-poke (which targets
+   *  the model via piggyback) — awareness-ping targets the user directly
+   *  via Telegram, so it lands even during pure-thinking or held-inbound
+   *  silences when no tool_result is available to piggyback on. */
+  awarenessPingFired: 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
@@ -101,6 +108,14 @@ export interface ThresholdsMs {
    *  75s `soft` threshold, which measures silence-since-last-outbound
    *  and is the wrong instrument for "you never said hello." */
   ack: number
+  /** Awareness ping: if NO outbound has landed this many ms after turn
+   *  start, send a framework-owned user-visible "still working…" status
+   *  message directly via Telegram. Sits between the model-targeted ack
+   *  poke (10s) and the 300s framework_fallback. Lands even during pure
+   *  extended-thinking or held-inbound silences when no tool_result is
+   *  available to piggyback the model-targeted pokes onto. One-shot per
+   *  turn — the 300s fallback handles further escalation if still silent. */
+  awarenessPing: number
   soft: number
   firm: number
   fallback: number
@@ -112,6 +127,7 @@ export interface ThresholdsMs {
 
 export const DEFAULT_THRESHOLDS: ThresholdsMs = {
   ack: 10_000,
+  awarenessPing: 60_000,
   soft: 75_000,
   firm: 180_000,
   fallback: 300_000,
@@ -145,6 +161,7 @@ export type SilencePokeMetric =
   | { kind: 'silence_poke_fired'; key: string; level: PokeLevel; silence_ms: number; subagent_wait: boolean }
   | { kind: 'silence_poke_succeeded'; key: string; level: PokeLevel; latency_ms: number }
   | { kind: 'silence_fallback_sent'; key: string; fallback_kind: 'working' | 'thinking'; silence_ms: number }
+  | { kind: 'awareness_ping_sent'; key: string; fallback_kind: 'working' | 'thinking'; silence_ms: number }
 
 export interface SilencePokeDeps {
   /** Called when the 300s fallback fires. Caller sends the user-visible
@@ -153,6 +170,12 @@ export interface SilencePokeDeps {
    *  not a model-sourced one, and we want pokes to continue (well, no,
    *  fallbackFired ensures only one per turn anyway). */
   onFrameworkFallback: (ctx: FrameworkFallbackContext) => Promise<void> | void
+  /** Called when the awareness ping fires (default 60s). Caller sends
+   *  a user-visible "still working…" message — silent (no device ping),
+   *  framework-owned, one-shot per turn. Reuses the same context shape
+   *  as onFrameworkFallback so the gateway can reuse `formatFrameworkFallbackText`
+   *  and the in-flight-tool enrichment. */
+  onAwarenessPing: (ctx: FrameworkFallbackContext) => Promise<void> | void
   /** Telemetry sink for poke events. */
   emitMetric: (event: SilencePokeMetric) => void
   /** Threshold overrides (tests). */
@@ -188,6 +211,7 @@ export function startTurn(key: string, now: number): void {
     lastThinkingAt: null,
     fallbackFired: false,
     ackPokeFired: false,
+    awarenessPingFired: false,
     lastPokeFiredAt: null,
     inFlightTools: new Map(),
   })
@@ -485,6 +509,64 @@ function tick(now: number): void {
       continue
     }
 
+    // Awareness ping — framework-owned user-visible status BEFORE the
+    // 300s heavy fallback. Lands at ~60s even when the model is in pure
+    // extended-thinking or the inbound is held (#1892 follow-up), since
+    // it's delivered directly via the gateway → Telegram, not
+    // piggybacked on tool_result. One-shot per turn; suppressed if any
+    // outbound has happened. The 300s fallback is unchanged and
+    // escalates further if silence persists.
+    //
+    // Independent of pokesFired so soft/firm/fallback still escalate on
+    // their own schedule. Independent of ackPokeFired so a long-running
+    // turn that already received the ack-poke (then went silent again)
+    // still gets the user-facing awareness ping.
+    if (
+      !s.awarenessPingFired
+      && s.lastOutboundAt == null
+      && !s.subagentDispatchActive
+      && silence >= thresholds.awarenessPing
+    ) {
+      s.awarenessPingFired = true
+      const { chatId, threadId } = parseKey(key)
+      const recentThinking = s.lastThinkingAt != null
+        && (now - s.lastThinkingAt) < 30_000
+      const fallbackKind: 'working' | 'thinking' = recentThinking ? 'thinking' : 'working'
+      const inFlightTools: ToolSnapshot[] = Array.from(s.inFlightTools.values())
+        .sort((a, b) => a.startedAt - b.startedAt)
+        .map(t => ({
+          name: t.name,
+          label: t.label,
+          durationMs: now - t.startedAt,
+        }))
+      activeDeps.emitMetric({
+        kind: 'awareness_ping_sent',
+        key,
+        fallback_kind: fallbackKind,
+        silence_ms: silence,
+      })
+      try {
+        const ret = activeDeps.onAwarenessPing({
+          key,
+          chatId,
+          threadId,
+          fallbackKind,
+          silenceMs: silence,
+          inFlightTools,
+        })
+        if (ret != null && typeof (ret as Promise<unknown>).then === 'function') {
+          ;(ret as Promise<unknown>).catch(err => {
+            process.stderr.write(`silence-poke: awareness-ping handler rejected: ${err}\n`)
+          })
+        }
+      } catch (err) {
+        process.stderr.write(`silence-poke: awareness-ping handler threw: ${err}\n`)
+      }
+      // Don't `continue` — soft/firm/fallback can still arm in the same tick
+      // if their thresholds have also been crossed. Awareness-ping is a
+      // sibling signal, not part of the ladder.
+    }
+
     if (s.pokesFired === 0 && silence >= softThreshold) {
       s.pokeArmed = { level: 'soft' }
       s.pokesFired = 1

package/telegram-plugin/tests/ack-flag.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { markAckSent, clearAckSent, ACK_SENT_MARKER } from "../ack-flag.js";
+
+describe("ack-flag — gateway-side state file for ack-first hook", () => {
+  let stateDir: string;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), "ack-flag-"));
+    prevEnv = process.env.TELEGRAM_STATE_DIR;
+    process.env.TELEGRAM_STATE_DIR = stateDir;
+  });
+
+  afterEach(() => {
+    if (prevEnv != null) process.env.TELEGRAM_STATE_DIR = prevEnv;
+    else delete process.env.TELEGRAM_STATE_DIR;
+    rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  it("markAckSent creates the marker file", () => {
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("markAckSent is idempotent (second call is a no-op)", () => {
+    markAckSent();
+    expect(() => markAckSent()).not.toThrow();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("clearAckSent removes the marker file", () => {
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+    clearAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+  });
+
+  it("clearAckSent is idempotent (works when marker doesn't exist)", () => {
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    expect(() => clearAckSent()).not.toThrow();
+  });
+
+  it("round-trip: mark → clear → mark cycles work across turns", () => {
+    // turn 1
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+    // turn end / next turn start
+    clearAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    // turn 2 first reply
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("noop when TELEGRAM_STATE_DIR is unset (best-effort)", () => {
+    delete process.env.TELEGRAM_STATE_DIR;
+    expect(() => markAckSent()).not.toThrow();
+    expect(() => clearAckSent()).not.toThrow();
+  });
+});

package/telegram-plugin/tests/post-fallback-outbound-count.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  reset,
+  noteOutbound,
+  getOutboundMetrics,
+  clear,
+  __resetAllForTests,
+} from '../turn-signal-tracker.js'
+
+/**
+ * switchroom#1892-follow-up — regression guard for the post-fallback
+ * outbound under-count.
+ *
+ * Scenario reproduced from clerk's 2026-05-27 wedge:
+ *   1. Turn starts (signalTracker.reset)
+ *   2. Model goes silent for 300s — silence-poke ladder fires, then
+ *      framework_fallback fires + emits turn_ended with outbound_count=0
+ *   3. Model recovers — sends 2 late reply tool calls → executeReply
+ *      calls signalTracker.noteOutbound
+ *   4. Canonical silent-marker turn-end path runs → reads metrics
+ *      again → emits final turn_ended
+ *
+ * Pre-fix (b6cd7e5...): framework_fallback called signalTracker.clear
+ * after emitting its turn_ended. Late noteOutbound calls hit cleared
+ * state and no-op. Silent-marker path re-read the empty default and
+ * reported outbound_count=0 again — late replies invisible to KPIs.
+ *
+ * Post-fix: framework_fallback no longer clears; only the canonical
+ * paths do. Late replies accumulate; the canonical turn_ended carries
+ * the correct count.
+ */
+beforeEach(() => {
+  __resetAllForTests()
+})
+
+describe('signal-tracker survives framework-fallback for late-reply accounting (#1892)', () => {
+  it('late noteOutbound after fallback (without clear) increments outbound_count', () => {
+    const key = 'chat:thread'
+    const turnStart = 1_000_000
+    reset(key, turnStart)
+
+    // Simulate framework_fallback at +300s — emits turn_ended with
+    // outbound_count=0 but DOES NOT clear (the fix).
+    const beforeFallback = getOutboundMetrics(key)
+    expect(beforeFallback.outboundCount).toBe(0)
+    expect(beforeFallback.ttfoMs).toBeNull()
+
+    // Model recovers post-fallback and sends two late replies.
+    noteOutbound(key, turnStart + 312_000) // first late reply at +312s
+    noteOutbound(key, turnStart + 358_000) // second late reply at +358s
+
+    // Canonical silent-marker turn-end reads metrics again and clears.
+    const afterRecovery = getOutboundMetrics(key)
+    expect(afterRecovery.outboundCount).toBe(2)
+    expect(afterRecovery.ttfoMs).toBe(312_000)
+
+    clear(key)
+    expect(getOutboundMetrics(key).outboundCount).toBe(0)
+  })
+
+  it('regression guard: clearing state mid-turn would silently lose late outbounds', () => {
+    // The buggy pre-fix sequence — kept here as the inverse case so a
+    // future change that re-introduces clear-at-fallback fails this
+    // test loudly with the late-reply count going to zero.
+    const key = 'chat:thread'
+    reset(key, 1_000_000)
+    clear(key) // simulates the pre-fix framework_fallback clear
+
+    noteOutbound(key, 1_000_312_000) // late reply after the bogus clear
+    noteOutbound(key, 1_000_358_000)
+
+    const metrics = getOutboundMetrics(key)
+    // This is the pre-fix bug: late replies are invisible because
+    // noteOutbound is a no-op when state is missing.
+    expect(metrics.outboundCount).toBe(0)
+    expect(metrics.ttfoMs).toBeNull()
+  })
+})

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

@@ -26,20 +26,27 @@ const ORIGINAL_KILL_SWITCH = process.env.SWITCHROOM_DISABLE_SILENCE_POKE
 interface TestFixtures {
   emitted: SilencePokeMetric[]
   fallbacks: FrameworkFallbackContext[]
+  awarenessPings: FrameworkFallbackContext[]
 }
 
 function setupDeps(opts?: { thresholds?: Partial<typeof DEFAULT_THRESHOLDS> }): TestFixtures {
-  const fixtures: TestFixtures = { emitted: [], fallbacks: [] }
+  const fixtures: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
   __setDepsForTests({
     emitMetric: (e) => fixtures.emitted.push(e),
     onFrameworkFallback: (ctx) => { fixtures.fallbacks.push(ctx) },
+    onAwarenessPing: (ctx) => { fixtures.awarenessPings.push(ctx) },
     // 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.
+    //
+    // The 60s awarenessPing is also disabled by default so the existing
+    // soft/firm/fallback ladder tests don't see the new sibling event;
+    // the 'awareness ping' describe block opts back in.
     thresholdsMs: {
       ...DEFAULT_THRESHOLDS,
       ack: Number.MAX_SAFE_INTEGER,
+      awarenessPing: Number.MAX_SAFE_INTEGER,
       ...(opts?.thresholds ?? {}),
     },
   })
@@ -733,13 +740,18 @@ describe('silence-poke — independence across turns', () => {
 
 describe('silence-poke — fallback handler errors do not break timer', () => {
   it('continues to function if onFrameworkFallback throws', () => {
-    const fx: TestFixtures = { emitted: [], fallbacks: [] }
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => { throw new Error('oh no') },
-      // ack budget out of the way — this test exercises the
+      onAwarenessPing: () => {},
+      // ack + awareness-ping 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 },
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: Number.MAX_SAFE_INTEGER,
+      },
     })
     startTurn('k', 0)
     expect(() => {
@@ -752,12 +764,17 @@ describe('silence-poke — fallback handler errors do not break timer', () => {
   })
 
   it('continues to function if onFrameworkFallback returns a rejected promise', async () => {
-    const fx: TestFixtures = { emitted: [], fallbacks: [] }
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
     __setDepsForTests({
       emitMetric: (e) => fx.emitted.push(e),
       onFrameworkFallback: () => Promise.reject(new Error('async fail')),
-      // ack budget out of the way — see the throwing-handler test above.
-      thresholdsMs: { ...DEFAULT_THRESHOLDS, ack: Number.MAX_SAFE_INTEGER },
+      onAwarenessPing: () => {},
+      // ack + awareness-ping out of the way — see the throwing-handler test above.
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: Number.MAX_SAFE_INTEGER,
+      },
     })
     startTurn('k', 0)
     __tickForTests(75_000)
@@ -860,3 +877,96 @@ describe('silence-poke — performance', () => {
     expect(elapsed).toBeLessThan(50)
   })
 })
+
+describe('silence-poke — awareness ping (early framework-owned user-visible status)', () => {
+  it('fires once at 60s when no outbound has happened', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(59_000)
+    expect(fx.awarenessPings.length).toBe(0)
+    __tickForTests(60_000)
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.awarenessPings[0]!.silenceMs).toBeGreaterThanOrEqual(60_000)
+    expect(fx.emitted.some(e => e.kind === 'awareness_ping_sent')).toBe(true)
+  })
+
+  it('is one-shot per turn — does not re-fire as silence continues', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(60_000)
+    __tickForTests(120_000)
+    __tickForTests(180_000)
+    expect(fx.awarenessPings.length).toBe(1)
+  })
+
+  it('is suppressed by an early outbound', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteOutbound('k', 30_000)
+    __tickForTests(90_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('is suppressed when subagentDispatchActive is true', () => {
+    // Sub-agent dispatch already widens soft to 300s; the awareness-ping
+    // should also defer so we don't pre-empt the sub-agent's natural
+    // progress signal.
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteSubagentDispatch('k')
+    __tickForTests(120_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('does NOT advance the soft/firm/fallback ladder', () => {
+    // Awareness ping is a sibling signal; soft/firm/fallback continue
+    // to escalate on their own schedule (and the model-targeted ack-poke
+    // similarly remains independent).
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    __tickForTests(60_000) // awareness fires
+    __tickForTests(75_000) // soft fires
+    __tickForTests(180_000) // firm fires
+    __tickForTests(300_000) // fallback fires
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.fallbacks.length).toBe(1)
+    expect(fx.emitted.filter(e => e.kind === 'silence_poke_fired').map(e => (e as { level: string }).level))
+      .toEqual(['soft', 'firm'])
+    expect(fx.emitted.some(e => e.kind === 'silence_fallback_sent')).toBe(true)
+  })
+
+  it('carries fallbackKind=thinking when a recent thinking event landed', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    noteThinking('k', 45_000)
+    __tickForTests(60_000)
+    expect(fx.awarenessPings.length).toBe(1)
+    expect(fx.awarenessPings[0]!.fallbackKind).toBe('thinking')
+  })
+
+  it('does not fire if turn ends before the threshold', () => {
+    const fx = setupDeps({ thresholds: { awarenessPing: 60_000 } })
+    startTurn('k', 0)
+    endTurn('k')
+    __tickForTests(120_000)
+    expect(fx.awarenessPings.length).toBe(0)
+  })
+
+  it('handler errors do not break the timer', () => {
+    const fx: TestFixtures = { emitted: [], fallbacks: [], awarenessPings: [] }
+    __setDepsForTests({
+      emitMetric: (e) => fx.emitted.push(e),
+      onFrameworkFallback: () => {},
+      onAwarenessPing: () => { throw new Error('awareness handler boom') },
+      thresholdsMs: {
+        ...DEFAULT_THRESHOLDS,
+        ack: Number.MAX_SAFE_INTEGER,
+        awarenessPing: 60_000,
+      },
+    })
+    startTurn('k', 0)
+    expect(() => __tickForTests(60_000)).not.toThrow()
+    // Telemetry still emitted
+    expect(fx.emitted.some(e => e.kind === 'awareness_ping_sent')).toBe(true)
+  })
+})