switchroom 0.19.38 → 0.19.40

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

@@ -133,6 +133,21 @@ import * as silencePoke from '../silence-poke.js'
 const PARKED_TURN_START_MAX = 16
 const PARKED_TURN_START_TTL_MS = 30 * 60_000
 
+// ─── Queued-turn card (#3927 follow-up) ──────────────────────────────────────
+// Since #3927 a genuinely-queued mid-turn message is parked with NO surface at
+// all until it dequeues — the user gets silence between sending and the turn
+// starting. We post an immediate, clearly-marked "queued" card at park time,
+// reply-anchored to the parked message, and store its id on the envelope. On
+// dequeue → `beginTurn` seeds it as the turn's `activityMessageId` (mirroring
+// the handback-card adoption) so the SAME card is EDITED IN PLACE into the live
+// progress card — one lifecycle, finalized by the normal turn end. A `remove`
+// (folded into the running turn) or a TTL expiry finalizes it so it never
+// freezes. Kill switch: SWITCHROOM_QUEUED_CARD=0.
+const QUEUED_CARD_ENABLED = process.env.SWITCHROOM_QUEUED_CARD !== '0'
+const QUEUED_CARD_HTML = '⏳ Queued — waiting for the current task to finish…'
+const QUEUED_CARD_FOLDED_HTML = '✅ Folded into the current task.'
+const QUEUED_CARD_EXPIRED_HTML = '⚠️ This queued message timed out before it could start.'
+
 /** The `enqueue` envelope fields `beginTurn` needs — the SessionEvent minus its
  *  discriminant. A parked entry additionally carries `parkedAt` for the TTL. */
 export interface TurnStartEnvelope {
@@ -140,6 +155,10 @@ export interface TurnStartEnvelope {
   messageId: string | null
   threadId: string | null
   rawContent: string
+  /** Message id of the "queued" card posted at park time (Part B). Seeded as the
+   *  turn's `activityMessageId` on dequeue so the card is edited in place into
+   *  the live progress card. Absent on the idle-mint path (no parking, no card). */
+  queuedCardMessageId?: number | null
 }
 interface ParkedTurnStart extends TurnStartEnvelope {
   parkedAt: number
@@ -149,7 +168,9 @@ interface ParkedTurnStart extends TurnStartEnvelope {
  *  claude CLI session's ONE queue, exactly like the `currentTurn` mirror. */
 const parkedTurnStarts: ParkedTurnStart[] = []
 
-function pruneParkedTurnStarts(now: number): void {
+/** `onDrop` (Part B) fires for every removed entry so the caller can finalize a
+ *  posted queued card. Best-effort — never throws into the prune loop. */
+function pruneParkedTurnStarts(now: number, onDrop?: (entry: ParkedTurnStart) => void): void {
   for (let i = parkedTurnStarts.length - 1; i >= 0; i--) {
     if (now - parkedTurnStarts[i].parkedAt > PARKED_TURN_START_TTL_MS) {
       const [dropped] = parkedTurnStarts.splice(i, 1)
@@ -157,19 +178,29 @@ function pruneParkedTurnStarts(now: number): void {
         `telegram gateway: parked-turn-start expired chat=${dropped.chatId ?? '-'} ` +
           `msg=${dropped.messageId ?? '-'} age_ms=${now - dropped.parkedAt}\n`,
       )
+      try { onDrop?.(dropped) } catch { /* never let card cleanup break the prune */ }
     }
   }
 }
 
-function parkTurnStart(env: TurnStartEnvelope, now: number): void {
-  parkedTurnStarts.push({ ...env, parkedAt: now })
+/** Returns the freshly-parked entry so the caller can attach a queued-card id to
+ *  it asynchronously. `onEvict` (Part B) fires for a cap-evicted entry. */
+function parkTurnStart(
+  env: TurnStartEnvelope,
+  now: number,
+  onEvict?: (entry: ParkedTurnStart) => void,
+): ParkedTurnStart {
+  const entry: ParkedTurnStart = { ...env, parkedAt: now }
+  parkedTurnStarts.push(entry)
   while (parkedTurnStarts.length > PARKED_TURN_START_MAX) {
     const [dropped] = parkedTurnStarts.splice(0, 1)
     process.stderr.write(
       `telegram gateway: parked-turn-start evicted (cap ${PARKED_TURN_START_MAX}) ` +
         `chat=${dropped.chatId ?? '-'} msg=${dropped.messageId ?? '-'}\n`,
     )
+    try { onEvict?.(dropped) } catch { /* never let card cleanup break parking */ }
   }
+  return entry
 }
 
 /** Pop the MOST RECENTLY parked envelope — the one a `dequeue` pairs with. */
@@ -181,14 +212,14 @@ function takeParkedTurnStart(): ParkedTurnStart | null {
  *  match first. A `remove` means "folded into the running turn" — that message
  *  will never get a turn of its own, so leaving it parked would let a LATER
  *  `dequeue` mint a spurious turn for an already-answered message. */
-function discardParkedTurnStart(rawContent: string): boolean {
+function discardParkedTurnStart(rawContent: string): ParkedTurnStart | null {
   for (let i = parkedTurnStarts.length - 1; i >= 0; i--) {
     if (parkedTurnStarts[i].rawContent === rawContent) {
-      parkedTurnStarts.splice(i, 1)
-      return true
+      const [dropped] = parkedTurnStarts.splice(i, 1)
+      return dropped
     }
   }
-  return false
+  return null
 }
 
 /** Test seam: the parked store is module-scope (one CLI session, one queue), so
@@ -201,6 +232,111 @@ export function __parkedTurnStartCountForTest(): number {
   return parkedTurnStarts.length
 }
 
+// ─── Queued-turn card send / finalize (Part B) ───────────────────────────────
+// These use the ALREADY-injected `bot` + `robustApiCall` deps, so the whole
+// feature lives in stream-render.ts with zero new wiring in gateway.ts. No
+// streaming is structurally possible before dequeue (no CurrentTurn exists),
+// so this card is a single static line until the turn adopts + edits it.
+
+/** Minimal deps the queued-card helpers need. */
+type QueuedCardDeps = Pick<StreamRenderDeps, 'bot' | 'robustApiCall'>
+
+/** Post the "queued" card, reply-anchored to the parked message. Resolves to the
+ *  sent message id, or null when the send failed / was suppressed (best-effort —
+ *  a null just means no card, so nothing to adopt or finalize). Forum topics use
+ *  the envelope's OWN thread id. */
+async function openQueuedCard(
+  deps: QueuedCardDeps,
+  chatId: string,
+  threadId: number | null,
+  replyToMessageId: number | null,
+): Promise<number | null> {
+  try {
+    const sent = await deps.robustApiCall(
+      // allow-raw-bot-api: sendRichMessage routed through robustApiCall (not in the THREAD_NOT_FOUND blast pattern)
+      () =>
+        deps.bot.api.sendRichMessage(chatId, richMessage(QUEUED_CARD_HTML), {
+          ...(threadId != null ? { message_thread_id: threadId } : {}),
+          ...(replyToMessageId != null
+            ? { reply_parameters: { message_id: replyToMessageId, allow_sending_without_reply: true } }
+            : {}),
+          // Status surface, not the user's answer — never ping the device.
+          disable_notification: true,
+        }),
+      {
+        chat_id: chatId,
+        ...(threadId != null ? { threadId } : {}),
+        verb: 'queued-card.send',
+      },
+    )
+    return sent?.message_id ?? null
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: queued card send failed: ${(err as Error).message}\n`,
+    )
+    return null
+  }
+}
+
+/** Finalize (single honest edit) a queued card that will NOT become a live turn:
+ *  folded into the running turn (`remove`) or timed out (TTL). Best-effort. */
+function finalizeQueuedCard(
+  deps: QueuedCardDeps,
+  chatId: string,
+  threadId: number | null,
+  messageId: number,
+  html: string,
+): void {
+  void deps
+    .robustApiCall(
+      // allow-raw-bot-api: editMessageText routed through robustApiCall
+      () => deps.bot.api.editMessageText(chatId, messageId, richMessage(html), {}),
+      {
+        chat_id: chatId,
+        ...(threadId != null ? { threadId } : {}),
+        verb: 'queued-card.finalize',
+      },
+    )
+    .catch(() => undefined)
+}
+
+/** Delete a queued card that lost its race (the entry left the store before its
+ *  card id was stored, so `beginTurn` couldn't adopt it — a fresh progress card
+ *  will open instead). Best-effort. */
+function deleteQueuedCard(
+  deps: QueuedCardDeps,
+  chatId: string,
+  messageId: number,
+): void {
+  void deps
+    .robustApiCall(
+      // allow-raw-bot-api: deleteMessage routed through robustApiCall
+      () => deps.bot.api.deleteMessage(chatId, messageId),
+      { chat_id: chatId, verb: 'queued-card.delete-orphan' },
+    )
+    .catch(() => undefined)
+}
+
+/** Numeric thread id from an envelope's string thread id (null/invalid → null). */
+function envThreadIdNum(threadId: string | null): number | null {
+  if (threadId == null) return null
+  const n = Number(threadId)
+  return Number.isFinite(n) ? n : null
+}
+
+/** Finalize a queued card carried by a parked entry that is being dropped
+ *  (folded via `remove`, cap-evicted, or TTL-expired). No-op when the entry
+ *  never got a card. */
+function finalizeParkedEntryCard(
+  deps: QueuedCardDeps,
+  entry: ParkedTurnStart,
+  html: string,
+): void {
+  if (!QUEUED_CARD_ENABLED) return
+  if (entry.queuedCardMessageId == null || entry.chatId == null) return
+  finalizeQueuedCard(deps, entry.chatId, envThreadIdNum(entry.threadId), entry.queuedCardMessageId, html)
+}
+
 /**
  * Mint the turn atom and open its surfaces. This is the ENTIRE pre-#3927
  * `case 'enqueue'` body, relocated verbatim except for (a) the hoisted
@@ -436,6 +572,41 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
         )
       }
     }
+    // Part B — ADOPT the queued card. A parked envelope reaching `beginTurn`
+    // (via `dequeue`) carries the id of the "queued" card posted at park time.
+    // Seed it exactly as the handback adoption does so `renderActivityFeed`
+    // EDITS that same message into the live progress card instead of opening a
+    // second one, and the turn's own end-of-turn `clearActivitySummary`
+    // finalizes it — one continuous lifecycle. Guarded on `activityMessageId`
+    // still being null so a card-bearing handback adoption (mutually exclusive
+    // in practice) is never clobbered.
+    if (QUEUED_CARD_ENABLED && ev.queuedCardMessageId != null && next.activityMessageId == null) {
+      next.activityMessageId = ev.queuedCardMessageId
+      next.activityEverOpened = true
+      process.stderr.write(
+        `telegram gateway: queued card adopted turnId=${turnId} card=${ev.queuedCardMessageId}\n`,
+      )
+    } else if (
+      QUEUED_CARD_ENABLED &&
+      ev.queuedCardMessageId != null &&
+      ev.chatId != null &&
+      next.activityMessageId != null &&
+      next.activityMessageId !== ev.queuedCardMessageId
+    ) {
+      // Part B safety net — the handback adoption above WON the surface (its card
+      // is now `activityMessageId`) yet this envelope ALSO carries a queued card:
+      // the park raced ahead of `noteHandbackRelease`, so the park-time
+      // suppression missed and a queued card got posted. It is now a pure
+      // duplicate that would otherwise FREEZE on "⏳ Queued" beneath the adopted
+      // handback card (the MAJOR). Delete it — the handback card is the one
+      // surface; a delete (not a "folded" edit) is right because there is no
+      // separate message to explain, just a stray duplicate to remove.
+      deleteQueuedCard(deps, ev.chatId, ev.queuedCardMessageId)
+      process.stderr.write(
+        `telegram gateway: queued card superseded by handback adoption turnId=${turnId} ` +
+          `queued=${ev.queuedCardMessageId} adopted=${next.activityMessageId}\n`,
+      )
+    }
     // #3544 — arm the turn-long `typing…` loop for EVERY minted turn,
     // unconditionally. It used to hang off the handback ADOPTION above,
     // which misses whenever the pre-turn entry was deduped (parallel
@@ -731,7 +902,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           )
         }
       }
-      pruneParkedTurnStarts(now)
+      pruneParkedTurnStarts(now, (e) => finalizeParkedEntryCard(deps, e, QUEUED_CARD_EXPIRED_HTML))
       // `enqueue` with no chat can never mint a turn (the whole mint block is
       // `if (ev.chatId)`-gated); parking it would only pollute the store, so
       // run the pre-turn drain path verbatim and stop.
@@ -751,11 +922,13 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
         beginTurn(deps, ev)
         return
       }
-      // PARKED. Deliberately NO surface work here — no `promoteQueuedStatus`
-      // ("On it — replying now" is a lie until the turn actually starts), no
-      // `typingWrapper.drainAll()` (that drains the LIVE turn's wraps), no card.
-      // The queued placeholder Hook A already posted is the honest surface, and
-      // its lifecycle stays owned by the existing reap machinery.
+      // PARKED. No `promoteQueuedStatus` ("On it — replying now" is a lie until
+      // the turn actually starts) and no `typingWrapper.drainAll()` (that drains
+      // the LIVE turn's wraps). Part B DOES post one honest, clearly-marked
+      // "queued" card here: on the machine-authoritative path (the default) the
+      // legacy Hook A placeholder never fires — it lives in the buffer-until-idle
+      // branch that returns BEFORE the machine enqueues — so before Part B a
+      // parked envelope had no surface at all until it dequeued.
       //
       // UNIFORM ACROSS SOURCES — synthetic enqueues (cron fire, subagent
       // handback, obligation-represent, vault-grant resume, wake inbound) park
@@ -766,7 +939,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // attachment), never by a `dequeue`. Minting for it invented a turn the
       // CLI never started. FIX B covers the residual case where a mint DOES
       // land on top of a live atom.
-      parkTurnStart(
+      const parkedEntry = parkTurnStart(
         {
           chatId: ev.chatId,
           messageId: ev.messageId,
@@ -774,12 +947,57 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           rawContent: ev.rawContent,
         },
         now,
+        // Cap-evicted (oldest lost its slot) → finalize its card as expired so
+        // it never freezes on "⏳ Queued".
+        (evicted) => finalizeParkedEntryCard(deps, evicted, QUEUED_CARD_EXPIRED_HTML),
       )
       process.stderr.write(
         `telegram gateway: turn-start parked (session busy) chat=${ev.chatId} ` +
           `thread=${enqThreadIdNum ?? '-'} msg=${ev.messageId ?? '-'} ` +
           `parked=${parkedTurnStarts.length}\n`,
       )
+      // Post the queued card, reply-anchored to the parked message, and store its
+      // id back on the envelope so `beginTurn` can adopt+edit it on dequeue. One
+      // card per envelope (multiple queued messages each get their own).
+      //
+      // SUPPRESS when a handback pre-turn signal already owns this turn's surface
+      // (the common worker-handoff-while-busy case): `noteHandbackRelease` fired
+      // at buffer drain BEFORE this injected handback inbound reached park, so an
+      // entry armed for THIS message's turnId is already live. That entry paints
+      // (and the dequeued turn adopts) its OWN card, so a queued card here would
+      // be a second card that then freezes on "⏳ Queued" (the MAJOR this fixes).
+      // Turn-scoped, not key-scoped: an unrelated user message parked on the same
+      // topic derives a different turnId and is NOT suppressed. beginTurn carries
+      // a belt-and-suspenders cleanup for the residual race where the queued card
+      // was already posted before the handback entry armed.
+      const parkTurnId = deriveTurnId(ev.chatId, enqThreadIdNum ?? null, ev.messageId)
+      const handbackOwnsSurface =
+        HANDBACK_PRETURN_ENABLED &&
+        parkTurnId != null &&
+        handbackPreturnSignal.hasPendingForTurnId(parkTurnId)
+      if (handbackOwnsSurface) {
+        process.stderr.write(
+          `telegram gateway: queued card suppressed (handback owns surface) ` +
+            `turnId=${parkTurnId} msg=${ev.messageId ?? '-'}\n`,
+        )
+      }
+      if (QUEUED_CARD_ENABLED && !handbackOwnsSurface) {
+        const cardChatId = ev.chatId
+        const replyToRaw = ev.messageId != null ? Number(ev.messageId) : null
+        const replyTo = replyToRaw != null && Number.isFinite(replyToRaw) ? replyToRaw : null
+        void openQueuedCard(deps, cardChatId, enqThreadIdNum ?? null, replyTo).then((cardId) => {
+          if (cardId == null) return
+          // Still parked → adopt on the next dequeue. Otherwise the entry already
+          // dequeued/removed/expired before the async send resolved (a sub-second
+          // race), so `beginTurn` ran without the id — delete the orphan card so
+          // no frozen duplicate lingers below the turn's own fresh card.
+          if (parkedTurnStarts.includes(parkedEntry)) {
+            parkedEntry.queuedCardMessageId = cardId
+          } else {
+            deleteQueuedCard(deps, cardChatId, cardId)
+          }
+        })
+      }
       return
     }
     case 'dequeue': {
@@ -789,7 +1007,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // RECENT enqueue, not the oldest. An empty store is the normal idle path
       // (the enqueue ms earlier already minted) and a dequeue with no parked
       // start at all is a no-op, exactly as before.
-      pruneParkedTurnStarts(Date.now())
+      pruneParkedTurnStarts(Date.now(), (e) => finalizeParkedEntryCard(deps, e, QUEUED_CARD_EXPIRED_HTML))
       const parked = takeParkedTurnStart()
       if (parked == null) return
       beginTurn(deps, parked)
@@ -801,8 +1019,11 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // its parked envelope so a later `dequeue` cannot mint a spurious turn
       // for it. Content-matched: `remove` replays its enqueue's `content`
       // byte-for-byte.
-      pruneParkedTurnStarts(Date.now())
-      discardParkedTurnStart(ev.rawContent)
+      pruneParkedTurnStarts(Date.now(), (e) => finalizeParkedEntryCard(deps, e, QUEUED_CARD_EXPIRED_HTML))
+      // Part B — finalize the removed envelope's queued card as "folded into the
+      // current task" so it never freezes on "⏳ Queued".
+      const removed = discardParkedTurnStart(ev.rawContent)
+      if (removed != null) finalizeParkedEntryCard(deps, removed, QUEUED_CARD_FOLDED_HTML)
       return
     }
     case 'model': {
@@ -2091,6 +2312,10 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
           let sentIds: number[] = []
           let chunkCount = 0
           let delivered = false
+          // Set by the send-ack claim callback below once the durable
+          // delivered-keys journal has been written at ACK time — so the finally
+          // block does not journal the same nonce a second time.
+          let earlyJournaled = false
           try {
             // #3276 — the ONE delivery primitive. deliverAnswer routes through
             // `sendReplyChunks` (the same send core executeReply uses) and posts
@@ -2109,6 +2334,33 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
               // S4 — anchor the flushed answer to the inbound it answers
               // (null for synthesized turns, which send bare as before).
               replyToMessageId: turn.sourceMessageId,
+              // Duplicate-message race fix — write the DURABLE delivered-keys
+              // journal at SEND-ACK, BEFORE deliverAnswer's read-back probe (which
+              // the cosmetic-edit flood-fuse can defer ~30s). Without this the
+              // journal write happened only in the finally below, AFTER `await
+              // deliverAnswer` returned, so the outbox sweep — which waits just
+              // OUTBOX_QUIET_MS (5s) before checking `deliveredNonces` — saw no
+              // entry and sent a SECOND copy of this answer. Journaling under the
+              // SAME nonce (turn.turnId == the Stop-hook record's turnNonce) makes
+              // the sweep skip-journaled and clears any captured record.
+              onAckClaim: (ackIds) => {
+                try {
+                  journalExternalDelivery(
+                    {
+                      turnNonce: turn.turnId,
+                      text: capturedText,
+                      tgMessageId: ackIds.length > 0 ? ackIds[0] : undefined,
+                      deliverySource: 'flush',
+                    },
+                    STATE_DIR,
+                  )
+                  earlyJournaled = true
+                } catch (err) {
+                  process.stderr.write(
+                    `telegram gateway: turn-flush send-ack journal write failed (non-fatal): ${(err as Error).message}\n`,
+                  )
+                }
+              },
             })
             sentIds = delivery.sentIds
             chunkCount = delivery.chunkCount
@@ -2212,7 +2464,14 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
               // between this send and the next process's backstop. Journal ONLY on
               // a receipt-gated `delivered` success. Best-effort: a journal-write
               // failure must never demote the successful delivery.
-              if (delivered) {
+              //
+              // Duplicate-message race fix: skip when the send-ack claim
+              // (`onAckClaim`) already journaled this nonce at ACK time. That
+              // path is the primary writer now (it runs before the read-back
+              // probe); this finally write only covers the case where the claim
+              // never fired — e.g. a card-only delivery where every chunk landed
+              // but no fresh receipt gated the claim, yet `delivered` still held.
+              if (delivered && !earlyJournaled) {
                 try {
                   journalExternalDelivery(
                     {

package/telegram-plugin/hooks/compaction-marker-precompact.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * PreCompact hook — marks "compaction in flight" for the gateway (#4058).
+ *
+ * Claude Code PreCompact protocol:
+ *   Input:  JSON on stdin — { session_id, transcript_path, cwd,
+ *           hook_event_name: "PreCompact", trigger: "auto"|"manual",
+ *           custom_instructions }
+ *   Output: exit 0 + empty stdout → proceed. We NEVER block compaction and
+ *           NEVER exit non-zero.
+ *
+ * Side effect: writes (overwrites) ONE small JSON file
+ *   $TELEGRAM_STATE_DIR/compaction-in-flight.json
+ * with shape { ts, session_id, trigger }.
+ *
+ * Why: during mid-turn auto-compaction the model emits zero output and runs
+ * zero tools for minutes, so the gateway's silence-poke saw pure silence and
+ * fired its 300s "stalled turn" fallback on a healthy turn. The transcript
+ * only records compaction at its END (`system/compact_boundary` carries the
+ * compaction's own durationMs), so this hook is the one observable START
+ * signal. The gateway reads the marker's mtime (compaction-marker.ts) to
+ * DEFER the fallback — bounded by the same hard ceiling as the in-flight-tool
+ * defer — and removes it when the compact_boundary lands.
+ *
+ * If $TELEGRAM_STATE_DIR is unset → silent skip (dev / one-shot contexts;
+ * the fallback just keeps its pre-#4058 behaviour).
+ */
+
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+function main() {
+  const stateDir = process.env.TELEGRAM_STATE_DIR
+  if (!stateDir) return
+
+  let payload = {}
+  try {
+    payload = JSON.parse(readStdin() || '{}')
+  } catch {
+    // Unparseable stdin — still write the marker: the mtime alone carries
+    // the load-bearing signal; the body fields are diagnostics.
+  }
+
+  try {
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(
+      join(stateDir, 'compaction-in-flight.json'),
+      JSON.stringify({
+        ts: Date.now(),
+        session_id: typeof payload.session_id === 'string' ? payload.session_id : null,
+        trigger: typeof payload.trigger === 'string' ? payload.trigger : null,
+      }) + '\n',
+      { mode: 0o600 },
+    )
+  } catch {
+    // Best-effort: a missed marker just reverts one fallback decision to
+    // the pre-#4058 behaviour. Never fail the hook (never block compaction).
+  }
+}
+
+main()
+process.exit(0)

package/telegram-plugin/hooks/hooks.json

@@ -71,6 +71,17 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/compaction-marker-precompact.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [

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

@@ -15,7 +15,9 @@
  * If $TELEGRAM_STATE_DIR is unset → silent skip (renderer just falls back
  * to its existing precedence ladder). If session_id or tool_use_id is
  * missing → skip (the row could never be joined anyway). If the rule
- * table doesn't produce a label for the tool → skip.
+ * table doesn't produce a label for the tool → skip. If the call is a
+ * SIDECHAIN (sub-agent) tool call → skip (see isSubagentToolCall / #cross-
+ * contamination below).
  *
  * Tools intentionally NOT labeled here (handled by existing description
  * / TodoWrite / sub-agent panels in the renderer):
@@ -364,6 +366,98 @@ export function computeLabel(toolName, input) {
   return 'Working…'
 }
 
+/**
+ * True IFF this PreToolUse payload is for a SIDECHAIN (sub-agent) tool call,
+ * i.e. one made inside a Task/worker/Explore/Plan sub-agent rather than the
+ * top-level thread.
+ *
+ * WHY THIS EXISTS — the cross-contamination bug. Claude Code fires PreToolUse
+ * hooks for sub-agent tool calls too, and (as of 2.1.x) passes the PARENT
+ * `session_id` in that payload. The sidecar JSONL is keyed by `session_id`
+ * (`tool-labels-<session_id>.jsonl`), so a still-running background worker's
+ * labels were being appended into the PARENT session's sidecar. The gateway's
+ * real-time draft-mirror tails that file and emits a main-tier `tool_label`
+ * event per line, which the renderer binds to whatever turn is live — so a
+ * worker dispatched by turn N streamed its Bash step labels into an unrelated
+ * turn N+1's progress card. The worker's OWN activity is already surfaced by
+ * the worker-feed (sub_agent_tool_use events tailed from the sub-agent's own
+ * transcript), so the correct fix is to never write sub-agent labels to the
+ * parent sidecar in the first place — the cheapest, at-source link.
+ *
+ * DISCRIMINATOR — the payload carries sidechain identity. The PreToolUse hook
+ * input is built by the CLI's base `Kf(...)` helper, whose real 2.1.219 field
+ * shape (verified against the installed binary — see
+ * tests/fixtures/pretool-*.json) is:
+ *   { session_id, transcript_path, cwd, prompt_id?, permission_mode,
+ *     agent_id, agent_type, effort?, hook_event_name, tool_name, tool_input,
+ *     tool_use_id }
+ * The CLI's own top-level predicate is `agentType === "main"` (its `hb()`
+ * seeds the main thread as `{ agentType: "main", agentId: <sessionId> }`),
+ * while every sub-agent carries a concrete non-"main" `agent_type` ("worker",
+ * "general-purpose", "Explore", "Plan", a custom agent name, …).
+ *
+ * AUTHORITY ORDER (this matters for correctness, not just style):
+ *   1. `agent_type` is AUTHORITATIVE whenever it is a non-empty string:
+ *        - "main"        ⇒ top-level thread (KEEP), full stop, and
+ *        - anything else ⇒ concrete sub-agent (DROP).
+ *      Making "main" short-circuit is what prevents the SYMMETRIC false
+ *      positive: a (hypothetical future) main-tier payload whose `agent_id`
+ *      no longer equals `session_id` must STILL be kept — the identity
+ *      corroboration below must never override an explicit "main".
+ *   2. Only when `agent_type` is ABSENT/empty (unknown / a legacy CLI) do we
+ *      fall back to identity corroboration: a sidechain carries the PARENT
+ *      `session_id` but its OWN `agent_id`, so `agent_id !== session_id`
+ *      ⇒ sub-agent (DROP). Equal (or either missing) ⇒ main-tier (KEEP).
+ *
+ * A genuine sub-agent always carries a concrete agent_type (the Task tool
+ * requires a subagent_type), so this never drops a real sub-agent while
+ * risking a main-tier drop. See `hasAttributionSignal` for the fail-loud
+ * guard that fires if a FUTURE CLI drops BOTH identity fields (which would
+ * silently revert this whole fix — the drift the canary + warning defend).
+ */
+export function isSubagentToolCall(event) {
+  if (!event || typeof event !== 'object') return false
+  const at = event.agent_type
+  // (1) agent_type is authoritative when present: "main" ⇒ keep, else ⇒ drop.
+  if (typeof at === 'string' && at.length > 0) return at !== 'main'
+  // (2) agent_type absent/empty — corroborate via identity. A sidechain carries
+  // the parent session_id but its own agent_id.
+  const aid = event.agent_id
+  const sid = event.session_id
+  return (
+    typeof aid === 'string' && aid.length > 0 &&
+    typeof sid === 'string' && sid.length > 0 &&
+    aid !== sid
+  )
+}
+
+/**
+ * True IFF the payload carries AT LEAST ONE sidechain-attribution field
+ * (`agent_type` or `agent_id`) that `isSubagentToolCall` can key on.
+ *
+ * DRIFT CANARY (runtime half). On CC 2.1.219 EVERY PreToolUse payload carries
+ * both `agent_id` and `agent_type` (the base `Kf` builder). If a future CLI
+ * renamed/dropped BOTH (e.g. `agent_type`→`agentType`), `isSubagentToolCall`
+ * would silently return false for real sub-agents and the cross-turn
+ * contamination bug would return with NO test catching it (a frozen fixture
+ * can't see the live CLI change). So `main()` emits a one-line stderr WARNING
+ * — captured by plugin-logger — when a real tool call arrives with neither
+ * field, making the drift LOUD instead of silent. We warn rather than drop:
+ * dropping every label on drift would dark-out the whole live feed (a worse,
+ * feed-wide regression), whereas a warning lets an operator re-point the
+ * predicate at the renamed field. The committed fixtures
+ * (tests/fixtures/pretool-*.json) are the compile-time half of the canary.
+ */
+export function hasAttributionSignal(event) {
+  if (!event || typeof event !== 'object') return false
+  const at = event.agent_type
+  const aid = event.agent_id
+  return (
+    (typeof at === 'string' && at.length > 0) ||
+    (typeof aid === 'string' && aid.length > 0)
+  )
+}
+
 function main() {
   const raw = readStdin().trim()
   if (!raw) process.exit(0)
@@ -383,6 +477,30 @@ function main() {
   const toolName = event.tool_name
   if (!sessionId || !toolUseId || !toolName) process.exit(0)
 
+  // DRIFT CANARY (runtime half). On 2.1.219 a real PreToolUse payload ALWAYS
+  // carries agent_type + agent_id. If a future CLI dropped/renamed BOTH, the
+  // sidechain discriminator below would silently fail open and the cross-turn
+  // contamination bug would return unnoticed. Warn LOUDLY (plugin-logger tails
+  // stderr) so the drift is visible; we do NOT drop here — dropping every label
+  // on drift would dark-out the whole live feed. See hasAttributionSignal.
+  if (!hasAttributionSignal(event)) {
+    try {
+      process.stderr.write(
+        `[tool-label-pretool] WARNING: PreToolUse payload carries neither ` +
+          `agent_type nor agent_id — the sidechain-attribution invariant may be ` +
+          `broken by a Claude Code schema change; sub-agent labels may be ` +
+          `mis-attributed to the parent session (tool_use_id=${toolUseId}).\n`,
+      )
+    } catch { /* never block */ }
+  }
+
+  // Sidechain (sub-agent) tool calls arrive here with the PARENT session_id,
+  // so writing their label to `tool-labels-<sessionId>.jsonl` pollutes the
+  // parent session's sidecar and cross-contaminates an unrelated turn's card.
+  // Drop them: the worker-feed already surfaces sub-agent activity. See
+  // isSubagentToolCall for the full rationale + discriminator.
+  if (isSubagentToolCall(event)) process.exit(0)
+
   let label
   try {
     label = computeLabel(toolName, event.tool_input)