switchroom 0.5.0

package/telegram-plugin/tests/boot-card-dedupe.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Unit tests for `shouldSkipDuplicateBootCard` — the helper that prevents
+ * the boot path AND the bridge-reconnect path from BOTH posting a boot
+ * card on a single gateway lifetime.
+ *
+ * Regression for the duplicate-post observed in klanker's journal at
+ * 2026-04-26 11:19:47, where msgId 2245 was posted by the boot path and
+ * msgId 2248 by the bridge-reconnect path within 5 seconds.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { shouldSkipDuplicateBootCard } from '../gateway/boot-card.js'
+
+describe('shouldSkipDuplicateBootCard — boot path', () => {
+  it('skips on the boot path when bridge-reconnect already posted a card', () => {
+    // First-write-wins: when the agent's IPC client connects faster
+    // than the gateway IIFE reaches its emit, bridge-reconnect runs
+    // first and sets activeBootCard. The boot path must defer.
+    // Regression for finn 2026-05-02 duplicate (msgId 673 + 674)
+    // — both posted within ~100ms because the boot path was
+    // unconditionally allowed past the gate.
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 42 } },
+      'boot',
+    )
+    expect(decision.skip).toBe(true)
+    expect(decision.reason).toMatch(/msgId.*42/)
+    expect(decision.reason).toMatch(/site=boot/)
+  })
+
+  it('skips on the boot path when bridge-reconnect emit is in-flight', () => {
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: null, bootCardPending: true },
+      'boot',
+    )
+    expect(decision.skip).toBe(true)
+    expect(decision.reason).toMatch(/in-flight/i)
+  })
+
+  it('does not skip on the boot path with no active card and no pending emit', () => {
+    const decision = shouldSkipDuplicateBootCard({ activeBootCard: null }, 'boot')
+    expect(decision.skip).toBe(false)
+  })
+})
+
+describe('shouldSkipDuplicateBootCard — bridge-reconnect path', () => {
+  it('skips when the boot path already posted (active card present)', () => {
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 2245 } },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(true)
+    expect(decision.reason).toBeDefined()
+    expect(decision.reason).toContain('2245')
+  })
+
+  it('does not skip when the boot path produced no card', () => {
+    // Plausible scenario: boot path skipped due to no chat_id known yet,
+    // and bridge-reconnect arrives later with a chat_id from the IPC client.
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: null },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(false)
+  })
+})
+
+describe('shouldSkipDuplicateBootCard — reason format', () => {
+  it('includes the active messageId in the reason for observability', () => {
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 9999 } },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(true)
+    expect(decision.reason).toMatch(/msgId.*9999/)
+  })
+
+  it('omits reason when not skipping', () => {
+    const decision = shouldSkipDuplicateBootCard({ activeBootCard: null }, 'boot')
+    expect(decision.skip).toBe(false)
+    expect(decision.reason).toBeUndefined()
+  })
+
+  it('reason carries the site label so dedupe-source is greppable in logs', () => {
+    const fromBoot = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 1 } },
+      'boot',
+    )
+    expect(fromBoot.reason).toMatch(/site=boot/)
+    const fromReconnect = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 1 } },
+      'bridge-reconnect',
+    )
+    expect(fromReconnect.reason).toMatch(/site=bridge-reconnect/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// In-flight race window (issue #489)
+//
+// Before #489, the gate only saw activeBootCard, which is only assigned
+// AFTER the boot path's `await startBootCard(...)` resolved. If the agent's
+// IPC client connected during that 1–2s sendMessage round-trip,
+// onClientRegistered would dedupe-check, see activeBootCard = null, and
+// fire its own boot card. Klanker on 2026-05-01 10:13:15 produced msgId
+// 4715 + 4716 from the same gateway PID via this race. The bootCardPending
+// flag is set synchronously before the await so the dedupe sees in-flight.
+// ---------------------------------------------------------------------------
+
+describe('shouldSkipDuplicateBootCard — in-flight (race window, #489)', () => {
+  it('skips bridge-reconnect when boot path is still awaiting sendMessage', () => {
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: null, bootCardPending: true },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(true)
+    expect(decision.reason).toMatch(/in-flight/i)
+  })
+
+  it('skips bridge-reconnect when both pending and active are set (post-resolution overlap)', () => {
+    // A bridge-reconnect can fire after activeBootCard was assigned but
+    // before the finally-clears bootCardPending — both true is legal.
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: { messageId: 4715 }, bootCardPending: true },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(true)
+    // In-flight wins because it's checked first; either reason is fine
+    // for observability — the card is correctly skipped either way.
+    expect(decision.reason).toBeDefined()
+  })
+
+  it('skips boot path when bridge-reconnect emit is in-flight (first-write-wins)', () => {
+    // The boot path is no longer "primary" — empirical evidence
+    // (finn 2026-05-02) shows bridge-reconnect can fire first when
+    // the agent IPC-connects before the gateway IIFE reaches its
+    // emit. Both sites consult the gate symmetrically.
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: null, bootCardPending: true },
+      'boot',
+    )
+    expect(decision.skip).toBe(true)
+  })
+
+  it('treats undefined bootCardPending as "not pending" for backward compat', () => {
+    // Callers that pre-date the flag still pass { activeBootCard } only.
+    // Their behaviour must not change.
+    const decision = shouldSkipDuplicateBootCard(
+      { activeBootCard: null },
+      'bridge-reconnect',
+    )
+    expect(decision.skip).toBe(false)
+  })
+})

