switchroom 0.7.15 → 0.10.0

package/telegram-plugin/gateway/auth-line.ts

@@ -0,0 +1,123 @@
+/**
+ * Boot-card auth row formatter (RFC H §7.3).
+ *
+ * The old auth-dashboard exported `formatAccountQuotaLine` + an
+ * `AccountSummary` shape that the boot card consumed for its
+ * "Accounts (N)" section. Both source-of-truth and shape moved to
+ * the auth-broker's `list-state` response. This module reformats that
+ * response into the same one-line-per-account block the boot card
+ * used to render — visual output unchanged, data source is now the
+ * broker.
+ *
+ * Inputs: a `list-state` data shape (see
+ * `src/auth/broker/protocol.ts` → `ListStateDataSchema`) plus the
+ * caller agent's name.
+ *
+ * Output: an array of HTML-safe lines. Empty array when there's
+ * nothing to show — preserves the boot-card's silent-when-healthy
+ * default.
+ */
+
+import type { ListStateData, AccountState } from '../../src/auth/broker/client.js'
+
+export type { ListStateData, AccountState }
+
+// Local HTML-escape (mirrors the helper formerly co-located in
+// auth-dashboard.ts so we keep the same escaping discipline without
+// pulling in a heavier util).
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** Format a duration in ms as a short relative string ("1h 22m", "12s"). */
+function formatRelativeMs(ms: number): string {
+  if (ms <= 0) return '0s'
+  const totalSec = Math.floor(ms / 1000)
+  const days = Math.floor(totalSec / 86400)
+  const hours = Math.floor((totalSec % 86400) / 3600)
+  const mins = Math.floor((totalSec % 3600) / 60)
+  const secs = totalSec % 60
+  if (days > 0) return `${days}d ${hours}h`
+  if (hours > 0) return `${hours}h ${mins}m`
+  if (mins > 0) return `${mins}m ${secs}s`
+  return `${secs}s`
+}
+
+/**
+ * Render the per-account quota inline for one account row. Returns
+ * null when there's nothing quota-shaped to say (account is healthy
+ * and we have no reset countdown to surface).
+ */
+export function formatAuthQuotaLine(acc: AccountState, now: number = Date.now()): string | null {
+  if (acc.exhausted) {
+    const until = acc.exhausted_until
+    if (until != null && until > now) {
+      return `<i>exhausted · resets in ${formatRelativeMs(until - now)}</i>`
+    }
+    return `<i>exhausted</i>`
+  }
+  return null
+}
+
+/**
+ * Boot-card auth-row block.
+ *
+ * Strategy:
+ *   1. Determine *which* account is active for `agentName` (per-agent
+ *      override wins over fleet-active).
+ *   2. Emit one row for that account marked with `▶` plus a
+ *      best-effort quota suffix.
+ *   3. Emit one row per other account in `fallback_order` marked with
+ *      `↳` so the operator sees the rollover plan at a glance.
+ *
+ * Returns an empty array when `state` is empty (no accounts) — the
+ * boot card's silent-when-healthy contract.
+ */
+export function renderAuthLine(
+  state: ListStateData,
+  agentName: string,
+  now: number = Date.now(),
+): string[] {
+  if (!state || state.accounts.length === 0) return []
+
+  const agentEntry = state.agents.find((a) => a.name === agentName)
+  const activeLabel = agentEntry?.override ?? agentEntry?.account ?? state.active
+
+  // Stable display order: active first, then `fallback_order` minus
+  // the active label, then any remaining accounts (defensive — should
+  // be empty in steady state) in account-list order.
+  const seen = new Set<string>()
+  const order: string[] = []
+  if (activeLabel) {
+    order.push(activeLabel)
+    seen.add(activeLabel)
+  }
+  for (const label of state.fallback_order) {
+    if (!seen.has(label)) {
+      order.push(label)
+      seen.add(label)
+    }
+  }
+  for (const acc of state.accounts) {
+    if (!seen.has(acc.label)) {
+      order.push(acc.label)
+      seen.add(acc.label)
+    }
+  }
+
+  const byLabel = new Map(state.accounts.map((a) => [a.label, a]))
+  const rows: string[] = []
+  rows.push(`<b>Accounts (${state.accounts.length})</b>`)
+  for (const label of order) {
+    const acc = byLabel.get(label)
+    if (!acc) continue
+    const marker = label === activeLabel ? '▶' : '↳'
+    const labelHtml = `<code>${escapeHtml(acc.label)}</code>`
+    const quotaLine = formatAuthQuotaLine(acc, now)
+    rows.push(quotaLine ? `${marker} ${labelHtml}  ${quotaLine}` : `${marker} ${labelHtml}`)
+  }
+  return rows
+}

