switchroom 0.13.33 → 0.13.36

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -1,45 +1,65 @@
 #!/usr/bin/env node
 /**
- * Stop hook — auto-interrupt for silent-end turns.
+ * Stop hook — deterministic guardrail that a turn ended with a final
+ * reply tool call.
  *
- * When a Claude Code session ends without the agent delivering a final
- * answer to the user, the Telegram gateway writes a state file at
- * $TELEGRAM_STATE_DIR/silent-end-pending.json. This hook reads that file and,
- * if a first-time silent-end is detected (retryCount === 0), returns a
- * decision:block to re-prompt the agent instead of letting the session close.
+ * Closes #1775. The pre-fix hook depended on the gateway's
+ * `$TELEGRAM_STATE_DIR/silent-end-pending.json` file as its block/allow
+ * signal. That file is written by the gateway's `turn_end` handler,
+ * which runs DOWNSTREAM of session-tail processing the `turn_duration`
+ * JSONL line — and the JSONL line is itself written AFTER
+ * `stop_hook_summary`. Live evidence on clerk (12 correlated samples,
+ * 2026-05-25): state file lands ~175ms (range 111-287ms) after the
+ * hook fires. The race is structurally always lost. The hook never
+ * saw its OWN turn's silent-end signal; the mechanism only worked
+ * one-turn-delayed via stale state from prior turns.
  *
- * #1664 — "no final answer delivered" covers two cases: (a) the turn ended
- * with zero outbound (the original case), and (b) the model sent only an
- * interim ack via reply/stream_reply but left its real answer as plain
- * transcript text, which the gateway renders into an ephemeral draft and
- * never finalizes. The re-prompt below tells the model to send its answer
- * through the reply tool, or reply NO_REPLY if it genuinely has nothing to
- * add / already delivered.
+ * Fix: the hook now reads `transcript_path` from its event input
+ * (Claude Code flushes assistant content to the JSONL before firing
+ * Stop hooks — verified empirically because `secret-scrub-stop.mjs`
+ * already reads `transcript_path` at Stop time successfully) and
+ * scans the CURRENT turn's tool_use entries for a qualifying reply.
+ * No race window — the decision is derived from the transcript that
+ * is on disk at the moment the hook runs.
  *
- * On the second silent-end (retryCount >= MAX_RETRIES), the hook allows the
- * stop. The gateway's turn-end path (recordSilentTurnEnd in silent-end.ts)
- * detects the exhausted re-prompt and delivers a user-facing fallback
- * message so the turn never silently vanishes (#1161).
+ * The gateway's state file is preserved for retry-count
+ * bookkeeping (the 1-retry budget + `silent-end.ts` user-facing
+ * fallback chain). The SIGNAL changes; the budget mechanism does
+ * not.
+ *
+ * #1664 — "no final answer delivered" covers two cases: (a) the turn
+ * ended with zero outbound, and (b) the model sent only an interim
+ * ack via reply/stream_reply but left its real answer as plain
+ * transcript text. The transcript scan handles BOTH cleanly:
+ *  - case (a) → no tool_use of reply tools in the turn → block
+ *  - case (b) → tool_use present but `isFinalAnswerReply` returns
+ *    false on every call → block
  *
  * Carve-outs preserved:
- *   - wasAutonomous=true turns: the gateway never writes a state file for
- *     these (no reply expected on autonomous wakeup turns).
- *   - Turns with running sub-agents: the gateway only fires onSilentEnd after
- *     all sub-agents have finished (same gate as completeTurnFully).
+ *   - NO_REPLY / HEARTBEAT_OK silent markers (`gateway.ts:6692`) → allow
+ *   - Sub-agent (`isSidechain:true`) lines → skipped (the parent's
+ *     reply obligation is not satisfied by a sub-agent's reply tool)
+ *   - Cron-fired turns DO carry a topic chat and reach the silent-end
+ *     path (`silent-end.ts:219-224`) — they must emit NO_REPLY
+ *     explicitly, not be specially exempted here
  *
  * Protocol:
  *   Input:  JSON on stdin — { session_id, transcript_path, ... }
  *   Output: exit 0 + empty stdout → allow stop.
  *           exit 0 + JSON stdout { decision: "block", reason: "..." } → re-prompt.
  *
- * Fail-open on any error — if we can't read/write the state file, allow stop
- * rather than blocking every session close.
+ * Fail-open on every error path (no transcript / unreadable / no
+ * turn-start anchor / state-file write failure) — blocking on a
+ * malfunction is worse than the original race because it loops
+ * every session close.
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 
+import { scanTurnForFinalReply } from './silent-end-scan.mjs'
+
 // MUST stay in sync with SILENT_END_MAX_RETRIES in telegram-plugin/silent-end.ts
 // (this hook is a standalone .mjs and can't import the TS module).
 const MAX_RETRIES = 1
@@ -60,52 +80,109 @@ function main() {
   const raw = readStdin().trim()
   if (!raw) process.exit(0)
 
-  // Parse the Stop hook input (fail-open)
-  let _event
+  let event
   try {
-    _event = JSON.parse(raw)
+    event = JSON.parse(raw)
   } catch {
     process.exit(0)
   }
 
-  const stateDir = getStateDir()
-  const statePath = join(stateDir, 'silent-end-pending.json')
-
-  if (!existsSync(statePath)) {
-    // No silent-end pending — normal completion, allow stop.
+  const transcriptPath = event?.transcript_path
+  if (!transcriptPath || typeof transcriptPath !== 'string' || !existsSync(transcriptPath)) {
+    // No transcript → can't scan → fail-open. Pre-fix the hook fell
+    // back to the state-file signal here; we deliberately do NOT do
+    // that anymore because the state-file signal is structurally
+    // stale (race-loses every time).
     process.exit(0)
   }
 
-  let state
+  let jsonl
   try {
-    state = JSON.parse(readFileSync(statePath, 'utf8'))
-  } catch {
-    // Corrupt state file — fail-open, allow stop.
+    jsonl = readFileSync(transcriptPath, 'utf8')
+  } catch (err) {
+    process.stderr.write(
+      `[silent-end-interrupt] failed to read transcript ${transcriptPath}: ${err.message}\n`,
+    )
+    process.exit(0)
+  }
+
+  const decision = scanTurnForFinalReply(jsonl)
+
+  // 'allow' (qualifying reply or silent marker) and 'unknown' (no
+  // turn-start anchor in the scanned range — session restart,
+  // compaction, etc.) both allow the stop.
+  if (decision.decided !== 'block') {
     process.exit(0)
   }
 
+  // Retry-budget bookkeeping. The state file is read/written here
+  // as a counter ONLY — the decision was already made from the
+  // transcript above. If a state file exists from a prior turn that
+  // never got cleared (clean shutdown not perfect), this read still
+  // works; if absent, retryCount defaults to 0.
+  const stateDir = getStateDir()
+  const statePath = join(stateDir, 'silent-end-pending.json')
+
+  let state = {}
+  if (existsSync(statePath)) {
+    try {
+      state = JSON.parse(readFileSync(statePath, 'utf8'))
+    } catch {
+      // Corrupt — treat as fresh.
+      state = {}
+    }
+  }
+
   const retryCount = typeof state.retryCount === 'number' ? state.retryCount : 0
 
   if (retryCount >= MAX_RETRIES) {
-    // Retry exhausted — let the session end so the gateway can render the
-    // warning card.
+    // Budget spent. Let the session end so the gateway's
+    // `silent-end.ts:recordUndeliveredTurnEnd` path delivers the
+    // user-facing fallback (the gateway sees `silentEnd.exhausted ===
+    // true` and posts SILENT_END_FALLBACK_TEXT).
     process.stderr.write(
       `[silent-end-interrupt] retry exhausted (retryCount=${retryCount} >= MAX_RETRIES=${MAX_RETRIES}) — allowing stop\n`,
     )
     process.exit(0)
   }
 
-  // First silent-end: increment retryCount and block to re-prompt the agent.
+  // Persist incremented retry count so a follow-up Stop in the same
+  // chat hits the exhaustion branch above. The gateway's existing
+  // clearSilentEndState path (`silent-end.ts:155-180`) handles
+  // resetting on successful delivery.
+  //
+  // CRITICAL: include `turnKey` (and the supporting `chatId` / `threadId`)
+  // when the scan derived them from the enqueue envelope. The gateway's
+  // `recordSilentTurnEnd` (`silent-end.ts:114`) preserves retryCount
+  // ONLY when `prev.turnKey === args.turnKey`. Without turnKey here,
+  // the gateway's later write (~175ms after the hook) sees `prev.turnKey
+  // === undefined`, fails the match, and resets retryCount to 0 — which
+  // doubles the effective re-prompt budget vs. the design. With turnKey
+  // present (same chatKey shape the gateway uses), the match succeeds
+  // and the budget is honored.
+  const nextState = {
+    ...state,
+    retryCount: retryCount + 1,
+    timestamp: Date.now(),
+  }
+  if (decision.turnKey) {
+    nextState.turnKey = decision.turnKey
+    nextState.chatId = decision.chatId
+    if (decision.threadId != null) {
+      nextState.threadId = decision.threadId
+    }
+  }
   try {
-    writeFileSync(statePath, JSON.stringify({ ...state, retryCount: retryCount + 1 }), 'utf8')
+    writeFileSync(statePath, JSON.stringify(nextState), 'utf8')
   } catch (err) {
     process.stderr.write(`[silent-end-interrupt] failed to update state file: ${err.message}\n`)
-    // Fail-open: allow stop rather than blocking forever.
+    // Fail-open: a retry-count write failure shouldn't loop the
+    // session forever.
     process.exit(0)
   }
 
   process.stderr.write(
-    `[silent-end-interrupt] blocking stop to re-prompt agent (chatId=${state.chatId ?? '?'} retryCount was ${retryCount})\n`,
+    `[silent-end-interrupt] blocking stop to re-prompt agent (transcriptScan=${decision.reason} retryCount was ${retryCount})\n`,
   )
 
   process.stdout.write(

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -0,0 +1,190 @@
+/**
+ * Pure helpers for the silent-end Stop hook — extracted so unit tests
+ * can exercise the scan logic without spawning the .mjs subprocess.
+ *
+ * Closes the race documented in #1775: the gateway writes
+ * `silent-end-pending.json` only AFTER the Stop hook fires (the
+ * gateway's `turn_end` handler runs downstream of the `turn_duration`
+ * JSONL line, which is itself written AFTER `stop_hook_summary`). The
+ * fix: the hook stops depending on the gateway's state file as its
+ * SIGNAL and instead scans `transcript_path` directly. Claude Code
+ * flushes assistant content to the JSONL before firing Stop hooks
+ * (verified empirically: `telegram-plugin/hooks/secret-scrub-stop.mjs`
+ * already reads `transcript_path` at Stop time successfully in
+ * production), so a transcript scan is race-free.
+ *
+ * The state file is preserved for retry-count bookkeeping (the
+ * 1-retry budget + user-facing fallback chain in `silent-end.ts`),
+ * but it is no longer the signal that drives the block/allow
+ * decision.
+ *
+ * Same `isFinalAnswerReply` predicate the gateway applies at every
+ * reply callsite (`final-answer-detect.ts:78-83`):
+ *   done===true  OR  !disableNotification  OR  text.length >= 200
+ *
+ * Plus the `NO_REPLY` / `HEARTBEAT_OK` silent-marker carve-out — if
+ * the model explicitly emitted that sentinel through the reply tool,
+ * the turn is "intentionally silent" and the hook must allow stop.
+ *
+ * Sidechain filter: sub-agent (Task) tool_use lines that leak into
+ * the parent transcript with `isSidechain:true` are skipped. The
+ * sub-agent's OWN replies live in `subagents/agent-<id>.jsonl` (per
+ * `session-tail.ts:277-281`) and never count toward the parent's
+ * delivery obligation.
+ */
+
+const REPLY_TOOLS = new Set([
+  'mcp__switchroom-telegram__reply',
+  'mcp__switchroom-telegram__stream_reply',
+])
+const FINAL_ANSWER_MIN_CHARS = 200
+// Match the gateway's silent-marker classifier (gateway.ts:6692 — the
+// `isSilentFlushMarker` helper accepts trailing punctuation + case
+// variants like "NO_REPLY." / "no_reply").
+const SILENT_MARKER_RE = /^(NO_REPLY|HEARTBEAT_OK)[\s.!?]*$/i
+
+/**
+ * Predicate ported from `telegram-plugin/final-answer-detect.ts:78-83`.
+ * Kept in this .mjs so the hook is fully self-contained (no TS import).
+ * If the TS file ever diverges, the test fixture below (T14) catches it.
+ */
+export function isFinalAnswerReply({ text, disableNotification, done }) {
+  if (done === true) return true
+  if (!disableNotification) return true
+  if ((text ?? '').length >= FINAL_ANSWER_MIN_CHARS) return true
+  return false
+}
+
+/**
+ * Parse a `<channel ...>` envelope's chat_id and message_thread_id
+ * attributes. Same shape session-tail.ts:125-140 uses to derive these
+ * from the enqueue line's `content` string.
+ *
+ * Returns `null` if the envelope can't be parsed (caller treats as
+ * "no turn key derivable" and writes a turnKey-less state file —
+ * still functional, just loses retry-count preservation across the
+ * hook→gateway write order).
+ *
+ * @param {string} content
+ * @returns {{ chatId: string | null, threadId: number | null }}
+ */
+function parseChannelEnvelope(content) {
+  if (typeof content !== 'string') return { chatId: null, threadId: null }
+  const chatMatch = content.match(/chat_id="([^"]+)"/)
+  const threadMatch = content.match(/message_thread_id="([^"]+)"/)
+  const threadRaw = threadMatch ? Number(threadMatch[1]) : NaN
+  return {
+    chatId: chatMatch ? chatMatch[1] : null,
+    threadId: Number.isFinite(threadRaw) && threadRaw !== 0 ? threadRaw : null,
+  }
+}
+
+/**
+ * Build the turnKey the gateway will use for `recordSilentTurnEnd`'s
+ * write of the state file. Matches `chatKey(chatId, threadId)` shape
+ * at `gateway/chat-key.ts:46`: `${chatId}:${threadId || '_'}`.
+ *
+ * @param {string} chatId
+ * @param {number | null} threadId
+ * @returns {string}
+ */
+function buildTurnKey(chatId, threadId) {
+  return `${chatId}:${threadId == null || threadId === 0 ? '_' : threadId}`
+}
+
+/**
+ * Scan a JSONL transcript and decide whether the current turn ended
+ * with a final reply delivered.
+ *
+ * Returns:
+ *   { decided: 'allow', reason }    — qualifying reply OR silent marker found
+ *   { decided: 'block', reason, turnKey?, chatId?, threadId? }
+ *                                   — turn-start found, no qualifying reply,
+ *                                     no marker. `turnKey`/`chatId`/`threadId`
+ *                                     populated from the enqueue's channel
+ *                                     envelope so the hook can write a state
+ *                                     file shape that matches what the
+ *                                     gateway's `recordSilentTurnEnd` would
+ *                                     write — keeping the retry-count
+ *                                     preservation gate at
+ *                                     `silent-end.ts:114` happy when the
+ *                                     gateway's later write reads back the
+ *                                     hook's state.
+ *   { decided: 'unknown', reason }  — couldn't locate turn-start; caller fail-open
+ *
+ * Turn-start anchor: the most recent `queue-operation`/`enqueue` line
+ * (the inbound message the gateway pushed onto the session). For
+ * queued mid-turn messages (multiple `enqueue` lines per "turn"), we
+ * anchor on the LAST enqueue — the model is responsible for at least
+ * the most recent message. (Mild over-allow risk on the multi-enqueue
+ * edge case where the model replied combined ahead of the second
+ * enqueue's append; accepted residual.)
+ *
+ * @param {string} jsonl
+ * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, chatId?: string, threadId?: number | null }}
+ */
+export function scanTurnForFinalReply(jsonl) {
+  const lines = jsonl.split('\n')
+
+  // 1. Walk backward to most-recent queue-operation/enqueue.
+  let startIdx = -1
+  let envelope = { chatId: null, threadId: null }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line || line[0] !== '{') continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    if (obj?.type === 'queue-operation' && obj.operation === 'enqueue') {
+      startIdx = i
+      envelope = parseChannelEnvelope(obj.content)
+      break
+    }
+  }
+  if (startIdx < 0) {
+    return { decided: 'unknown', reason: 'no-turn-start' }
+  }
+
+  // 2. Scan forward from the turn start; look for qualifying tool_use
+  //    or silent-marker text.
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line || line[0] !== '{') continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    // Skip sub-agent contamination (defensive — sub-agent lines should
+    // be in a separate transcript file, but `isSidechain:true` is the
+    // documented marker if they leak).
+    if (obj?.isSidechain === true) continue
+    if (obj?.type !== 'assistant') continue
+    const content = obj?.message?.content
+    if (!Array.isArray(content)) continue
+    for (const c of content) {
+      if (c?.type !== 'tool_use') continue
+      if (!REPLY_TOOLS.has(c.name)) continue
+      const input = c.input ?? {}
+      const text = String(input.text ?? '')
+      // Silent-marker carve-out: the operator explicitly signaled
+      // "intentionally silent" (cron HEARTBEAT_OK, model-driven
+      // NO_REPLY). Don't block — same posture as the gateway's
+      // silent-marker suppression at gateway.ts:6692.
+      if (SILENT_MARKER_RE.test(text.trim())) {
+        return { decided: 'allow', reason: 'silent-marker' }
+      }
+      if (isFinalAnswerReply({
+        text,
+        disableNotification: input.disable_notification === true,
+        done: input.done === true,
+      })) {
+        return { decided: 'allow', reason: 'final-reply' }
+      }
+    }
+  }
+
+  const block = { decided: 'block', reason: 'no-final-reply' }
+  if (envelope.chatId) {
+    block.chatId = envelope.chatId
+    block.threadId = envelope.threadId
+    block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+  }
+  return block
+}

