switchroom 0.7.15 → 0.10.0

package/telegram-plugin/permission-title.ts

@@ -17,6 +17,45 @@ import { basename } from "node:path";
 const COMMAND_TITLE_MAX = 40;
 const PATH_TITLE_MAX = 40;
 
+/**
+ * Human-friendly descriptions for switchroom-managed MCP tools. The
+ * raw `mcp__<server>__<tool>` name is operator-unfriendly — they shouldn't
+ * have to decode the namespace to understand what the agent is asking
+ * to do. Use this map to turn the code-level identifier into a verb
+ * phrase ("Read its own merged config" instead of
+ * "mcp__agent-config__config_get") for the approval card.
+ *
+ * Note: post-#1215 these tools are pre-allowed in scaffolded
+ * settings.permissions.allow, so the card should fire rarely.
+ * This map is for the fallback path — agents the operator
+ * narrowed the allowlist on, or tools added in future PRs that
+ * haven't shipped the allowlist bump yet.
+ */
+const MCP_TOOL_DESCRIPTIONS: Record<string, string> = {
+  // agent-config — every agent's self-service surface (#1163, #1215)
+  "mcp__agent-config__config_get": "Read its own merged config",
+  "mcp__agent-config__cron_list": "List its own scheduled tasks",
+  "mcp__agent-config__skill_list": "List its own installed skills",
+  "mcp__agent-config__audit_tail": "Read its own recent tool-call audit log",
+  "mcp__agent-config__peers_list": "List the other agents on this instance",
+  "mcp__agent-config__schedule_add": "Add a scheduled task to its own cron",
+  "mcp__agent-config__schedule_remove": "Remove one of its own scheduled tasks",
+  "mcp__agent-config__skill_install": "Install a bundled skill onto itself",
+  "mcp__agent-config__skill_remove": "Remove one of its own installed skills",
+  // hostd — admin-flagged agents' fleet-management surface (#1175, #1215)
+  "mcp__hostd__agent_restart": "Restart an agent in the fleet",
+  "mcp__hostd__agent_start": "Start a stopped agent in the fleet",
+  "mcp__hostd__agent_stop": "Stop a running agent in the fleet",
+  "mcp__hostd__agent_logs": "Read another agent's container logs",
+  "mcp__hostd__agent_exec": "Run a read-only inspection inside another agent",
+  "mcp__hostd__update_check": "Check what a fleet-wide update would do",
+  "mcp__hostd__update_apply": "Apply a fleet-wide update (pull + recreate)",
+  // hindsight — memory
+  "mcp__hindsight__recall": "Recall relevant memories",
+  "mcp__hindsight__retain": "Retain a memory",
+  "mcp__hindsight__reflect": "Reflect across its memory bank",
+};
+
 /**
  * Build a title fragment for a permission prompt. Returns the toolName
  * for any tool we don't recognise — the helper is intentionally
@@ -27,6 +66,23 @@ export function summarizeToolForTitle(
   toolName: string,
   inputPreview: string | undefined,
 ): string {
+  // MCP tools: `mcp__<server>__<verb>`. Prefer a curated human
+  // description (so the card reads "Read its own merged config"
+  // instead of "mcp__agent-config__config_get"). Fall through to a
+  // generic `<server>: <verb-with-spaces>` shape for unknown MCP
+  // tools and finally to the raw name when even that fails.
+  if (toolName.startsWith("mcp__")) {
+    const curated = MCP_TOOL_DESCRIPTIONS[toolName];
+    if (curated) return curated;
+    const parts = toolName.split("__");
+    if (parts.length >= 3) {
+      const server = parts[1]!;
+      const verb = parts.slice(2).join("__").replace(/_/g, " ");
+      return `${server}: ${verb}`;
+    }
+    return toolName;
+  }
+
   const input = parseInput(inputPreview);
   if (!input) return toolName;
 

package/telegram-plugin/quota-check.ts

@@ -17,11 +17,13 @@
 
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
-import {
-  readAccountQuota,
-  snapshotFromQuotaUtilization,
-  writeAccountQuota,
-} from "../src/auth/account-quota-store.js";
+
+// RFC H: per-account quota state moved to switchroom-auth-broker
+// (state/auth-broker/quota.json). The gateway's in-process cache
+// below is still useful for sub-second formatting, but the disk-
+// persistence layer that account-quota-store provided is gone —
+// the broker owns the canonical store and exposes it via
+// `list-state`. Disk hydrate / disk persist below are no-ops.
 
 /**
  * OAuth beta flag — proves the request is coming from a subscription client.
@@ -350,20 +352,10 @@ export async function fetchAccountQuota(
     timeoutMs: opts.timeoutMs,
   });
   accountQuotaCache.set(label, { fetchedAt: now, result });
-  // Persist the snapshot to disk so a future gateway restart can
-  // re-hydrate its in-process cache without an API call. Best-effort
-  // (write errors swallowed inside writeAccountQuota). Issue #708.
-  if (result.ok) {
-    try {
-      writeAccountQuota(
-        label,
-        snapshotFromQuotaUtilization(result.data, new Date(now)),
-        opts.home,
-      );
-    } catch {
-      /* best-effort */
-    }
-  }
+  // Note: pre-RFC-H this also persisted to disk via writeAccountQuota
+  // (#708) so a gateway restart could re-hydrate without an API call.
+  // Post-RFC-H the broker holds canonical quota state and answers
+  // via `list-state`, so the gateway's in-process cache is enough.
   return result;
 }
 
