switchroom 0.20.7 → 0.20.9

package/telegram-plugin/tests/cron-bridge-drain-spool-ack.test.ts

@@ -0,0 +1,150 @@
+/**
+ * #4348 — the Tier-1 cheap-cron bridge-register drain must route through the
+ * shared `redeliverBufferedInbound` chokepoint so a delivered cron fire is
+ * `spool.ack`'d exactly once and CANNOT re-fire after a restart.
+ *
+ * The bug: `onClientRegistered`'s `<agent>-cron` branch did a raw
+ * `pendingInboundBuffer.drain()` + `client.send()` loop and returned early,
+ * never reaching `spool.ack` (which lives only inside
+ * `redeliverBufferedInbound`). A due cron tick spooled during the boot window
+ * (before the cron bridge registered) stayed live in the durable spool, so
+ * boot-replay re-pushed it on the next restart and the SAME fire was delivered
+ * a second time — a duplicate cron delivery bounded only by the 15-min
+ * escalation sweep.
+ *
+ * These tests assert the OUTCOME on the real drain seam
+ * (`drainCronBridgeOnRegister`), against a REAL spool + buffer:
+ *   1. the boot-window fire is delivered to the cron bridge, AND
+ *   2. its durable spool entry is acked (liveCount → 0), AND
+ *   3. a simulated restart's boot-replay finds nothing to re-push, so the fire
+ *      does NOT re-fire.
+ *
+ * RED-before-GREEN: with the pre-#4348 raw-drain body the fire is delivered but
+ * the spool entry stays live, so assertions (2)+(3) fail. With the fix routing
+ * through `redeliverBufferedInbound` they pass.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createInboundSpool,
+  type InboundSpoolFsSeam,
+  type InboundSpool,
+} from '../gateway/inbound-spool.js'
+import { createPendingInboundBuffer } from '../gateway/pending-inbound-buffer.js'
+import { drainCronBridgeOnRegister, cronIdentity } from '../gateway/cron-session.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+const SPOOL_PATH = '/state/agent/telegram/inbound-spool.jsonl'
+
+/** In-memory fake fs for the spool — models append + atomic-rename compaction.
+ *  Shared across "restarts" so the durable JSONL survives, exactly like the
+ *  persistent per-agent volume. */
+function fakeFs(): InboundSpoolFsSeam {
+  const files = new Map<string, string>()
+  return {
+    appendFileSync: (p, d) => files.set(p, (files.get(p) ?? '') + d),
+    readFileSync: (p) => files.get(p) ?? '',
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (from, to) => {
+      files.set(to, files.get(from) ?? '')
+      files.delete(from)
+    },
+    existsSync: (p) => files.has(p),
+    statSizeSync: (p) => Buffer.byteLength(files.get(p) ?? ''),
+    fsyncFileSync: () => {},
+    fsyncDirSync: () => {},
+  }
+}
+
+function cronFire(over: Partial<InboundMessage> = {}): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'c1',
+    messageId: 0, // synthetic — cron fires carry no Telegram messageId
+    user: 'system',
+    userId: 0,
+    ts: 1000,
+    text: 'Time for the daily digest',
+    meta: { source: 'cron', session: 'cron' },
+    ...over,
+  } as InboundMessage
+}
+
+/** A capturing stand-in for the just-registered cron IPC client. */
+function fakeClient(agentName: string): {
+  agentName: string
+  send: (msg: unknown) => void
+  sent: unknown[]
+} {
+  const sent: unknown[] = []
+  return { agentName, send: (m) => void sent.push(m), sent }
+}
+
+/** Simulate the gateway's boot-replay: re-push every live (un-acked) spool
+ *  entry into a fresh in-memory buffer, exactly as gateway.ts does at boot. */
+function bootReplayInto(spool: InboundSpool): ReturnType<typeof createPendingInboundBuffer> {
+  const buffer = createPendingInboundBuffer({ log: () => {}, spool })
+  for (const { agent, msg } of spool.liveEntries()) buffer.push(agent, msg)
+  return buffer
+}
+
+describe('#4348 cron-bridge drain routes through the spool-ack chokepoint', () => {
+  it('acks the boot-window cron fire and does not re-fire after restart', () => {
+    const fs = fakeFs()
+    const spool = createInboundSpool({ path: SPOOL_PATH, fs, log: () => {} })
+    const cronAgent = cronIdentity('overlord') // "overlord-cron"
+
+    // Boot window: a due cron tick arrives BEFORE the cron bridge registers.
+    // It is buffered (in-memory) AND durably spooled by the same push.
+    const buffer = createPendingInboundBuffer({ log: () => {}, spool })
+    buffer.push(cronAgent, cronFire())
+    expect(spool.liveCount()).toBe(1) // durably recorded, not yet delivered
+
+    // The cron bridge registers → the drain seam under test runs.
+    const client = fakeClient(cronAgent)
+    const result = drainCronBridgeOnRegister(client, buffer, spool)
+
+    // (1) The fire was delivered to the cron bridge.
+    expect(result.drained).toBe(1)
+    expect(result.redelivered).toBe(1)
+    const deliveredFires = client.sent.filter(
+      (m): m is InboundMessage => (m as InboundMessage).type === 'inbound',
+    )
+    expect(deliveredFires).toHaveLength(1)
+    expect(deliveredFires[0]!.text).toBe('Time for the daily digest')
+
+    // (2) The durable spool entry is tombstoned — the whole point of #4348.
+    expect(spool.liveCount()).toBe(0)
+    expect(spool.liveEntries()).toHaveLength(0)
+
+    // (3) Simulated restart: boot-replay finds nothing to re-push, so the SAME
+    //     fire does NOT re-fire. (Pre-fix this replayed the un-acked entry.)
+    const afterRestart = bootReplayInto(spool)
+    expect(afterRestart.drain(cronAgent)).toHaveLength(0)
+  })
+
+  it('a send failure re-buffers the fire and leaves the spool entry live (lossless)', () => {
+    const fs = fakeFs()
+    const spool = createInboundSpool({ path: SPOOL_PATH, fs, log: () => {} })
+    const cronAgent = cronIdentity('overlord')
+
+    const buffer = createPendingInboundBuffer({ log: () => {}, spool })
+    buffer.push(cronAgent, cronFire())
+
+    // Client whose send throws for inbound fires (bridge wedged mid-drain).
+    const throwing = {
+      agentName: cronAgent,
+      send: (m: unknown) => {
+        if ((m as InboundMessage).type === 'inbound') throw new Error('socket gone')
+      },
+    }
+    const result = drainCronBridgeOnRegister(throwing, buffer, spool)
+
+    // Not delivered → re-buffered, and the spool entry stays LIVE so the next
+    // register (or boot-replay) retries it. Nothing is dropped, nothing acked.
+    expect(result.redelivered).toBe(0)
+    expect(result.rebuffered).toBe(1)
+    expect(spool.liveCount()).toBe(1)
+    expect(buffer.drain(cronAgent)).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/handback-tasknotif-dedup.test.ts

@@ -0,0 +1,248 @@
+/**
+ * Double-wake dedup (v0.20.8 candidate) — one background sub-agent completion
+ * must produce ONE parent wake, not two.
+ *
+ * The bug: a single background sub-agent completion fanned out to TWO
+ * independent wakes of the parent session —
+ *   1. the claude CLI's own `<task-notification>` (enqueued by the CLI itself;
+ *      switchroom read it only as a background-shell liveness signal), and
+ *   2. the gateway-synthesized `subagent_handback` inbound (subagent-watcher
+ *      `onFinish` → `pendingInboundBuffer.push`).
+ * Nothing linked them. The CLI-native wake cannot be suppressed (it is the
+ * CLI's internal queue), so the fix gates the ONE lever switchroom holds — the
+ * handback enqueue — on a recently-seen terminal `<task-notification>` for
+ * EXACTLY the same task/agent id (`CliTaskNotificationLedger`,
+ * subagent-handback-marker.ts; consumed by `decideSubagentHandback`).
+ *
+ * FAIL-OPEN contract pinned here: every uncertain path DELIVERS the handback.
+ * A dropped real wake (silent worker, user waits forever) is strictly worse
+ * than an occasional double.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  CliTaskNotificationLedger,
+  TASK_NOTIFICATION_DEDUP_TTL_MS,
+} from '../gateway/subagent-handback-marker.js'
+import { decideSubagentHandback } from '../gateway/subagent-handback-inbound-builder.js'
+import { projectTranscriptLine } from '../session-tail.js'
+import { applyBackgroundShellLiveness } from '../gateway/background-shell-liveness.js'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const T0 = 1_700_000_000_000
+
+const base = {
+  handbackEnvValue: undefined as string | undefined,
+  outcome: 'completed' as 'completed' | 'failed' | 'orphan',
+  isBackground: true,
+  fleetChatId: '777',
+  ownerChatId: '999',
+  taskDescription: 'Do the thing',
+  resultText: 'Done.',
+  jsonlAgentId: 'a204deeaedb27b580',
+  nowMs: T0,
+}
+
+// A real captured queue-operation enqueue line shape (fixture
+// bg-shell-liveness-3519.jsonl), retargeted at an AGENT task id — the live
+// transcripts prove `<task-id>` for a backgrounded agent equals the
+// `agent-<id>.jsonl` stem the subagent-watcher uses as `agentId`
+// (verified: <task-id>a204deeaedb27b580</task-id> ↔
+// subagents/agent-a204deeaedb27b580.jsonl).
+function notifLine(taskId: string, status: string): string {
+  return JSON.stringify({
+    type: 'queue-operation',
+    operation: 'enqueue',
+    timestamp: '2026-08-04T00:00:00.000Z',
+    sessionId: 'deadbeef-0000-4000-8000-000000000000',
+    content:
+      `<task-notification>\n<task-id>${taskId}</task-id>\n` +
+      `<tool-use-id>toolu_01TESTTESTTESTTEST</tool-use-id>\n` +
+      `<output-file>/tmp/tasks/${taskId}.output</output-file>\n` +
+      `<status>${status}</status>\n<summary>Agent done</summary>\n</task-notification>`,
+  })
+}
+
+describe('CliTaskNotificationLedger', () => {
+  it('records a terminal notification and reports it within the TTL', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('a204deeaedb27b580', 'completed', T0)
+    expect(l.seenRecently('a204deeaedb27b580', T0 + 5_000)).toBe(true)
+    expect(l.seenRecently('a204deeaedb27b580', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS)).toBe(true)
+  })
+
+  it('fail-open: expires after the TTL (a resumed worker second completion delivers)', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('a204deeaedb27b580', 'completed', T0)
+    expect(l.seenRecently('a204deeaedb27b580', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 1)).toBe(false)
+  })
+
+  it('fail-open: a DIFFERENT task id never matches', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('a204deeaedb27b580', 'completed', T0)
+    expect(l.seenRecently('a999999999999999', T0 + 1)).toBe(false)
+  })
+
+  it('fail-open: non-terminal statuses and empty ids are never recorded', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('a204deeaedb27b580', 'running', T0)
+    l.record('', 'completed', T0)
+    expect(l.seenRecently('a204deeaedb27b580', T0 + 1)).toBe(false)
+    expect(l.seenRecently('', T0 + 1)).toBe(false)
+  })
+
+  it('records failed and killed as terminal (the CLI wakes the parent for those too)', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('aaa', 'failed', T0)
+    l.record('bbb', 'killed', T0)
+    expect(l.seenRecently('aaa', T0 + 1)).toBe(true)
+    expect(l.seenRecently('bbb', T0 + 1)).toBe(true)
+  })
+
+  it('prunes expired entries on write (bounded memory)', () => {
+    const l = new CliTaskNotificationLedger()
+    l.record('old', 'completed', T0)
+    l.record('new', 'completed', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 60_000)
+    // The old entry is both expired AND physically pruned; either way the
+    // observable contract is: it no longer suppresses.
+    expect(l.seenRecently('old', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 60_001)).toBe(false)
+    expect(l.seenRecently('new', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 60_001)).toBe(true)
+  })
+})
+
+describe('decideSubagentHandback × CLI task-notification dedup', () => {
+  // ── Outcome (a): one background completion → exactly ONE parent wake ──────
+  // RED-before/GREEN-after core: on pre-fix code this decision delivered a
+  // second wake; post-fix it is suppressed with the dedicated reason.
+  it('suppresses the handback when the CLI already woke the parent for this exact completion', () => {
+    const ledger = new CliTaskNotificationLedger()
+    // The CLI's wake for this completion (wake #1) is observed by the tail…
+    for (const ev of projectTranscriptLine(notifLine('a204deeaedb27b580', 'completed'))) {
+      if (ev.kind === 'task_notification') ledger.record(ev.taskId, ev.status, T0)
+    }
+    // …then the watcher's onFinish runs the decide gate (would-be wake #2).
+    const wakes: string[] = ['cli-task-notification'] // wake #1 already happened
+    const d = decideSubagentHandback({
+      ...base,
+      cliTaskNotificationSeen: ledger.seenRecently(base.jsonlAgentId, T0 + 2_000),
+    })
+    if (d.deliver) wakes.push('subagent_handback')
+    expect(d).toEqual({ deliver: false, reason: 'cli-task-notification' })
+    expect(wakes).toHaveLength(1) // exactly one parent wake, not two
+  })
+
+  it('suppresses a FAILED completion the CLI already reported, too', () => {
+    const d = decideSubagentHandback({
+      ...base,
+      outcome: 'failed',
+      cliTaskNotificationSeen: true,
+    })
+    expect(d).toEqual({ deliver: false, reason: 'cli-task-notification' })
+  })
+
+  // ── Outcome (b): fail-open — a handback with NO matching notification fires ─
+  it('fail-open: delivers when no notification was seen (flag false)', () => {
+    const d = decideSubagentHandback({ ...base, cliTaskNotificationSeen: false })
+    expect(d.deliver).toBe(true)
+    if (d.deliver) {
+      expect(d.chatId).toBe('777')
+      expect(d.inbound.meta?.source).toBe('subagent_handback')
+    }
+  })
+
+  it('fail-open: delivers when the flag is omitted entirely (older callers)', () => {
+    const d = decideSubagentHandback({ ...base })
+    expect(d.deliver).toBe(true)
+  })
+
+  it('fail-open end-to-end: a notification for a DIFFERENT agent id does not suppress', () => {
+    const ledger = new CliTaskNotificationLedger()
+    for (const ev of projectTranscriptLine(notifLine('a999999999999999', 'completed'))) {
+      if (ev.kind === 'task_notification') ledger.record(ev.taskId, ev.status, T0)
+    }
+    const d = decideSubagentHandback({
+      ...base,
+      cliTaskNotificationSeen: ledger.seenRecently(base.jsonlAgentId, T0 + 2_000),
+    })
+    expect(d.deliver).toBe(true)
+  })
+
+  it('fail-open end-to-end: an EXPIRED notification does not suppress', () => {
+    const ledger = new CliTaskNotificationLedger()
+    ledger.record(base.jsonlAgentId, 'completed', T0)
+    const d = decideSubagentHandback({
+      ...base,
+      cliTaskNotificationSeen: ledger.seenRecently(
+        base.jsonlAgentId,
+        T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 1,
+      ),
+    })
+    expect(d.deliver).toBe(true)
+  })
+
+  it('gate ordering: foreground/outcome/env gates still win over the dedup reason', () => {
+    expect(
+      decideSubagentHandback({ ...base, isBackground: false, cliTaskNotificationSeen: true }),
+    ).toEqual({ deliver: false, reason: 'foreground' })
+    expect(
+      decideSubagentHandback({ ...base, outcome: 'orphan', cliTaskNotificationSeen: true }),
+    ).toEqual({ deliver: false, reason: 'outcome-not-terminal' })
+    expect(
+      decideSubagentHandback({ ...base, handbackEnvValue: '0', cliTaskNotificationSeen: true }),
+    ).toEqual({ deliver: false, reason: 'env-disabled' })
+  })
+})
+
+// ── Outcome (c): the task-notification keeps working as a liveness signal ────
+// Recording into the dedup ledger is an ADDITIVE read of the same event; the
+// background-shell-liveness consumer must still see the shell as DEAD.
+describe('task_notification still drives background-shell liveness (not swallowed)', () => {
+  it('one projected event feeds BOTH the liveness registry and the dedup ledger', () => {
+    const dead: string[] = []
+    const alive: string[] = []
+    const registry = {
+      noteBackgroundShellAlive: (_k: string, id: string) => void alive.push(id),
+      noteBackgroundShellDead: (_k: string, id: string) => void dead.push(id),
+    }
+    const ledger = new CliTaskNotificationLedger()
+    const events = projectTranscriptLine(notifLine('bxa4sv3dq', 'completed'))
+    expect(events).toHaveLength(1)
+    for (const ev of events) {
+      applyBackgroundShellLiveness(registry, 'chat:-', ev)
+      if (ev.kind === 'task_notification') ledger.record(ev.taskId, ev.status, T0)
+    }
+    expect(dead).toEqual(['bxa4sv3dq']) // liveness signal intact
+    expect(ledger.seenRecently('bxa4sv3dq', T0 + 1)).toBe(true) // dedup recorded
+    expect(alive).toEqual([])
+  })
+
+  it('a foreground-shell task-notification with NO handback in flight changes nothing else', () => {
+    // A background Bash shell death has no subagent-watcher onFinish — the
+    // ledger entry simply ages out; nothing consults it for shells.
+    const ledger = new CliTaskNotificationLedger()
+    ledger.record('bxa4sv3dq', 'completed', T0)
+    expect(ledger.seenRecently('bxa4sv3dq', T0 + TASK_NOTIFICATION_DEDUP_TTL_MS + 1)).toBe(false)
+  })
+})
+
+// ── Wiring pins — the gateway must actually consult the ledger ───────────────
+// gateway.ts is not unit-instantiable; pin the two wiring sites statically
+// (repo precedent: subagent-handback-marker.test.ts scans gateway source).
+describe('gateway wiring pins', () => {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const gatewaySrc = readFileSync(join(here, '..', 'gateway', 'gateway.ts'), 'utf8')
+
+  it('onSessionEvent records terminal task-notifications into the ledger', () => {
+    expect(gatewaySrc).toMatch(
+      /if \(ev\.kind === 'task_notification'\) cliTaskNotifLedger\.record\(ev\.taskId, ev\.status, Date\.now\(\)\)/,
+    )
+  })
+
+  it('the onFinish decide callsite passes the fail-open seenRecently read', () => {
+    expect(gatewaySrc).toMatch(
+      /cliTaskNotificationSeen: cliTaskNotifLedger\.seenRecently\(agentId, Date\.now\(\)\)/,
+    )
+  })
+})

package/telegram-plugin/tests/ipc-client-reconnect-rejection.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Regression test for fleet-audit B2 — the bridge's background reconnect
+ * loop must never surface a failed connect attempt as a process-level
+ * unhandledRejection.
+ *
+ * Live evidence (kdogg, 2026-07-17):
+ *   bridge-crash.log: `unhandledRejection … Error: Failed to connect
+ *     | at doConnect (dist/server.js:24188) …`
+ *
+ * Mechanism: `scheduleReconnect()`'s timer invoked `doConnect()` without a
+ * rejection handler. `doConnect` returns a promise that REJECTS whenever
+ * the `Bun.connect` attempt fails (gateway restarting out from under a
+ * long-lived bridge — the exact window every planned `docker restart`
+ * opens). The initial-connect call sites attach a `.catch`; the retry
+ * timer did not, so every failed background retry escaped as an
+ * unhandledRejection. Pre-#3033 that killed the bridge process outright
+ * (Claude Code never respawns a dead MCP server → mute agent); post-#3033
+ * it still spams `bridge-crash.log` with pseudo-crash breadcrumbs and
+ * leans on a global process handler for survival.
+ *
+ * Outcome asserted: with nothing listening on the socket path, the client
+ * runs through its initial attempt AND several background retries without
+ * a single unhandledRejection reaching the process. RED without the
+ * `.catch` in scheduleReconnect's timer, GREEN with it.
+ *
+ * Run with: bun test telegram-plugin/tests/ipc-client-reconnect-rejection.test.ts
+ */
+import { describe, it, expect } from "bun:test";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createIpcClient } from "../bridge/ipc-client.js";
+
+describe("ipc-client background reconnect", () => {
+  it("a failed reconnect attempt never escapes as a process-level unhandledRejection", async () => {
+    const captured: unknown[] = [];
+    const onUnhandled = (err: unknown) => {
+      captured.push(err);
+    };
+    process.on("unhandledRejection", onUnhandled);
+
+    // Nothing listens here — every connect attempt fails, exercising both
+    // the (already-handled) initial attempt and the retry-timer path.
+    const socketPath = join(tmpdir(), `ipc-b2-${crypto.randomUUID()}.sock`);
+
+    const handle = await createIpcClient({
+      socketPath,
+      agentName: "b2-test",
+      onInbound: () => {},
+      onPermission: () => {},
+      onStatus: () => {},
+      log: () => {},
+      reconnectDelayMs: 15,
+      maxReconnectDelayMs: 30,
+    });
+
+    try {
+      // Long enough for several background retries (15ms, 30ms, 30ms, …)
+      // plus the macrotask on which unhandledRejection is delivered.
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    } finally {
+      handle.close();
+      // Give any in-flight rejection its delivery tick before detaching.
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      process.off("unhandledRejection", onUnhandled);
+    }
+
+    expect(handle.isConnected()).toBe(false);
+    expect(captured).toEqual([]);
+  });
+});

package/telegram-plugin/tests/narrative-lane-golden.test.ts

@@ -282,6 +282,92 @@ describe('narrative-lane golden — clearActivitySummary finalize', () => {
   })
 })
 
+// ── #4348 — silent-sentinel activity card is SUPPRESSED (deleted, not finalized) ─
+// A turn whose entire user-facing outcome is a bare NO_REPLY / HEARTBEAT_OK
+// (the sentinel-reply-guard dropped the sentinel-only reply, or the flush net
+// classified the captured text as silent) must leave NO visible telemetry card
+// in the chat — most visibly on the forced-synthesis handback turns a
+// background sub-agent injects. A real reply's card must still finalize.
+describe('narrative-lane golden — silent-sentinel card suppression (#4348)', () => {
+  // Open the feed card on a fresh (working) turn FIRST — the card-open gate
+  // (mayOpenActivityCard) won't open one once the answer is already delivered —
+  // then stamp the turn's terminal outcome, exactly as the real turn does:
+  // the card opens mid-work, and lastReplyText / finalAnswerEverDelivered are
+  // only known at turn end.
+  async function openThenClear(over: Partial<CurrentTurn>) {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane)
+    lane.showNarrativeStep(turn, 'Doing the work now')
+    await turn.activityInFlight
+    const cardId = turn.activityMessageId
+    expect(cardId).not.toBeNull()
+    Object.assign(turn, over)
+    lane.clearActivitySummary(turn)
+    await settle()
+    return { calls, cardId, turn }
+  }
+
+  it('reply("NO_REPLY") turn: DELETES the card, never edits a done record', async () => {
+    // The guard drops the sentinel-only reply before chat, but the blocked
+    // tool_use still stamps lastReplyText — the exact `✓ NO_REPLY` noise card.
+    const { calls, cardId, turn } = await openThenClear({
+      replyCalled: true,
+      lastReplyText: 'NO_REPLY',
+      finalAnswerEverDelivered: false,
+    })
+    expect(calls.filter((c) => c.method === 'deleteMessage' && c.message_id === cardId)).toHaveLength(1)
+    expect(calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId)).toHaveLength(0)
+    expect(turn.activityMessageId).toBeNull()
+  })
+
+  it('HEARTBEAT_OK. (trailing punctuation, case-insensitive) is also suppressed', async () => {
+    const { calls, cardId } = await openThenClear({
+      replyCalled: true,
+      lastReplyText: 'heartbeat_ok.',
+      finalAnswerEverDelivered: false,
+    })
+    expect(calls.filter((c) => c.method === 'deleteMessage' && c.message_id === cardId)).toHaveLength(1)
+    expect(calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId)).toHaveLength(0)
+  })
+
+  it('flush path (no reply): prose + trailing NO_REPLY (H6/#2053) is suppressed', async () => {
+    const { calls, cardId } = await openThenClear({
+      replyCalled: false,
+      lastReplyText: '',
+      capturedText: ["Nothing actionable in today's digest.", 'NO_REPLY'],
+      finalAnswerEverDelivered: false,
+    })
+    expect(calls.filter((c) => c.method === 'deleteMessage' && c.message_id === cardId)).toHaveLength(1)
+    expect(calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId)).toHaveLength(0)
+  })
+
+  it('normal reply turn: still FINALIZES the card (edit, no delete)', async () => {
+    // The guarantee the fix must not break: a real answer keeps its record.
+    const { calls, cardId, turn } = await openThenClear({
+      replyCalled: true,
+      lastReplyText: 'The fix is deployed and the tests are green.',
+      finalAnswerEverDelivered: true,
+    })
+    expect(calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId).length)
+      .toBeGreaterThanOrEqual(1)
+    expect(calls.filter((c) => c.method === 'deleteMessage')).toHaveLength(0)
+    expect(turn.activityMessageId).toBeNull()
+  })
+
+  it('reply "prose\\nNO_REPLY" that WAS delivered (finalAnswerEverDelivered) keeps its card', async () => {
+    // The guard does NOT drop a reply with non-marker content, so its prose
+    // reached chat — endsWithSilentMarker must NOT suppress a delivered reply.
+    const { calls, cardId } = await openThenClear({
+      replyCalled: true,
+      lastReplyText: 'Here is the full answer to your question.\nNO_REPLY',
+      finalAnswerEverDelivered: true,
+    })
+    expect(calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId).length)
+      .toBeGreaterThanOrEqual(1)
+    expect(calls.filter((c) => c.method === 'deleteMessage')).toHaveLength(0)
+  })
+})
+
 // ── THREE-MODULE cross-surface dedup (Amendment 1) ────────────────────────
 // The REAL P4-A handleSessionEvent turn-flush, with the REAL P4-B lane wired
 // into its deps, records the delivered answer into ONE OutboundDedupCache;