package/telegram-plugin/gateway/boot-card.ts

@@ -33,8 +33,8 @@
  */
 
 import type { ProbeResult, GatewayRuntimeInfo } from './boot-probes.js'
-import type { AccountSummary } from '../auth-dashboard.js'
-import { formatAccountQuotaLine } from '../auth-dashboard.js'
+import type { ListStateData } from './auth-line.js'
+import { renderAuthLine } from './auth-line.js'
 import {
   probeAccount,
   probeAgentProcess,
@@ -50,6 +50,12 @@ import {
   AGENT_LIVE_POLL_INTERVAL_MS,
 } from './boot-probes.js'
 import { escapeHtml } from '../card-format.js'
+import {
+  loadCache as loadBootIssueCache,
+  diffProbes as diffBootProbes,
+  applyAndSave as saveBootIssueCache,
+  type ProbeDiffMap,
+} from './boot-issue-cache.js'
 import { join } from 'path'
 import { loadConfig as _loadSwitchroomConfig } from '../../src/config/loader.js'
 
@@ -243,6 +249,10 @@ const REASON_LABEL: Record<RestartReason, string> = {
 
 export interface RenderBootCardOpts {
   agentName: string
+  /** Lowercase slug used for systemd unit names. Falls back to
+   *  `agentName` when omitted — matches the same fallback used by
+   *  `runAllProbes` for systemd targets. */
+  agentSlug?: string
   /** Pre-formatted version string, e.g. "v0.3.0+44" or "v0.3.0 · #143 · 2h ago". */
   version: string
   /** Probe results (only present after the settle window). When absent or
@@ -264,9 +274,21 @@ export interface RenderBootCardOpts {
    * silent-when-healthy contract for callers that don't pass account
    * data (tests, harnesses, gateways without the auth model).
    *
-   * Closes #708.
+   * Post-RFC H (auth-broker rewire): this carries the broker's
+   * `list-state` shape — `renderAuthLine` consumes it to emit the
+   * same one-line-per-account rows as before. Callers that pass
+   * `null`/`undefined` get no section. Closes #708.
    */
-  accounts?: ReadonlyArray<AccountSummary>
+  accounts?: ListStateData | null
+  /** Probe keys for which the prior boot saw degraded/fail and this boot
+   *  sees ok. Rendered as a small ✅ line above the degraded section so
+   *  the user gets positive-feedback that a known issue is gone. */
+  resolvedRows?: ReadonlyArray<ProbeKey>
+  /** Probe keys whose degraded/fail row is hidden on this boot because
+   *  the user has seen the same fingerprint for too many consecutive
+   *  boots (snooze). The renderer skips the corresponding probe row.
+   *  See `boot-issue-cache.ts`. */
+  snoozeRows?: ReadonlyArray<ProbeKey>
   /** Clock injection point for tests; defaults to `new Date()`. */
   now?: Date
 }
@@ -279,12 +301,42 @@ export interface RenderBootCardOpts {
  * user only needs to know the agent came back up. Anything red catches
  * the eye; everything else stays out of the way.
  */
+/**
+ * Render a probe's `nextStep` hint as Telegram HTML. The hint is
+ * authored as plain text with backtick-quoted commands (one shell idiom
+ * across the codebase — search "Run `switchroom"). We translate those
+ * to <code> spans and escape everything else, so commands stay tap-to-
+ * copy on mobile without bleeding raw HTML through.
+ */
+function renderNextStep(text: string): string {
+  const parts = text.split('`')
+  // Odd-count backticks means an unterminated <code> span — fall back to
+  // plain-escaped text rather than rendering the trailing tail inside a
+  // code block. Author error, not user-input, but defensive is cheap.
+  if (parts.length % 2 === 0) return escapeHtml(text)
+  return parts.map((p, i) => (i % 2 === 0 ? escapeHtml(p) : `<code>${escapeHtml(p)}</code>`)).join('')
+}
+
 export function renderBootCard(opts: RenderBootCardOpts): string {
   const { agentName, version, probes, restartReason, restartAgeMs } = opts
+  const agentSlug = opts.agentSlug ?? agentName
   const ackEmoji = restartReason ? REASON_EMOJI[restartReason] : '✅'
   const ack = `${ackEmoji} <b>${escapeHtml(agentName)}</b> back up · ${escapeHtml(version)}`
 
   const degradedRows: string[] = []
+  const snoozeSet = new Set<ProbeKey>(opts.snoozeRows ?? [])
+
+  // Resolved rows (issue dedup, this PR) — render ✅ entries for probes
+  // that were degraded/fail on the previous boot and are now ok. Small
+  // positive-feedback signal so the user sees their fix worked instead
+  // of guessing from the absence of a row.
+  if (opts.resolvedRows && opts.resolvedRows.length > 0) {
+    for (const key of opts.resolvedRows) {
+      const lbl = PROBE_LABELS[key]
+      if (!lbl) continue
+      degradedRows.push(`✅ <b>${escapeHtml(lbl)}</b>  resolved`)
+    }
+  }
 
   // Crash recovery: surface explicitly so the user can tell whether
   // their next message will land on a fresh process. The agent-crashed
@@ -295,25 +347,49 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
       ? ` · ${(restartAgeMs / 1000).toFixed(1)}s ago`
       : ''
     degradedRows.push(`⚠️ <b>Restart</b>  ${escapeHtml(REASON_LABEL.crash)}${ageStr}`)
+    // Principle 1: every failure carries its next step. The crash row
+    // tells the user how to inspect why.
+    degradedRows.push(`    ↳ Tail logs: <code>journalctl --user -u switchroom-${escapeHtml(agentSlug)} -n 100</code>`)
   }
 
   // Probe rows — only those that surfaced as degraded/fail. Healthy
-  // (`ok`) probes don't render at all.
+  // (`ok`) probes don't render at all. When a probe carries a nextStep,
+  // it renders as an indented continuation line beneath the row — see
+  // `reference/principles.md` principle 1 ("If they need the docs, we've
+  // failed"): every failure surface tells the user what to run.
   if (probes) {
     for (const key of PROBE_KEYS) {
       const r = probes[key]
       if (!r) continue
       if (r.status === 'ok') continue
+      // Snoozed rows (issue dedup, this PR) — the user has seen the
+      // same fingerprint enough consecutive boots that we hide the row.
+      // The cache still tracks it; if the fingerprint changes (new
+      // failure mode) the snooze resets and the row reappears.
+      if (snoozeSet.has(key)) continue
       const dot = DOT[r.status] ?? DOT.fail
+      // The "Still: " prefix is reserved for rows the user has seen
+      // before (consecutiveBoots > 1) but hasn't been snoozed yet.
+      // We can't compute that from probes alone — the caller signals
+      // it implicitly: a degraded/fail row that's NOT in snoozeRows
+      // and NOT in resolvedRows is either novel or still-being-shown.
+      // We surface the existing row format unchanged here; the
+      // "Still:" / "New:" distinction is conveyed by which rows the
+      // user does or doesn't see across consecutive boots.
       degradedRows.push(`${dot} <b>${PROBE_LABELS[key]}</b>  ${escapeHtml(r.detail)}`)
+      if (r.nextStep) {
+        degradedRows.push(`    ↳ ${renderNextStep(r.nextStep)}`)
+      }
     }
   }
 
-  // Per-account quota section (issue #708) — one line per enabled
-  // account showing 5h % / 7d % / nearest reset, with the active
-  // account marked. Renders alongside the ack line so users see
-  // headroom without running /auth or /usage.
-  const accountRows = renderAccountRows(opts.accounts, opts.now ?? new Date())
+  // Per-account auth section (issue #708, RFC H rewire) — one line
+  // per known account with the active account marked. Renders
+  // alongside the ack line so users see headroom without running
+  // /auth or /usage. Source of truth: auth-broker list-state.
+  const accountRows = opts.accounts
+    ? renderAuthLine(opts.accounts, agentName, (opts.now ?? new Date()).getTime())
+    : []
 
   const sections: string[] = [ack]
   if (degradedRows.length > 0) sections.push('', ...degradedRows)
@@ -323,31 +399,12 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
 }
 
 /**
- * Render the per-account quota rows. Returns an empty array when no
- * accounts are passed — keeping the boot card's silent-when-healthy
- * default for callers that don't supply account data.
- *
- * Reuses the dashboard's `formatAccountQuotaLine` so the two surfaces
- * speak with one voice.
+ * Re-export the broker-fed auth-row renderer under its historical
+ * name so direct callers (tests, harnesses) keep working without
+ * importing two modules. New code should import `renderAuthLine`
+ * from `./auth-line.js` directly.
  */
-export function renderAccountRows(
-  accounts: ReadonlyArray<AccountSummary> | undefined,
-  now: Date,
-): string[] {
-  if (!accounts || accounts.length === 0) return []
-  const rows: string[] = []
-  rows.push(`<b>Accounts (${accounts.length})</b>`)
-  const nowMs = now.getTime()
-  for (const a of accounts) {
-    const marker = a.activeForThisAgent ? '▶' : '↳'
-    const labelHtml = `<code>${escapeHtml(a.label)}</code>`
-    // formatAccountQuotaLine returns HTML (with <i> tags) so we don't
-    // re-escape — pass it through verbatim.
-    const quotaLine = formatAccountQuotaLine(a, nowMs)
-    rows.push(quotaLine ? `${marker} ${labelHtml}  ${quotaLine}` : `${marker} ${labelHtml}`)
-  }
-  return rows
-}
+export { renderAuthLine as renderAccountRows } from './auth-line.js'
 
 // ─── Probe orchestration ─────────────────────────────────────────────────────
 
@@ -368,6 +425,15 @@ export interface RunProbesOpts {
   restartReason?: RestartReason
   /** Age of the restart marker in ms — shown in the crash row. */
   restartAgeMs?: number
+  /** Free-form reason text from `clean-shutdown.json` (e.g.
+   *  `"operator: switchroom update"`, `"user: /restart from chat"`).
+   *  Used to silence the boot-card notification for operator-initiated
+   *  redeploys: routine fleet updates shouldn't ping every user every
+   *  time. `user:` reasons (and crash / fresh) still notify normally —
+   *  the user asked for that restart, so the boot card should
+   *  announce. The text is also passed through unchanged so future
+   *  surfaces can render it. */
+  restartReasonDetail?: string
   /** Override fetch for tests. */
   fetchImpl?: typeof fetch
   /** Override settle window for tests; production uses SETTLE_WINDOW_MS. */
@@ -400,12 +466,21 @@ export interface RunProbesOpts {
    * during the post-settle re-render so the first paint stays fast.
    */
   loadAccounts?: () =>
-    | ReadonlyArray<AccountSummary>
+    | ListStateData
     | null
-    | Promise<ReadonlyArray<AccountSummary> | null>
+    | Promise<ListStateData | null>
   /** When true, resolve the agent PID via cgroup walk instead of MainPID
    *  (which is the tmux server pid under tmux supervisor). */
   tmuxSupervisor?: boolean
+  /** Path to the per-agent boot-issue cache file. When set, the
+   *  post-settle render applies snooze + resolved-row dedup against
+   *  prior boots (see `boot-issue-cache.ts`). Omit to disable dedup
+   *  entirely (legacy behaviour). */
+  bootIssueCachePath?: string
+  /** Override snoozeBoots threshold for tests. */
+  snoozeBoots?: number
+  /** Override snoozeMs threshold for tests. */
+  snoozeMs?: number
   /** When true, the gateway is running inside an agent docker container.
    *  Probes that depend on systemctl (Agent, Crons) switch to /proc walks
    *  and externally-managed surface text instead of execing systemctl
@@ -424,7 +499,7 @@ export async function runAllProbes(opts: RunProbesOpts): Promise<ProbeMap> {
   const slug = opts.agentSlug ?? opts.agentName
 
   await Promise.allSettled([
-    probeAccount(opts.agentDir).then(r => { probes.account = r }),
+    probeAccount(opts.agentDir, { agentName: opts.agentSlug ?? opts.agentName }).then(r => { probes.account = r }),
     probeAgentProcess(slug, { execFileImpl: opts.probeExecFileImpl, tmuxSupervisor: opts.tmuxSupervisor, dockerMode: opts.dockerMode }).then(r => { probes.agent = r }),
     probeGateway(opts.gatewayInfo).then(r => { probes.gateway = r }),
     probeQuota(claudeDir, opts.agentDir, opts.fetchImpl).then(r => { probes.quota = r }),
@@ -432,7 +507,7 @@ export async function runAllProbes(opts: RunProbesOpts): Promise<ProbeMap> {
     probeScheduler(slug, { dockerMode: opts.dockerMode }).then(r => { probes.scheduler = r }),
     probeBroker(undefined, { dockerMode: opts.dockerMode }).then(r => { probes.broker = r }),
     probeKernel(undefined, { dockerMode: opts.dockerMode }).then(r => { probes.kernel = r }),
-    probeSkills(opts.agentDir).then(r => { probes.skills = r }),
+    probeSkills(opts.agentDir, { agentName: opts.agentSlug ?? opts.agentName }).then(r => { probes.skills = r }),
   ])
 
   return probes
@@ -461,11 +536,24 @@ export async function startBootCard(
   // confirmation that the agent is back without waiting on probes.
   const ackText = renderBootCard({
     agentName: opts.agentName,
+    agentSlug: opts.agentSlug,
     version: opts.version,
     restartReason: opts.restartReason,
     restartAgeMs: opts.restartAgeMs,
   })
 
+  // Silence the notification for operator-initiated redeploys. A
+  // routine `switchroom update` should land in the chat as a record
+  // but not buzz every user's phone — every agent posts a card, so
+  // a fleet update with N agents produces N notifications otherwise.
+  // We key on the reason-text prefix `operator:` (today only
+  // `operator: switchroom update` writes this) so user-initiated
+  // restarts (`user: /restart from chat`, `cli: switchroom restart`)
+  // and unplanned events (crash, fresh, planned-marker) keep their
+  // normal notification behaviour — the user explicitly asked for
+  // those, or they need to know something went wrong.
+  const silentBootCard = opts.restartReasonDetail?.startsWith('operator:') === true
+
   let messageId: number
   try {
     const sent = await bot.sendMessage(chatId, ackText, {
@@ -473,9 +561,10 @@ export async function startBootCard(
       link_preview_options: { is_disabled: true },
       ...(threadId != null ? { message_thread_id: threadId } : {}),
       ...(ackMessageId != null ? { reply_parameters: { message_id: ackMessageId } } : {}),
+      ...(silentBootCard ? { disable_notification: true } : {}),
     })
     messageId = sent.message_id
-    logger(`telegram gateway: boot-card: posted msgId=${messageId} chatId=${chatId} reason=${opts.restartReason ?? '-'}\n`)
+    logger(`telegram gateway: boot-card: posted msgId=${messageId} chatId=${chatId} reason=${opts.restartReason ?? '-'} reason_detail=${opts.restartReasonDetail ?? '-'} silent=${silentBootCard}\n`)
   } catch (err: unknown) {
     logger(`telegram gateway: boot-card: failed to post ack: ${(err as Error)?.message ?? String(err)}\n`)
     return { messageId: -1, complete: () => {} }
@@ -501,7 +590,7 @@ export async function startBootCard(
         // Per-account rows (issue #708). Loaded best-effort
         // alongside probes; failures are swallowed so the card still
         // renders correctly with no accounts section.
-        let accountRows: ReadonlyArray<AccountSummary> | null = null
+        let accountRows: ListStateData | null = null
         if (opts.loadAccounts) {
           try {
             accountRows = await opts.loadAccounts()
@@ -514,14 +603,49 @@ export async function startBootCard(
           }
         }
 
+        // Issue-dedup diff: when a cache path is configured, compare this
+        // boot's probe outcomes against the cached fingerprints to derive
+        // resolvedRows (was bad, now ok) and snoozeRows (same fingerprint
+        // shown too many consecutive boots). One disk read up-front, one
+        // disk write on the way out — no second write from the live-watch
+        // loop below (which reuses the same masks).
+        let diff: ProbeDiffMap = {}
+        let resolvedRows: import('./boot-card.js').ProbeKey[] = []
+        let snoozeRows: import('./boot-card.js').ProbeKey[] = []
+        if (opts.bootIssueCachePath) {
+          try {
+            const cache = loadBootIssueCache(opts.bootIssueCachePath)
+            diff = diffBootProbes(probes, cache, {
+              snoozeBoots: opts.snoozeBoots,
+              snoozeMs: opts.snoozeMs,
+            })
+            for (const [k, d] of Object.entries(diff) as [import('./boot-card.js').ProbeKey, NonNullable<ProbeDiffMap[import('./boot-card.js').ProbeKey]>][]) {
+              if (d.resolved) resolvedRows.push(k)
+              if (d.snoozed) snoozeRows.push(k)
+            }
+            // Persist once. The live-watch loop reuses the same mask in
+            // memory; it does NOT re-write the cache.
+            saveBootIssueCache(opts.bootIssueCachePath, cache, diff)
+          } catch (diffErr: unknown) {
+            logger(
+              `telegram gateway: boot-card: issue-dedup diff failed: ${
+                (diffErr as Error)?.message ?? String(diffErr)
+              }\n`,
+            )
+          }
+        }
+
         // Render with current probe state and edit if anything changed.
         let currentText = renderBootCard({
           agentName: opts.agentName,
+          agentSlug: opts.agentSlug,
           version: opts.version,
           probes,
           restartReason: opts.restartReason,
           restartAgeMs: opts.restartAgeMs,
           ...(accountRows ? { accounts: accountRows } : {}),
+          ...(resolvedRows.length > 0 ? { resolvedRows } : {}),
+          ...(snoozeRows.length > 0 ? { snoozeRows } : {}),
         })
 
         if (currentText !== ackText) {
@@ -563,11 +687,16 @@ export async function startBootCard(
           const updatedProbes: ProbeMap = { ...probes, agent: agentResult }
           const updatedText = renderBootCard({
             agentName: opts.agentName,
+            agentSlug: opts.agentSlug,
             version: opts.version,
             probes: updatedProbes,
             restartReason: opts.restartReason,
             restartAgeMs: opts.restartAgeMs,
             ...(accountRows ? { accounts: accountRows } : {}),
+            // Reuse the same masks computed once above — no second
+            // cache write from the live-watch loop.
+            ...(resolvedRows.length > 0 ? { resolvedRows } : {}),
+            ...(snoozeRows.length > 0 ? { snoozeRows } : {}),
           })
 
           if (updatedText === currentText) continue