@@ -381,29 +373,15 @@ export async function fetchAccountQuota(
  * prefetch will replace it on the next tap.
  */
 export function hydrateAccountQuotaCacheFromDisk(
-  labels: ReadonlyArray<string>,
-  home?: string,
+  _labels: ReadonlyArray<string>,
+  _home?: string,
 ): void {
-  for (const label of labels) {
-    if (accountQuotaCache.has(label)) continue;
-    const snap = readAccountQuota(label, home);
-    if (!snap) continue;
-    const fetchedAt = Date.parse(snap.capturedAt);
-    if (!Number.isFinite(fetchedAt)) continue;
-    const result: QuotaResult = {
-      ok: true,
-      data: {
-        fiveHourUtilizationPct: snap.fiveHourPct ?? 0,
-        sevenDayUtilizationPct: snap.sevenDayPct ?? 0,
-        fiveHourResetAt: snap.fiveHourResetAt ? new Date(snap.fiveHourResetAt) : null,
-        sevenDayResetAt: snap.sevenDayResetAt ? new Date(snap.sevenDayResetAt) : null,
-        representativeClaim: null,
-        overageStatus: null,
-        overageDisabledReason: null,
-      },
-    };
-    accountQuotaCache.set(label, { fetchedAt, result });
-  }
+  // No-op post-RFC-H. The disk-snapshot store this function used to
+  // re-hydrate from (per-account quota.json files under
+  // ~/.switchroom/accounts/<label>/) is gone — switchroom-auth-broker
+  // now owns canonical quota state. Boot-time hydration is the
+  // broker's `list-state` call instead. Signature preserved so
+  // existing call sites continue to compile while we phase them out.
 }
 
 /** Test/utility helper — wipe the per-account quota cache. The

package/telegram-plugin/registry/reaper.ts

@@ -0,0 +1,223 @@
+/**
+ * Registry reaper — prunes long-lived `subagents` and `turns` rows.
+ *
+ * Issue #1073. The init-time prune in `history.ts` only sweeps the `messages`
+ * table. `subagents` and `turns` in `registry.db` grew unbounded — a
+ * long-running agent accumulates a row per `Agent()` call and per turn
+ * forever. The SQLite WAL also grew without bound because no path issued
+ * a checkpoint.
+ *
+ * This module adds:
+ *
+ *   - `pruneSubagentsOlderThan(db, cutoffMs, batchLimit)` — batch DELETE on
+ *     `subagents` where `COALESCE(ended_at, last_activity_at, started_at)`
+ *     is older than the cutoff. Batched so a huge backlog can't lock the
+ *     DB for minutes; stops when a batch deletes 0 rows.
+ *   - `pruneTurnsOlderThan(db, cutoffMs, batchLimit)` — same shape for
+ *     `turns`, using `COALESCE(ended_at, started_at)`.
+ *   - `runRegistryReaper(db, opts)` — one-shot orchestrator that runs both
+ *     prunes, issues `PRAGMA wal_checkpoint(TRUNCATE)`, and returns counts.
+ *
+ * Timestamp model
+ *   `subagents.started_at` / `last_activity_at` / `ended_at` and
+ *   `turns.started_at` / `ended_at` are all unix MILLISECONDS (see
+ *   subagents-schema.ts and turns-schema.ts), distinct from
+ *   `messages.ts` which is unix SECONDS. Callers pass `cutoffMs`
+ *   directly — no conversion is done here.
+ *
+ * Retention selection
+ *   Default retention window is 14 days. Resolved by the gateway from:
+ *     1. `process.env.HISTORY_RETENTION_DAYS` (integer days)
+ *     2. `access.json:historyRetentionDays` (legacy: shared with the
+ *        messages-table init prune)
+ *     3. fallback constant `DEFAULT_RETENTION_DAYS = 14`
+ *
+ * Concurrency
+ *   bun:sqlite holds the DB connection in WAL mode. Reader/writer
+ *   concurrency is fine. The batch DELETE statements use short
+ *   transactions so the gateway's record paths (recordSubagentStart,
+ *   bumpSubagentActivity, recordTurnStart, recordTurnEnd) never block
+ *   for more than a single batch's worth of work.
+ *
+ * Hard rules
+ *   - Never touch the `messages` table from here. That table has its
+ *     own (separately-configured) retention policy.
+ *   - Bound the loop: every prune call must have a max-iteration safety
+ *     so a runaway clock or schema-corruption bug can't spin forever.
+ */
+
+type SqliteDatabase = {
+  exec(sql: string): void
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+    get(...params: unknown[]): unknown
+  }
+  transaction(fn: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown
+  close(): void
+}
+
+/** Default retention window for subagents + turns. */
+export const DEFAULT_RETENTION_DAYS = 14
+
+/** Default batch size — empirically a good ceiling for SQLite write
+ *  transactions on a busy WAL. Tuneable by callers via `batchLimit`. */
+export const DEFAULT_BATCH_LIMIT = 5000
+
+/** Defence-in-depth ceiling on the batch-delete loop. At
+ *  DEFAULT_BATCH_LIMIT this caps a single prune call at 5 million rows,
+ *  far more than any healthy agent registry will ever hold. */
+const MAX_BATCH_ITERATIONS = 1000
+
+export interface PruneResult {
+  /** Total rows deleted across all batches. */
+  deleted: number
+  /** Number of batch iterations executed. */
+  batches: number
+}
+
+/**
+ * Delete `subagents` rows whose latest-known activity is older than
+ * `cutoffMs`. Activity is `COALESCE(ended_at, last_activity_at,
+ * started_at)` — a row gets the most generous timestamp available,
+ * so a still-running row that simply hasn't pinged liveness in 14d
+ * is NOT pruned if its `last_activity_at` is recent.
+ *
+ * Batched: deletes up to `batchLimit` rows per iteration, looping until
+ * a batch returns 0. Bounded by MAX_BATCH_ITERATIONS.
+ */
+export function pruneSubagentsOlderThan(
+  db: SqliteDatabase,
+  cutoffMs: number,
+  batchLimit: number = DEFAULT_BATCH_LIMIT,
+): PruneResult {
+  // SQLite's DELETE ... LIMIT requires the SQLITE_ENABLE_UPDATE_DELETE_LIMIT
+  // compile flag. bun:sqlite ships with it OFF, so a literal LIMIT clause
+  // on DELETE fails parsing. Wrap with a sub-SELECT on rowid — that works
+  // on every SQLite build and behaves identically. The same pattern is
+  // used by pruneTurnsOlderThan below.
+  const stmt = db.prepare(`
+    DELETE FROM subagents
+    WHERE rowid IN (
+      SELECT rowid FROM subagents
+      WHERE COALESCE(ended_at, last_activity_at, started_at) < ?
+      LIMIT ?
+    )
+  `)
+  let total = 0
+  let batches = 0
+  for (let i = 0; i < MAX_BATCH_ITERATIONS; i++) {
+    const result = stmt.run(cutoffMs, batchLimit) as { changes: number }
+    batches += 1
+    const n = result.changes ?? 0
+    total += n
+    if (n === 0) break
+  }
+  return { deleted: total, batches }
+}
+
+/**
+ * Delete `turns` rows whose latest-known activity is older than `cutoffMs`.
+ * Activity is `COALESCE(ended_at, started_at)` — an open turn (ended_at
+ * NULL) is preserved if its `started_at` is recent. Batched like
+ * pruneSubagentsOlderThan.
+ */
+export function pruneTurnsOlderThan(
+  db: SqliteDatabase,
+  cutoffMs: number,
+  batchLimit: number = DEFAULT_BATCH_LIMIT,
+): PruneResult {
+  const stmt = db.prepare(`
+    DELETE FROM turns
+    WHERE rowid IN (
+      SELECT rowid FROM turns
+      WHERE COALESCE(ended_at, started_at) < ?
+      LIMIT ?
+    )
+  `)
+  let total = 0
+  let batches = 0
+  for (let i = 0; i < MAX_BATCH_ITERATIONS; i++) {
+    const result = stmt.run(cutoffMs, batchLimit) as { changes: number }
+    batches += 1
+    const n = result.changes ?? 0
+    total += n
+    if (n === 0) break
+  }
+  return { deleted: total, batches }
+}
+
+export interface RegistryReaperResult {
+  subagents: PruneResult
+  turns: PruneResult
+  /** True if the WAL checkpoint ran without throwing. The result of the
+   *  pragma is logged but not propagated (it can legitimately report
+   *  "busy" under reader pressure — not a failure). */
+  walCheckpointed: boolean
+}
+
+export interface RegistryReaperOpts {
+  /** Retention window in days. */
+  retentionDays?: number
+  /** Override "now" for tests. Defaults to Date.now(). */
+  now?: number
+  /** Override batch size (mostly for tests). */
+  batchLimit?: number
+}
+
+/**
+ * Run the full registry reaper: prune subagents, prune turns, checkpoint
+ * the WAL. Caller logs the result.
+ */
+export function runRegistryReaper(
+  db: SqliteDatabase,
+  opts: RegistryReaperOpts = {},
+): RegistryReaperResult {
+  const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS
+  const now = opts.now ?? Date.now()
+  const batchLimit = opts.batchLimit ?? DEFAULT_BATCH_LIMIT
+  const cutoffMs = now - retentionDays * 86_400_000
+
+  const subagents = pruneSubagentsOlderThan(db, cutoffMs, batchLimit)
+  const turns = pruneTurnsOlderThan(db, cutoffMs, batchLimit)
+
+  // WAL checkpoint releases the .db-wal file's pages back to the main DB
+  // and truncates the WAL to zero bytes. TRUNCATE mode does both;
+  // PASSIVE/FULL leave WAL pages behind. Wrap in try/catch — the
+  // checkpoint can return SQLITE_BUSY under concurrent reads, which
+  // bun:sqlite surfaces as a thrown error. That's a transient,
+  // non-fatal condition: the next reaper tick will retry.
+  let walCheckpointed = false
+  try {
+    db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').run()
+    walCheckpointed = true
+  } catch {
+    walCheckpointed = false
+  }
+
+  return { subagents, turns, walCheckpointed }
+}
+
+/**
+ * Resolve the retention window in days from environment + access-file
+ * sources. Order: env `HISTORY_RETENTION_DAYS` → `accessRetentionDays`
+ * (caller passes whatever's in access.json) → `DEFAULT_RETENTION_DAYS`.
+ *
+ * Returns a clamped positive integer. Invalid env values (non-numeric,
+ * <= 0, NaN) fall through to the access value, then to the default.
+ */
+export function resolveRetentionDays(accessRetentionDays?: number): number {
+  const envRaw = process.env.HISTORY_RETENTION_DAYS
+  if (envRaw != null && envRaw !== '') {
+    const n = Number.parseInt(envRaw, 10)
+    if (Number.isFinite(n) && n > 0) return n
+  }
+  if (
+    typeof accessRetentionDays === 'number'
+    && Number.isFinite(accessRetentionDays)
+    && accessRetentionDays > 0
+  ) {
+    return accessRetentionDays
+  }
+  return DEFAULT_RETENTION_DAYS
+}

package/telegram-plugin/retry-api-call.ts

@@ -170,3 +170,83 @@ export function createRetryApiCall(
     throw giveUpErr
   }
 }
