switchroom 0.20.3 → 0.20.5

package/telegram-plugin/gateway/stream-render.ts

@@ -64,6 +64,7 @@ import { backstopAlreadyDelivered } from '../outbox.js'
 import { journalExternalDelivery } from './outbox-sweep.js'
 import { NarrativeFlushController } from '../narrative-flush.js'
 import { recordTurnEnd, recordTurnStart } from '../registry/turns-schema.js'
+import { stampSubagentDispatchTurn } from '../registry/subagents-schema.js'
 import { retryWithThreadFallback } from '../retry-api-call.js'
 import { richMessage } from '../rich-send.js'
 import { emitRuntimeMetric } from '../runtime-metrics.js'
@@ -604,6 +605,10 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
       replyCalled: false,
       finalAnswerDelivered: false,
       finalAnswerSubstantive: false,
+      // Post-substantive feed-reopen counter — reset each turn.
+      postSubstantiveToolLabelCount: 0,
+      // Post-substantive lever-1 lift latch — reset each turn.
+      postAnswerMainActivity: false,
       // Sticky latch — reset ONLY here (turn start), never by reopen.
       finalAnswerEverDelivered: false,
       // 2026-07 double-reply-on-DM fix (Part 2) — answer-delivered race
@@ -879,6 +884,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
     CONTEXT_EXHAUSTION_COOLDOWN_MS,
     DELIVERY_CONFIRM_ENABLED,
     FEED_REOPEN_AFTER_ACK_ENABLED,
+    FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED,
     HANDBACK_PRETURN_ENABLED,
     HISTORY_ENABLED,
     LIVENESS_TERMINAL_HONESTY,
@@ -1250,6 +1256,35 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // failure mode #116 originally tracked) emit no more tool_use
       // events, so the marker mtime stops advancing → watchdog acts.
       touchTurnActiveMarker(STATE_DIR)
