switchroom 0.7.15 → 0.10.0

package/telegram-plugin/gateway/startup-network-retry.ts

@@ -1,5 +1,6 @@
 /**
- * Bounded exponential-backoff retry for gateway startup network errors.
+ * Bounded exponential-backoff retry for gateway startup network errors,
+ * with classification of the failure mode so the caller can act.
  *
  * On 2026-04-29 all five switchroom gateways silently broke at boot because
  * `api.telegram.org` was unreachable for ~27 minutes after system boot (the
@@ -9,22 +10,29 @@
  * process alive but not polling. No crash, so systemd's `Restart=always` never
  * fired. Telegram → agent delivery was dead until manual restarts.
  *
- * This module provides:
- *
- *   `isBootNetworkError(err)`  — recognises network-layer errors thrown by
- *       grammy's HttpError wrapper and by raw fetch/Node network failures.
+ * Then issue #1076: a *revoked or wrong-typed* bot token returns Telegram API
+ * 401 `Unauthorized`. Pre-fix `gatewayStartupRetry` rethrew non-network errors
+ * immediately, the surrounding gateway catch block exited 1, the in-container
+ * `_switchroom_supervise` respawned, the new gateway re-hit 401, repeat. Ten
+ * restarts in <60 s tripped the supervisor cap and the gateway went silently
+ * dead with no operator-visible signal. This module now distinguishes 401 as
+ * a permanent config error, which the gateway handles by writing an issue +
+ * quarantine marker + exit-78 (the supervisor's "config error, don't
+ * restart" sentinel — see profiles/_base/start.sh.hbs).
  *
- *   `STARTUP_RETRY_DELAYS_MS`  — the chosen backoff schedule.
+ * This module provides:
  *
- *   `gatewayStartupRetry(fn, opts)` — drives the retry loop. Calls `fn()` up to
- *       `maxAttempts` times with delays from `delaysMs`. On success it resolves.
- *       On exhaustion it calls `opts.onExhausted()` (default: `process.exit(1)`)
- *       so systemd's `Restart=always` can restart the unit cleanly.
+ *   `classifyStartupError(err)` — returns `'network' | 'unauthorized' | 'other'`.
+ *   `isBootNetworkError(err)` — back-compat alias for the network arm.
+ *   `STARTUP_RETRY_DELAYS_MS` — the chosen backoff schedule.
+ *   `gatewayStartupRetry(fn, opts)` — drives the retry loop.
  *
  * The function is extracted from `gateway.ts`'s top-level IIFE so it can be
  * unit-tested without spinning up the full bot runtime.
  */
 
+export type StartupErrorKind = 'network' | 'unauthorized' | 'other'
+
 export interface StartupRetryOpts {
   /**
    * Delay schedule in milliseconds. Each attempt waits the corresponding
@@ -39,11 +47,23 @@ export interface StartupRetryOpts {
   sleep?: (ms: number) => Promise<void>
 
   /**
-   * Called when all attempts are exhausted. Should NOT return (exit/throw).
-   * Defaults to `process.exit(1)`.
+   * Called when all NETWORK retries are exhausted. Should NOT return
+   * (exit/throw). Defaults to `process.exit(1)` so systemd /
+   * `_switchroom_supervise` restart-on-failure can recycle the unit.
    */
   onExhausted?: (lastError: unknown) => never
 
+  /**
+   * Called when a startup API call returns 401 Unauthorized. The bot token
+   * is permanently wrong (revoked, wrong type, typo) — retrying just burns
+   * the supervisor restart budget. Caller should write an issue + quarantine
+   * marker and `process.exit(78)` (EX_CONFIG). Should NOT return.
+   *
+   * Default: same exit-1 path as `onExhausted` so callers that haven't been
+   * updated keep the pre-fix behaviour (rather than silently swallowing 401).
+   */
+  onUnauthorized?: (err: unknown) => never
+
   /** Log sink for retry progress messages. Defaults to process.stderr.write. */
   log?: (line: string) => void
 }
