switchroom 0.14.2 → 0.14.4

package/telegram-plugin/gateway/gateway.ts

@@ -59,6 +59,7 @@ import {
   registerAndRender,
   describeToolUse,
   appendActivityLine,
+  appendActivityLabel,
   type ActivityState,
 } from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
@@ -286,7 +287,7 @@ import { chatKey, chatKeyWithSuffix, chatIdOfChatKey } from './chat-key.js'
 // should do. Behavior unchanged in this PR — the imperative code below
 // still runs everything. PR 3 will cut over to executing the machine's
 // effects.
-import { shadowEmit } from './inbound-delivery-machine-shadow.js'
+import { shadowEmit, isMachineInTurn, isDeliveryCutoverEnabled } from './inbound-delivery-machine-shadow.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import { dispatchEffects, isDispatchEnabled } from './inbound-delivery-machine-dispatch.js'
 import { maybeFireWarmup } from './prefix-warmup.js'
@@ -367,7 +368,7 @@ import { createIssuesCardHandle, type IssuesCardHandle } from '../issues-card.js
 import { startIssuesWatcher, type IssuesWatcherHandle } from '../issues-watcher.js'
 import { list as listIssues, resolve as resolveIssue } from '../../src/issues/index.js'
 import { summarizeToolForTitle, formatPermissionCardBody } from '../permission-title.js'