package/telegram-plugin/pending-work-progress.ts

@@ -112,6 +112,20 @@ export interface PendingProgressDeps {
   nowMs?: () => number
   /** Optional poll interval override for tests. */
   pollIntervalMs?: number
+  /**
+   * Defense-in-depth (#1760). When provided, returns the gateway's
+   * `activeTurnStartedAt` epoch ms for this chat key, or undefined if no
+   * turn is currently active. The ticker uses this on every fire to detect
+   * a stale ambient: if a NEWER turn has started (epoch > our activatedAt)
+   * the prior turn's cross-turn pending-progress is by definition orphaned
+   * (the turn_end teardown was missed, e.g. SDK event dropped) and the
+   * ticker self-terminates instead of editing a stale anchor. Converts the
+   * #1760 failure mode from "stuck forever" to "at most one stale tick."
+   *
+   * Defaults to undefined — preserves prior behaviour for tests that
+   * exercise the ticker without a gateway.
+   */
+  isActiveTurnNewerThan?: (key: string, activatedAt: number) => boolean
 }
 
 interface State {
@@ -276,7 +290,14 @@ export function noteTurnEnd(key: string): void {
  */
 export function clearPending(
   key: string,
-  reason: 'inbound' | 'handback' | 'progress' | 'timeout' | 'manual',
+  reason:
+    | 'inbound'
+    | 'handback'
+    | 'progress'
+    | 'timeout'
+    | 'manual'
+    | 'reply_finalize'
+    | 'stale_turn',
 ): void {
   if (!stateByKey.has(key)) return
   const s = stateByKey.get(key)!
@@ -337,6 +358,21 @@ function tick(now: number): void {
       continue
     }
 
+    // #1760 defense-in-depth: if a newer turn is currently active for
+    // this chat, the prior turn's cross-turn pending-progress is stale
+    // (the canonical teardown — turn_end or the next turn's reply-
+    // finalize — was missed). Drop the timer instead of editing the
+    // old anchor; the new turn will manage its own anchor via the
+    // regular noteOutbound / noteTurnEnd path. Converts "stuck forever"
+    // (the live #1760 evidence) into "at most one stale tick."
+    if (
+      activeDeps.isActiveTurnNewerThan != null
+      && activeDeps.isActiveTurnNewerThan(key, s.activatedAt)
+    ) {
+      clearPending(key, 'stale_turn')
+      continue
+    }
+
     const sinceEdit = s.lastEditAt == null ? 0 : now - s.lastEditAt
     if (sinceEdit < EDIT_INTERVAL_MS) continue
 

package/telegram-plugin/tests/boot-clears-clean-shutdown-marker.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Regression guard for the marker-stale crash banner class.
+ *
+ * Pre-2026-05-25 the boot path read the clean-shutdown marker but
+ * never cleared it. A marker from a graceful shutdown 11 hours ago
+ * sat on disk untouched; subsequent boots after an unhandledRejection
+ * crash (which explicitly SKIPS writing a new marker, per
+ * gateway.ts:15107) read the stale marker, classified the age as
+ * >5min, and fired `boot.clean_shutdown_marker_stale age=39976s` →
+ * `reason=crash` → `agent-crashed` operator-event banner posted to
+ * the user's chat.
+ *
+ * That misclassified the user-visible state ("clerk seems to be
+ * crashing") because the banner detail included the stale-marker
+ * artifact rather than just naming the actual crash.
+ *
+ * Fix: clear the marker after every successful boot reads it. The
+ * marker now describes the IMMEDIATELY PRECEDING shutdown only;
+ * a subsequent crash with no marker write leaves an empty marker
+ * file, and boot-reason.ts:84 correctly classifies via the
+ * sessionMarker fallback.
+ *
+ * The gateway IIFE is too entangled to instantiate in-process; this
+ * is a source-level pin matching the pattern used by
+ * `reply-terminal-reaction.test.ts` and `buffer-gate-broadened.test.ts`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('boot path clears the clean-shutdown marker after reading it', () => {
+  it('imports clearCleanShutdownMarker (no longer the "intentionally not imported" comment)', () => {
+    // Pre-fix the import block had a `clearCleanShutdownMarker is
+    // intentionally NOT imported here` block-comment, with a rationale
+    // that was wrong for the unhandledRejection edge case. If a future
+    // commit re-removes the import (and re-adds the wrong comment),
+    // this test trips.
+    expect(gatewaySrc).toMatch(/^\s*clearCleanShutdownMarker,$/m)
+    // The old "intentionally NOT imported" comment must be gone.
+    expect(gatewaySrc).not.toMatch(/clearCleanShutdownMarker is intentionally NOT imported/)
+  })
+
+  it('calls clearCleanShutdownMarker inside the marker-read block at boot', () => {
+    // Slice the marker-read block (between the boot.clean_shutdown_*
+    // diagnostic logs and the next `if (marker)` line). The clear call
+    // MUST appear inside this block, not later in the boot flow —
+    // future readers should see the read and clear together.
+    const anchor = gatewaySrc.indexOf('boot.clean_shutdown_detected')
+    expect(anchor).toBeGreaterThan(-1)
+    const slice = gatewaySrc.slice(anchor, anchor + 4000)
+    expect(slice).toMatch(/clearCleanShutdownMarker\(GATEWAY_CLEAN_SHUTDOWN_MARKER_PATH\)/)
+  })
+
+  it('clear comment explains the unhandledRejection edge case', () => {
+    // Future maintainers MUST understand why the clear is here.
+    // The comment block above the call references the
+    // unhandledRejection / "crash path" semantics so the next
+    // engineer doesn't remove it as cleanup.
+    const callIdx = gatewaySrc.indexOf(
+      'clearCleanShutdownMarker(GATEWAY_CLEAN_SHUTDOWN_MARKER_PATH)',
+    )
+    expect(callIdx).toBeGreaterThan(-1)
+    // The 1500 chars immediately before the call should mention the
+    // failure mode this fixes (the comment block sits right above
+    // the call and is ~1100 chars at current writing).
+    const lead = gatewaySrc.slice(Math.max(0, callIdx - 1500), callIdx)
+    expect(lead).toMatch(/unhandledRejection|crash path/)
+  })
+})

package/telegram-plugin/tests/error-envelope-unlock-card.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Telegram bridge unlock-card safety (#1758 Phase 1).
+ *
+ * The bridge MUST validate `flip_yaml_flag.yaml_path` against the
+ * config-edit-validator allowlist before rendering a one-tap approval
+ * card. A malformed or hostile envelope from any backend could
+ * otherwise nudge the operator into approving an arbitrary flag flip.
+ */
+
+import { describe, it, expect } from "vitest";
+import { renderErrorEnvelopeCard } from "../gateway/error-envelope-card.js";
+import type { HostdResponse } from "../../src/host-control/protocol.js";
+
+function mkResp(fix: HostdResponse["error_envelope"]["fix"]): HostdResponse {
+  return {
+    v: 1,
+    request_id: "r-1",
+    result: "error",
+    exit_code: null,
+    duration_ms: 0,
+    error: "E_FOO: foo",
+    error_envelope: {
+      v: 1,
+      code: "E_FOO",
+      human: "foo",
+      fix,
+      request_id: "r-1",
+    },
+  } as HostdResponse;
+}
+
+describe("renderErrorEnvelopeCard — allowlist guard", () => {
+  it("renders an approval card for an allowlisted yaml_path", () => {
+    const resp = mkResp({
+      kind: "flip_yaml_flag",
+      yaml_path: "hostd.config_edit_enabled",
+      to: true,
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out.kind).toBe("card");
+    if (out.kind === "card") {
+      expect(out.yaml_path).toBe("hostd.config_edit_enabled");
+      expect(out.to).toBe(true);
+      expect(out.card.text).toContain("klanker");
+    }
+  });
+
+  it("falls back to plain-text for a NON-allowlisted yaml_path", () => {
+    const resp = mkResp({
+      kind: "flip_yaml_flag",
+      yaml_path: "hostd.evil_backdoor_flag",
+      to: true,
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+
+  it("falls back to plain-text for request_vault_grant (Phase 2 scope)", () => {
+    const resp = mkResp({
+      kind: "request_vault_grant",
+      vault_key: "openai/api-key",
+    });
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+
+  it("falls back to plain-text when no envelope is present", () => {
+    const resp: HostdResponse = {
+      v: 1,
+      request_id: "r-1",
+      result: "error",
+      exit_code: null,
+      duration_ms: 0,
+      error: "legacy string",
+    };
+    const out = renderErrorEnvelopeCard(resp, "klanker", "a".repeat(32));
+    expect(out).toEqual({ kind: "plain-text" });
+  });
+});