@@ -67,38 +87,83 @@ const DEFAULT_SLEEP = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms))
 
 /**
- * Returns true if `err` is a transient network-level failure that the startup
- * retry loop should absorb. Covers:
+ * Classify a startup-time error into one of:
  *
- * - Grammy's `HttpError` (name === 'HttpError'), which wraps fetch/ECONN errors
- *   during `deleteWebhook` and `getMe`.
- * - Raw Node/fetch errors: ECONNRESET, ETIMEDOUT, ENOTFOUND, ECONNREFUSED,
- *   fetch failed, etc.
+ *   - `network`: transient connectivity / DNS / TCP / fetch failure — the
+ *     retry loop should absorb these with backoff.
+ *   - `unauthorized`: Telegram API 401 (revoked or wrong-typed bot token).
+ *     Permanent until the operator rotates the token. Retrying compounds
+ *     the supervisor restart budget for no gain — see #1076.
+ *   - `other`: everything else (bad request shape, 5xx, server bug, etc.).
+ *     Rethrown to the surrounding gateway catch block, which exits non-zero
+ *     so the supervisor can recycle.
+ *
+ * Grammy surfaces 401 via `GrammyError` (name === 'GrammyError') with
+ * `error_code === 401`. Some test fixtures and node-fetch wrappers surface
+ * 401 only in the message string, so we fall through to a substring match
+ * for `Unauthorized` as defence in depth.
  */
-export function isBootNetworkError(err: unknown): boolean {
-  if (!(err instanceof Error)) return false
-  // Grammy wraps network errors in HttpError (name is set in the constructor)
-  if (err.name === 'HttpError') return true
+export function classifyStartupError(err: unknown): StartupErrorKind {
+  if (!(err instanceof Error)) return 'other'
+
+  // Unauthorized (#1076). Check BEFORE the network arm so a Grammy-wrapped
+  // 401 doesn't accidentally match the "Network request" substring branch
+  // through some future change to grammy's error stringification.
+  const errAny = err as Error & {
+    error_code?: number
+    name?: string
+  }
+  if (
+    errAny.name === 'GrammyError' &&
+    errAny.error_code === 401
+  ) {
+    return 'unauthorized'
+  }
+  // Fall-back string match. Telegram's API returns the literal token
+  // 'Unauthorized' for 401 in the description field. We avoid a substring
+  // of just '401' here because that can match unrelated error codes /
+  // ports / numeric content.
+  if (err.message.includes('Unauthorized')) return 'unauthorized'
+
+  // Network arm — grammy wraps fetch/ECONN errors in HttpError.
+  if (err.name === 'HttpError') return 'network'
   const msg = err.message
-  return (
+  if (
     msg.includes('ECONNRESET') ||
     msg.includes('ETIMEDOUT') ||
     msg.includes('ENOTFOUND') ||
     msg.includes('ECONNREFUSED') ||
     msg.includes('fetch failed') ||
     msg.includes('Network request')
-  )
+  ) {
+    return 'network'
+  }
+
+  return 'other'
+}
+
+/**
+ * Returns true if `err` is a transient network-level failure that the startup
+ * retry loop should absorb. Retained as a named export for the existing
+ * regression tests and downstream callers that only care about the network
+ * arm. Prefer `classifyStartupError` for new code.
+ */
+export function isBootNetworkError(err: unknown): boolean {
+  return classifyStartupError(err) === 'network'
 }
 
 /**
- * Attempt `fn()` and retry on `isBootNetworkError` failures using the
- * provided delay schedule.
+ * Attempt `fn()` and retry on network failures using the provided delay
+ * schedule.
  *
  * - On success: returns whatever `fn()` resolved to.
- * - On non-network error: re-throws immediately (not a transient boot issue).
- * - On exhausted retries: calls `opts.onExhausted(lastError)` which must not
- *   return (it should exit or throw). The default is `process.exit(1)` so
- *   systemd's `Restart=always` picks up the dead unit.
+ * - On unauthorized (401): calls `opts.onUnauthorized(err)` which must not
+ *   return. The gateway uses this to write an issue + quarantine marker
+ *   + `process.exit(78)`. Default is `process.exit(1)` for back-compat.
+ * - On other non-network error: re-throws immediately (not a transient
+ *   boot issue, not a known config error).
+ * - On exhausted network retries: calls `opts.onExhausted(lastError)` which
+ *   must not return. Default is `process.exit(1)`.
  */
 export async function gatewayStartupRetry<T>(
   fn: () => Promise<T>,
@@ -114,6 +179,16 @@ export async function gatewayStartupRetry<T>(
       )
       process.exit(1)
     })