-import { resolveAlwaysAllowRule } from '../permission-rule.js'
+import { resolveAlwaysAllowRule, isRulePersisted } from '../permission-rule.js'
 import {
   readClaudeJsonOverage,
   evaluateCreditState,
@@ -1161,6 +1162,24 @@ function markClaudeBusyForInbound(m: {
   }
   claudeBusyKeys.add(chatKey(m.chatId, tid))
 }
+
+/**
+ * Authoritative "is a turn in flight?" for every gate that previously
+ * read `claudeBusyKeys.size`. PR 3b cutover (extends PR 3a's bridgeUp
+ * dispatch): when the delivery state machine is authoritative
+ * (`SWITCHROOM_DELIVERY_MACHINE_CUTOVER` on + shadow on) the answer is
+ * its single-`activeTurn` global state, which — unlike the
+ * per-delivery `claudeBusyKeys` set — cannot accumulate orphan keys and
+ * wedge the gate "in-flight forever" (the gymbro/clerk 5-min dangle,
+ * 2026-05-28). Kill-switch off → exact legacy claudeBusyKeys behaviour.
+ *
+ * NOT for the inbound-receipt gate (line ~8551): that must snapshot the
+ * machine state BEFORE the inbound event advances it, or a fresh-turn
+ * message self-blocks. See the snapshot at the inbound handler.
+ */
+function turnInFlightForGate(): boolean {
+  return isDeliveryCutoverEnabled() ? isMachineInTurn() : claudeBusyKeys.size > 0
+}
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
 
 // ─── Proactive context compaction (session.max_context_tokens) ──────────
@@ -1490,7 +1509,11 @@ function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
   // activeTurnStartedAt entry in the fresh-turn branch) doesn't pin this
   // gate forever while claude is genuinely idle. See the claudeBusyKeys
   // declaration for the supergroup deadlock this fixes.
-  if (claudeBusyKeys.size === 0) {
+  // PR3b-cutover: `turnInFlightForGate()` reads the delivery machine
+  // when the cutover kill-switch is on; the turnEnd event was emitted
+  // just above (purgeReactionTracking head), so the machine is already
+  // idle here.
+  if (!turnInFlightForGate()) {
     // #1556: the deterministic delivery point. claude has just gone
     // idle — flush any inbound held mid-turn so the channel
     // notification lands at the idle prompt and submits as a fresh
@@ -1590,7 +1613,9 @@ function releaseTurnBufferGate(key: string): void {
   // test-harness's 13:02 UAT now opens after the reply.
   //
   // PR3b: gated on claudeBusyKeys (see purgeReactionTracking comment).
-  if (claudeBusyKeys.size === 0) {
+  // PR3b-cutover: turnEnd was emitted just above (releaseTurnBufferGate
+  // head), so the machine is already idle when the cutover gate reads.
+  if (!turnInFlightForGate()) {
     const selfAgentForFlush = process.env.SWITCHROOM_AGENT_NAME ?? ''
     if (pendingInboundBuffer.depth(selfAgentForFlush) > 0) {
       const fr = redeliverBufferedInbound(
@@ -3656,6 +3681,23 @@ silencePoke.startTimer({
   },
 })
 
+// PR3b-cutover: drive the delivery machine's TTL `tick`. The machine
+// expires any turn whose `turnStartedAt` is older than TURN_TTL_MS
+// (5 min) and drops global state back to idle — its structural
+// equivalent of the imperative silence-poke framework-fallback. This
+// is the load-bearing safety net for the cutover gate: even if a
+// `turnEnd` event is somehow missed (the dangle class), the machine
+// self-heals at TTL instead of pinning the gate "in-flight forever".
+// shadowEmit only advances state + logs the predicted effects; we
+// deliberately do NOT execute the machine's firePoke here (the
+// imperative silence-poke still owns the user-facing ping), so there
+// is no double-poke. unref so the interval never holds the process.
+const DELIVERY_MACHINE_TICK_MS = 30_000
+const _deliveryMachineTick = setInterval(() => {
+  shadowEmit({ kind: 'tick', now: Date.now() })
+}, DELIVERY_MACHINE_TICK_MS)
+_deliveryMachineTick.unref?.()
+
 // #1445 cross-turn pending-async ambient. When a turn ends after the
 // model dispatched background async work (Agent / Task / Bash run-in-
 // background) and the model has stopped speaking, keep editing the
@@ -4195,7 +4237,8 @@ const ipcServer: IpcServer = createIpcServer({
     // PR3b: gated on claudeBusyKeys (actually-handed-to-claude turns)
     // not activeTurnStartedAt (receipt-eager), so a buffered topic-B
     // inbound doesn't pin this as turnInFlight=true forever.
-    const turnInFlight = claudeBusyKeys.size > 0;
+    // PR3b-cutover: reads the delivery machine when the kill-switch is on.
+    const turnInFlight = turnInFlightForGate();
 
     if (!turnInFlight) {
       // No active turn, restart immediately. Cycle both the agent and
@@ -4615,7 +4658,8 @@ if (!STATIC) {
         // #1556: never drain mid-turn — that re-creates the composer
         // wedge this buffer exists to prevent.
         // PR3b: gated on claudeBusyKeys (see purgeReactionTracking).
-        if (claudeBusyKeys.size > 0) return false
+        // PR3b-cutover: reads the delivery machine when the kill-switch is on.
+        if (turnInFlightForGate()) return false
         const c = ipcServer.getClient(selfAgent)
         return c != null && c.isAlive()
       },
@@ -5020,6 +5064,11 @@ 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())
+  // PR3b-cutover: feed lastOutboundAt to the delivery machine so its
+  // TTL `tick` suppresses the fallback for a long-but-active turn
+  // (model streaming past 5 min) — parity with silencePoke's own
+  // suppression, so the cutover gate doesn't clear a live turn.
+  shadowEmit({ kind: 'modelOutbound', key: statusKey(chat_id, threadId) as _ChatKey, at: Date.now() })
   // #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
@@ -5615,6 +5664,9 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       const sKey = statusKey(streamChatId, streamThreadId)
       signalTracker.noteOutbound(sKey, Date.now())
       silencePoke.noteOutbound(sKey, Date.now())
+      // PR3b-cutover: feed lastOutboundAt to the delivery machine (see
+      // executeReply) so its TTL tick suppresses an active-turn fallback.
+      shadowEmit({ kind: 'modelOutbound', key: sKey as _ChatKey, at: Date.now() })
       // #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
@@ -7012,6 +7064,20 @@ function handleSessionEvent(ev: SessionEvent): void {
           isDm: isDmChatId(ev.chatId),
         }
         currentTurn = next
+        // PR3b-cutover: feed the authoritative turn-start to the delivery
+        // machine. `enqueue` fires for EVERY turn atom regardless of
+        // source — inbound, cron, subagent-handback, vault-resume,
+        // restart-marker — so it is the single chokepoint that captures
+        // the non-inbound turns the machine's own `inbound` event never
+        // sees (those bypass handleInbound). Without it the machine reads
+        // idle during a cron/handback turn and the gate would mis-deliver
+        // a concurrent inbound mid-turn (the #1556 composer wedge).
+        // Idempotent when already in_turn (turnStart only sets perKey).
+        shadowEmit({
+          kind: 'turnStart',
+          key: statusKey(ev.chatId, ev.threadId != null ? Number(ev.threadId) : undefined) as _ChatKey,
+          at: startedAt,
+        })
         // #549 fix — fresh turn, reset preamble-suppression state.
         preambleSuppressor.reset()
         // Reset the silent-end retry budget for this chat. The stored
@@ -7130,7 +7196,12 @@ function handleSessionEvent(ev: SessionEvent): void {
         // empty draft to wipe the compose-area preview; for persisted
         // messages, delete. The user sees the real reply land in the
         // same beat the summary disappears.
-        if (wasFirstReply) {
+        // Legacy (flag-off): the activity summary clears on the first
+        // reply — it was a one-shot "what I did" line. DRAFT_MIRROR keeps
+        // the live feed running through mid-turn replies and clears it at
+        // turn_end instead, so an early reply doesn't wipe the stream
+        // (the fast-turn determinism fix).
+        if (wasFirstReply && !DRAFT_MIRROR_ENABLED) {
           clearActivitySummary(turn)
         }
       }
@@ -7153,22 +7224,19 @@ function handleSessionEvent(ev: SessionEvent): void {
       // exactly once at a time and re-running until pending matches
       // the last-sent. Captures `turn` so a late drain after turn-swap
       // can't corrupt the next turn's atom.
-      // DRAFT_MIRROR (RFC draft-mirror-preview): accumulate each tool_use
-      // into a human-friendly running feed in the live preview, using the
-      // model-authored descriptive field (Bash.description, Read/Edit file
-      // basename, hindsight→"Searching memory", etc. — see describeToolUse
-      // / appendActivityLine). The draft shows the turn's actions as a
-      // capped chronological list (Claude Code-style), clears on reply.
-      // Never surfaces raw shell/query syntax — option A, uniform across
-      // code + non-code agents.
-      //
       // Flag OFF (default): the legacy generic verb-count summary
       // ("Ran 5 commands") via registerAndRender — byte-identical to
-      // pre-draft-mirror behavior.
-      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
-        const rendered = DRAFT_MIRROR_ENABLED
-          ? appendActivityLine(turn.mirrorLines, name, ev.input)
-          : registerAndRender(turn.toolActivity, name)
+      // pre-draft-mirror behavior, cleared on first reply.
+      //
+      // DRAFT_MIRROR: the draft is NOT driven from this (flush-gated)
+      // tool_use event — it's driven by the real-time `tool_label` event
+      // (PreToolUse sidecar, fires at tool-call time regardless of when
+      // claude flushes the transcript). See `case 'tool_label'`. That's
+      // the determinism fix: on a fast/clustered-tool turn the JSONL
+      // tool_use rows aren't on disk until ~turn-end, so sourcing the
+      // draft here lost the feed; the sidecar is flush-independent.
+      if (!DRAFT_MIRROR_ENABLED && !turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = registerAndRender(turn.toolActivity, name)
         if (rendered != null) {
           turn.activityPendingRender = rendered
           if (turn.activityInFlight == null) {
@@ -7184,6 +7252,31 @@ function handleSessionEvent(ev: SessionEvent): void {
       }
       return
     }
+    case 'tool_label': {
+      // DRAFT_MIRROR real-time driver. The PreToolUse hook wrote this
+      // label synchronously at tool-call time; the sidecar surfaced it
+      // here (~250ms) independent of the transcript flush. Accumulate it
+      // into the live feed and update the ephemeral draft — this is what
+      // makes the draft deterministic on fast/clustered-tool turns where
+      // the JSONL tool_use rows arrive too late.
+      if (!DRAFT_MIRROR_ENABLED) return
+      const turn = currentTurn
+      if (turn == null) return
+      // Surface tools (reply/stream_reply/react) are the conversation, not
+      // activity — the hook labels them ("Replying"), so filter by name.
+      if (isTelegramSurfaceTool(ev.toolName)) return
+      // Unlike the legacy tool_use path, do NOT gate on replyCalled — the
+      // whole point is to show activity even when a reply raced ahead of
+      // the (lagged) transcript. The feed clears at turn_end.
+      const rendered = appendActivityLabel(turn.mirrorLines, ev.label)
+      if (rendered != null) {
+        turn.activityPendingRender = rendered
+        if (turn.activityInFlight == null) {
+          turn.activityInFlight = drainActivitySummary(turn)
+        }
+      }
+      return
+    }
     case 'text': {
       // #1067: snapshot at entry. The answer-stream creation closures
       // below also read `turn` instead of currentTurn so they pin to
@@ -7454,6 +7547,14 @@ function handleSessionEvent(ev: SessionEvent): void {
         clearTimeout(turn.orphanedReplyTimeoutId)
         turn.orphanedReplyTimeoutId = null
       }
+      // DRAFT_MIRROR: the live activity feed runs through the whole turn
+      // (it is NOT cleared on the first reply, unlike the legacy summary)
+      // so an early/mid-turn reply can't wipe it. Clear it here, at the
+      // real end of the turn — the ephemeral compose-area draft goes away
+      // once the work is actually done.
+      if (DRAFT_MIRROR_ENABLED && turn != null) {
+        clearActivitySummary(turn)
+      }
       // #549 fix — flush any pending preamble BEFORE the answer stream is
       // nulled below. Text emitted immediately before turn_end (no tool
       // followed) is the answer; the suppressor's emitAnswer callback
@@ -8505,6 +8606,14 @@ async function handleInbound(
   // vs mid-turn — its decision will be visible in the gw-trace shadow
   // line emitted to stderr.
   const _shadowKey = statusKey(ctx.chat?.id != null ? String(ctx.chat.id) : '0', ctx.message?.message_thread_id) as _ChatKey
+  // PR3b-cutover: snapshot the machine's in-turn state BEFORE the
+  // inbound event advances it. A fresh-turn inbound transitions the
+  // machine idle→in_turn; reading after the emit would see THIS
+  // message's own just-started turn and self-block it (the same
+  // self-block hazard the claudeBusyKeys snapshot below guards). When
+  // the kill-switch is off this is null and the gate uses the legacy
+  // claudeBusyKeys read.
+  const machineInTurnAtReceipt = isDeliveryCutoverEnabled() ? isMachineInTurn() : null
   shadowEmit({
     kind: 'inbound',
     key: _shadowKey,
@@ -8556,7 +8665,12 @@ async function handleInbound(
   // no turn_end ever fires). With claudeBusyKeys, B sees true (A is
   // busy) → B is buffered correctly, AND the gate cleanly reopens
   // when A's turn_end deletes keyA → flush triggers → B delivered.
-  const turnInFlightAtReceipt = claudeBusyKeys.size > 0
+  // PR3b-cutover: prefer the machine snapshot taken before the inbound
+  // event advanced it (machineInTurnAtReceipt); null when the
+  // kill-switch is off, in which case the legacy claudeBusyKeys read
+  // stands. Both are "was a turn in flight at receipt", not a live
+  // post-this-inbound read — see machineInTurnAtReceipt's comment.
+  const turnInFlightAtReceipt = machineInTurnAtReceipt ?? (claudeBusyKeys.size > 0)
 
   const access = result.access
   const from = ctx.from!
@@ -15172,25 +15286,56 @@ bot.on('callback_query:data', async ctx => {
       return
     }
     let grantOk = false
+    let grantFailReason = ''
     try {
       // --no-restart: settings.json gets the new entry on the next
       // reconcile but we don't bounce the agent mid-turn. Operator
       // can restart manually if they want this rule live in this
       // session; otherwise it kicks in next session.
       switchroomExec(['agent', 'grant', agentName, rule.rule, '--no-restart'])
-      grantOk = true
-      process.stderr.write(
-        `telegram gateway: always-allow added rule="${rule.rule}" agent=${agentName} (request_id=${request_id})\n`,
-      )
+      // Verify the rule actually landed in the resolved config — guards
+      // against config-location-drift (gateway edited a yaml that isn't
+      // the durable source-of-truth, or the grant was a no-op). One
+      // fresh config read; cheap since this is a rare operator tap.
+      try {
+        const cfg = loadSwitchroomConfig()
+        const rawAgent = cfg.agents?.[agentName]
+        if (rawAgent) {
+          const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent)
+          const allowList: string[] = (resolved as { tools?: { allow?: string[] } }).tools?.allow ?? []
+          if (isRulePersisted(allowList, rule.rule)) {
+            grantOk = true
+            process.stderr.write(
+              `telegram gateway: always-allow added rule="${rule.rule}" agent=${agentName} (request_id=${request_id})\n`,
+            )
+          } else {
+            grantFailReason = `rule "${rule.rule}" not found in resolved tools.allow after write — config location may have drifted`
+            process.stderr.write(
+              `telegram gateway: always-allow VERIFY FAILED: ${grantFailReason} (request_id=${request_id})\n`,
+            )
+          }
+        } else {
+          grantFailReason = `agent "${agentName}" not found in config after write`
+          process.stderr.write(
+            `telegram gateway: always-allow VERIFY FAILED: ${grantFailReason} (request_id=${request_id})\n`,
+          )
+        }
+      } catch (verifyErr) {
+        grantFailReason = `config re-read failed: ${(verifyErr as Error).message}`
+        process.stderr.write(
+          `telegram gateway: always-allow VERIFY FAILED: ${grantFailReason} (request_id=${request_id})\n`,
+        )
+      }
     } catch (err) {
-      process.stderr.write(`telegram gateway: always-allow grant failed: ${(err as Error).message}\n`)
+      grantFailReason = (err as Error).message
+      process.stderr.write(`telegram gateway: always-allow grant failed: ${grantFailReason}\n`)
     }
 
     pendingPermissions.delete(request_id)
 
     const ackText = grantOk
       ? `🔁 Always allow ${rule.label} for ${agentName}`
-      : `✅ Allowed (always-allow yaml edit failed; check gateway log)`
+      : `⚠️ Allowed for now, but "always" did NOT save — it will ask again after restart. Check gateway log.`
     // HTML-escape baseText — `ctx.callbackQuery.message.text` returns
     // entities-stripped plain UTF-8, so raw `<`/`>`/`&` in the
     // expanded permission card's `description` or `input_preview`
@@ -15203,7 +15348,7 @@ bot.on('callback_query:data', async ctx => {
       : ''
     const editLabel = grantOk
       ? `🔁 <b>Always allow ${escapeHtmlForTg(rule.label)}</b> for ${escapeHtmlForTg(agentName)} — restart agent for full effect`
-      : `✅ <b>Allowed</b> (always-allow rule edit failed; see logs)`
+      : `⚠️ <b>Allowed for now — "always" did NOT save.</b> It will ask again after restart. Check gateway log.`
     // #1150 audit: route through finalizeCallback so the keyboard
     // strips alongside the status-line edit. Pre-fix this called
     // editMessageText without `reply_markup` so the Allow/Deny/Always

package/telegram-plugin/gateway/inbound-delivery-machine-shadow.ts

@@ -43,6 +43,39 @@ import {
 let state: State = initialState()
 const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_SHADOW !== '0'
 
+// Phase 2b PR 3 — STAGED CUTOVER. When enabled, the gateway's
+// "is a turn in flight?" gate reads this machine's global state
+// instead of the PR3b `claudeBusyKeys` set. The machine tracks ONE
+// `activeTurn` (single bridge) plus TTL `tick` expiry, so — unlike a
+// per-delivery key set — it cannot accumulate orphan keys and wedge
+// the gate "in-flight forever" (the gymbro/clerk 5-min dangle of
+// 2026-05-28). Scope is the turn-in-flight GATE only; the poke ladder
+// and perm-verdict effects stay imperative for a follow-up PR.
+//
+// Kill switch: `SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0` reverts every
+// gate to the legacy claudeBusyKeys read (zero behaviour change).
+// Requires shadow mode ON — with shadow off the machine state is
+// frozen and must NOT be read as authoritative.
+const cutoverEnabled = enabled && process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
+
+/**
+ * True when the kill-switch leaves the delivery machine authoritative
+ * for the turn-in-flight gate. Gateway gate sites branch on this.
+ */
+export function isDeliveryCutoverEnabled(): boolean {
+  return cutoverEnabled
+}
+
+/**
+ * Authoritative "is a turn currently in flight?" read for the gate.
+ * Maps the machine's global state to the boolean the legacy
+ * `claudeBusyKeys.size > 0` gate produced. `bridge_dead` and
+ * `bridge_alive_idle` are both "not in flight".
+ */
+export function isMachineInTurn(): boolean {
+  return state.global.kind === 'bridge_alive_in_turn'
+}
+
 /**
  * Run an event through the state machine in shadow mode. The machine
  * state advances, the predicted effects are LOGGED, but no I/O fires.

package/telegram-plugin/hooks/tool-label-pretool.mjs

@@ -74,15 +74,24 @@ function urlHostPath(u) {
 export function computeLabel(toolName, input) {
   const i = input ?? {}
 
-  // Tools whose labels are already handled elsewhere — emit nothing so
-  // the existing description / TodoWrite / sub-agent paths win.
+  // Bash / Task / ToolSearch / TodoWrite: previously emitted nothing
+  // (deferred to the session-JSONL description path). The draft-mirror
+  // now drives off THIS sidecar in real time (flush-independent), so we
+  // must label them here too — otherwise the most common tool (Bash)
+  // never reaches the live draft. Uses the model-authored `description`
+  // for Bash/Task, matching the gateway's describeToolUse rendering.
   switch (toolName) {
     case 'Bash':
+      return clip(String(i.description ?? ''), 70).trim() || 'Running a command'
     case 'Task':
-    case 'Agent':
+    case 'Agent': {
+      const d = clip(String(i.description ?? ''), 60).trim()
+      return d ? `Delegating: ${d}` : 'Delegating to a sub-agent'
+    }
     case 'TodoWrite':
+      return 'Updating the plan'
     case 'ToolSearch':
-      return null
+      return 'Finding the right tool'
   }
 
   // Built-in rule table.

package/telegram-plugin/permission-rule.ts

@@ -132,6 +132,28 @@ function skillBasenameFromPath(input: Record<string, unknown>): string | null {
   return basename(trimmed) || null;
 }
 
+/**
+ * Verify that a grant actually landed in the resolved `tools.allow` list.
+ *
+ * Called by the `perm:always:*` handler after `switchroom agent grant`
+ * returns to guard against silently-failed or misdirected yaml writes.
+ * Extracted as a pure helper so it can be unit-tested without a full
+ * Grammy + switchroomExec harness.
+ *
+ * @param resolvedAllow  The `tools.allow` array from `resolveAgentConfig`
+ *                       for the target agent (pass `[]` when absent/undefined).
+ * @param ruleRule       The rule string produced by `resolveAlwaysAllowRule`
+ *                       (e.g. `"Skill(garmin)"`, `"Bash"`, `"mcp__x__y"`).
+ * @returns `true` when the rule is present (grant confirmed), `false` when
+ *          absent (grant failed / config location drifted).
+ */
+export function isRulePersisted(
+  resolvedAllow: readonly string[],
+  ruleRule: string,
+): boolean {
+  return resolvedAllow.includes(ruleRule);
+}
+
 /**
  * Inverse of `resolveAlwaysAllowRule` — does a stored allow-rule cover a
  * fresh `permission_request`? Used by the bridge's session-scoped

package/telegram-plugin/session-tail.ts

@@ -93,6 +93,11 @@ export type SessionEvent =
   | { kind: 'dequeue' }
   | { kind: 'thinking' }
   | { kind: 'tool_use'; toolName: string; toolUseId?: string | null; input?: Record<string, unknown>; precomputedLabel?: string }
+  // Real-time tool label from the PreToolUse-hook sidecar — fires when the
+  // hook writes the label (synchronous at tool-call time), independent of
+  // the lazily-flushed transcript. The draft-mirror drives off THIS, not
+  // the flush-gated `tool_use`, so activity streams deterministically.
+  | { kind: 'tool_label'; toolUseId: string; label: string; toolName: string }
   | { kind: 'text'; text: string }
   | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
   | { kind: 'turn_end'; durationMs: number }
@@ -639,6 +644,13 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
     try {
       const s = createToolLabelSidecar({ stateDir: stateDirForSidecar, sessionId })
       sidecars.set(sessionId, s)
+      // Real-time draft-mirror source: emit a `tool_label` event the moment
+      // the hook writes a label (flush-independent), so the gateway can
+      // stream the activity feed without waiting on the transcript flush.
+      // Subscribed once per sidecar (this is the only creation site).
+      s.onLabel((toolUseId, label, toolName) => {
+        rawOnEvent({ kind: 'tool_label', toolUseId, label, toolName })
+      })
       return s
     } catch (err) {
       log?.(`session-tail: sidecar create failed: ${(err as Error).message}`)
@@ -775,6 +787,12 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       }
       log?.(`session-tail: attached to ${file} (cursor=${cursor})`)
     }
+    // Eagerly create + subscribe the PreToolUse sidecar for this session
+    // NOW (on attach), not lazily on the first JSONL tool_use — otherwise
+    // the real-time `tool_label` source wouldn't exist until a flush-gated
+    // tool_use arrived, re-introducing the very lag the sidecar avoids.
+    const attachSid = sessionIdForFile(file)
+    if (attachSid) ensureSidecar(attachSid)
     try {
       watcher = watch(file, () => readNew())
     } catch (err) {

package/telegram-plugin/tests/always-allow-grant.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Structural contract tests for the "🔁 Always allow" handler in
+ * gateway.ts (the `behavior === 'always'` branch of the perm: callback
+ * dispatcher).
+ *
+ * Why structural: the handler lives inside a Grammy callback closure
+ * that's not exported. Full-function invocation would require a complete
+ * Grammy + switchroomExec harness. Instead, we pin the source-level
+ * invariants that were introduced to fix the silent-failure bug:
+ *
+ *   1. Loud failure text — the failure path must NOT read like success
+ *      (`✅ Allowed …`). After the fix, both the toast (ackText) and the
+ *      chat edit (editLabel) use the `⚠️` marker.
+ *   2. Post-write verification — after `switchroomExec` returns success
+ *      the handler MUST re-read the config and check that the rule is
+ *      actually present in `tools.allow`. If the check fails it sets
+ *      grantOk=false and surfaces the loud message.
+ *   3. Success path unchanged — when `grantOk` is true the success
+ *      strings (`🔁 Always allow …`, `restart agent for full effect`)
+ *      are still present.
+ *   4. Error reason capture — `grantFailReason` is declared and
+ *      populated from `(err as Error).message` so the root cause can
+ *      appear in logs; it is NOT silently swallowed into `message`-less
+ *      stderr output.
+ *
+ * Slicing strategy: we extract the `if (behavior === 'always') {` block
+ * from gateway.ts and run string assertions against that slice only —
+ * so additions elsewhere in the 17k-line file don't produce false
+ * positives or negatives.
+ */
+
+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',
+)
+
+/**
+ * Extract the `behavior === 'always'` block from the perm: callback
+ * dispatcher. The slice runs from the `if (behavior === 'always')` guard
+ * up to (but not including) the next top-level `// Forward permission`
+ * comment which opens the allow/deny branch.
+ */
+function sliceAlwaysBlock(): string {
+  const start = gatewaySrc.indexOf("if (behavior === 'always')")
+  const end = gatewaySrc.indexOf('// Forward permission decision to connected bridges', start)
+  if (start === -1 || end === -1) return ''
+  return gatewaySrc.slice(start, end)
+}
+
+const alwaysBlock = sliceAlwaysBlock()
+
+describe('always-allow handler — loud failure invariants', () => {
+  it('failure ackText uses the ⚠️ warning marker, not ✅', () => {
+    // The failure path must be unambiguous. Before the fix, the failure
+    // ackText started with "✅ Allowed …" which reads like success.
+    expect(alwaysBlock).toContain(
+      `⚠️ Allowed for now, but "always" did NOT save — it will ask again after restart. Check gateway log.`,
+    )
+    // Confirm the old misleading text is gone.
+    expect(alwaysBlock).not.toContain('✅ Allowed (always-allow yaml edit failed')
+  })
+
+  it('failure editLabel uses the ⚠️ warning marker, not ✅', () => {
+    // The inline-keyboard collapse edit also must NOT look like success.
+    expect(alwaysBlock).toContain(
+      `⚠️ <b>Allowed for now — "always" did NOT save.</b> It will ask again after restart. Check gateway log.`,
+    )
+    // Confirm the old misleading text is gone.
+    expect(alwaysBlock).not.toContain('✅ <b>Allowed</b> (always-allow rule edit failed')
+  })
+})
+
+describe('always-allow handler — success path unchanged', () => {
+  it('success ackText still uses 🔁 and names the rule', () => {
+    expect(alwaysBlock).toContain('`🔁 Always allow ${rule.label} for ${agentName}`')
+  })
+
+  it('success editLabel still uses 🔁 bold + restart hint', () => {
+    expect(alwaysBlock).toContain('restart agent for full effect')
+    expect(alwaysBlock).toContain('🔁 <b>Always allow')
+  })
+})
+
+describe('always-allow handler — post-write verification', () => {
+  it('reloads config after switchroomExec returns', () => {
+    // The verification block must call loadSwitchroomConfig() AFTER
+    // the switchroomExec call to confirm the rule landed in the
+    // resolved tools.allow.
+    const execIdx = alwaysBlock.indexOf("switchroomExec(['agent', 'grant'")
+    const loadIdx = alwaysBlock.indexOf('loadSwitchroomConfig()', execIdx)
+    expect(execIdx).toBeGreaterThan(-1)
+    expect(loadIdx).toBeGreaterThan(execIdx)
+  })
+
+  it('calls resolveAgentConfig to obtain the merged tools.allow list', () => {
+    const execIdx = alwaysBlock.indexOf("switchroomExec(['agent', 'grant'")
+    const resolveIdx = alwaysBlock.indexOf('resolveAgentConfig(', execIdx)
+    expect(resolveIdx).toBeGreaterThan(execIdx)
+  })
+
+  it('calls isRulePersisted(allowList, rule.rule) after the reload', () => {
+    // The handler delegates the membership check to the extracted pure
+    // helper so the behavioral test in always-allow-persist.test.ts can
+    // cover the same code path.
+    expect(alwaysBlock).toContain('isRulePersisted(allowList, rule.rule)')
+  })
+
+  it('sets grantOk=true only when isRulePersisted returns true', () => {
+    // grantOk=true must be inside the `if (isRulePersisted(...))` branch,
+    // not unconditionally after switchroomExec.
+    const persistIdx = alwaysBlock.indexOf('isRulePersisted(allowList, rule.rule)')
+    const grantOkIdx = alwaysBlock.indexOf('grantOk = true', persistIdx)
+    expect(persistIdx).toBeGreaterThan(-1)
+    expect(grantOkIdx).toBeGreaterThan(persistIdx)
+    // Confirm grantOk=true does NOT appear before the persistence check
+    // (i.e., not unconditionally on switchroomExec success as in the old code).
+    const grantOkFirst = alwaysBlock.indexOf('grantOk = true')
+    expect(grantOkFirst).toBeGreaterThanOrEqual(persistIdx)
+  })
+
+  it('logs a VERIFY FAILED message when the rule is absent after the write', () => {
+    expect(alwaysBlock).toContain('always-allow VERIFY FAILED')
+  })
+
+  it('surfaces config-location drift as a failure reason', () => {
+    expect(alwaysBlock).toContain('config location may have drifted')
+  })
+})
+
+describe('always-allow handler — error reason capture', () => {
+  it('declares grantFailReason to capture the root cause', () => {
+    expect(alwaysBlock).toContain('let grantFailReason')
+  })
+
+  it('populates grantFailReason from the thrown error on switchroomExec failure', () => {
+    // After the catch for switchroomExec, grantFailReason must be set
+    // from the error object so log messages can show the actual cause.
+    const catchIdx = alwaysBlock.lastIndexOf('} catch (err) {')
+    const reasonIdx = alwaysBlock.indexOf('grantFailReason = (err as Error).message', catchIdx)
+    expect(catchIdx).toBeGreaterThan(-1)
+    expect(reasonIdx).toBeGreaterThan(catchIdx)
+  })
+})