package/telegram-plugin/tests/queued-card-surface.test.ts

@@ -260,3 +260,69 @@ describe('Part B — handback-while-busy: exactly one card, never a frozen "Queu
     expect(rec.edits).toHaveLength(0)
   })
 })
+
+describe('Part B — synthetic (fabricated) message ids never 400 the queued card', () => {
+  /** Recording bot that enforces the REAL Telegram Bot API contract on
+   *  `reply_parameters.message_id`: anything non-integer or beyond signed int32
+   *  is hard-rejected with the exact 400 the live gateway hit
+   *  (gateway-supervisor.log 2026-08-04, msg=1785846295635) — BEFORE recording,
+   *  exactly like the wire call. `allow_sending_without_reply` does not bypass
+   *  the range check, only the message-not-found case. */
+  function withTelegramStrictBot(h: Harness) {
+    const sends: SendRec[] = []
+    let nextId = 9001
+    ;(h.deps as unknown as { bot: unknown }).bot = {
+      api: {
+        sendRichMessage: async (chatId: string, msg: { markdown: string }, opts: Record<string, unknown>) => {
+          const rp = opts.reply_parameters as { message_id?: unknown } | undefined
+          if (rp != null) {
+            const mid = rp.message_id
+            if (typeof mid !== 'number' || !Number.isInteger(mid) || mid <= 0 || mid >= 2 ** 31) {
+              throw new Error(
+                `Call to 'sendRichMessage' failed! (400: Bad Request: field "message_id" must be a valid Number)`,
+              )
+            }
+          }
+          const id = nextId++
+          sends.push({ chatId, markdown: msg.markdown, opts, id })
+          return { message_id: id }
+        },
+        editMessageText: async () => true,
+        deleteMessage: async () => true,
+      },
+    }
+    return { sends }
+  }
+
+  it('sends the queued card UNANCHORED (no 400) when the parked message id is a fabricated Date.now() timestamp', async () => {
+    const h = makeHarness()
+    const rec = withTelegramStrictBot(h)
+
+    // Turn A mints on an idle session.
+    handleSessionEvent(h.deps, enqueue('501'))
+    expect(rec.sends).toHaveLength(0)
+
+    // A synthetic enqueue (subagent handback / boot resume) parks mid-turn with
+    // a fabricated ms-timestamp message id — finite, but NOT a Telegram id.
+    handleSessionEvent(h.deps, enqueue('1785846295635', 'handback: worker done'))
+    await settle()
+    expect(__parkedTurnStartCountForTest()).toBe(1)
+
+    // The card SENT (no 400 — RED on the pre-fix guard, which forwarded the
+    // 13-digit id into reply_parameters and lost the whole card)…
+    expect(rec.sends).toHaveLength(1)
+    // …and it sent WITHOUT reply-linkage: no reply_parameters at all.
+    expect(rec.sends[0]!.opts.reply_parameters).toBeUndefined()
+  })
+
+  it('still reply-anchors when the parked message id is a real Telegram id', async () => {
+    const h = makeHarness()
+    const rec = withTelegramStrictBot(h)
+
+    handleSessionEvent(h.deps, enqueue('501'))
+    handleSessionEvent(h.deps, enqueue('502', 'real mid-turn message'))
+    await settle()
+    expect(rec.sends).toHaveLength(1)
+    expect((rec.sends[0]!.opts.reply_parameters as { message_id: number }).message_id).toBe(502)
+  })
+})