switchroom 0.5.0 → 0.7.8

package/telegram-plugin/progress-card-driver.ts

@@ -26,6 +26,8 @@ import {
   type SubAgentState,
 } from './progress-card.js'
 import { isTelegramReplyTool } from './tool-names.js'
+import { emitCardEvent } from './card-event-log.js'
+import { createHash } from 'crypto'
 import {
   applyCapped as fleetApplyCapped,
   applyToolResult as fleetApplyToolResult,
@@ -217,9 +219,26 @@ export interface ProgressDriverConfig {
    * starts (see `promoteOnSubAgent`) — long-running tool work and
    * background dispatches stay visible without waiting the full delay.
    *
-   * Default 60000 (60 seconds, #553 PR 4). Set to 0 to disable.
+   * Default 45000 (45 seconds, #842). Set to 0 to disable.
    */
   initialDelayMs?: number
+  /**
+   * First-render delay (ms) override for explicit background sub-agent
+   * dispatches (#842). When the agent calls
+   * `Agent({ run_in_background: true })`, the card is promoted out of
+   * the suppression window using this delay instead of `initialDelayMs`.
+   * Default 0 (immediate render — backgrounded work should be visible
+   * right away).
+   *
+   * Implementation: at `tool_use` ingest time the driver detects the
+   * background flag (existing `cs.backgroundParentToolUseIds` book-
+   * keeping). If `initialDelayMsBackground` is 0 the card promotes
+   * immediately via `promoteFirstEmit`. If positive, the deferred timer
+   * is rescheduled to fire that many ms from turn start (or now, if
+   * already past) — but only when shorter than what's currently
+   * scheduled. Never lengthens an in-flight delay.
+   */
+  initialDelayMsBackground?: number
   /**
    * Promote the first emit immediately when a sub-agent transitions to
    * running during the suppression window, when the watcher fires
@@ -417,6 +436,16 @@ interface PerChatState {
   isFirstEmit: boolean
   /** Timer for the deferred first emit (initial-delay suppression). */
   deferredFirstEmitTimer: unknown
+  /**
+   * #842: per-chat first-emit delay budget in ms. Initialised to
+   * `config.initialDelayMs`; lowered to `config.initialDelayMsBackground`
+   * the first time the parent dispatches an Agent/Task with
+   * `run_in_background: true`. Never increases. flush() reads this
+   * (instead of the closure-level `initialDelayMs`) when scheduling the
+   * deferred first-emit timer so the background bypass takes effect on
+   * the next scheduling pass.
+   */
+  effectiveInitialDelayMs: number
   /**
    * F3 fix (#553): timer for the time-based first-emit promotion.
    * Scheduled on the first ingest event; fires after `promoteAfterMs`
@@ -751,6 +780,18 @@ export interface ProgressDriver {
    * No-op if no card is currently tracking this `agentId`.
    */
   onSubAgentStall(agentId: string, idleMs: number, description: string): void
+  /**
+   * Symmetric to `onSubAgentStall`. Fires when the watcher observes
+   * JSONL activity returning for a previously-stalled sub-agent. Forces
+   * a re-render so the ⚠ Stalled badge clears immediately, instead of
+   * waiting on the next heartbeat tick (which the diff-guard might
+   * suppress if no chat-level state otherwise changed). The render
+   * itself reads the now-current `sa.lastEventAt` (already bumped by
+   * the standard event path), so this method is purely a render-trigger.
+   *
+   * No-op if no card is currently tracking this `agentId`.
+   */
+  onSubAgentUnstall(agentId: string, description: string): void
   /**
    * Test-only accessor exposing the driver's internal Maps so unit tests
    * can assert TTL eviction and outer-base-key cleanup actually drop
@@ -799,20 +840,29 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
   const editBudgetThreshold = config.editBudgetThreshold ?? 18
   const editBudgetCoalesceMs = config.editBudgetCoalesceMs ?? 3000
   const maxIdleMs = config.maxIdleMs ?? 30 * 60_000
-  // v2 card-gate (#553 PR 4): card visibility is `(elapsed >= 60s) OR
-  // (any sub-agent appeared)`. Tools alone never trigger the card.
-  //   - initialDelayMs: 60s (was 30s) — pushes the time-based gate to
-  //     the spec value.
+  // v2 card-gate (#553 PR 4 / #842): card visibility is `(elapsed >= 45s)
+  // OR (any sub-agent appeared) OR (explicit background dispatch)`.
+  // Tools alone never trigger the card.
+  //   - initialDelayMs: 45s (was 60s, #842) — pushes the time-based gate
+  //     to the spec value. The lower threshold means more turns flash a
+  //     card; the explicit-background bypass below offsets that for the
+  //     "fire-and-forget" case where the user always wants to see the
+  //     card immediately.
+  //   - initialDelayMsBackground: 0 (#842) — explicit
+  //     `Agent({run_in_background:true})` dispatches promote the card
+  //     immediately. Lets backgrounded work be visible right away
+  //     without waiting for any other promotion path.
   //   - promoteOnParentToolCount: 0 (was 3) — disabled. The check below
   //     treats 0 (and Infinity) as "never promote on tool count".
   //   - promoteAfterMs: 0 (was 5_000) — disabled. ensureTimePromoteScheduled
   //     no-ops when this is 0, so the timer never schedules. The PR #570
   //     time-promote was a stop-gap when initialDelayMs was 30s; with
-  //     initialDelayMs=60s and the sub-agent promote intact, it is no
+  //     initialDelayMs=45s and the sub-agent promote intact, it is no
   //     longer needed.
   //   - promoteOnSubAgent: true (unchanged) — sub-agents/background workers
   //     break the suppression immediately.
-  const initialDelayMs = config.initialDelayMs ?? 60_000
+  const initialDelayMs = config.initialDelayMs ?? 45_000
+  const initialDelayMsBackground = config.initialDelayMsBackground ?? 0
   const promoteOnSubAgent = config.promoteOnSubAgent ?? true
   const promoteOnParentToolCount = config.promoteOnParentToolCount ?? 0
   const promoteAfterMs = config.promoteAfterMs ?? 0
@@ -985,6 +1035,13 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
     }
     if (config.onTurnComplete) {
       process.stderr.write(`telegram gateway: progress-card: onTurnComplete firing turnKey=${cs.turnKey}\n`)
+      emitCardEvent({
+        agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+        chatId: cs.chatId ?? '',
+        turnKey: cs.turnKey,
+        event: 'finalized',
+        reason: 'onTurnComplete',
+      })
       try {
         config.onTurnComplete({
           chatId: cs.chatId,
@@ -1050,6 +1107,13 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
     if (hasAnyRunningSubAgent(cs.state)) return
     if (hasLiveBackground(cs.fleet)) return
     process.stderr.write(`telegram gateway: progress-card: deferred completion firing turnKey=${cs.turnKey} (last sub-agent finished)\n`)
+    emitCardEvent({
+      agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+      chatId: cs.chatId ?? '',
+      turnKey: cs.turnKey,
+      event: 'force-completed',
+      reason: 'deferred-completion: last sub-agent finished',
+    })
     // Route through the unified close path (turn-end reason) so the
     // prelude (silentEnd suppression, final flush, tail cleanup) matches
     // every other completion site.
@@ -1505,27 +1569,45 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
     // Suppress the card entirely if the turn ends before the initial
     // delay has elapsed — no point flashing a "Working…" card for a
     // turn that completed in under initialDelayMs.
-    if (chatState.isFirstEmit && initialDelayMs > 0 && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED) {
+    const effectiveDelayMs = chatState.effectiveInitialDelayMs
+    if (chatState.isFirstEmit && effectiveDelayMs > 0 && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED) {
       if (forceDone || chatState.state.stage === 'done') {
         // Turn ended before the card was ever shown — suppress it.
         if (chatState.deferredFirstEmitTimer != null) {
           clearT(chatState.deferredFirstEmitTimer)
           chatState.deferredFirstEmitTimer = null
         }
-        process.stderr.write(`telegram gateway: progress-card: fast-turn suppression turnKey=${chatState.turnKey} (turn ended before initialDelayMs=${initialDelayMs}ms)\n`)
+        process.stderr.write(`telegram gateway: progress-card: fast-turn suppression turnKey=${chatState.turnKey} (turn ended before initialDelayMs=${effectiveDelayMs}ms)\n`)
+        emitCardEvent({
+          agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+          chatId: chatState.chatId ?? '',
+          turnKey: chatState.turnKey,
+          event: 'suppressed',
+          reason: `fast-turn: ended before initialDelayMs=${effectiveDelayMs}`,
+        })
         return
       }
-      // Defer the first emit — schedule it for initialDelayMs from now
-      // if not already scheduled.
+      // Defer the first emit — schedule it for the per-chat budget from
+      // turn start if not already scheduled. Uses
+      // `chatState.effectiveInitialDelayMs` so the #842 background-
+      // dispatch bypass (which lowers this number on tool_use) takes
+      // effect on the very next flush.
       if (chatState.deferredFirstEmitTimer == null) {
         const capturedTurnKey = chatState.turnKey
-        process.stderr.write(`telegram gateway: progress-card: scheduled initial-delay timer turnKey=${capturedTurnKey} delay=${initialDelayMs}ms\n`)
+        // Schedule from turn start, not from now — multiple flush
+        // attempts during the buffering window must not push the
+        // first-emit clock back.
+        const elapsed = chatState.state.turnStartedAt > 0
+          ? Math.max(0, now() - chatState.state.turnStartedAt)
+          : 0
+        const remaining = Math.max(0, effectiveDelayMs - elapsed)
+        process.stderr.write(`telegram gateway: progress-card: scheduled initial-delay timer turnKey=${capturedTurnKey} delay=${remaining}ms budget=${effectiveDelayMs}ms\n`)
         chatState.deferredFirstEmitTimer = setT(() => {
           if (!chats.has(capturedTurnKey)) return
           chatState.deferredFirstEmitTimer = DELAY_ELAPSED
           process.stderr.write(`telegram gateway: progress-card: initial-delay timer fired turnKey=${capturedTurnKey}\n`)
           flush(chatState, false)
-        }, initialDelayMs)
+        }, remaining)
       }
       return
     }
@@ -1613,6 +1695,18 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
         ? { replyToMessageId: chatState.replyToMessageId }
         : {}),
     })
+    // #card-audit-log: structured lifecycle entry for retroactive audit.
+    // Mirrors the existing free-text traces but is grep-able by turnKey.
+    emitCardEvent({
+      agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+      chatId: chatState.chatId ?? '',
+      turnKey: chatState.turnKey,
+      event: isFirst ? 'rendered' : (terminal ? 'finalized' : 'edited'),
+      reason: terminal ? 'flush-terminal' : (isFirst ? 'flush-first' : 'flush-edit'),
+      htmlHash: html.length > 0
+        ? createHash('sha1').update(html).digest('hex').slice(0, 12)
+        : undefined,
+    })
   }
 
   /**
@@ -1758,6 +1852,7 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
           role,
           startedAt: now(),
           originatingTurnKey: currentTurnKey ?? cs.turnKey,
+          isBackgroundDispatch: isBackground,
         })
         cs.fleet.set(event.agentId, isBackground ? { ...member, status: 'background' } : member)
         return
@@ -1813,6 +1908,9 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
         // a stuck condition. `originatingTurnKey` has no legacy
         // counterpart — fall back to the current/active turn.
         const startedAt = sa.startedAt > 0 ? sa.startedAt : now()
+        const isBg =
+          sa.parentToolUseId != null &&
+          cs.backgroundParentToolUseIds.has(sa.parentToolUseId)
         cs.fleet.set(
           agentId,
           createFleetMember({
@@ -1820,6 +1918,7 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
             role: sa.description ?? 'agent',
             startedAt,
             originatingTurnKey: currentTurnKey ?? cs.turnKey,
+            isBackgroundDispatch: isBg,
           }),
         )
       }
@@ -1979,6 +2078,7 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
           pendingTimer: null,
           isFirstEmit: true,
           deferredFirstEmitTimer: null,
+          effectiveInitialDelayMs: initialDelayMs,
           timePromoteTimer: null,
           lastEventAt: now(),
           pendingCompletion: false,
@@ -2125,6 +2225,60 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
         promoteFirstEmit(chatState, 'sub_agent_started')
       }
 
+      // #842: explicit background dispatch bypass. When the parent calls
+      // `Agent({ run_in_background: true })`, swap the active delay
+      // budget over to `initialDelayMsBackground` instead of the longer
+      // `initialDelayMs`. Detection: an Agent/Task tool_use whose
+      // `event.input.run_in_background === true` (the same flag
+      // `updateFleetForEvent` uses to populate
+      // `cs.backgroundParentToolUseIds` for fleet membership).
+      //
+      // - `initialDelayMsBackground === 0` (default) → promote now.
+      // - `initialDelayMsBackground > 0` → set
+      //   `cs.effectiveInitialDelayMs` so the next flush() schedules
+      //   (or reschedules) the deferred timer at the lower budget.
+      //   Never lengthens an existing budget.
+      if (
+        event.kind === 'tool_use'
+        && (event.toolName === 'Agent' || event.toolName === 'Task')
+        && event.toolUseId != null
+        && event.input?.run_in_background === true
+        && chatState.isFirstEmit
+        && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED
+        && !chatState.apiFailures.terminal
+      ) {
+        if (initialDelayMsBackground <= 0) {
+          promoteFirstEmit(chatState, 'background_dispatch')
+        } else if (initialDelayMsBackground < chatState.effectiveInitialDelayMs) {
+          chatState.effectiveInitialDelayMs = initialDelayMsBackground
+          // If a longer-budget timer is already scheduled, cancel and
+          // reschedule against the new budget. Compute the remaining
+          // gap from turn start; if we're already past it, promote.
+          if (chatState.deferredFirstEmitTimer != null) {
+            const elapsed = now() - chatState.state.turnStartedAt
+            const remaining = initialDelayMsBackground - elapsed
+            clearT(chatState.deferredFirstEmitTimer)
+            if (remaining <= 0) {
+              chatState.deferredFirstEmitTimer = null
+              promoteFirstEmit(chatState, 'background_dispatch_elapsed')
+            } else {
+              const capturedTurnKey = chatState.turnKey
+              process.stderr.write(
+                `telegram gateway: progress-card: rescheduled initial-delay timer turnKey=${capturedTurnKey} delay=${remaining}ms reason=background_dispatch\n`,
+              )
+              chatState.deferredFirstEmitTimer = setT(() => {
+                if (!chats.has(capturedTurnKey)) return
+                chatState.deferredFirstEmitTimer = DELAY_ELAPSED
+                process.stderr.write(
+                  `telegram gateway: progress-card: initial-delay timer fired turnKey=${capturedTurnKey} reason=background_dispatch\n`,
+                )
+                flush(chatState, false)
+              }, remaining)
+            }
+          }
+        }
+      }
+
       // #478 / #553 PR 4: promote the card when the agent has issued
       // enough parent-side tool calls during the suppression window.
       // Disabled by default in v2 (promoteOnParentToolCount=0 / Infinity)
@@ -2250,6 +2404,14 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
               if (m.status === 'background' && m.terminalAt == null) background.push(k)
             }
             process.stderr.write(`telegram gateway: progress-card: turn_end deferred turnKey=${chatState.turnKey} reason=in-flight-sub-agents correlated=${correlated.length} orphans=${orphans.length} background=${background.length} correlatedAgentIds=[${correlated.join(',')}] orphanAgentIds=[${orphans.join(',')}] backgroundAgentIds=[${background.join(',')}]\n`)
+            emitCardEvent({
+              agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+              chatId: chatState.chatId ?? '',
+              turnKey: chatState.turnKey,
+              event: 'deferred',
+              reason: `turn_end: in-flight-sub-agents correlated=${correlated.length} orphans=${orphans.length} background=${background.length}`,
+              subagents: [...correlated, ...orphans, ...background],
+            })
             return
           }
           closePerChat(chatState, 'turn-end')
@@ -2363,6 +2525,13 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
       // running sub-agents just because the final reply was sent.
       if (target.completionFired) return
       process.stderr.write(`telegram gateway: progress-card: forceCompleteTurn turnKey=${target.turnKey} (external completion signal, e.g. stream_reply done=true)\n`)
+      emitCardEvent({
+        agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
+        chatId: target.chatId ?? '',
+        turnKey: target.turnKey,
+        event: 'force-completed',
+        reason: 'external completion signal (stream_reply done=true)',
+      })
       const durationMs = Math.max(0, now() - target.state.turnStartedAt)
       beginTurnEnd(target, durationMs)
       target.lastEventAt = now()
@@ -2678,6 +2847,26 @@ export function createProgressDriver(config: ProgressDriverConfig): ProgressDriv
       }
     },
 
+    onSubAgentUnstall(agentId: string, _description: string) {
+      // Symmetric to onSubAgentStall: watcher saw JSONL activity return.
+      // The standard event path has already bumped sa.lastEventAt and
+      // (for tool events) flipped fleet member status stuck→running via
+      // applyToolUse. All this method needs to do is force a re-render
+      // so the ⚠ badge clears immediately — the diff-guard can otherwise
+      // suppress the heartbeat for several seconds if no chat-level
+      // state changed, which manifests as the badge lingering even
+      // though the underlying state is fresh.
+      for (const cs of chats.values()) {
+        if (!cs.state.subAgents.has(agentId)) continue
+        const sa = cs.state.subAgents.get(agentId)!
+        if (sa.state !== 'running') continue
+        lastHeartbeatBucket.delete(cs.turnKey)
+        lastSubAgentTickBucket.delete(cs.turnKey)
+        if (chats.size > 0) startHeartbeatIfNeeded()
+        break
+      }
+    },
+
     /**
      * Test-only accessor. Returns the live internal Maps so tests can
      * assert TTL eviction and outer-base-key cleanup actually drop

package/telegram-plugin/progress-card.ts

@@ -504,7 +504,7 @@ export function reduce(
         id: state.items.length,
         toolUseId: event.toolUseId ?? null,
         tool: event.toolName,
-        label: toolLabel(event.toolName, event.input, preamble),
+        label: toolLabel(event.toolName, event.input, preamble, event.precomputedLabel),
         humanAuthored: isHumanDescription(event.toolName, event.input),
         state: 'running',
         startedAt: now,
@@ -833,7 +833,7 @@ export function reduce(
         currentTool: event.toolUseId
           ? {
               tool: event.toolName,
-              label: toolLabel(event.toolName, event.input, preamble),
+              label: toolLabel(event.toolName, event.input, preamble, event.precomputedLabel),
               humanAuthored: isHumanDescription(event.toolName, event.input),
               toolUseId: event.toolUseId,
               startedAt: now,

package/telegram-plugin/quota-check.ts

@@ -358,6 +358,7 @@ export async function fetchAccountQuota(
       writeAccountQuota(
         label,
         snapshotFromQuotaUtilization(result.data, new Date(now)),
+        opts.home,
       );
     } catch {
       /* best-effort */

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

@@ -24,6 +24,9 @@
  *
  * Status transitions:
  *   running → stalled     (via recordSubagentStall — no ended_at, may resume)
+ *   stalled → running     (via recordSubagentResume — JSONL activity returned
+ *                          before terminal; closes the resume edge the watcher
+ *                          documented but never wired)
  *   running → completed   (via recordSubagentEnd)
  *   running → failed      (via recordSubagentEnd)
  *   stalled → completed   (via recordSubagentEnd — terminal beats stalled)
@@ -139,6 +142,14 @@ export interface BumpSubagentActivityArgs {
   ts: number
 }
 
+export interface RecordSubagentResumeArgs {
+  id: string
+  /** Wall-clock when the resume was observed. Not stored — last_activity_at
+   *  is updated separately by bumpSubagentActivity. Available for callers
+   *  that want to log it. */
+  resumedAt: number
+}
+
 export interface ReapStuckRunningArgs {
   /**
    * Maximum age (ms since `last_activity_at`, or since `started_at` for rows
@@ -458,6 +469,32 @@ export function reapStuckRunningRows(
   return { reaped: candidates.length, ids: candidates.map((r) => r.id) }
 }
 
+/**
+ * Reverse the stalled→running edge when JSONL activity returns. Mirror of
+ * `recordSubagentStall` for the resume direction the schema doc has always
+ * promised but the watcher never implemented (the cause of "card freezes
+ * at ⚠ Stalled even after sub-agent resumes / completes" — see
+ * subagent-watcher.ts checkStalls + bumpSubagentActivity).
+ *
+ * Idempotent + safe:
+ *   - Only flips rows where status is currently 'stalled'. A row that's
+ *     already 'running' is untouched (no-op UPDATE). A terminal row
+ *     ('completed' / 'failed') stays terminal — terminal beats both
+ *     stalled and running.
+ *   - No-ops gracefully if `id` is not found.
+ *   - last_activity_at is NOT touched here — callers separately call
+ *     bumpSubagentActivity for the activity bump on the same tick.
+ */
+export function recordSubagentResume(db: SqliteDatabase, args: RecordSubagentResumeArgs): void {
+  void args.resumedAt // available for log lines; not persisted (started_at + last_activity_at carry the timing)
+  db.prepare(`
+    UPDATE subagents
+    SET status = 'running'
+    WHERE id = ?
+      AND status = 'stalled'
+  `).run(args.id)
+}
+
 /**
  * Bump `last_activity_at` for a subagent. Used by the watcher (Phase 3) each
  * time the subagent's JSONL file mtime advances.

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

@@ -24,6 +24,7 @@ import {
   recordSubagentStart,
   recordSubagentEnd,
   recordSubagentStall,
+  recordSubagentResume,
   bumpSubagentActivity,
   getSubagent,
   reapStuckRunningRows,
@@ -230,6 +231,69 @@ describe('start → stall → end', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// Test 4b — recordSubagentResume (stalled → running edge)
+// ---------------------------------------------------------------------------
+//
+// The schema doc (subagents-schema.ts:26) has always promised
+// "running → stalled (may resume)" but the resume edge wasn't
+// implemented — leaving the registry stuck at 'stalled' even when
+// JSONL activity returned. recordSubagentResume closes that gap.
+
+describe('recordSubagentResume — stalled → running edge', () => {
+  it('flips a stalled row back to running', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, { id: 'sa-r1', background: false, startedAt: 1000 })
+    recordSubagentStall(db, { id: 'sa-r1', stalledAt: 1500 })
+    expect(getSubagent(db, 'sa-r1')!.status).toBe('stalled')
+    recordSubagentResume(db, { id: 'sa-r1', resumedAt: 2000 })
+    const row = getSubagent(db, 'sa-r1')
+    expect(row!.status).toBe('running')
+    expect(row!.ended_at).toBeNull()
+    db.close()
+  })
+
+  it('is a no-op on a row that is already running', () => {
+    // Idempotency: the watcher fires resume on the first activity tick
+    // after a stall, but the same code path is also reached during
+    // normal activity bumps where stallNotified is already false. We
+    // never want a redundant resume to spuriously demote a row.
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, { id: 'sa-r2', background: false, startedAt: 1000 })
+    recordSubagentResume(db, { id: 'sa-r2', resumedAt: 2000 })
+    expect(getSubagent(db, 'sa-r2')!.status).toBe('running')
+    db.close()
+  })
+
+  it('is a no-op on a completed row — terminal beats resume', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, { id: 'sa-r3', background: false, startedAt: 1000 })
+    recordSubagentEnd(db, { id: 'sa-r3', endedAt: 2000, status: 'completed' })
+    recordSubagentResume(db, { id: 'sa-r3', resumedAt: 3000 })
+    const row = getSubagent(db, 'sa-r3')
+    expect(row!.status).toBe('completed')
+    expect(row!.ended_at).toBe(2000)
+    db.close()
+  })
+
+  it('is a no-op on a failed row', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, { id: 'sa-r4', background: false, startedAt: 1000 })
+    recordSubagentEnd(db, { id: 'sa-r4', endedAt: 2000, status: 'failed' })
+    recordSubagentResume(db, { id: 'sa-r4', resumedAt: 3000 })
+    expect(getSubagent(db, 'sa-r4')!.status).toBe('failed')
+    db.close()
+  })
+
+  it('is a no-op on a missing row (graceful)', () => {
+    const db = openFreshSubagentsDbInMemory()
+    expect(() =>
+      recordSubagentResume(db, { id: 'sa-nope', resumedAt: 1000 }),
+    ).not.toThrow()
+    db.close()
+  })
+})
+
 // ---------------------------------------------------------------------------
 // Test 5 — Duplicate start is a no-op
 // ---------------------------------------------------------------------------

package/telegram-plugin/session-tail.ts

@@ -36,6 +36,7 @@ import { homedir } from 'os'
 import { basename, join } from 'path'
 import { isMultiAgentEnabled } from './progress-card.js'
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
+import { createToolLabelSidecar, type ToolLabelSidecar } from './tool-label-sidecar.js'
 
 /** Match Claude Code's cli.js VX() function. */
 export function sanitizeCwdToProjectName(cwd: string): string {
@@ -86,7 +87,7 @@ export type SessionEvent =
   | { kind: 'enqueue'; chatId: string | null; messageId: string | null; threadId: string | null; rawContent: string; isSync?: boolean }
   | { kind: 'dequeue' }
   | { kind: 'thinking' }
-  | { kind: 'tool_use'; toolName: string; toolUseId?: string | null; input?: Record<string, unknown> }
+  | { kind: 'tool_use'; toolName: string; toolUseId?: string | null; input?: Record<string, unknown>; precomputedLabel?: string }
   | { kind: 'text'; text: string }
   | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
   | { kind: 'turn_end'; durationMs: number }
@@ -94,7 +95,7 @@ export type SessionEvent =
   // filename stem (e.g. "aac6f1…"). Routed through the same ingest path
   // as parent events; the reducer fans them out to per-sub-agent state.
   | { kind: 'sub_agent_started'; agentId: string; firstPromptText: string; subagentType?: string }
-  | { kind: 'sub_agent_tool_use'; agentId: string; toolUseId: string | null; toolName: string; input?: Record<string, unknown> }
+  | { kind: 'sub_agent_tool_use'; agentId: string; toolUseId: string | null; toolName: string; input?: Record<string, unknown>; precomputedLabel?: string }
   | { kind: 'sub_agent_text'; agentId: string; text: string }
   | { kind: 'sub_agent_narrative'; agentId: string; text: string }
   | { kind: 'sub_agent_tool_result'; agentId: string; toolUseId: string; isError?: boolean; errorText?: string }
@@ -499,11 +500,53 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
   const projectsDir = getProjectsDirForCwd(cwd, claudeHome)
   const rescanMs = config.rescanIntervalMs ?? 500
   const log = config.log
-  const onEvent = config.onEvent
+  const rawOnEvent = config.onEvent
   const onOperatorEvent = config.onOperatorEvent
 
   log?.(`session-tail: projectsDir=${projectsDir}`)
 
+  // PreToolUse sidecar readers (#783) keyed by sessionId. Created lazily
+  // the first time we observe a tool_use / sub_agent_tool_use whose
+  // toolUseId could be looked up. The hook writes to
+  // $TELEGRAM_STATE_DIR/tool-labels-<session_id>.jsonl. Each sub-agent
+  // has its OWN sessionId (its jsonl filename stem), so we key by that.
+  const sidecars = new Map<string, ToolLabelSidecar>()
+  const stateDirForSidecar = process.env.TELEGRAM_STATE_DIR ?? null
+  function sessionIdForFile(file: string | null): string | null {
+    if (!file) return null
+    const b = file.endsWith('.jsonl') ? basename(file, '.jsonl') : null
+    return b && b.length > 0 ? b : null
+  }
+  function ensureSidecar(sessionId: string): ToolLabelSidecar | null {
+    if (!stateDirForSidecar) return null
+    const existing = sidecars.get(sessionId)
+    if (existing) return existing
+    try {
+      const s = createToolLabelSidecar({ stateDir: stateDirForSidecar, sessionId })
+      sidecars.set(sessionId, s)
+      return s
+    } catch (err) {
+      log?.(`session-tail: sidecar create failed: ${(err as Error).message}`)
+      return null
+    }
+  }
+  function decorate(ev: SessionEvent, sessionId: string | null): SessionEvent {
+    if (!sessionId) return ev
+    if (ev.kind !== 'tool_use' && ev.kind !== 'sub_agent_tool_use') return ev
+    if (!ev.toolUseId) return ev
+    const s = ensureSidecar(sessionId)
+    if (!s) return ev
+    // One quick poll attempt before lookup — the hook is synchronous from
+    // Claude Code's perspective and the sidecar line is typically on disk
+    // before the JSONL row is appended, but the file watcher is on a
+    // 250ms tick. Forcing a poll closes the race for the common case.
+    s.poll()
+    const label = s.getLabel(ev.toolUseId)
+    if (!label) return ev
+    return { ...ev, precomputedLabel: label }
+  }
+  const onEvent = (ev: SessionEvent): void => rawOnEvent(ev)
+
   let currentFile: string | null = null
   let cursor = 0 // byte offset of next read
   let watcher: FSWatcher | null = null
@@ -550,9 +593,10 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
       for (const line of lines) {
         if (!line) continue
         const events = projectTranscriptLine(line)
+        const sid = sessionIdForFile(currentFile)
         for (const ev of events) {
           try {
-            onEvent(ev)
+            onEvent(decorate(ev, sid))
           } catch (err) {
             log?.(`session-tail: onEvent threw: ${(err as Error).message}`)
           }
@@ -721,7 +765,12 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
             t.hasSeenTerminal = true
           }
           try {
-            onEvent(ev)
+            // Sub-agent JSONLs have their own sessionId (the file's stem
+            // — sub-agent files are typically named agent-<id>.jsonl).
+            // Hook fires inside the sub-agent process with that
+            // session_id, so we look up the sidecar by it.
+            const subSid = sessionIdForFile(t.file)
+            onEvent(decorate(ev, subSid))
           } catch (err) {
             log?.(`session-tail: sub onEvent threw: ${(err as Error).message}`)
           }
@@ -872,6 +921,10 @@ export function startSessionTail(config: SessionTailConfig): SessionTailHandle {
         }
       }
       subTails.clear()
+      for (const s of sidecars.values()) {
+        try { s.stop() } catch { /* ignore */ }
+      }
+      sidecars.clear()
       if (pollTimer) {
         clearInterval(pollTimer)
         pollTimer = null