switchroom 0.7.15 → 0.10.0

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

@@ -11,12 +11,13 @@
  * caller as a thrown error — only as ProbeResult{ status:'fail', ... }.
  */
 
-import { readFileSync, readdirSync, existsSync, mkdirSync, writeFileSync } from 'fs'
+import { readFileSync, readdirSync, existsSync } from 'fs'
 import { join } from 'path'
 import { execFile as execFileCb } from 'child_process'
 import { promisify } from 'util'
 
 import { readQuotaCache, writeQuotaCache } from './quota-cache.js'
+import { fetchQuota, formatQuotaLine } from '../quota-check.js'
 
 const execFile = promisify(execFileCb)
 
@@ -28,6 +29,13 @@ export interface ProbeResult {
   status: ProbeStatus
   label: string
   detail: string
+  /** Plain-text remediation hint shown beneath the degraded row in the
+   *  boot card. Per `reference/principles.md` principle 1, every failure
+   *  should tell the user what to do next — naming the failure without a
+   *  next step is the explicit ❌ Bad pattern. Omitted on ok rows (they
+   *  don't render) and on degraded rows where no actionable hint exists.
+   */
+  nextStep?: string
   /** True when a 429 caused the probe to skip the live check. Used by
    *  writeQuotaCache to select the short RATE_LIMIT_TTL_MS instead of the
    *  default 5-min TTL. Keying off this boolean avoids matching on the
@@ -111,10 +119,18 @@ const TOKEN_EXPIRING_SOON_DAYS = 7
  * Read account info from the agent's .claude.json.
  * agentDir: e.g. /home/user/.switchroom/agents/clerk
  */
-export async function probeAccount(agentDir: string): Promise<ProbeResult> {
+export async function probeAccount(
+  agentDir: string,
+  opts: { agentName?: string } = {},
+): Promise<ProbeResult> {
   return withTimeout('Account', (async (): Promise<ProbeResult> => {
     const claudeDir = join(agentDir, '.claude')
     const claudeJsonPath = join(claudeDir, '.claude.json')
+    // Fall back to the literal placeholder only when no agentName is plumbed
+    // through — the renderer's <code> escape will keep that safe in Telegram
+    // HTML, but real call sites should always pass the name so users can
+    // tap-to-copy a working command.
+    const agentRef = opts.agentName ?? '<agent>'
     let cfg: ClaudeJson = {}
     try {
       const raw = readFileSync(claudeJsonPath, 'utf8')
@@ -125,7 +141,12 @@ export async function probeAccount(agentDir: string): Promise<ProbeResult> {
 
     const acc = cfg.oauthAccount
     if (!acc?.emailAddress) {
-      return { status: 'degraded', label: 'Account', detail: 'not signed in' }
+      return {
+        status: 'degraded',
+        label: 'Account',
+        detail: 'not signed in',
+        nextStep: `Run \`switchroom auth login ${agentRef}\` to start the OAuth flow`,
+      }
     }
 
     const plan = mapPlan(acc.billingType, acc.hasExtraUsageEnabled)
@@ -154,10 +175,16 @@ export async function probeAccount(agentDir: string): Promise<ProbeResult> {
       }
     }
 
+    const nextStep = status === 'fail'
+      ? `OAuth token expired — run \`switchroom auth login ${agentRef}\` to re-authenticate`
+      : status === 'degraded'
+        ? `Token expiring soon — run \`switchroom auth login ${agentRef}\` before it lapses`
+        : undefined
     return {
       status,
       label: 'Account',
       detail: `${acc.emailAddress} · ${plan}${tokenStr}`,
+      ...(nextStep ? { nextStep } : {}),
     }
   })())
 }
@@ -378,10 +405,36 @@ export function uptimeMsForStarttime(
   }
 }
 
+/**
+ * Compute a remediation hint for a non-active agent systemd state. Returns
+ * `undefined` when no actionable hint applies. Per `reference/principles.md`
+ * principle 1, every degraded/fail row should tell the user what to do next.
+ * Hints share a common journalctl shape so they're greppable across
+ * agents.
+ */
+function nextStepForAgentState(agentName: string, state: string): string | undefined {
+  if (state === 'failed') {
+    return `Service failed — inspect with \`journalctl --user -u switchroom-${agentName} -n 100\` then \`switchroom agent restart ${agentName}\``
+  }
+  if (state === 'inactive') {
+    return `Service inactive — start with \`switchroom agent start ${agentName}\` (or \`systemctl --user start switchroom-${agentName}\`)`
+  }
+  if (state === 'deactivating' || state === 'activating' || state === 'auto-restart') {
+    return `Service is in a transient \`${state}\` state — re-check with \`switchroom agent status ${agentName}\` in a few seconds`
+  }
+  // Unknown state — keep the door open with a generic hint.
+  return `Inspect with \`journalctl --user -u switchroom-${agentName} -n 100\``
+}
+
 function probeAgentProcessDocker(): ProbeResult {
   const found = findAgentProcessInContainer()
   if (!found) {
-    return { status: 'fail', label: 'Agent', detail: 'claude process not found' }
+    return {
+      status: 'fail',
+      label: 'Agent',
+      detail: 'claude process not found',
+      nextStep: 'No claude process in container — check container logs with `docker logs <container>` and restart with `switchroom agent restart <agent>`',
+    }
   }
   const uptimeMs = uptimeMsForStarttime(found.starttime)
   const mb = Math.round(found.rssKb / 1024)
@@ -570,7 +623,8 @@ export async function probeAgentProcess(
           state === 'activating' ||
           state === 'auto-restart'
         const status = isTransient ? 'degraded' : 'fail'
-        return { status, label: 'Agent', detail: `service ${state}` }
+        const nextStep = nextStepForAgentState(agentName, state)
+        return { status, label: 'Agent', detail: `service ${state}`, ...(nextStep ? { nextStep } : {}) }
       }
 
       // Still within retry budget — wait and try again.
@@ -681,7 +735,8 @@ export async function* watchAgentProcess(
       state === 'auto-restart' ||
       state === 'inactive'
     const status = isTransient ? 'degraded' : 'fail'
-    return { status, label: 'Agent', detail: `service ${state}` }
+    const nextStep = nextStepForAgentState(agentName, state)
+    return { status, label: 'Agent', detail: `service ${state}`, ...(nextStep ? { nextStep } : {}) }
   }
 
   while (true) {
@@ -758,144 +813,83 @@ export async function probeGateway(info: GatewayRuntimeInfo): Promise<ProbeResul
 
 // ─── Probe: Quota ─────────────────────────────────────────────────────────────
 
-const QUOTA_DEBUG_FILE = 'quota-debug.json'
-
 /**
- * Attempt to read quota info via the /api/oauth/usage endpoint.
- * The response schema is undocumented — we probe defensively and
- * save the raw response to a debug file on first 2xx hit.
+ * Read quota utilization via the Pro/Max plan rate-limit headers on a
+ * `/v1/messages` probe — the same mechanism `/usage` and `/status` use.
+ *
+ * Pre-#1163 this hit Anthropic's `/api/oauth/usage` endpoint, which has
+ * deprecated/tightened auth and now returns HTTP 403 even for healthy
+ * OAuth tokens. That produced the useless boot-card row "Quota HTTP 403
+ * — re-authenticate" while `/status` (using the unified-ratelimit
+ * headers path) reported the agent as 🟢. See `quota-check.ts` for the
+ * underlying probe and `/v1/messages` header surface.
  *
- * Result is cached for 5 min in `~/.switchroom/quota-cache.json` and
- * shared across all agents. Without the cache, every gateway boot +
- * bridge-reconnect across 4 agents hits the endpoint, triggering 429s
- * that surface as 🟡 "rate limited" in the boot card. See `quota-cache.ts`.
+ * Result is cached briefly via `quota-cache.ts` so simultaneous fleet
+ * restarts (multiple agents booting at once, each with their own gateway)
+ * coalesce on the cache instead of each spending a `/v1/messages` token.
  *
  * Tests can override the cache path via SWITCHROOM_QUOTA_CACHE_PATH.
  */
 export async function probeQuota(
   claudeConfigDir: string,
-  agentDir: string,
+  _agentDir: string,
   fetchImpl: typeof fetch = fetch,
 ): Promise<ProbeResult> {
   return withTimeout('Quota', (async (): Promise<ProbeResult> => {
-    // Cache hit → return early (avoids the rate-limit cascade)
     const cached = readQuotaCache()
     if (cached) {
       return cached
     }
 
-    // Read token
-    let token: string | null = null
+    // The fallback per-agent token path is `accounts/default/.oauth-token`;
+    // fetchQuota's own resolver only checks the top-level `.oauth-token`,
+    // so prefer that, and if it's missing surface the same degraded row
+    // we did before (no live probe — that's a setup issue, not a runtime
+    // one).
+    let claudeDirForProbe: string | null = null
     for (const candidate of [
-      join(claudeConfigDir, '.oauth-token'),
-      join(claudeConfigDir, 'accounts', 'default', '.oauth-token'),
+      claudeConfigDir,
+      join(claudeConfigDir, 'accounts', 'default'),
     ]) {
-      if (existsSync(candidate)) {
-        try {
-          const raw = readFileSync(candidate, 'utf8').trim()
-          if (raw.length > 0) { token = raw; break }
-        } catch {}
+      if (existsSync(join(candidate, '.oauth-token'))) {
+        claudeDirForProbe = candidate
+        break
       }
     }
-    if (!token) {
-      return { status: 'degraded', label: 'Quota', detail: 'no OAuth token' }
-    }
-
-    let resp: Response
-    try {
-      const controller = new AbortController()
-      const t = setTimeout(() => controller.abort(), 1800)
-      resp = await fetchImpl('https://api.anthropic.com/api/oauth/usage', {
-        method: 'GET',
-        headers: {
-          'Authorization': `Bearer ${token}`,
-          'Accept': 'application/json',
-          'anthropic-version': '2023-06-01',
-          'anthropic-beta': 'oauth-2025-04-20',
-          'User-Agent': 'switchroom-boot/0.1',
-        },
-        signal: controller.signal,
-      })
-      clearTimeout(t)
-    } catch (err: unknown) {
-      return { status: 'fail', label: 'Quota', detail: `request failed: ${(err as Error).message ?? String(err)}` }
-    }
-
-    if (resp.status === 429) {
-      // A 429 from /api/oauth/usage means the endpoint is rate-limiting our
-      // probe calls — it does NOT mean the user is out of quota. Conflating
-      // the two is the root cause of the false 🟡 "rate limited" alarm
-      // reported in #210. Return ok-with-note and cache it for 30 s so
-      // simultaneous fleet restarts read the cached result instead of piling
-      // up on the same endpoint (see quota-cache.ts: RATE_LIMIT_TTL_MS).
-      //
-      // We assume 429 from /api/oauth/usage signals endpoint rate-limiting,
-      // not quota exhaustion. Anthropic uses 403 / 200-with-flag for the
-      // latter today; if that changes, revisit this 🟢 mapping.
-      const rateLimitResult: ProbeResult = {
-        status: 'ok',
+    if (!claudeDirForProbe) {
+      return {
+        status: 'degraded',
         label: 'Quota',
-        detail: 'quota check skipped: rate limited',
-        rateLimited: true,
+        detail: 'no OAuth token',
+        nextStep: 'No OAuth token on disk — register a fleet account: `switchroom auth add <label> --from-oauth` then `switchroom auth use <label>` (RFC H)',
       }
-      writeQuotaCache(rateLimitResult)
-      return rateLimitResult
-    }
-    if (!resp.ok) {
-      return { status: 'degraded', label: 'Quota', detail: `HTTP ${resp.status}` }
-    }
-
-    let body: unknown
-    try {
-      body = await resp.json()
-    } catch {
-      return { status: 'degraded', label: 'Quota', detail: 'invalid JSON response' }
     }
 
-    // Defensive schema discovery — save raw response for tightening
-    const debugPath = join(agentDir, 'telegram', QUOTA_DEBUG_FILE)
-    try {
-      // Redact token/UUID fields before saving
-      const redacted = JSON.parse(JSON.stringify(body, (k, v) => {
-        if (/token|uuid|id|key/i.test(k) && typeof v === 'string' && v.length > 10) return '[REDACTED]'
-        return v
-      }))
-      mkdirSync(join(agentDir, 'telegram'), { recursive: true })
-      writeFileSync(debugPath, JSON.stringify({ capturedAt: new Date().toISOString(), body: redacted }, null, 2))
-    } catch {}
-
-    // Try common field paths — schema not yet locked
-    const b = body as Record<string, unknown>
-    const sessionQuota =
-      (b?.['data'] as Record<string, unknown> | undefined)?.['session_quota'] ??
-      b?.['session_quota'] ??
-      (b?.['quota'] as Record<string, unknown> | undefined)?.['session'] ??
-      (b?.['usage'] as Record<string, unknown> | undefined)?.['session']
-
-    if (!sessionQuota) {
+    const probe = await fetchQuota({
+      claudeConfigDir: claudeDirForProbe,
+      fetchImpl,
+      timeoutMs: 1800,
+    })
+    if (!probe.ok) {
+      // Auth rejection from /v1/messages is a strong signal — the same
+      // endpoint claude itself uses. Other errors are surfaced verbatim
+      // so operators can see what's wrong.
+      const isAuth = /auth rejected|HTTP 401|HTTP 403/i.test(probe.reason)
       return {
         status: 'degraded',
         label: 'Quota',
-        detail: `schema unknown — first call captured (debug: ${debugPath})`,
+        detail: probe.reason,
+        nextStep: isAuth
+          ? 'Auth rejected by Anthropic — broker auto-refreshes; if persistent, replace the account: `switchroom auth add <label> --from-oauth --replace`'
+          : 'Anthropic quota probe failed — re-check after a minute; broker auto-rotates per `auth.fallback_order`',
       }
     }
 
-    const sq = sessionQuota as Record<string, unknown>
-    const parts: string[] = []
-    if (typeof sq['sonnet_used_pct'] === 'number') parts.push(`Sonnet ${Math.round(sq['sonnet_used_pct'] as number)}%`)
-    if (typeof sq['opus_used_pct'] === 'number') parts.push(`Opus ${Math.round(sq['opus_used_pct'] as number)}%`)
-    if (typeof sq['used_pct'] === 'number') parts.push(`${Math.round(sq['used_pct'] as number)}% used`)
-    if (typeof sq['resets_in_sec'] === 'number') {
-      const sec = sq['resets_in_sec'] as number
-      const h = Math.floor(sec / 3600)
-      const m = Math.round((sec % 3600) / 60)
-      parts.push(`resets in ${h}h ${m}m`)
+    const result: ProbeResult = {
+      status: 'ok',
+      label: 'Quota',
+      detail: formatQuotaLine(probe.data),
     }
-
-    if (parts.length === 0) {
-      return { status: 'degraded', label: 'Quota', detail: 'schema unknown — saving raw response' }
-    }
-    const result: ProbeResult = { status: 'ok', label: 'Quota', detail: parts.join(' · ') }
     writeQuotaCache(result)
     return result
   })())
@@ -922,7 +916,12 @@ export async function probeHindsight(
     }
 
     if (!resp || !resp.ok) {
-      return { status: 'fail', label: 'Hindsight', detail: 'unreachable' }
+      return {
+        status: 'fail',
+        label: 'Hindsight',
+        detail: 'unreachable',
+        nextStep: 'Hindsight server not responding on 127.0.0.1:18888 — start it with `hindsight serve` or check `systemctl --user status hindsight`',
+      }
     }
 
     const bankSuffix = bankName ? ` · bank=${bankName}` : ''
@@ -1082,6 +1081,9 @@ export async function probeScheduler(
         status: stillSettling ? 'degraded' : 'fail',
         label: 'Scheduler',
         detail: `sidecar not running (no lockfile)${settlingNote}`,
+        nextStep: stillSettling
+          ? 'Scheduler sidecar still starting — re-check in 30s'
+          : 'Scheduler sidecar not running — restart the agent with `switchroom agent restart <agent>` so the supervisor relaunches it',
       }
     }
     let holderPid: number | null = null
@@ -1090,16 +1092,27 @@ export async function probeScheduler(
       const parsed = Number.parseInt(raw, 10)
       if (Number.isInteger(parsed) && parsed > 0) holderPid = parsed
     } catch {
-      return { status: 'degraded', label: 'Scheduler', detail: 'lockfile unreadable' }
+      return {
+        status: 'degraded',
+        label: 'Scheduler',
+        detail: 'lockfile unreadable',
+        nextStep: `Inspect with \`cat ${lockPath}\` — if corrupt, remove it and restart the agent so the supervisor recreates the sidecar`,
+      }
     }
     if (holderPid == null) {
-      return { status: 'degraded', label: 'Scheduler', detail: 'lockfile contents invalid' }
+      return {
+        status: 'degraded',
+        label: 'Scheduler',
+        detail: 'lockfile contents invalid',
+        nextStep: `Inspect with \`cat ${lockPath}\` — if corrupt, remove it and restart the agent so the supervisor recreates the sidecar`,
+      }
     }
     if (!isAlive(holderPid)) {
       return {
         status: 'degraded',
         label: 'Scheduler',
         detail: `lock holder pid ${holderPid} not alive (supervisor restart in progress?)`,
+        nextStep: 'Supervisor should relaunch the sidecar shortly — re-check in 30s; if still stale, restart the agent',
       }
     }
 
@@ -1147,14 +1160,24 @@ async function probeUds(
     return { status: 'ok', label, detail: 'n/a (non-docker)' }
   }
   if (!socketPath) {
-    return { status: 'fail', label, detail: 'socket path not configured' }
+    return {
+      status: 'fail',
+      label,
+      detail: 'socket path not configured',
+      nextStep: udsNextStep(label, 'unconfigured'),
+    }
   }
   return withTimeout(label, (async (): Promise<ProbeResult> => {
     if (!opts.connectImpl) {
       // Cheap pre-check: stat the file. Saves the connect round-trip on
       // the common "broker container down → bind mount empty" case.
       if (!existsSync(socketPath)) {
-        return { status: 'fail', label, detail: `socket missing: ${socketPath}` }
+        return {
+          status: 'fail',
+          label,
+          detail: `socket missing: ${socketPath}`,
+          nextStep: udsNextStep(label, 'missing'),
+        }
       }
     }
     const connect = opts.connectImpl ?? defaultUdsConnect
@@ -1164,13 +1187,31 @@ async function probeUds(
     } catch (err: unknown) {
       const code = (err as NodeJS.ErrnoException)?.code
       const msg = (err as Error)?.message ?? String(err)
-      if (code === 'ENOENT') return { status: 'fail', label, detail: 'socket missing' }
-      if (code === 'ECONNREFUSED') return { status: 'fail', label, detail: 'connection refused' }
-      return { status: 'fail', label, detail: `connect failed: ${msg}` }
+      if (code === 'ENOENT') return { status: 'fail', label, detail: 'socket missing', nextStep: udsNextStep(label, 'missing') }
+      if (code === 'ECONNREFUSED') return { status: 'fail', label, detail: 'connection refused', nextStep: udsNextStep(label, 'refused') }
+      return { status: 'fail', label, detail: `connect failed: ${msg}`, nextStep: udsNextStep(label, 'other') }
     }
   })())
 }
 
+/**
+ * Remediation hints for the UDS (vault-broker / approval-kernel) probe.
+ * Both services are run by docker-compose alongside agents; recovery is
+ * almost always the same shape ("the service container isn't up"), so we
+ * surface the right `docker compose` target per label.
+ */
+function udsNextStep(label: string, kind: 'missing' | 'refused' | 'unconfigured' | 'other'): string {
+  const svc = label.toLowerCase() === 'broker' ? 'vault-broker' : 'approval-kernel'
+  if (kind === 'unconfigured') {
+    return `${label} socket path not set — check the compose mount for the agent container`
+  }
+  if (kind === 'refused') {
+    return `${label} socket present but not accepting connections — restart with \`docker compose restart ${svc}\``
+  }
+  // missing | other: most common case is the daemon container isn't running.
+  return `${label} socket not reachable — bring up the daemon with \`docker compose up -d ${svc}\` (or check \`docker compose ps\`)`
+}
+
 /**
  * Default UDS connect — opens a stream, then immediately closes it.
  * Resolves on `connect` event, rejects on `error`. 1s connect timeout
@@ -1236,7 +1277,7 @@ export async function probeKernel(
  */
 export async function probeSkills(
   agentDir: string,
-  opts: { fs?: SkillsFsImpl; maxNamesShown?: number } = {},
+  opts: { fs?: SkillsFsImpl; maxNamesShown?: number; agentName?: string } = {},
 ): Promise<ProbeResult> {
   return withTimeout('Skills', (async (): Promise<ProbeResult> => {
     const fs = opts.fs ?? realSkillsFs
@@ -1282,10 +1323,12 @@ export async function probeSkills(
     }
     const named = dangling.slice(0, max).join(', ')
     const more = dangling.length > max ? ` +${dangling.length - max} more` : ''
+    const reconcileTarget = opts.agentName ? ` ${opts.agentName}` : ''
     return {
       status: 'degraded',
       label: 'Skills',
       detail: `${dangling.length}/${entries.length} dangling: ${named}${more}`,
+      nextStep: `Run \`switchroom agent reconcile${reconcileTarget}\` to rebuild symlinks, or remove unused entries from switchroom.yaml`,
     }
   })())
 }

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

@@ -14,12 +14,44 @@ import type { SessionMarker } from './session-marker.js'
 // Re-export so tests can import from a single path
 export type { RestartReason }
 
+/**
+ * Operator-initiated restart-marker freshness window. Longer than the
+ * default `clean-shutdown.json` window (60s) because operator-driven
+ * flows — specifically `switchroom update` from the host CLI — stamp
+ * the marker BEFORE `docker compose up -d --remove-orphans` runs, and
+ * the recreate for a multi-agent fleet can comfortably take longer
+ * than 60s to bring every container's gateway back up (9 agents ×
+ * docker network/volume setup + gateway boot probes). Without this
+ * extended window, my "operator: switchroom update" marker reads
+ * stale by the time the late-bootstrapping agent's gateway reads it
+ * — `determineRestartReason` falls through to `'crash'` and the
+ * boot card renders the planned redeploy as a crash with a noisy
+ * `agent-crashed` operator-events broadcast (the very pattern
+ * PR #1139 set out to suppress).
+ *
+ * Five minutes is generous: a 50-agent fleet recreate would still
+ * finish well inside it, and we still treat a 5-min-old marker as a
+ * crash if the gateway eventually does come up so the longer window
+ * isn't a "silent forever" mode. Verified end-to-end against a 9-agent
+ * fleet on 2026-05-13: latest-recreated agent's marker age was 97s.
+ *
+ * Keyed on the reason-text prefix (`operator:`) so user/cli/in-gateway
+ * restart paths keep their 60s tight window — those produce a much
+ * shorter shutdown-to-boot delta and a 5-min window there would mask
+ * a real crash during/after a `/restart`.
+ */
+const OPERATOR_MARKER_MAX_AGE_MS = 5 * 60_000
+
 /**
  * Determine why this gateway is starting up.
  *
  * Priority order:
  *   1. restart-pending.json present + fresh (<5 min) → 'planned'
- *   2. clean-shutdown.json present + fresh (<60s default) → 'graceful'
+ *   2. clean-shutdown.json present + fresh:
+ *        - default <60s → 'graceful'
+ *        - reason starts with `operator:` → <5min → 'graceful' (#1141
+ *          follow-up: fleet recreate can exceed 60s and still be a
+ *          planned operator update)
  *   3. gateway-session.json present (prior process existed) → 'crash'
  *   4. Otherwise → 'fresh'
  */
@@ -30,6 +62,7 @@ export function determineRestartReason(opts: {
   now: number
   cleanMaxAgeMs?: number
   markerMaxAgeMs?: number
+  operatorMaxAgeMs?: number
 }): RestartReason {
   const {
     marker,
@@ -38,14 +71,15 @@ export function determineRestartReason(opts: {
     now,
     cleanMaxAgeMs = CLEAN_SHUTDOWN_MAX_AGE_MS,
     markerMaxAgeMs = 5 * 60_000,
+    operatorMaxAgeMs = OPERATOR_MARKER_MAX_AGE_MS,
   } = opts
   if (marker != null && now - marker.ts < markerMaxAgeMs) return 'planned'
-  if (
-    cleanMarker != null &&
-    now - cleanMarker.ts >= 0 &&
-    now - cleanMarker.ts < cleanMaxAgeMs
-  )
-    return 'graceful'
+  if (cleanMarker != null && now - cleanMarker.ts >= 0) {
+    const isOperator = typeof cleanMarker.reason === 'string'
+      && cleanMarker.reason.startsWith('operator:')
+    const window = isOperator ? operatorMaxAgeMs : cleanMaxAgeMs
+    if (now - cleanMarker.ts < window) return 'graceful'
+  }
   if (sessionMarker != null) return 'crash'
   return 'fresh'
 }

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

@@ -0,0 +1,66 @@
+/**
+ * Pure boot-card version-string composer + helpers.
+ *
+ * Extracted from gateway.ts so the version-string code path can be
+ * exercised by property-based tests without dragging in the gateway's
+ * runtime side effects (env loading, bot client init, etc.). Live
+ * callers stay in gateway.ts; this file is pure functions only.
+ */
+
+export type BootVersionInputs = {
+  version: string
+  commitSha: string | null
+  commitDate: string | null
+  latestPr: number | null
+  commitsAheadOfTag: number | null
+  claudeCliVersion: string | null
+}
+
+export function formatRelativeAgo(iso: string | null): string | null {
+  if (!iso) return null
+  const t = Date.parse(iso)
+  if (Number.isNaN(t)) return null
+  const diffSec = Math.max(0, Math.floor((Date.now() - t) / 1000))
+  if (diffSec < 60) return `${diffSec}s ago`
+  if (diffSec < 3600) return `${Math.floor(diffSec / 60)}m ago`
+  if (diffSec < 86400) return `${Math.floor(diffSec / 3600)}h ago`
+  return `${Math.floor(diffSec / 86400)}d ago`
+}
+
+/**
+ * Compose the version string shown in the boot-card ack line and the
+ * status card's Version row. Two shapes, matching the deleted greeting
+ * card's behavior:
+ *
+ *   - on a tag (commits_ahead = 0 or null):   "v0.2.0 · #44 · claude 2.1.123 · 2h ago"
+ *     (omit "#44 ·" when no PR was parsed; omit claude segment if unavailable)
+ *   - ahead of a tag (commits_ahead > 0):     "v0.2.0+3 · db6de9e · claude 2.1.123 · 2m ago"
+ *     (always show short SHA when ahead, omit PR)
+ *
+ * Age segment is omitted if no commit date is available (npm consumer).
+ *
+ * Sanitization: claude --version output is whitespace-collapsed before
+ * embedding — a malicious or rogue `claude` on PATH must not be able to
+ * smuggle newlines into the ack line. HTML escaping happens at the
+ * boot-card boundary (see boot-card.ts: escapeHtml(version)).
+ */
+export function composeBootVersionString(inputs: BootVersionInputs): string {
+  const ago = formatRelativeAgo(inputs.commitDate)
+  const onTag = inputs.commitsAheadOfTag === 0 || inputs.commitsAheadOfTag === null
+  const claudeVerRaw = inputs.claudeCliVersion?.replace(/\s+/g, ' ').trim()
+  const claudeVer = claudeVerRaw && claudeVerRaw.length > 0 ? claudeVerRaw : null
+
+  if (onTag) {
+    const parts: string[] = [`v${inputs.version}`]
+    if (inputs.latestPr != null) parts.push(`#${inputs.latestPr}`)
+    if (claudeVer) parts.push(`claude ${claudeVer}`)
+    if (ago) parts.push(ago)
+    return parts.join(' · ')
+  }
+
+  const parts: string[] = [`v${inputs.version}+${inputs.commitsAheadOfTag}`]
+  if (inputs.commitSha) parts.push(inputs.commitSha)
+  if (claudeVer) parts.push(`claude ${claudeVer}`)
+  if (ago) parts.push(ago)
+  return parts.join(' · ')
+}