+  const onUnauthorized: (err: unknown) => never =
+    opts.onUnauthorized ??
+    ((err: unknown) => {
+      // Back-compat default. Real callers (gateway.ts) override this with
+      // an issue-sink writer + quarantine-marker writer + exit-78.
+      process.stderr.write(
+        `telegram gateway: startup unauthorized (bot token rejected) — exiting: ${(err as Error).message}\n`,
+      )
+      process.exit(1)
+    })
   const log =
     opts.log ??
     ((line: string) => {
@@ -127,7 +202,10 @@ export async function gatewayStartupRetry<T>(
     try {
       return await fn()
     } catch (err) {
-      if (!isBootNetworkError(err)) throw err
+      const kind = classifyStartupError(err)
+      if (kind === 'unauthorized') return onUnauthorized(err)
+      if (kind === 'other') throw err
+      // network
       lastError = err
       if (attempt >= maxAttempts) break
       const delayMs = delays[attempt - 1]

package/telegram-plugin/gateway/vault-grant-inbound-builders.ts

@@ -0,0 +1,125 @@
+/**
+ * Pure builders for the synthetic `vault_grant_approved` and
+ * `vault_grant_denied` inbounds the gateway injects after the
+ * operator taps Approve / Deny on a `vault_request_access` card
+ * (#1052 / #1150).
+ *
+ * Extracted from `gateway.ts` so the InboundMessage shape is pinned
+ * by tests separate from the broker/IPC plumbing. The shape is
+ * load-bearing — it carries the `meta.source` field the bridge keys
+ * on when rendering `<channel source="vault_grant_approved">` /
+ * `<channel source="vault_grant_denied">` blocks for the model, and
+ * the `meta.{agent,key,scope,stage_id,operator_id}` fields that
+ * downstream filters / dashboards may anchor on.
+ *
+ * A regression that drops a meta field or changes the source string
+ * would silently break the agent's wake-up flow — the bridge wouldn't
+ * recognize the source and route as a generic channel event, the
+ * model wouldn't know it was an approval response, and the
+ * conversation would drift. Pinning the builders against fixture
+ * tests is cheaper than catching that downstream.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/** Subset of the pending-request state the builders need. Kept narrow
+ *  so callers don't have to pass the full PendingVaultRequestAccess. */
+export interface VaultGrantInboundContext {
+  agent: string
+  key: string
+  scope: 'read' | 'write'
+  /** Telegram chat id where the approval card lived. Used as the
+   *  inbound's chatId — keeps the synthesized turn associated with
+   *  the conversation that triggered the request. */
+  chat_id: string
+  /** Seconds. For approved grants; ignored for deny. */
+  ttl_seconds: number
+}
+
+/**
+ * Build the synthetic InboundMessage for a successful operator
+ * approval. Meta fields are pinned by tests.
+ *
+ * @param ctx              Per-request context (agent, key, scope, chat).
+ * @param grantId          Broker-returned grant id (e.g. "vg_a1b2c3").
+ * @param stageId          The card's stage id from the approval flow.
+ * @param operatorId       Telegram user id of the approving operator
+ *                         (string for portability — Telegram ids are
+ *                         numeric but routinely round-trip as strings).
+ * @param nowMs            Wall-clock ms. Used for both `ts` and
+ *                         `messageId` so the helper is deterministic
+ *                         under fake clock. Defaults to `Date.now()`.
+ */
+export function buildVaultGrantApprovedInbound(opts: {
+  ctx: VaultGrantInboundContext
+  grantId: string
+  stageId: string
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const days = Math.round(opts.ctx.ttl_seconds / 86400)
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: 'vault-broker',
+    userId: 0,
+    ts,
+    text:
+      `✅ Operator approved your vault access request for ` +
+      `\`${opts.ctx.key}\` (scope=${opts.ctx.scope}, ` +
+      `${days}d, grant=${opts.grantId}). ` +
+      `The token has been written. Please resume the task that was ` +
+      `waiting on this credential — fetch via the usual switchroom vault ` +
+      `get path.`,
+    meta: {
+      source: 'vault_grant_approved',
+      agent: opts.ctx.agent,
+      key: opts.ctx.key,
+      scope: opts.ctx.scope,
+      grant_id: opts.grantId,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  }
+}
+
+/**
+ * Build the synthetic InboundMessage for an operator denial.
+ *
+ * The text steers the model toward a fallback path (apologise, try a
+ * different approach, skip the feature) — added in #1156 alongside
+ * the buffer-on-disconnect fix because the deny side had the same
+ * agent-stays-idle bug as the approve side.
+ */
+export function buildVaultGrantDeniedInbound(opts: {
+  ctx: VaultGrantInboundContext
+  stageId: string
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    messageId: ts,
+    user: 'vault-broker',
+    userId: 0,
+    ts,
+    text:
+      `🚫 Operator denied your vault access request for ` +
+      `\`${opts.ctx.key}\` (scope=${opts.ctx.scope}). ` +
+      `The credential is unavailable — pick a fallback for the original task ` +
+      `(apologise to the user, try a different approach, or skip the feature). ` +
+      `Do NOT re-request this key without first asking the user.`,
+    meta: {
+      source: 'vault_grant_denied',
+      agent: opts.ctx.agent,
+      key: opts.ctx.key,
+      scope: opts.ctx.scope,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  }
+}

package/telegram-plugin/history.ts

@@ -195,6 +195,69 @@ export function _resetForTests(): void {
   }
 }
 
+/**
+ * Issue a WAL checkpoint on the history DB, releasing `*.db-wal` pages
+ * back to the main DB and truncating the WAL file. Called by the
+ * gateway's periodic reaper so the WAL doesn't grow unbounded in
+ * long-running agent sessions (issue #1073).
+ *
+ * Wrapped in try/catch — `PRAGMA wal_checkpoint(TRUNCATE)` can return
+ * SQLITE_BUSY under reader pressure, which bun:sqlite raises as a thrown
+ * error. That's non-fatal; the next reaper tick retries. Returns true
+ * on success, false on a swallowed error.
+ *
+ * No-op (returns false) if `initHistory` was never called.
+ */
+export function checkpointWal(): boolean {
+  if (db == null) return false
+  try {
+    db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').run()
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Prune `messages` rows older than `retentionDays`. Used by the periodic
+ * reaper (#1073) to catch the case where the gateway runs for weeks or
+ * months — the init-time prune only fires once at boot.
+ *
+ * Returns the number of rows deleted (sum across all batches). No-op
+ * if `retentionDays <= 0` or if `initHistory` was never called.
+ *
+ * Batched to keep transactions short; otherwise a years-old DB on first
+ * boot after an upgrade would lock the inbound write path for the duration
+ * of a single multi-million-row DELETE. Uses the rowid-subselect form
+ * because bun:sqlite is built without SQLITE_ENABLE_UPDATE_DELETE_LIMIT
+ * (same constraint as reaper.ts).
+ */
+export function pruneMessagesOlderThanDays(
+  retentionDays: number,
+  nowSec?: number,
+  batchLimit = 5000,
+): number {
+  if (db == null) return 0
+  if (retentionDays <= 0) return 0
+  const cutoffSec = (nowSec ?? Math.floor(Date.now() / 1000)) - retentionDays * 86400
+  const stmt = db.prepare(`
+    DELETE FROM messages
+    WHERE rowid IN (
+      SELECT rowid FROM messages WHERE ts < ? LIMIT ?
+    )
+  `)
+  let total = 0
+  // Same defence-in-depth ceiling as reaper.ts — caps a single call at
+  // 5M rows at the default batch size, more than any healthy fleet.
+  for (let i = 0; i < 1000; i++) {
+    const result = stmt.run(cutoffSec, batchLimit) as { changes: number }
+    const n = result.changes ?? 0
+    total += n
+    if (n === 0) break
+  }
+  return total
+}
+
 function requireDb(): SqliteDatabase {
   if (db == null) {
     throw new Error('history: initHistory() must be called before any record/query operation')
@@ -430,6 +493,34 @@ export function getLatestInboundMessageId(
   return row?.message_id ?? null
 }
 
+/**
+ * Look up the role + text of a single message by (chat_id, message_id).
+ * Returns `null` if no row exists (the message predates history, the
+ * row was reaped, or history is disabled). Used by the reaction-trigger
+ * handler (#1074) to decide whether a reacted-to message is bot-authored
+ * AND to pull the preview text for the synthesized inbound — both in
+ * one DB hit, so the trigger predicate doesn't need a Telegram API call
+ * per reaction.
+ *
+ * Telegram message_ids are unique within a chat regardless of thread,
+ * so we match on (chat_id, message_id) and ignore thread_id — same as
+ * recordEdit / recordReaction.
+ */
+export function lookupMessageRoleAndText(
+  chatId: string,
+  messageId: number,
+): { role: 'user' | 'assistant'; text: string } | null {
+  const row = requireDb()
+    .prepare(
+      `SELECT role, text FROM messages WHERE chat_id = ? AND message_id = ? LIMIT 1`,
+    )
+    .get(chatId, messageId) as
+    | { role: 'user' | 'assistant'; text: string | null }
+    | undefined
+  if (!row) return null
+  return { role: row.role, text: row.text ?? '' }
+}
+
 export function getRecentOutboundCount(
   chatId: string,
   withinSeconds: number,

package/telegram-plugin/hooks/hooks.json

@@ -40,6 +40,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/sandbox-hint-posttool.mjs\"",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "Stop": [

package/telegram-plugin/hooks/sandbox-hint-posttool.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — detects sandbox-related errors in tool_response and
+ * injects a one-line hint via Claude Code's `hookSpecificOutput.
+ * additionalContext` channel. The hint reminds the agent that the
+ * read-only file system / EROFS error is the switchroom sandbox working
+ * as intended, and that it should respond to the user with a concrete
+ * "Operator action: ..." line rather than retrying or echoing the raw
+ * kernel error.
+ *
+ * Pairs with the SANDBOX_GUIDANCE primer in --append-system-prompt
+ * (src/agents/scaffold.ts). The primer is the always-on context; this
+ * hook is the just-in-time nudge that fires only when the agent
+ * actually hits the boundary.
+ *
+ * Claude Code PostToolUse protocol:
+ *   stdin:  JSON { tool_name, tool_use_id, tool_input, tool_response, ... }
+ *   stdout: optional JSON
+ *             {"hookSpecificOutput":{"hookEventName":"PostToolUse",
+ *              "additionalContext":"<text>"}}
+ *           prepended to the model's next-turn context after the tool
+ *           result is shown.
+ *   exit:   0 always. Hook failures must never block the tool flow.
+ *
+ * Design notes:
+ *   - Detection is a substring/regex match against the stringified
+ *     tool_response (covers stdout, stderr, error fields).
+ *   - No DB writes, no IPC. Pure stdin → stdout, fail-silent.
+ *   - Idempotent: re-reading the same tool_response yields the same
+ *     hint. Claude Code dedupes additionalContext naturally because the
+ *     hook fires once per PostToolUse event.
+ */
+
+import { readFileSync } from 'node:fs'
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Patterns that indicate a sandbox-boundary hit, in order of specificity.
+ * Each entry: [regex, hint-key]. Hint text is composed below from the
+ * matched key — keeps the patterns easy to scan.
+ */
+const PATTERNS = [
+  // The canonical kernel error code + message. Covers most write/mkdir/
+  // rename/unlink failures against the read-only rootfs.
+  [/\bEROFS\b/, 'erofs'],
+  [/read[- ]only file ?system/i, 'erofs'],
+  // npm/pip install attempts that hit a read-only prefix. These usually
+  // surface as ENOENT or permission errors against /usr/lib/node_modules
+  // or /usr/local/lib — listing the explicit paths keeps us from
+  // false-matching on user code that legitimately mentions /usr.
+  [/EACCES.+\/(usr|opt|etc|bin|lib)\//, 'eacces-rootfs'],
+  // apt / dpkg refusing to write to /var/lib/dpkg etc.
+  [/dpkg.*permission denied|apt.*permission denied|Unable to acquire the dpkg/i, 'apt'],
+]
+
+function buildHint(key) {
+  const common =
+    'Sandbox boundary hit. The agent container has `read_only: true` rootfs ' +
+    '(see the SANDBOX primer in the system prompt). Do NOT retry the same ' +
+    'write. Tell the user what you tried, why the sandbox blocked it, and ' +
+    'name an operator action (e.g. "edit on host then `switchroom apply`", ' +
+    'or "add to docker/Dockerfile.agent and rebuild"). Writable paths: ' +
+    '$HOME (/state/agent/home), /tmp, /state/agent/**, /var/log/switchroom.'
+
+  if (key === 'apt') {
+    return (
+      common +
+      ' For package installs specifically: ask the operator to add the ' +
+      'package to docker/Dockerfile.agent and rebuild the agent image — ' +
+      'in-container apt is not the right path.'
+    )
+  }
+  return common
+}
+
+function emitContext(text) {
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: text,
+    },
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n')
+}
+
+function main() {
+  const raw = readStdin()
+  if (!raw) return
+
+  let evt
+  try {
+    evt = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  // tool_response shape varies by tool — string for Bash, object with
+  // file/oldString/newString for Edit/Write, etc. Stringify the whole
+  // thing so we match against every nested error field at once. Cap the
+  // scan window to keep memory bounded if the model just dumped a 10MB
+  // log into the tool_response.
+  let body
+  try {
+    body = JSON.stringify(evt.tool_response ?? '')
+  } catch {
+    return
+  }
+  if (!body) return
+  if (body.length > 64 * 1024) body = body.slice(0, 64 * 1024)
+
+  for (const [pattern, key] of PATTERNS) {
+    if (pattern.test(body)) {
+      emitContext(buildHint(key))
+      return
+    }
+  }
+}
+
+try {
+  main()
+} catch {
+  // Fail-silent. The PostToolUse must never block the tool flow.
+}

package/telegram-plugin/hooks/subagent-tracker-posttool.mjs

@@ -11,7 +11,13 @@
  * block the tool response.
  *
  * DB location: <agentDir>/telegram/registry.db
- *   agentDir = SWITCHROOM_AGENT_DIR env var, falling back to process.cwd()
+ *   agentDir lookup (first hit wins):
+ *     1. SWITCHROOM_AGENT_DIR env var (explicit override, mainly used in tests)
+ *     2. TELEGRAM_STATE_DIR with `/telegram` suffix stripped — the canonical
+ *        env var start.sh exports on every switchroom agent. See the
+ *        sibling pretool hook docblock for why this lookup matters (without
+ *        it the hook used to write to a registry.db nobody read).
+ *     3. process.cwd() (legacy fallback for ad-hoc invocations).
  *
  * Performance: the actual DB write is deferred via setImmediate (Node 22+
  * node:sqlite path) or non-blocking spawn (CLI fallback) so the hook returns
@@ -268,7 +274,18 @@ function main() {
   const id = event.tool_use_id ?? null
   if (!id) process.exit(0)
 
-  const agentDir = process.env.SWITCHROOM_AGENT_DIR ?? process.cwd()
+  // Same agent-dir resolution as the pretool hook (Bug 2 fix). Without
+  // the TELEGRAM_STATE_DIR derivation the posttool would write the
+  // `ended_at` row to a registry.db nobody reads, even though the row
+  // was originally inserted by the pretool hook that DID write to the
+  // correct DB (after this PR). Keep the two hooks in lock-step.
+  const stateDir = process.env.TELEGRAM_STATE_DIR
+  const derivedFromStateDir = stateDir && stateDir.endsWith('/telegram')
+    ? stateDir.slice(0, -'/telegram'.length)
+    : null
+  const agentDir = process.env.SWITCHROOM_AGENT_DIR
+    ?? derivedFromStateDir
+    ?? process.cwd()
   const dbPath = join(agentDir, 'telegram', 'registry.db')
 
   // If DB doesn't exist yet, nothing to update

package/telegram-plugin/hooks/subagent-tracker-pretool.mjs

@@ -11,7 +11,17 @@
  * block the tool call.
  *
  * DB location: <agentDir>/telegram/registry.db
- *   agentDir = SWITCHROOM_AGENT_DIR env var, falling back to process.cwd()
+ *   agentDir lookup (first hit wins):
+ *     1. SWITCHROOM_AGENT_DIR env var (explicit override, mainly used in tests)
+ *     2. TELEGRAM_STATE_DIR with `/telegram` suffix stripped — the canonical
+ *        env var start.sh exports for every switchroom agent (and the same
+ *        path the gateway + watcher resolve their DB through). Without this
+ *        the hook used to fall through to process.cwd() in production,
+ *        writing to a registry.db nobody read, leaving every bg sub-agent
+ *        invisible to the watcher. Surfaced by
+ *        bg-sub-agent-dispatch-dm.test.ts; see RFC Phase 2 §Bug 2 in
+ *        reference/sub-agent-visibility-rfc.md.
+ *     3. process.cwd() (legacy fallback for ad-hoc invocations).
  *
  * Performance: the actual DB write is deferred via setImmediate (Node 22+
  * node:sqlite path) or a non-blocking spawn (CLI fallback) so the hook
@@ -223,7 +233,17 @@ function main() {
   // misroute).
   if (event.tool_name !== 'Agent' && event.tool_name !== 'Task') process.exit(0)
 
-  const agentDir = process.env.SWITCHROOM_AGENT_DIR ?? process.cwd()
+  // Resolve agent dir: explicit env override → derive from TELEGRAM_STATE_DIR
+  // (start.sh exports this on every agent) → cwd fallback. The middle case
+  // is the production path; without it the hook silently wrote to a
+  // registry.db nobody read (#709 / #776 / #782 / #788 Bug 2).
+  const stateDir = process.env.TELEGRAM_STATE_DIR
+  const derivedFromStateDir = stateDir && stateDir.endsWith('/telegram')
+    ? stateDir.slice(0, -'/telegram'.length)
+    : null
+  const agentDir = process.env.SWITCHROOM_AGENT_DIR
+    ?? derivedFromStateDir
+    ?? process.cwd()
   const telegramDir = join(agentDir, 'telegram')
   const dbPath = join(telegramDir, 'registry.db')
 

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

@@ -111,6 +111,17 @@ export function computeLabel(toolName, input) {
     case 'KillBash':
     case 'KillShell':
       return 'Stopping background process'
+    case 'Skill': {
+      // The Skill tool's input is `{ skill: "<slug>", args?: "..." }`.
+      // We emit `Running skill <slug>` so downstream observers
+      // (notably the skill-coverage UAT runner at
+      // telegram-plugin/uat/runners/skill-coverage.ts) can tail the
+      // sidecar JSONL and recover which skill fired per turn —
+      // the progress card path that used to surface this was retired
+      // when `progressDriver` was nulled out in #1122 PR3.
+      const slug = clip(String(i.skill ?? ''), 64)
+      return slug ? `Running skill ${slug}` : null
+    }
   }
 
   // MCP allowlist.