package/telegram-plugin/tests/boot-card-probe-target.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for #309: boot card uses the agent slug (not display name) for
+ * systemd unit probes.
+ *
+ * Root cause: probeAgentProcess and probeCronTimers were called with
+ * opts.agentName (the persona display name, e.g. "Klanker") instead of
+ * the lowercase slug ("klanker"). systemctl returns LoadState=not-found
+ * for the capitalised name because unit files are always lowercase.
+ *
+ * Fix: RunProbesOpts.agentSlug carries the slug separately; runAllProbes
+ * passes opts.agentSlug (falling back to opts.agentName for compat) to
+ * both probeAgentProcess and probeCronTimers.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { join } from 'path'
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+
+import { runAllProbes } from '../gateway/boot-card.js'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+type ExecFileResult = { stdout: string; stderr: string }
+type RecordedCall = { cmd: string; args: string[] }
+
+/**
+ * Build an execFile mock that records every (cmd, args) call and dispatches
+ * the response based on which systemctl sub-command is being called.
+ *
+ * `show`       → responds with a valid "active" systemctl kv blob so that
+ *               probeAgentProcess resolves immediately without retrying.
+ * `list-timers`→ responds with empty JSON array (0 timers).
+ * anything else→ responds with empty stdout.
+ */
+function makeDispatchingExecFile(slug: string): {
+  fn: (cmd: string, args: string[]) => Promise<ExecFileResult>
+  calls: RecordedCall[]
+} {
+  const calls: RecordedCall[] = []
+  return {
+    fn: async (cmd: string, args: string[]) => {
+      calls.push({ cmd, args })
+      if (cmd === 'systemctl') {
+        if (args.includes('show')) {
+          // Return a valid active systemd kv blob so probeAgentProcess exits
+          // immediately on the first call (no retry needed).
+          return {
+            stdout: [
+              'MainPID=9999',
+              'ActiveState=active',
+              'MemoryCurrent=52428800',
+              'ActiveEnterTimestamp=1700000000000000',
+            ].join('\n') + '\n',
+            stderr: '',
+          }
+        }
+        if (args.includes('list-timers')) {
+          return { stdout: '[]', stderr: '' }
+        }
+      }
+      return { stdout: '', stderr: '' }
+    },
+    calls,
+  }
+}
+
+// ── Core probe-target tests ───────────────────────────────────────────────────
+
+describe('#309: runAllProbes — slug vs display name for systemd calls', () => {
+  function makeTmpAgentDir(): string {
+    return mkdtempSync(join(tmpdir(), 'switchroom-test-'))
+  }
+
+  it('probeAgentProcess target is switchroom-<slug>.service, not switchroom-<displayName>.service', async () => {
+    const tmpDir = makeTmpAgentDir()
+    try {
+      const { fn: execFileMock, calls } = makeDispatchingExecFile('klanker')
+
+      await runAllProbes({
+        agentName: 'Klanker',   // persona display name — capitalised
+        agentSlug: 'klanker',   // systemd slug — lowercase
+        version: 'v0.3.0',
+        agentDir: tmpDir,
+        gatewayInfo: { pid: 12345, startedAtMs: Date.now() },
+        fetchImpl: async () => new Response('', { status: 200 }),
+        settleWindowMs: 0,
+        agentLiveWindowMs: 0,   // disable live loop
+        probeExecFileImpl: execFileMock,
+      })
+
+      // probeAgentProcess calls: systemctl --user show switchroom-<name>.service -p ...
+      const agentProbeCall = calls.find(c =>
+        c.cmd === 'systemctl' && c.args.includes('show'),
+      )
+      expect(agentProbeCall, 'probeAgentProcess must call systemctl show').toBeDefined()
+      const unitArg = agentProbeCall!.args.find(a => a.startsWith('switchroom-'))
+      // Must use the slug, not the capitalised display name.
+      expect(unitArg).toBe('switchroom-klanker.service')
+    } finally {
+      rmSync(tmpDir, { recursive: true })
+    }
+  })
+
+  it('probeCronTimers target is switchroom-<slug>-cron-*, not switchroom-<displayName>-cron-*', async () => {
+    const tmpDir = makeTmpAgentDir()
+    try {
+      const { fn: execFileMock, calls } = makeDispatchingExecFile('klanker')
+
+      await runAllProbes({
+        agentName: 'Klanker',
+        agentSlug: 'klanker',
+        version: 'v0.3.0',
+        agentDir: tmpDir,
+        gatewayInfo: { pid: 12345, startedAtMs: Date.now() },
+        fetchImpl: async () => new Response('', { status: 200 }),
+        settleWindowMs: 0,
+        agentLiveWindowMs: 0,
+        probeExecFileImpl: execFileMock,
+      })
+
+      // probeCronTimers calls: systemctl --user list-timers switchroom-<name>-cron-*
+      const cronProbeCall = calls.find(c =>
+        c.cmd === 'systemctl' && c.args.includes('list-timers'),
+      )
+      expect(cronProbeCall, 'probeCronTimers must call systemctl list-timers').toBeDefined()
+      const cronGlob = cronProbeCall!.args.find(a => a.includes('cron'))
+      expect(cronGlob).toBe('switchroom-klanker-cron-*')
+    } finally {
+      rmSync(tmpDir, { recursive: true })
+    }
+  })
+
+  it('no systemctl call uses the capitalised display name as the unit target', async () => {
+    const tmpDir = makeTmpAgentDir()
+    try {
+      const { fn: execFileMock, calls } = makeDispatchingExecFile('klanker')
+
+      await runAllProbes({
+        agentName: 'Klanker',
+        agentSlug: 'klanker',
+        version: 'v0.3.0',
+        agentDir: tmpDir,
+        gatewayInfo: { pid: 12345, startedAtMs: Date.now() },
+        fetchImpl: async () => new Response('', { status: 200 }),
+        settleWindowMs: 0,
+        agentLiveWindowMs: 0,
+        probeExecFileImpl: execFileMock,
+      })
+
+      const systemctlCalls = calls.filter(c => c.cmd === 'systemctl')
+      expect(systemctlCalls.length, 'execFileMock must be called at least once').toBeGreaterThan(0)
+
+      for (const call of systemctlCalls) {
+        for (const arg of call.args) {
+          expect(
+            arg,
+            `systemctl was invoked with arg "${arg}" which contains the display name "Klanker" — expected slug "klanker"`,
+          ).not.toContain('Klanker')
+        }
+      }
+    } finally {
+      rmSync(tmpDir, { recursive: true })
+    }
+  })
+
+  it('falls back to agentName when agentSlug is not provided (backwards compat)', async () => {
+    const tmpDir = makeTmpAgentDir()
+    try {
+      const { fn: execFileMock, calls } = makeDispatchingExecFile('myagent')
+
+      await runAllProbes({
+        agentName: 'myagent',
+        // no agentSlug — should fall back to agentName
+        version: 'v0.3.0',
+        agentDir: tmpDir,
+        gatewayInfo: { pid: 12345, startedAtMs: Date.now() },
+        fetchImpl: async () => new Response('', { status: 200 }),
+        settleWindowMs: 0,
+        agentLiveWindowMs: 0,
+        probeExecFileImpl: execFileMock,
+      })
+
+      const agentProbeCall = calls.find(c =>
+        c.cmd === 'systemctl' && c.args.includes('show'),
+      )
+      expect(agentProbeCall, 'probeAgentProcess must call systemctl show').toBeDefined()
+      const unitArg = agentProbeCall!.args.find(a => a.startsWith('switchroom-'))
+      expect(unitArg).toBe('switchroom-myagent.service')
+    } finally {
+      rmSync(tmpDir, { recursive: true })
+    }
+  })
+})