+
+/**
+ * Compose a swallowing wrapper around a `retryApiCall` instance.
+ *
+ * Use this for **fire-and-forget** Telegram API callsites — boot/issues/
+ * subagent cards, "agent restarting" notices, reactions on stale targets,
+ * anything where the caller previously had `.catch(() => {})`. The wrapper
+ * resolves to `undefined` on the cases retryApiCall throws (THREAD_NOT_FOUND,
+ * give-up after network retries, GrammyError 403/400-not-chat, …) and logs
+ * a one-line note to `log` so the failure is at least visible in stderr.
+ *
+ * Why not just `.catch(() => {})` at the callsite? Two reasons:
+ *
+ *   1. We want THREAD_NOT_FOUND specifically to NOT crash but to be
+ *      *visible* — `.catch(() => {})` silently swallows everything, which
+ *      hid #1075 for months. The log here surfaces it.
+ *   2. Callers shouldn't have to remember to wrap each raw `bot.api.*`
+ *      with the retry policy AND the swallow — this is one function.
+ *
+ * For callsites that legitimately need to inspect failure (e.g. drop
+ * thread_id and retry on main chat), use `retryApiCall` directly and
+ * handle `THREAD_NOT_FOUND` explicitly — see `gateway.ts:2806` for the
+ * canonical pattern (the reply chunk loop).
+ */
+export function createSwallowingRetryApiCall(
+  retry: <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T>,
+  log?: (line: string) => void,
+): <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T | undefined> {
+  return async function swallow<T>(
+    fn: () => Promise<T>,
+    opts?: RetryCallOpts,
+  ): Promise<T | undefined> {
+    try {
+      return await retry(fn, opts)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      const verb = opts?.verb ?? 'api-call'
+      log?.(`telegram gateway: ${verb} swallowed: ${msg}\n`)
+      return undefined
+    }
+  }
+}
+
+/**
+ * Helper for callsites that pass `message_thread_id` and want to fall
+ * back to the main chat when the thread is deleted.
+ *
+ * The caller provides a `send` closure that takes `threadId?: number` and
+ * builds its own request. On THREAD_NOT_FOUND, `send(undefined)` is invoked
+ * once more — the wrapper drops the thread id and re-tries; everything
+ * else falls through to the underlying retry policy.
+ *
+ * Returns the final API response (typed as `T` — fallback resolved, or
+ * threadId-bearing call resolved). On non-thread errors, propagates as
+ * `retry` does.
+ */
+export async function retryWithThreadFallback<T>(
+  retry: <U>(fn: () => Promise<U>, opts?: RetryCallOpts) => Promise<U>,
+  send: (threadId: number | undefined) => Promise<T>,
+  opts: { threadId: number | undefined; chat_id: string; verb?: string },
+): Promise<T> {
+  try {
+    return await retry(() => send(opts.threadId), {
+      ...(opts.threadId != null ? { threadId: opts.threadId } : {}),
+      chat_id: opts.chat_id,
+      ...(opts.verb != null ? { verb: opts.verb } : {}),
+    })
+  } catch (err) {
+    if (err instanceof Error && err.message === 'THREAD_NOT_FOUND') {
+      // Drop the thread id and retry once on the main chat. Don't pass
+      // threadId in opts so a *second* thread-not-found (shouldn't
+      // happen) just propagates as a normal error.
+      return await retry(() => send(undefined), {
+        chat_id: opts.chat_id,
+        ...(opts.verb != null ? { verb: opts.verb } : {}),
+      })
+    }
+    throw err
+  }
+}