+      // Dispatch-time parent_turn_key stamp from the GATEWAY's live turn
+      // context (Telegram msg 6897 misroute, 2026-08-04). The pretool hook's
+      // #2085 stamp reads the turn-active marker FILE, and the watcher's
+      // backfill needs a turns row whose window contains the dispatch — both
+      // can miss at once (marker swept, hook write lost to SQLITE_BUSY, a
+      // turn whose surface registration failed). The gateway observing this
+      // Agent/Task tool_use inside a live turn KNOWS the turn key directly:
+      // stamp it marker-free. COALESCE inside the helper — a hook-stamped
+      // value is never overwritten, so normal in-turn dispatch is unchanged.
+      if (
+        (ev.toolName === 'Agent' || ev.toolName === 'Task') &&
+        ev.toolUseId != null && ev.toolUseId.length > 0 &&
+        turn.registryKey != null && turnsDb != null
+      ) {
+        try {
+          stampSubagentDispatchTurn(turnsDb, {
+            toolUseId: ev.toolUseId,
+            parentTurnKey: turn.registryKey,
+            agentType: typeof ev.input?.subagent_type === 'string' ? ev.input.subagent_type : null,
+            description: typeof ev.input?.description === 'string' ? ev.input.description : null,
+            background: ev.input?.run_in_background === true,
+            now: Date.now(),
+          })
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: dispatch-time parent_turn_key stamp failed toolUseId=${ev.toolUseId}: ${(err as Error).message}\n`,
+          )
+        }
+      }
       // #549 fix: a tool_use immediately following text events makes
       // those texts "preamble" — the progress card already captured
       // them as a narrative for this tool. Drop the pending answer-
@@ -1377,25 +1412,45 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // liveness is the bounded no-reply timer's job) and lets the silent-end
       // re-prompt fire if the turn ends on only an ack.
       // Kill switch SWITCHROOM_FEED_REOPEN_AFTER_ACK=0 → legacy `return`.
+      //
+      // POST-SUBSTANTIVE reopen: a turn that delivered a real answer and then
+      // kept doing tool work reopens the feed once >= SUBSTANTIVE_REOPEN_MIN_
+      // LABELS post-answer labels arrive — WITHOUT clearing finalAnswerDelivered
+      // (that would trip the turn-end re-prompt → duplicate answer). Instead the
+      // decision returns liftLeverOne, and the drain below opens the fresh card
+      // below the reply via `postAnswerMainActivity` (the foreground sibling of
+      // the sub-agent post-answer liveness exemption). Kill switch
+      // SWITCHROOM_FEED_REOPEN_AFTER_SUBSTANTIVE=0 → post-substantive labels stay
+      // dropped (legacy).
       if (turn.finalAnswerDelivered) {
-        // decideFeedReopen returns dropLabel (legacy return) or the reset
-        // deltas: finalAnswerDelivered→false (the turn has NOT delivered its
-        // final answer while still doing tool work), activityMessageId→null
-        // (a FRESH feed message opens below the ack), activityLastSentRender
-        // →null (so the drain loop's `pending !== lastSent` guard never
-        // mistakes the fresh render for the ack's finalized one and skips it).
+        // Count post-substantive-answer labels so the reopen fires only once the
+        // turn is plainly still working (>=2), not on a stray housekeeping tool.
+        if (turn.finalAnswerSubstantive) turn.postSubstantiveToolLabelCount++
+        // decideFeedReopen returns dropLabel (legacy return), or — on the ACK
+        // path — the reset deltas (finalAnswerDelivered→false, a FRESH feed
+        // message, last-sent cleared), or — on the SUBSTANTIVE path — no reset
+        // but liftLeverOne=true (keep finalAnswerDelivered true, open the card
+        // below the reply).
         const reopen = decideFeedReopen({
           finalAnswerDelivered: turn.finalAnswerDelivered,
-          // ACK-ONLY: reopen only when the prior final was a short ack, not a
-          // substantive answer — otherwise post-answer housekeeping would
-          // reset finalAnswerDelivered and trip the silent-end re-prompt.
           finalAnswerSubstantive: turn.finalAnswerSubstantive,
           enabled: FEED_REOPEN_AFTER_ACK_ENABLED,
+          reopenAfterSubstantiveEnabled: FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED,
+          postSubstantiveToolLabelCount: turn.postSubstantiveToolLabelCount,
         })
         if (reopen.dropLabel) return
-        turn.finalAnswerDelivered = reopen.reset!.finalAnswerDelivered
-        turn.activityMessageId = reopen.reset!.activityMessageId
-        turn.activityLastSentRender = reopen.reset!.activityLastSentRender
+        // ACK reopen carries a reset; the substantive reopen deliberately does
+        // not (finalAnswerDelivered stays true, activityMessageId is already
+        // null from the answer's clearActivitySummary).
+        if (reopen.reset != null) {
+          turn.finalAnswerDelivered = reopen.reset.finalAnswerDelivered
+          turn.activityMessageId = reopen.reset.activityMessageId
+          turn.activityLastSentRender = reopen.reset.activityLastSentRender
+        }
+        // Post-substantive reopen: latch the lever-1 lift so the drain (which
+        // reads this off `turn`) opens the fresh card below the delivered reply.
+        // Sticky for the rest of the turn — the model stays "still working".
+        if (reopen.liftLeverOne) turn.postAnswerMainActivity = true
       }
       const rendered = appendActivityLabel(turn.mirrorLines, ev.label)
       if (rendered != null) {

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -115,6 +115,19 @@ export function buildSubagentHandbackInbound(opts: {
     meta: {
       source: 'subagent_handback',
       outcome: opts.ctx.outcome,
+      // Carry the originating chat as a model-visible channel attribute
+      // (mirrors the real-inbound + resume_interrupted shapes — see
+      // inbound-router.ts:buildInboundEnvelope and resume-inbound-builder.ts).
+      // LOAD-BEARING for turn registration: the gateway's enqueue handler
+      // (`beginTurn`, stream-render.ts) gates the ENTIRE turn-atom mint on
+      // `ev.chatId`, which is parsed from the channel XML's `chat_id`
+      // attribute — rendered ONLY from meta. Without it a handback turn gets
+      // NO `turns` row and NO `turn-active.json` marker, so a worker
+      // dispatched from inside that turn cannot be stamped with a
+      // `parent_turn_key` at dispatch (#2085) nor attributed by the
+      // started_at window backfill — its card + handback then misroute to
+      // the owner DM (Telegram msg 6897 incident, 2026-08-04).
+      chat_id: opts.ctx.chatId,
       // #3268 — round-trip the fabricated `ts` through `meta.message_id` so it
       // survives to enqueue. `ev.messageId` at enqueue is parsed from the
       // channel envelope's `message_id` attribute, which is rendered ONLY from

package/telegram-plugin/gateway/subagent-origin-surface.ts

@@ -0,0 +1,181 @@
+/**
+ * Sub-agent surface-chat resolution — the DB-backed seam behind the
+ * gateway's `resolveSubagentOriginChat` / `resolveWorkerFeedChat` and the
+ * handback/progress destination inputs.
+ *
+ * Extracted (Telegram msg 6897 misroute, 2026-08-04) so the FULL resolution
+ * precedence — including the new most-recent-turn floor — is unit-testable
+ * against a real registry DB (gateway.ts is not importable in tests; the
+ * repo's `decideWorkerFeedDestination` pattern).
+ *
+ * Precedence (resolveWorkerSurfaceChat):
+ *   1. `origin`       — the dispatch-attributed turn: jsonl_agent_id →
+ *      subagents.parent_turn_key (walking the nested-parent chain) →
+ *      turns.chat_id/thread_id. The correct answer whenever the row was
+ *      stamped (pretool-hook marker stamp #2085, gateway dispatch stamp, or
+ *      the watcher's started_at window backfill).
+ *   2. `fleet`        — the configured fleet chat (permanently '' today).
+ *   3. `recent-turn`  — NEW safe-degradation floor: the chat+topic of the
+ *      most recent turn AT OR BEFORE the worker's dispatch time. A
+ *      gap-dispatched worker (no turns row open at its started_at, stamp
+ *      missed) lands NEAR the work — in the topic the operator drove last
+ *      before dispatching — instead of the owner DM with the thread
+ *      stripped. Bounded by the dispatch time so a turn the operator drives
+ *      LATER in an unrelated (possibly shared) chat can never capture the
+ *      worker's surface; with no pre-dispatch turn (or no subagents row to
+ *      date the dispatch from) the floor declines and resolution falls to
+ *      the owner DM.
+ *   4. `owner-dm`     — the durable last resort ("wrong chat" beats
+ *      "no card").
+ */
+
+import {
+  getTurnByKey,
+  findMostRecentTurn,
+  type Turn,
+} from '../registry/turns-schema.js'
+import {
+  resolveSubagentOriginTurnKey,
+  getSubagentByJsonlId,
+} from '../registry/subagents-schema.js'
+
+/** Structural sqlite shape — byte-matches the registry modules' own
+ *  bun:sqlite structural type, so handles flow both ways without casts. */
+type SqliteDatabase = {
+  exec(sql: string): void
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+    get(...params: unknown[]): unknown
+  }
+  transaction(fn: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown
+  close(): void
+}
+
+export interface SubagentSurfaceChat {
+  chatId: string
+  threadId?: number
+}
+
+export type SubagentSurfaceVia = 'origin' | 'fleet' | 'recent-turn' | 'owner-dm' | 'none'
+
+/** Map a turns row to a routable {chatId, threadId}. Null when the row has
+ *  no usable chat. thread_id is stored as TEXT — parse defensively. */
+function turnToSurfaceChat(turn: Pick<Turn, 'chat_id' | 'thread_id'> | null): SubagentSurfaceChat | null {
+  if (turn == null || turn.chat_id.length === 0) return null
+  const threadNum =
+    turn.thread_id != null && turn.thread_id.length > 0 ? Number(turn.thread_id) : NaN
+  return {
+    chatId: turn.chat_id,
+    ...(Number.isFinite(threadNum) ? { threadId: threadNum } : {}),
+  }
+}
+
+/**
+ * The dispatch-attributed origin chat for a worker (jsonl stem →
+ * parent_turn_key chain → turns row). Null on any miss; never throws.
+ * The DB-parameterized body of the gateway's `resolveSubagentOriginChat`.
+ */
+export function resolveSubagentOriginChatDb(
+  db: SqliteDatabase,
+  jsonlAgentId: string,
+): SubagentSurfaceChat | null {
+  try {
+    const originKey = resolveSubagentOriginTurnKey(db, jsonlAgentId)
+    if (originKey == null) return null
+    return turnToSurfaceChat(getTurnByKey(db, originKey))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The recent-turn routing floor: chat+topic of the newest turns row
+ * (running or ended) started AT OR BEFORE the worker's own dispatch time
+ * (`subagents.started_at`, looked up by jsonl stem). The bound is
+ * load-bearing (see `findMostRecentTurn`): a turn newer than the dispatch
+ * can never be the dispatching context, so flooring to it would leak the
+ * worker's surface into whatever unrelated chat the operator drove LAST.
+ * Null when the worker has no subagents row (no dispatch time to bound by —
+ * declining beats guessing), no pre-dispatch turn exists, or the row is
+ * unusable; never throws.
+ */
+export function resolveRecentTurnFallbackChat(
+  db: SqliteDatabase,
+  jsonlAgentId: string,
+): SubagentSurfaceChat | null {
+  try {
+    const worker = getSubagentByJsonlId(db, jsonlAgentId)
+    if (worker == null) return null
+    return turnToSurfaceChat(findMostRecentTurn(db, worker.started_at))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Once-per-agent recent-turn-floor audit line (msg-6897 hardening). The floor
+ * firing is deliberate safe degradation, but it must never be silent — an
+ * operator diagnosing a mis-landed worker surface needs the routing decision
+ * on stderr, exactly like the gateway's owner-DM fallback log. Bounded FIFO
+ * set (a late duplicate line is harmless; the cap bounds a long gateway
+ * lifetime); a gateway restart clears it. `log` injectable for tests.
+ */
+const RECENT_TURN_FLOOR_LOG_CAP = 256
+const recentTurnFloorLogged = new Set<string>()
+export function noteWorkerRecentTurnFloor(
+  agentId: string,
+  dest: SubagentSurfaceChat,
+  log: (line: string) => void = (line) => process.stderr.write(line),
+): void {
+  if (recentTurnFloorLogged.has(agentId)) return
+  recentTurnFloorLogged.add(agentId)
+  if (recentTurnFloorLogged.size > RECENT_TURN_FLOOR_LOG_CAP) {
+    const oldest = recentTurnFloorLogged.values().next().value
+    if (oldest != null) recentTurnFloorLogged.delete(oldest)
+  }
+  log(
+    `telegram gateway: worker origin unresolved agent=${agentId} — flooring to pre-dispatch recent turn chat=${dest.chatId}${dest.threadId != null ? ` thread=${dest.threadId}` : ''}\n`,
+  )
+}
+
+/**
+ * The full ladder resolved into the SHAPE the handback/progress deciders
+ * take (`decideSubagentHandback` / `decideSubagentProgress`): the resolved
+ * surface chat in their `fleetChatId` slot ('' on owner-dm/none so each
+ * decider's own `ownerChatId` floor stays the last resort) and the resolved
+ * topic in `originThreadId` (omitted when none). Audits the recent-turn
+ * floor when it fires. One helper so the gateway call sites are a spread,
+ * not a third and fourth hand-rolled copy of the precedence.
+ */
+export function resolveWorkerSurfaceForDecider(
+  db: SqliteDatabase | null,
+  jsonlAgentId: string,
+  opts: { fleetChatId: string; ownerDm: string },
+): { fleetChatId: string; originThreadId?: number } {
+  const dest = resolveWorkerSurfaceChat(db, jsonlAgentId, opts)
+  if (dest.via === 'recent-turn') noteWorkerRecentTurnFloor(jsonlAgentId, dest)
+  return {
+    fleetChatId: dest.via === 'owner-dm' || dest.via === 'none' ? '' : dest.chatId,
+    ...(dest.threadId != null ? { originThreadId: dest.threadId } : {}),
+  }
+}
+
+/**
+ * Full surface-chat precedence for a worker's card/handback/progress
+ * destination. `db` may be null (turn registry disabled) — resolution then
+ * degrades to fleet → owner DM exactly as before the recent-turn floor.
+ */
+export function resolveWorkerSurfaceChat(
+  db: SqliteDatabase | null,
+  jsonlAgentId: string,
+  opts: { fleetChatId: string; ownerDm: string },
+): { chatId: string; threadId?: number; via: SubagentSurfaceVia } {
+  const origin = db != null ? resolveSubagentOriginChatDb(db, jsonlAgentId) : null
+  if (origin != null && origin.chatId.length > 0) return { ...origin, via: 'origin' }
+  if (opts.fleetChatId.length > 0) return { chatId: opts.fleetChatId, via: 'fleet' }
+  const recent = db != null ? resolveRecentTurnFallbackChat(db, jsonlAgentId) : null
+  if (recent != null) return { ...recent, via: 'recent-turn' }
+  if (opts.ownerDm.length > 0) return { chatId: opts.ownerDm, via: 'owner-dm' }
+  return { chatId: '', via: 'none' }
+}

package/telegram-plugin/gateway/subagent-progress-inbound-builder.ts

@@ -137,6 +137,13 @@ export function buildSubagentProgressInbound(opts: {
     text,
     meta: {
       source: 'subagent_progress',
+      // Originating chat as a model-visible channel attribute — same
+      // load-bearing turn-registration role as the handback builder's
+      // meta.chat_id (see subagent-handback-inbound-builder.ts): without it
+      // the progress turn mints no turn atom (no `turns` row, no
+      // `turn-active.json`), so a worker dispatched from inside it can never
+      // be attributed to this chat/topic and its surfaces fall to the DM.
+      chat_id: opts.ctx.chatId,
       ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       subagent_jsonl_id: opts.ctx.subagentJsonlId,
       bucket_idx: String(opts.ctx.bucketIdx),

package/telegram-plugin/registry/subagents-schema.ts

@@ -784,6 +784,67 @@ export function recordNestedSubagentDispatch(
   `).run(args.parentJsonlAgentId, args.parentJsonlAgentId, args.toolUseId)
 }
 