package/telegram-plugin/tests/boot-card-reason.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for determineRestartReason() — the pure helper that decides
+ * which restart reason to show in the boot card.
+ *
+ * Run with:
+ *   bun test telegram-plugin/tests/boot-card-reason.test.ts
+ */
+import { describe, it, expect } from 'bun:test'
+import { determineRestartReason } from '../gateway/boot-reason.js'
+
+const NOW = 1_700_000_000_000 // arbitrary fixed timestamp
+
+// ── Marker fixtures ────────────────────────────────────────────────────────
+
+function recentMarker(offsetMs = 0) {
+  return { ts: NOW - offsetMs }
+}
+
+function recentCleanMarker(offsetMs = 0) {
+  return { ts: NOW - offsetMs }
+}
+
+function sessionMarker() {
+  return { pid: 1234 }
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe('determineRestartReason', () => {
+  it('returns "planned" when a restart marker is present and fresh (<5 min)', () => {
+    const result = determineRestartReason({
+      marker: recentMarker(10_000),     // 10s ago
+      cleanMarker: null,
+      sessionMarker: sessionMarker(),
+      now: NOW,
+    })
+    expect(result).toBe('planned')
+  })
+
+  it('returns "graceful" when clean-shutdown marker is present and fresh, no restart marker', () => {
+    const result = determineRestartReason({
+      marker: null,
+      cleanMarker: recentCleanMarker(5_000),   // 5s ago, within 60s default
+      sessionMarker: sessionMarker(),
+      now: NOW,
+    })
+    expect(result).toBe('graceful')
+  })
+
+  it('returns "crash" when session marker exists but no other markers', () => {
+    const result = determineRestartReason({
+      marker: null,
+      cleanMarker: null,
+      sessionMarker: sessionMarker(),
+      now: NOW,
+    })
+    expect(result).toBe('crash')
+  })
+
+  it('returns "fresh" when no markers exist at all (first ever start)', () => {
+    const result = determineRestartReason({
+      marker: null,
+      cleanMarker: null,
+      sessionMarker: null,
+      now: NOW,
+    })
+    expect(result).toBe('fresh')
+  })
+
+  it('returns "crash" (not "graceful") when clean-shutdown marker is stale (>60s)', () => {
+    const result = determineRestartReason({
+      marker: null,
+      cleanMarker: recentCleanMarker(90_000),  // 90s ago, stale
+      sessionMarker: sessionMarker(),
+      now: NOW,
+    })
+    // stale clean-shutdown = marker too old to suppress crash detection
+    expect(result).toBe('crash')
+  })
+
+  it('returns "planned" even when clean-shutdown marker is also present (planned wins)', () => {
+    // Both present: planned restart marker takes priority
+    const result = determineRestartReason({
+      marker: recentMarker(3_000),
+      cleanMarker: recentCleanMarker(3_000),
+      sessionMarker: sessionMarker(),
+      now: NOW,
+    })
+    expect(result).toBe('planned')
+  })
+
+  it('respects custom markerMaxAgeMs — stale marker does not count as planned', () => {
+    const result = determineRestartReason({
+      marker: recentMarker(10 * 60_000),  // 10 min ago
+      cleanMarker: null,
+      sessionMarker: sessionMarker(),
+      now: NOW,
+      markerMaxAgeMs: 5 * 60_000,          // 5 min window
+    })
+    // Marker is too old to be "planned", session marker present → crash
+    expect(result).toBe('crash')
+  })
+})

package/telegram-plugin/tests/boot-card-render.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for the post-#142 boot-card renderer.
+ *
+ * The contract this PR locks in:
+ *   - Healthy boot → one line ack ("✅ <agent> back up · <version>"). No probe
+ *     rows ever, regardless of `probes` shape (all-ok or absent).
+ *   - Crash recovery → ⚠️ on the ack line + a single "Crash recovery" row.
+ *   - Degraded probes (status='degraded' or 'fail') → one row per probe,
+ *     in PROBE_KEYS order, with the matching dot emoji.
+ *   - All-green probes after the settle window → no edit (text equals
+ *     the initial post).
+ *   - HTML escaping on agentName, version, and probe `detail`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { renderBootCard, resolvePersonaName } from '../gateway/boot-card.js'
+
+describe('renderBootCard — quiet by default', () => {
+  it('returns one-line ack with default ✅ when no probes and no restart reason', () => {
+    const out = renderBootCard({ agentName: 'klanker', version: 'v0.3.0+44' })
+    expect(out).toBe('✅ <b>klanker</b> back up · v0.3.0+44')
+    expect(out).not.toContain('\n')
+  })
+
+  it('uses ✅ for planned and graceful restart reasons (return-to-service)', () => {
+    for (const reason of ['planned', 'graceful'] as const) {
+      const out = renderBootCard({ agentName: 'agent', version: 'v1', restartReason: reason })
+      expect(out).toBe('✅ <b>agent</b> back up · v1')
+    }
+  })
+
+  it('uses 🆕 for fresh starts (no prior session marker — first boot)', () => {
+    const out = renderBootCard({ agentName: 'a', version: 'v', restartReason: 'fresh' })
+    expect(out.startsWith('🆕')).toBe(true)
+    expect(out).toBe('🆕 <b>a</b> back up · v')
+  })
+
+  it('all-ok probes produce no extra rows — same output as no probes at all', () => {
+    const ackOnly = renderBootCard({ agentName: 'k', version: 'v0.3.0' })
+    const ackWithGreenProbes = renderBootCard({
+      agentName: 'k',
+      version: 'v0.3.0',
+      probes: {
+        account:   { status: 'ok', label: 'Account',   detail: 'a@b' },
+        agent:     { status: 'ok', label: 'Agent',     detail: 'PID 1' },
+        gateway:   { status: 'ok', label: 'Gateway',   detail: 'up 5s' },
+        quota:     { status: 'ok', label: 'Quota',     detail: '50% used' },
+        hindsight: { status: 'ok', label: 'Hindsight', detail: 'reachable' },
+        crons:     { status: 'ok', label: 'Crons',     detail: '0 timers' },
+      },
+    })
+    expect(ackWithGreenProbes).toBe(ackOnly)
+  })
+})
+
+describe('renderBootCard — degraded conditions', () => {
+  it('crash reason flips ack emoji to ⚠️ and appends a Crash recovery row', () => {
+    const out = renderBootCard({
+      agentName: 'lawgpt',
+      version: 'v0.3.0+44',
+      restartReason: 'crash',
+      restartAgeMs: 2_100,
+    })
+    const lines = out.split('\n')
+    expect(lines[0]).toBe('⚠️ <b>lawgpt</b> back up · v0.3.0+44')
+    expect(lines[1]).toBe('') // separator
+    expect(lines[2]).toContain('⚠️ <b>Restart</b>')
+    expect(lines[2]).toContain('crash recovery')
+    expect(lines[2]).toContain('2.1s ago')
+  })
+
+  it('crash reason without restartAgeMs omits the "ago" suffix', () => {
+    const out = renderBootCard({ agentName: 'a', version: 'v1', restartReason: 'crash' })
+    expect(out).toContain('⚠️ <b>Restart</b>  crash recovery')
+    expect(out).not.toMatch(/\d+\.\d+s ago/)
+  })
+
+  it('appends one row per non-ok probe, healthy probes never render', () => {
+    const out = renderBootCard({
+      agentName: 'klanker',
+      version: 'v0.3.0',
+      probes: {
+        account:   { status: 'degraded', label: 'Account',   detail: 'token expiring · 3d' },
+        agent:     { status: 'ok',       label: 'Agent',     detail: 'PID 1' },
+        gateway:   { status: 'ok',       label: 'Gateway',   detail: 'up 30s' },
+        quota:     { status: 'fail',     label: 'Quota',     detail: 'rate limited' },
+        hindsight: { status: 'ok',       label: 'Hindsight', detail: 'reachable' },
+        crons:     { status: 'ok',       label: 'Crons',     detail: '4 timers' },
+      },
+    })
+    expect(out).toContain('🟡 <b>Account</b>  token expiring · 3d')
+    expect(out).toContain('🔴 <b>Quota</b>  rate limited')
+    // Healthy probes must not render.
+    expect(out).not.toContain('Agent</b>')
+    expect(out).not.toContain('Gateway</b>')
+    expect(out).not.toContain('Hindsight</b>')
+    expect(out).not.toContain('Crons</b>')
+  })
+
+  it('orders probe rows in PROBE_KEYS canonical order regardless of object iteration', () => {
+    // Insert in a non-canonical order; renderer must still output Account first,
+    // then Hindsight, then Crons (matching PROBE_KEYS).
+    const out = renderBootCard({
+      agentName: 'a',
+      version: 'v',
+      probes: {
+        crons:     { status: 'fail',     label: 'Crons',     detail: 'bad' },
+        hindsight: { status: 'fail',     label: 'Hindsight', detail: 'unreachable' },
+        account:   { status: 'degraded', label: 'Account',   detail: 'expiring' },
+      },
+    })
+    const accountIdx = out.indexOf('Account</b>')
+    const hindsightIdx = out.indexOf('Hindsight</b>')
+    const cronsIdx = out.indexOf('Crons</b>')
+    expect(accountIdx).toBeGreaterThan(-1)
+    expect(hindsightIdx).toBeGreaterThan(accountIdx)
+    expect(cronsIdx).toBeGreaterThan(hindsightIdx)
+  })
+
+  it('crash + degraded probe = both rows render', () => {
+    const out = renderBootCard({
+      agentName: 'a',
+      version: 'v',
+      restartReason: 'crash',
+      restartAgeMs: 1_500,
+      probes: {
+        account: { status: 'degraded', label: 'Account', detail: 'expiring' },
+      },
+    })
+    const lines = out.split('\n')
+    expect(lines[0].startsWith('⚠️')).toBe(true)
+    expect(lines).toContain('') // separator after ack
+    expect(out).toContain('⚠️ <b>Restart</b>')
+    expect(out).toContain('🟡 <b>Account</b>  expiring')
+  })
+
+  it('null probe entries are skipped (defensive against partial probe maps)', () => {
+    const out = renderBootCard({
+      agentName: 'a',
+      version: 'v',
+      probes: {
+        account: null,
+        agent: { status: 'fail', label: 'Agent', detail: 'service deactivating' },
+      },
+    })
+    expect(out).not.toContain('Account')
+    expect(out).toContain('🔴 <b>Agent</b>  service deactivating')
+  })
+})
+
+describe('renderBootCard — HTML escaping', () => {
+  it('escapes special chars in agent name', () => {
+    const out = renderBootCard({ agentName: 'foo<bar>', version: 'v1' })
+    expect(out).toContain('foo&lt;bar&gt;')
+    expect(out).not.toContain('foo<bar>')
+  })
+
+  it('escapes special chars in version', () => {
+    const out = renderBootCard({ agentName: 'a', version: 'v<1>' })
+    expect(out).toContain('v&lt;1&gt;')
+  })
+
+  it('escapes special chars in probe detail', () => {
+    const out = renderBootCard({
+      agentName: 'a',
+      version: 'v',
+      probes: {
+        quota: { status: 'fail', label: 'Quota', detail: 'rate <limited>' },
+      },
+    })
+    expect(out).toContain('rate &lt;limited&gt;')
+    expect(out).not.toContain('rate <limited>')
+  })
+})
+
+describe('resolvePersonaName — persona name over slug (#169)', () => {
+  it('returns soul.name when set in config', () => {
+    const fakeCfg = () => ({
+      agents: { finn: { soul: { name: 'Finn', style: 'warm' } } },
+    })
+    expect(resolvePersonaName('finn', fakeCfg)).toBe('Finn')
+  })
+
+  it('falls back to slug when soul.name is absent', () => {
+    const fakeCfg = () => ({
+      agents: { finn: { soul: null } },
+    })
+    expect(resolvePersonaName('finn', fakeCfg)).toBe('finn')
+  })
+
+  it('falls back to slug when soul.name is empty string', () => {
+    const fakeCfg = () => ({
+      agents: { finn: { soul: { name: '', style: 'warm' } } },
+    })
+    expect(resolvePersonaName('finn', fakeCfg)).toBe('finn')
+  })
+
+  it('falls back to slug when agent key is not in config', () => {
+    const fakeCfg = () => ({ agents: {} })
+    expect(resolvePersonaName('finn', fakeCfg)).toBe('finn')
+  })
+
+  it('falls back to slug when config loader throws', () => {
+    const throwing = () => { throw new Error('no config file') }
+    expect(resolvePersonaName('finn', throwing)).toBe('finn')
+  })
+
+  it('boot card rendered with soul.name not slug — acceptance criterion for #169', () => {
+    // Simulate: slug is "finn", soul.name is "Finn"
+    const fakeCfg = () => ({
+      agents: { finn: { soul: { name: 'Finn', style: 'warm' } } },
+    })
+    const displayName = resolvePersonaName('finn', fakeCfg)
+    const out = renderBootCard({ agentName: displayName, version: 'v0.3.0+50' })
+    // User sees "Finn", not the slug "finn"
+    expect(out).toBe('✅ <b>Finn</b> back up · v0.3.0+50')
+    expect(out).not.toContain('<b>finn</b>')
+  })
+})