package/telegram-plugin/runtime-metrics.ts

@@ -0,0 +1,177 @@
+/**
+ * runtime-metrics.ts — high-value gateway events fanned out to PostHog
+ * AND a local JSONL file.
+ *
+ * Why both sinks:
+ *  - PostHog gets the events for dashboards, funnels, error correlation,
+ *    fleet-wide KPI tracking. This is the source of truth for the
+ *    conversational-turn-UX redesign KPIs (see docs/posthog.md).
+ *  - JSONL is preserved as a per-agent debug breadcrumb so the agent's
+ *    own context (or an operator on the host) can read what happened
+ *    without round-tripping to PostHog. Same file the silence-poke
+ *    subsystem (next PR) will append to.
+ *
+ * Distinct from `streaming-metrics.ts` — that module is the noisy
+ * gated-by-env stderr stream used for one-off streaming-perf analysis.
+ * Runtime metrics are always-on, narrow, and KPI-shaped.
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { captureEvent } from './analytics-posthog.js'
+
+export type RuntimeMetricEvent =
+  /**
+   * A user-sent message that matches a status-query pattern
+   * ("status?", "still there?", etc). Primary lagging KPI for the
+   * conversational turn UX — every fire is a JTBD failure.
+   */
+  | {
+      kind: 'inbound_status_query'
+      chat_id: string
+      message_id: number | null
+      thread_id: number | null
+      text_length: number
+      prior_turn_in_flight: boolean
+      seconds_since_turn_start: number | null
+    }
+  /**
+   * A fresh turn began (user message arrived, ack reaction fired).
+   * Pairs with `turn_ended` for duration / TTFO computation.
+   */
+  | {
+      kind: 'turn_started'
+      chat_id: string
+      message_id: number | null
+      thread_id: number | null
+      inbound_classified_as_status_query: boolean
+    }
+  /**
+   * A turn completed (terminal reply or silent close). Carries the
+   * gap distribution + TTFO so the dashboard can compute outbound
+   * silence p95 without per-event reconstruction.
+   */
+  | {
+      kind: 'turn_ended'
+      chat_id: string
+      thread_id: number | null
+      duration_ms: number
+      ttfo_ms: number | null
+      outbound_count: number
+      longest_silent_gap_ms: number
+      ended_via: 'reply' | 'stream_reply_done' | 'silent' | 'forced' | 'framework_fallback'
+    }
+  /**
+   * Framework safety-net: a silence-poke was armed at 75s (soft) or
+   * 180s (firm). The system-reminder appended to the next tool result
+   * nudges the model to send an update. Doubles as a design-health
+   * signal — if these fire frequently, the conversational-pacing
+   * prompt isn't doing its job.
+   */
+  | {
+      kind: 'silence_poke_fired'
+      key: string
+      level: 'soft' | 'firm'
+      silence_ms: number
+      subagent_wait: boolean
+    }
+  /**
+   * The model sent an outbound message within the success window
+   * (default 15s) after a poke fired. Pair with `silence_poke_fired`
+   * to compute success rate — the design target is >80%.
+   */
+  | {
+      kind: 'silence_poke_succeeded'
+      key: string
+      level: 'soft' | 'firm'
+      latency_ms: number
+    }
+  /**
+   * Last-resort: 5 minutes silent, the framework itself sent a
+   * user-visible "still working… / still thinking…" message. Should
+   * be rare (target <5 per 1000 turns); a high rate means the model
+   * is genuinely stuck or the soft/firm pokes aren't being honoured.
+   */
+  | {
+      kind: 'silence_fallback_sent'
+      key: string
+      fallback_kind: 'working' | 'thinking'
+      silence_ms: number
+    }
+
+/**
+ * The JSONL sink lives under the runtime state dir so it's per-agent
+ * and survives container restarts (the dir is bind-mounted from the
+ * host). Path can be overridden for tests via SWITCHROOM_RUNTIME_METRICS_PATH.
+ */
+function resolveJsonlPath(): string {
+  const override = process.env.SWITCHROOM_RUNTIME_METRICS_PATH
+  if (override && override.trim() !== '') return override.trim()
+  const base = process.env.SWITCHROOM_RUNTIME_STATE_DIR ?? '/state/agent'
+  return join(base, 'runtime-metrics.jsonl')
+}
+
+function appendJsonl(line: string): void {
+  const path = resolveJsonlPath()
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    appendFileSync(path, line + '\n', 'utf-8')
+  } catch (err) {
+    // JSONL is a local debug aid; failing to write must not break
+    // the gateway. Surface to stderr so it's at least visible in
+    // the plugin log.
+    process.stderr.write(`runtime-metrics: jsonl write failed: ${(err as Error).message}\n`)
+  }
+}
+
+/**
+ * Whether to write JSONL at all. Defaults to ON (the user asked for it
+ * to stay as a local debugging side-channel). Operator can opt-out with
+ * SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED=1 if disk pressure is a
+ * concern.
+ */
+function jsonlEnabled(): boolean {
+  const v = process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED
+  return !(v === '1' || v === 'true')
+}
+
+/**
+ * Emit one runtime metric event. Fans out to:
+ *   1. JSONL file (unless disabled)
+ *   2. PostHog (unless SWITCHROOM_TELEMETRY_DISABLED=1)
+ *
+ * Never throws. Each sink fails independently — a broken sink does not
+ * block the other.
+ */
+export function emitRuntimeMetric(event: RuntimeMetricEvent): void {
+  const wrapped = { ts: Date.now(), ...event }
+  if (jsonlEnabled()) {
+    try {
+      appendJsonl(JSON.stringify(wrapped))
+    } catch {
+      // already guarded inside appendJsonl
+    }
+  }
+  // captureEvent is async + internally guarded; void-fire to avoid blocking
+  // the caller. PostHog batches, so this is cheap.
+  void captureEvent(event.kind, { ...event, ts: wrapped.ts })
+}
+
+/** Exposed for tests — pin the JSONL path to a temp file. */
+export function __setRuntimeMetricsPathForTests(path: string | null): void {
+  if (path == null) {
+    delete process.env.SWITCHROOM_RUNTIME_METRICS_PATH
+  } else {
+    process.env.SWITCHROOM_RUNTIME_METRICS_PATH = path
+  }
+}
+
+/** Exposed for tests — read back the current resolved path. */
+export function __getRuntimeMetricsPathForTests(): string {
+  return resolveJsonlPath()
+}
+
+/** Exposed for tests — JSONL gate helper. */
+export function __isJsonlEnabledForTests(): boolean {
+  return jsonlEnabled()
+}