+export interface StampSubagentDispatchTurnArgs {
+  /** tool_use id of the Agent/Task dispatch — the subagents PK the pretool
+   *  hook inserts (or will insert) the row under. */
+  toolUseId: string
+  /** The live turn's registry key (`turns.turn_key`) at dispatch time. */
+  parentTurnKey: string
+  agentType?: string | null
+  description?: string | null
+  /** `run_in_background` from the dispatch's tool_input. */
+  background: boolean
+  now: number
+}
+
+/**
+ * Stamp `parent_turn_key` on a depth-1 sub-agent row at DISPATCH time, from
+ * the gateway's own live turn context (the `tool_use` session event for an
+ * Agent/Task dispatch observed while a turn atom is open).
+ *
+ * Why this exists (Telegram msg 6897 misroute, 2026-08-04): the pretool
+ * hook's dispatch-time stamp (#2085) sources the turn key from the
+ * `turn-active.json` marker file, and the watcher's backfill
+ * (subagent-watcher.ts) sources it from a `turns` row whose
+ * [started_at, ended_at] window contains the dispatch. Both sources can be
+ * missing at once — a synthesized turn that never registered its surface, a
+ * swept/corrupted marker, a hook write lost to SQLITE_BUSY — leaving
+ * `parent_turn_key` NULL and the worker's card + handback falling back to
+ * the owner DM with the thread stripped. The gateway, however, KNOWS the
+ * live turn key when it observes the dispatch: this helper writes it
+ * directly, marker-free and window-free.
+ *
+ * Behaviour (idempotent, mirrors recordNestedSubagentDispatch):
+ *   - INSERT OR IGNORE a row keyed on the dispatch tool_use_id (harmless
+ *     no-op when the pretool hook's row already landed — the common case).
+ *   - UPDATE `parent_turn_key` only when NULL (COALESCE), so a value the
+ *     hook already stamped from the live marker is never overwritten.
+ */
+export function stampSubagentDispatchTurn(
+  db: SqliteDatabase,
+  args: StampSubagentDispatchTurnArgs,
+): void {
+  db.prepare(`
+    INSERT OR IGNORE INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status)
+    VALUES (?, NULL, ?, ?, ?, ?, ?, ?, 'running')
+  `).run(
+    args.toolUseId,
+    args.parentTurnKey,
+    args.agentType ?? null,
+    args.description ?? null,
+    args.background ? 1 : 0,
+    args.now,
+    args.now,
+  )
+  db.prepare(`
+    UPDATE subagents
+    SET parent_turn_key = COALESCE(parent_turn_key, ?)
+    WHERE id = ?
+  `).run(args.parentTurnKey, args.toolUseId)
+}
+
 /**
  * Resolve the ORIGIN turn key for a worker, walking the nested-parent chain.
  *

package/telegram-plugin/registry/turns-schema.ts

@@ -673,6 +673,32 @@ export function findRecentTurnsForChat(
   return rows.map(mapRow)
 }
 
+/**
+ * Return the most recent turn across ALL chats (any state — running or
+ * ended) whose `started_at` is at or before `beforeOrAtMs`, or null when no
+ * such turn exists. The last-resort routing floor for an unattributable
+ * sub-agent's surfaces (worker card / handback): when origin resolution
+ * misses (parent_turn_key never stamped), the last turn BEFORE the worker's
+ * dispatch is where the operator dispatched it from — a strictly better
+ * landing spot than the owner DM with the thread stripped.
+ *
+ * The bound is load-bearing, not an optimisation: an UNBOUNDED "newest turn"
+ * floor routes a worker's private result to wherever the operator chatted
+ * LAST — possibly an unrelated, shared group entered after the dispatch. A
+ * turn newer than the dispatch can never be the dispatching context, so it
+ * is never a valid floor; callers with no pre-dispatch turn fall through to
+ * the owner-DM last resort instead.
+ */
+export function findMostRecentTurn(db: SqliteDatabase, beforeOrAtMs: number): Turn | null {
+  const row = db.prepare(`
+    SELECT * FROM turns
+    WHERE started_at <= ?
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get(beforeOrAtMs) as RawTurnRow | undefined
+  return row ? mapRow(row) : null
+}
+
 /**
  * Return the most recent N turns across all chats for an agent, ordered by
  * started_at DESC. Intended for the REST API endpoint

package/telegram-plugin/silence-poke.ts

@@ -28,6 +28,14 @@
  * is visibly running; nulling `currentTurn` there would darken the very feed the
  * user is watching. A turn with no in-flight tool is unaffected.
  *
+ * #4330 caveat: an activity-card render that LANDED on Telegram within
+ * `CARD_RENDER_FRESH_MS` (stamped via `noteCardRender` from the card-drain
+ * transport) likewise DEFERS the terminal unwedge, bounded by the same hard
+ * ceiling — a visibly-updating pinned "→ Working…" card is user-visible
+ * activity, and killing the turn under it is a false positive. It never
+ * resets the clock: the framework heartbeat climbs the card on pure wall
+ * clock even on a hung turn, so a reset would pin a dead turn forever.
+ *
  * Terminal action, once per turn:
  *
  *   t=0       startTurn() — silence clock starts at turnStartedAt
@@ -110,6 +118,21 @@ export interface SilencePokeState {
    * silence clock — a real reply / feed edit still does that; this only
    * gates the terminal teardown. */
   sawBashThisTurn: boolean
+  /**
+   * #4330: wall-clock ms of the last activity-card render (open or in-place
+   * edit) that actually LANDED on Telegram for this turn — the pinned
+   * "→ Working… · Nm · N tools" status card the user is watching. Stamped by
+   * `noteCardRender` from the card-drain transport site
+   * (`gateway/narrative-lane.ts` drainActivitySummary), which covers every
+   * producer: tool labels, narrative SHOWs, the liveness open, and the
+   * framework heartbeat climb. Deliberately NOT a clock reset — the heartbeat
+   * climb re-renders on pure wall clock, so a hung turn's card keeps
+   * "updating" and an unbounded reset would pin a dead turn forever (the
+   * #1556 class). Instead the tick() DEFERS the terminal fallback while the
+   * card moved within `CARD_RENDER_FRESH_MS`, bounded by
+   * `fallbackHardCeiling` exactly like the in-flight-tool / compaction
+   * defers. null until the first card render of the turn. */
+  lastCardRenderAt: number | null
   /**
    * #3519 sharpen: claude-CLI background shells PROVEN alive right now. A
    * shell is added on its launch marker (structured `backgroundTaskId`, via
@@ -153,6 +176,16 @@ export const DEFAULT_THRESHOLDS: ThresholdsMs = {
 
 export const DEFAULT_POLL_INTERVAL_MS = 5_000
 
+/**
+ * #4330 — how recent the last landed activity-card render must be for the
+ * card to count as "actively updating in front of the user". The framework
+ * heartbeat edits the card every ~6s (FEED_HEARTBEAT_MIN_STALE_MS); 30s
+ * tolerates several shed/coalesced cosmetic edits under flood-control
+ * backoff while still lapsing quickly once the card genuinely stops moving
+ * (turn ended → card cleared, or the drain wedged).
+ */
+export const CARD_RENDER_FRESH_MS = 30_000
+
 export interface FrameworkFallbackContext {
   key: string
   chatId: string
@@ -326,6 +359,7 @@ export function startTurn(key: string, now: number): void {
     fallbackFired: false,
     floorFired: false,
     inFlightTools: new Map(),
+    lastCardRenderAt: null,
     sawBashThisTurn: false,
     aliveShells: new Set(),
   })
@@ -397,6 +431,36 @@ export function noteProduction(key: string, now: number): void {
   s.fallbackFired = false
 }
 
+/**
+ * #4330: record an activity-card render (open or in-place edit) that actually
+ * LANDED on Telegram for `key` — the pinned "→ Working…" status card visibly
+ * moved. Called from the card-drain transport site
+ * (`gateway/narrative-lane.ts` drainActivitySummary) after a successful
+ * sendRichMessage / non-shed editMessageText, so it covers every card
+ * producer — tool labels, narrative SHOWs, the liveness open, AND the
+ * framework heartbeat climb (`feedHeartbeatTick`), which is exactly the path
+ * that has no `noteProduction` site.
+ *
+ * Deliberately does NOT reset the silence clock (`lastOutboundAt` untouched,
+ * `fallbackFired` untouched): the heartbeat climb renders on pure wall clock
+ * (`now - turn.startedAt`), so a genuinely hung turn's card keeps climbing
+ * forever — counting that as production would keep a dead turn alive
+ * indefinitely (the #1556 dangling-turn class the stream-render tool-label
+ * comment warns about). Instead, tick() DEFERS the terminal fallback while
+ * `now - lastCardRenderAt < CARD_RENDER_FRESH_MS`, bounded by
+ * `fallbackHardCeiling` — same semantics as the #1292/#3519/#4058 defers.
+ * Model-driven card progress (a NEW tool label, a foreground sub-agent nested
+ * render, a draft update) additionally resets the clock via the existing
+ * `noteProduction` sites; this stamp is the floor beneath them.
+ *
+ * No-op when the kill switch is on or the key has no live turn.
+ */
+export function noteCardRender(key: string, now: number): void {
+  const s = state.get(key)
+  if (s == null) return
+  s.lastCardRenderAt = now
+}
+
 /**
  * Record a `thinking` session event. Used to pick "still thinking…" vs
  * "still working…" wording for the 300s framework fallback.
@@ -801,6 +865,22 @@ function tick(now: number): void {
         // gated by SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS=0 — that flag
         // scopes the TOOL defers; compaction has no tool in flight.
         if (activeDeps.isCompactionInFlight?.(key) === true) continue
+        // #4330 — the pinned activity card is visibly updating. A card render
+        // (open or edit) landed on Telegram within CARD_RENDER_FRESH_MS, so
+        // the user is watching a live "→ Working… · Nm · N tools" surface —
+        // the "silent to the user" premise does not hold, and tearing the
+        // turn down would kill the very card they are watching, then re-ask
+        // their message under it. DEFER (clock untouched, fallbackFired
+        // unset, re-checked next tick), bounded by the enclosing
+        // `underCeiling` guard: the heartbeat climb keeps a hung turn's card
+        // moving on pure wall clock, so a truly wedged turn still unwedges at
+        // the hard ceiling. Like the #4058 compaction defer, deliberately NOT
+        // gated by SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS=0 — that flag
+        // scopes the TOOL defers; a card render is not a tool signal.
+        if (
+          s.lastCardRenderAt != null &&
+          now - s.lastCardRenderAt < CARD_RENDER_FRESH_MS
+        ) continue
         const forceDisable = process.env.SWITCHROOM_SILENCE_DEFER_INFLIGHT_TOOLS === '0'
         if (!forceDisable && activeDeps.isLegitimatelyWorking != null) {
           if (activeDeps.isLegitimatelyWorking(key)) continue