package/telegram-plugin/scripts/build.mjs

@@ -24,7 +24,6 @@ const entries = [
   { src: "server.ts", out: "server.js", label: "server (legacy + dual-mode shim)" },
   { src: "gateway/gateway.ts", out: "gateway/gateway.js", label: "gateway (persistent service)" },
   { src: "bridge/bridge.ts", out: "bridge/bridge.js", label: "bridge (MCP proxy)" },
-  { src: "foreman/foreman.ts", out: "foreman/foreman.js", label: "foreman (admin bot)" },
 ];
 
 for (const { src, out, label } of entries) {

package/telegram-plugin/secret-detect/index.ts

@@ -25,6 +25,7 @@
  */
 import { ALL_PATTERNS } from './patterns.js'
 import { scanKeyValue, type RawHit } from './kv-scanner.js'
+import { shannonEntropy } from './entropy.js'
 import { chunk } from './chunker.js'
 import { isSuppressed } from './suppressor.js'
 import { deriveSlug } from './slug.js'
@@ -79,6 +80,29 @@ export function detectSecrets(text: string): Detection[] {
         const globalEnd = globalStart + cap.length
         // For env_key_value (captureIndex=3), the LHS is group 1.
         const keyName = p.rule_id === 'env_key_value' ? m[1] : undefined
+        // 2026-05-12: shape gate on env_key_value — the pattern matches
+        // any value after an ALLCAPS *_KEY/_TOKEN/_SECRET/_PASSWORD
+        // identifier, which previously fired on casual chat like
+        // "MY_TOKEN=hello" or "OPENAI_API_KEY=sk-yourkey" (placeholder
+        // values, code-shaped human language). Operator UAT reproduced
+        // this on 2026-05-12 — the redaction pipeline was deleting the
+        // operator's *question* and staging a card asking them to save
+        // the literal word "hello" as a vault entry.
+        //
+        // Mirror the kv_entropy gate from kv-scanner.ts: require
+        // BOTH a length floor (cuts short placeholders) AND a Shannon
+        // entropy floor (cuts low-randomness words like "hello",
+        // "yourkey", "foo"). Threshold is slightly looser than
+        // kv_entropy's 4.0 because the LHS structure already gives us
+        // higher confidence that this IS an env declaration.
+        // See tests/secret-detect-false-positives.test.ts for the
+        // pinned cases.
+        if (p.rule_id === 'env_key_value') {
+          const ENV_KV_MIN_LEN = 12
+          const ENV_KV_MIN_ENTROPY = 3.5
+          if (cap.length < ENV_KV_MIN_LEN) continue
+          if (shannonEntropy(cap) < ENV_KV_MIN_ENTROPY) continue
+        }
         raw.push({
           rule_id: p.rule_id,
           start: globalStart,