switchroom 0.18.3 → 0.18.7

package/telegram-plugin/tests/resolve-person.test.ts

@@ -0,0 +1,290 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  buildPersonDirectory,
+  resolvePersonName,
+  runPersonDirectoryBootCheck,
+  safeResolvePersonName,
+  type PersonDirectory,
+  type RawPersonEntry,
+} from '../gateway/resolve-person.js'
+
+/**
+ * Telegram person_id name resolution (docs/configuration.md).
+ *
+ * Covers the requirements from the converged design:
+ *   - happy-path resolution
+ *   - unresolved-id fallback (fail-open)
+ *   - a malformed single entry is dropped WITHOUT affecting others
+ *   - chat-scoping: a name is shown only in a chat/group the person is a
+ *     member of (per that chat's allowFrom), never broadcast into every
+ *     chat
+ *   - boot-time validation alert firing on bad config
+ *   - validation-step-crash alert firing (dead-man's-switch)
+ */
+
+const LISA: RawPersonEntry = { key: 'lisa', person_id: 'Lisa', telegram_ids: ['8201250670'] }
+const KEN: RawPersonEntry = { key: 'ken', person_id: 'Ken', telegram_ids: ['mekenthompson', '111'] }
+
+describe('buildPersonDirectory — happy path', () => {
+  it('resolves a single well-formed entry', () => {
+    const { directory, dropped } = buildPersonDirectory([LISA])
+    expect(dropped).toEqual([])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+  })
+
+  it('resolves multiple entries, multiple telegram_ids each, case/@-insensitive', () => {
+    const { directory, dropped } = buildPersonDirectory([LISA, KEN])
+    expect(dropped).toEqual([])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(directory.byTelegramKey['mekenthompson']?.personId).toBe('Ken')
+    expect(directory.byTelegramKey['111']?.personId).toBe('Ken')
+    // username lookups are normalized: leading "@" stripped, lowercased
+    expect(directory.byTelegramKey['@MeKenThompson'.trim().replace(/^@/, '').toLowerCase()]?.personId).toBe('Ken')
+  })
+
+  it('no entries → empty directory (fleet behaves as today)', () => {
+    const { directory, dropped } = buildPersonDirectory([])
+    expect(directory.byTelegramKey).toEqual({})
+    expect(dropped).toEqual([])
+  })
+})
+
+describe('buildPersonDirectory — per-entry validation drops only the bad entry', () => {
+  it('drops an entry with an empty person_id, keeps the other entry intact', () => {
+    const bad: RawPersonEntry = { key: 'ghost', person_id: '', telegram_ids: ['999'] }
+    const { directory, dropped } = buildPersonDirectory([LISA, bad])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(directory.byTelegramKey['999']).toBeUndefined()
+    expect(dropped).toHaveLength(1)
+    expect(dropped[0]?.key).toBe('ghost')
+    expect(dropped[0]?.reason).toMatch(/person_id/)
+  })
+
+  it('drops an entry with no telegram_ids, keeps the other entry intact', () => {
+    const bad: RawPersonEntry = { key: 'ghost', person_id: 'Ghost', telegram_ids: [] }
+    const { directory, dropped } = buildPersonDirectory([LISA, bad])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(dropped).toHaveLength(1)
+    expect(dropped[0]?.key).toBe('ghost')
+    expect(dropped[0]?.reason).toMatch(/telegram_ids/)
+  })
+
+  it('drops a duplicate person_id (later entry loses), keeps the first entry intact', () => {
+    const dupe: RawPersonEntry = { key: 'lisa2', person_id: 'Lisa', telegram_ids: ['555'] }
+    const { directory, dropped } = buildPersonDirectory([LISA, dupe])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(directory.byTelegramKey['555']).toBeUndefined()
+    expect(dropped).toHaveLength(1)
+    expect(dropped[0]?.key).toBe('lisa2')
+    expect(dropped[0]?.reason).toMatch(/duplicate person_id/)
+  })
+
+  it('drops a duplicate telegram_id claimed by a different person_id (later entry loses), keeps the first entry intact — no silent last-write-wins', () => {
+    const dupe: RawPersonEntry = { key: 'imposter', person_id: 'Imposter', telegram_ids: ['8201250670'] }
+    const { directory, dropped } = buildPersonDirectory([LISA, dupe])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(dropped).toHaveLength(1)
+    expect(dropped[0]?.key).toBe('imposter')
+    expect(dropped[0]?.reason).toMatch(/duplicate telegram_id/)
+  })
+
+  it('telegram_id collision on boot check fires the config-warning alert path, does not blank the whole directory', () => {
+    const dupe: RawPersonEntry = { key: 'imposter', person_id: 'Imposter', telegram_ids: ['8201250670'] }
+    const result = runPersonDirectoryBootCheck(() => [LISA, KEN, dupe])
+    expect(result.alertDetail).not.toBeNull()
+    expect(result.alertDetail).toContain('imposter')
+    expect(result.directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(result.directory.byTelegramKey['mekenthompson']?.personId).toBe('Ken')
+  })
+
+  // ── #2957 honesty fix: broadcast alertDetail must not surface the
+  //    person_id human-name value (the display path chat-scopes names;
+  //    the config-warning card fans out to EVERY allowFrom chat, incl.
+  //    groups where the named person may not be a member). The verbose
+  //    reason stays in the private logLine. ─────────────────────────
+  it('duplicate person_id: alertDetail scrubs the person_id value (keeps key + class); logLine keeps it', () => {
+    const dupe: RawPersonEntry = { key: 'lisa2', person_id: 'Lisa', telegram_ids: ['555'] }
+    const result = runPersonDirectoryBootCheck(() => [LISA, dupe])
+    expect(result.alertDetail).not.toBeNull()
+    // Broadcast-safe: names the losing config key + the collision class,
+    // but NOT the human-name "Lisa" value nor which name it collided with.
+    expect(result.alertDetail).toContain('lisa2')
+    expect(result.alertDetail).toContain('duplicate person_id already claimed')
+    expect(result.alertDetail).not.toContain('"Lisa"')
+    // Private stderr log keeps the verbose detail.
+    expect(result.logLine).toContain('"Lisa"')
+  })
+
+  it('duplicate telegram_id: alertDetail scrubs the colliding id; logLine keeps it', () => {
+    const dupe: RawPersonEntry = { key: 'imposter', person_id: 'Imposter', telegram_ids: ['8201250670'] }
+    const result = runPersonDirectoryBootCheck(() => [LISA, dupe])
+    expect(result.alertDetail).not.toBeNull()
+    expect(result.alertDetail).toContain('imposter')
+    expect(result.alertDetail).toContain('duplicate telegram_id already claimed')
+    // The colliding telegram id value is scrubbed from the broadcast.
+    expect(result.alertDetail).not.toContain('8201250670')
+    expect(result.logLine).toContain('8201250670')
+  })
+
+  it('drops an entry with a missing users: map key', () => {
+    const bad: RawPersonEntry = { key: '', person_id: 'Nobody', telegram_ids: ['1'] }
+    const { directory, dropped } = buildPersonDirectory([LISA, bad])
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(dropped).toHaveLength(1)
+    expect(dropped[0]?.reason).toMatch(/users: map key/)
+  })
+
+  it('multiple malformed entries each get their own drop reason, valid entries unaffected', () => {
+    const bad1: RawPersonEntry = { key: 'a', person_id: '', telegram_ids: ['1'] }
+    const bad2: RawPersonEntry = { key: 'b', person_id: 'B', telegram_ids: [] }
+    const { directory, dropped } = buildPersonDirectory([LISA, bad1, KEN, bad2])
+    expect(dropped).toHaveLength(2)
+    expect(directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(directory.byTelegramKey['mekenthompson']?.personId).toBe('Ken')
+  })
+})
+
+describe('resolvePersonName — unresolved id falls back (fail-open)', () => {
+  it('returns undefined for an id not in the directory', () => {
+    const { directory } = buildPersonDirectory([LISA])
+    const name = resolvePersonName(directory, { telegramId: '000', isDm: true })
+    expect(name).toBeUndefined()
+  })
+
+  it('returns undefined for an empty directory', () => {
+    const { directory } = buildPersonDirectory([])
+    const name = resolvePersonName(directory, { telegramId: '8201250670', isDm: true })
+    expect(name).toBeUndefined()
+  })
+})
+
+describe('resolvePersonName — chat scoping', () => {
+  const { directory } = buildPersonDirectory([LISA])
+
+  it('DM: always resolves (the chat IS the sender)', () => {
+    const name = resolvePersonName(directory, { telegramId: '8201250670', isDm: true })
+    expect(name).toBe('Lisa')
+  })
+
+  it('group: resolves when the sender is present in that chat\'s allowFrom', () => {
+    const name = resolvePersonName(directory, {
+      telegramId: '8201250670',
+      isDm: false,
+      groupAllowFrom: ['8201250670', '111'],
+    })
+    expect(name).toBe('Lisa')
+  })
+
+  it('group: does NOT resolve when allowFrom is empty/unset (can\'t confirm membership)', () => {
+    expect(resolvePersonName(directory, { telegramId: '8201250670', isDm: false })).toBeUndefined()
+    expect(resolvePersonName(directory, { telegramId: '8201250670', isDm: false, groupAllowFrom: [] })).toBeUndefined()
+  })
+
+  it('group: does NOT resolve when the sender is absent from that group\'s allowFrom (a name safe in a DM is not broadcast elsewhere)', () => {
+    const name = resolvePersonName(directory, {
+      telegramId: '8201250670',
+      isDm: false,
+      groupAllowFrom: ['111'], // some other member, not lisa
+    })
+    expect(name).toBeUndefined()
+  })
+
+  it('group: resolves via username when username (not id) is in allowFrom', () => {
+    const { directory: dir2 } = buildPersonDirectory([KEN])
+    const name = resolvePersonName(dir2, {
+      telegramId: '999999',
+      username: 'mekenthompson',
+      isDm: false,
+      groupAllowFrom: ['mekenthompson'],
+    })
+    expect(name).toBe('Ken')
+  })
+})
+
+describe('safeResolvePersonName — fail-open call-site wrapper used by handleInbound', () => {
+  it('happy path: resolves same as resolvePersonName when nothing throws', () => {
+    const { directory } = buildPersonDirectory([LISA])
+    const name = safeResolvePersonName(directory, { telegramId: '8201250670', isDm: true }, 'raw-fallback')
+    expect(name).toBe('Lisa')
+  })
+
+  it('unresolved id: falls back to the raw id/username, same as today\'s behavior', () => {
+    const { directory } = buildPersonDirectory([LISA])
+    const name = safeResolvePersonName(directory, { telegramId: '000', isDm: true }, 'raw-fallback')
+    expect(name).toBe('raw-fallback')
+  })
+
+  it('resolution throwing (e.g. a malformed opts shape at the call site) is swallowed — falls back to the raw id/username instead of propagating and aborting handleInbound', () => {
+    const { directory } = buildPersonDirectory([LISA])
+    // Force resolvePersonName's internal normalizeTelegramKey to throw by
+    // passing a non-string telegramId past the type system, simulating an
+    // unexpected runtime shape from the Telegram payload.
+    const name = safeResolvePersonName(
+      directory,
+      { telegramId: undefined as unknown as string, isDm: true },
+      'raw-fallback',
+    )
+    expect(name).toBe('raw-fallback')
+  })
+
+  it('a directory whose lookup throws is also swallowed, not propagated', () => {
+    const throwingDirectory: PersonDirectory = {
+      byTelegramKey: new Proxy(
+        {},
+        {
+          get() {
+            throw new Error('boom: directory lookup exploded')
+          },
+        },
+      ),
+    }
+    const spy = vi.fn()
+    try {
+      const name = safeResolvePersonName(throwingDirectory, { telegramId: '8201250670', isDm: true }, 'raw-fallback')
+      expect(name).toBe('raw-fallback')
+    } catch (err) {
+      spy(err)
+    }
+    expect(spy).not.toHaveBeenCalled()
+  })
+})
+
+describe('runPersonDirectoryBootCheck — one-time boot validation + alerting', () => {
+  it('happy path: no alert, directory populated', () => {
+    const result = runPersonDirectoryBootCheck(() => [LISA, KEN])
+    expect(result.alertDetail).toBeNull()
+    expect(result.directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+    expect(result.logLine).toMatch(/boot validation ok/)
+  })
+
+  it('no entries configured: no alert (this is not an error)', () => {
+    const result = runPersonDirectoryBootCheck(() => [])
+    expect(result.alertDetail).toBeNull()
+    expect(result.directory.byTelegramKey).toEqual({})
+  })
+
+  it('dropped entry at boot fires an alert (routes through the caller\'s fleet-alert path) and still resolves the good entries', () => {
+    const bad: RawPersonEntry = { key: 'ghost', person_id: '', telegram_ids: ['1'] }
+    const result = runPersonDirectoryBootCheck(() => [LISA, bad])
+    expect(result.alertDetail).not.toBeNull()
+    expect(result.alertDetail).toContain('dropped 1')
+    expect(result.alertDetail).toContain('ghost')
+    expect(result.directory.byTelegramKey['8201250670']?.personId).toBe('Lisa')
+  })
+
+  it('dead-man\'s-switch: readEntries throwing is caught, reported via alertDetail, and PERSON_DIRECTORY falls back to empty (fail-open)', () => {
+    const result = runPersonDirectoryBootCheck(() => {
+      throw new Error('disk read exploded')
+    })
+    expect(result.alertDetail).not.toBeNull()
+    expect(result.alertDetail).toContain('crashed')
+    // alertDetail is broadcast to every allowFrom chat (incl. groups), so
+    // the raw error message — which may carry a host path or other detail
+    // — is scrubbed from it. The full message stays in the private logLine.
+    expect(result.alertDetail).not.toContain('disk read exploded')
+    expect(result.alertDetail).toContain('see gateway stderr for detail')
+    expect(result.directory.byTelegramKey).toEqual({})
+    expect(result.logLine).toContain('CRASHED')
+    expect(result.logLine).toContain('disk read exploded')
+  })
+})

package/telegram-plugin/tests/resume-inbound-builder.test.ts

@@ -18,7 +18,13 @@ import {
   humanizeElapsed,
   buildResumeInterruptedInbound,
   buildResumeWatchdogReportInbound,
+  buildResumeDeferredReportInbound,
+  isResumeSyntheticTurn,
   selectResumeBuilder,
+  decideBootResumeKind,
+  RESUME_SYNTHETIC_PROMPT_PREFIX,
+  renderInterruptedSubagentsBlock,
+  type InterruptedSubagent,
 } from '../gateway/resume-inbound-builder.js'
 import type { Turn, TurnEndedVia } from '../registry/turns-schema.js'
 
@@ -158,6 +164,155 @@ describe('buildResumeInterruptedInbound', () => {
   })
 })
 
+describe('interrupted sub-agent block', () => {
+  const twoRunning: InterruptedSubagent[] = [
+    { agentType: 'worker', description: 'refactor the auth module and add tests', status: 'running' },
+    { agentType: 'researcher', description: 'survey the pricing pages of 5 competitors', status: 'running' },
+  ]
+
+  it('renderInterruptedSubagentsBlock lists each worker with type + prompt', () => {
+    const block = renderInterruptedSubagentsBlock(twoRunning)
+    expect(block).toContain('2 sub-agents were still')
+    expect(block).toContain('did NOT complete')
+    expect(block).toContain('[worker]')
+    expect(block).toContain('refactor the auth module and add tests')
+    expect(block).toContain('[researcher]')
+    expect(block).toContain('survey the pricing pages of 5 competitors')
+    expect(block).toContain('Re-dispatch the ones still needed')
+  })
+
+  it('returns empty string when there are no in-flight sub-agents', () => {
+    expect(renderInterruptedSubagentsBlock(undefined)).toBe('')
+    expect(renderInterruptedSubagentsBlock([])).toBe('')
+  })
+
+  it('interrupted-turn inbound contains BOTH running sub-agents', () => {
+    const msg = buildResumeInterruptedInbound({ turn: makeTurn(), subagents: twoRunning })
+    expect(msg.text).toContain('refactor the auth module and add tests')
+    expect(msg.text).toContain('survey the pricing pages of 5 competitors')
+    expect(msg.text).toContain('did NOT complete')
+    expect(msg.text).toContain('Re-dispatch the ones still needed')
+  })
+
+  it('interrupted-turn inbound is UNCHANGED when no sub-agents were running', () => {
+    const withNone = buildResumeInterruptedInbound({ turn: makeTurn(), subagents: [] })
+    const bare = buildResumeInterruptedInbound({ turn: makeTurn() })
+    expect(withNone.text).toBe(bare.text)
+    expect(withNone.text).not.toContain('did NOT complete')
+  })
+
+  it('truncates each dispatch prompt to ~200 chars', () => {
+    const long = 'x'.repeat(400)
+    const block = renderInterruptedSubagentsBlock([{ agentType: 'worker', description: long }])
+    // The 400-char prompt must not survive in full; the entry line is capped.
+    expect(block).not.toContain(long)
+    expect(block).toContain('…')
+    // 200-char cap → the truncated slice (199 chars + ellipsis) is present.
+    expect(block).toContain('x'.repeat(199))
+    expect(block).not.toContain('x'.repeat(201))
+  })
+
+  it('caps the list at 10 and summarises the remainder', () => {
+    const many: InterruptedSubagent[] = Array.from({ length: 14 }, (_, i) => ({
+      agentType: 'worker',
+      description: `task number ${i + 1}`,
+    }))
+    const block = renderInterruptedSubagentsBlock(many)
+    expect(block).toContain('14 sub-agents were still')
+    expect(block).toContain('task number 10')
+    expect(block).not.toContain('task number 11')
+    expect(block).toContain('…and 4 more.')
+    // Exactly 10 numbered entries rendered.
+    const numbered = block.match(/^\s+\d+\. \[/gm) ?? []
+    expect(numbered.length).toBe(10)
+  })
+
+  it('falls back to a generic label + placeholder when type/prompt are missing', () => {
+    const block = renderInterruptedSubagentsBlock([{ agentType: null, description: null }])
+    expect(block).toContain('[sub-agent]')
+    expect(block).toContain('(no task description recorded)')
+  })
+
+  it('singularises a single killed sub-agent', () => {
+    const block = renderInterruptedSubagentsBlock([{ agentType: 'worker', description: 'do X' }])
+    expect(block).toContain('1 sub-agent was still')
+    expect(block).not.toContain('1 sub-agents')
+  })
+
+  it('codepoint-safe truncation never splits a surrogate pair', () => {
+    // 199 ASCII chars, then an astral-plane emoji (2 UTF-16 code units)
+    // straddling the cap. A code-unit slice would cut the pair in half and
+    // leave a lone surrogate; the codepoint-safe slice must not.
+    const desc = 'a'.repeat(199) + '🚀' + 'b'.repeat(50)
+    const block = renderInterruptedSubagentsBlock([{ agentType: 'worker', description: desc }])
+    expect(block).toContain('…')
+    // No lone surrogates anywhere in the rendered block.
+    expect(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(block)).toBe(false)
+    expect(block).toBe(block.normalize('NFC')) // sanity: still a well-formed string
+  })
+
+  it('the watchdog report inbound carries the block in DEFERRED form (ask-first contract)', () => {
+    const msg = buildResumeWatchdogReportInbound({
+      turn: makeTurn({ ended_via: 'timeout' }),
+      idleMs: 300_000,
+      subagents: twoRunning,
+    })
+    expect(msg.text).toContain('did NOT complete')
+    expect(msg.text).toContain('refactor the auth module and add tests')
+    // Deferred wording: re-dispatch is conditional on the user asking to retry…
+    expect(msg.text).toContain("If the user asks you to retry, they'll need re-dispatching")
+    expect(msg.text).toContain("don't assume their work landed")
+    // …and the resume-path imperative must NOT appear — it would contradict
+    // the watchdog inbound's "Do NOT silently resume … ask" hang-safety gate.
+    expect(msg.text).not.toContain('Re-dispatch the ones still needed')
+    expect(msg.text).not.toContain('before declaring the task done')
+  })
+
+  it('the resume-path inbound keeps the assertive imperative (and not the deferred form)', () => {
+    const msg = buildResumeInterruptedInbound({ turn: makeTurn(), subagents: twoRunning })
+    expect(msg.text).toContain('Re-dispatch the ones still needed before declaring the task done')
+    expect(msg.text).not.toContain('If the user asks you to retry')
+  })
+
+  for (const reason of ['loop-guard', 'clean-restart-suppressed'] as const) {
+    it(`the deferred report (${reason}) carries the block in DEFERRED form — suppressed resumes still name worker deaths`, () => {
+      const msg = buildResumeDeferredReportInbound({
+        turn: makeTurn(),
+        reason,
+        subagents: twoRunning,
+      })
+      expect(msg.text).toContain('did NOT complete')
+      expect(msg.text).toContain('refactor the auth module and add tests')
+      expect(msg.text).toContain('survey the pricing pages of 5 competitors')
+      // Deferred wording only — never the resume-path imperative, which would
+      // contradict this inbound's "Do NOT silently resume … ask" contract.
+      expect(msg.text).toContain("If the user asks you to retry, they'll need re-dispatching")
+      expect(msg.text).not.toContain('Re-dispatch the ones still needed')
+      expect(msg.text).not.toContain('before declaring the task done')
+      // Appending the block must not disturb the loop-guard anchor at pos 0.
+      expect(msg.text.startsWith(RESUME_SYNTHETIC_PROMPT_PREFIX)).toBe(true)
+    })
+  }
+
+  it('deferred report without subagents is unchanged (no block)', () => {
+    const withNone = buildResumeDeferredReportInbound({ turn: makeTurn(), reason: 'loop-guard', subagents: [] })
+    const bare = buildResumeDeferredReportInbound({ turn: makeTurn(), reason: 'loop-guard' })
+    expect(withNone.text).toBe(bare.text)
+    expect(withNone.text).not.toContain('did NOT complete')
+  })
+
+  it('appending the block preserves the RESUME_SYNTHETIC_PROMPT_PREFIX anchor on resume + watchdog inbounds too', () => {
+    const resume = buildResumeInterruptedInbound({ turn: makeTurn(), subagents: twoRunning })
+    expect(resume.text.startsWith(RESUME_SYNTHETIC_PROMPT_PREFIX)).toBe(true)
+    const report = buildResumeWatchdogReportInbound({
+      turn: makeTurn({ ended_via: 'timeout' }),
+      idleMs: 300_000,
+      subagents: twoRunning,
+    })
+    expect(report.text.startsWith(RESUME_SYNTHETIC_PROMPT_PREFIX)).toBe(true)
+  })
+})
+
 describe('buildResumeWatchdogReportInbound', () => {
   it('sets the resume_watchdog_timeout source and idle_ms passthrough', () => {
     const turn = makeTurn({ ended_via: 'timeout' })
@@ -243,3 +398,134 @@ describe('selectResumeBuilder', () => {
     expect(selectResumeBuilder('restart', { ageMs: MAX + 1 })).toBe('resume') // needs BOTH to cap
   })
 })
+
+// ---------------------------------------------------------------------------
+// Loop-guard: RESUME_SYNTHETIC_PROMPT_PREFIX / isResumeSyntheticTurn
+// ---------------------------------------------------------------------------
+
+describe('resume synthetic-turn detection (loop-guard anchor)', () => {
+  it('EVERY synthetic boot inbound text starts with the machine-stable prefix', () => {
+    // The loop-guard keys on this prefix landing in user_prompt_preview, so if
+    // a prose edit drops it the chain-cap silently breaks. Pin it here.
+    const turn = makeTurn({ user_prompt_preview: 'do the thing' })
+    expect(buildResumeInterruptedInbound({ turn }).text.startsWith(RESUME_SYNTHETIC_PROMPT_PREFIX)).toBe(true)
+    expect(
+      buildResumeWatchdogReportInbound({ turn: makeTurn({ ended_via: 'timeout' }), idleMs: 1000 }).text.startsWith(
+        RESUME_SYNTHETIC_PROMPT_PREFIX,
+      ),
+    ).toBe(true)
+    expect(
+      buildResumeDeferredReportInbound({ turn, reason: 'loop-guard' }).text.startsWith(
+        RESUME_SYNTHETIC_PROMPT_PREFIX,
+      ),
+    ).toBe(true)
+    expect(
+      buildResumeDeferredReportInbound({ turn, reason: 'clean-restart-suppressed' }).text.startsWith(
+        RESUME_SYNTHETIC_PROMPT_PREFIX,
+      ),
+    ).toBe(true)
+  })
+
+  it('isResumeSyntheticTurn is true for a turn whose preview is a synthetic prompt', () => {
+    const synthetic = buildResumeInterruptedInbound({ turn: makeTurn() })
+    // A resume turn stores the first ~200 chars of the synthetic text as its
+    // preview (channel wrapper stripped) — simulate that.
+    const resumeTurn = makeTurn({ user_prompt_preview: synthetic.text.slice(0, 200) })
+    expect(isResumeSyntheticTurn(resumeTurn)).toBe(true)
+  })
+
+  it('isResumeSyntheticTurn is false for real user work and for null preview', () => {
+    expect(isResumeSyntheticTurn(makeTurn({ user_prompt_preview: 'refactor the auth module' }))).toBe(false)
+    expect(isResumeSyntheticTurn(makeTurn({ user_prompt_preview: null }))).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// buildResumeDeferredReportInbound
+// ---------------------------------------------------------------------------
+
+describe('buildResumeDeferredReportInbound', () => {
+  it('emits source=resume_deferred and carries the dedup anchor + reason', () => {
+    const turn = makeTurn({ turn_key: 'zz:3' })
+    const msg = buildResumeDeferredReportInbound({ turn, reason: 'loop-guard' })
+    expect(msg.meta.source).toBe('resume_deferred')
+    expect(msg.meta.resume_turn_key).toBe('zz:3')
+    expect(msg.meta.defer_reason).toBe('loop-guard')
+  })
+
+  it('loop-guard framing tells the model the chain was capped, not to resume', () => {
+    const msg = buildResumeDeferredReportInbound({ turn: makeTurn(), reason: 'loop-guard' })
+    expect(msg.text.toLowerCase()).toContain('resume of earlier interrupted work')
+    expect(msg.text).toContain('Do NOT silently resume')
+  })
+
+  it('clean-restart-suppressed framing cites boot_resume: never', () => {
+    const msg = buildResumeDeferredReportInbound({ turn: makeTurn(), reason: 'clean-restart-suppressed' })
+    expect(msg.text).toContain('boot_resume: never')
+    expect(msg.text).toContain('Do NOT silently resume')
+  })
+
+  it('routes to the origin thread when the turn carried one', () => {
+    const turn = makeTurn({ chat_id: '-100999', thread_id: '77' })
+    const msg = buildResumeDeferredReportInbound({ turn, reason: 'loop-guard' })
+    expect(msg.chatId).toBe('-100999')
+    expect(msg.threadId).toBe(77)
+    expect(msg.meta.message_thread_id).toBe('77')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// decideBootResumeKind — boot-resume precedence + bounded resume chain
+// ---------------------------------------------------------------------------
+
+describe('decideBootResumeKind', () => {
+  const MAX = 10_800_000 // 3h
+
+  it('resumes genuinely in-flight work after a deliberate restart (not suppressed)', () => {
+    // The core product fix: clean restart mid-turn → resume, not silence.
+    const pending = makeTurn({ ended_via: 'restart', user_prompt_preview: 'ship the release' })
+    expect(decideBootResumeKind({ pending, suppressed: false, ageMs: 1000, maxAgeMs: MAX })).toBe('resume')
+  })
+
+  it("boot_resume:never (suppressed) → 'defer-suppressed' passive report, never silence", () => {
+    const pending = makeTurn({ ended_via: 'restart', user_prompt_preview: 'ship the release' })
+    expect(decideBootResumeKind({ pending, suppressed: true, ageMs: 1000, maxAgeMs: MAX })).toBe('defer-suppressed')
+  })
+
+  it('watchdog timeout still reports even when not suppressed', () => {
+    const pending = makeTurn({ ended_via: 'timeout', user_prompt_preview: 'ship the release' })
+    expect(decideBootResumeKind({ pending, suppressed: false, ageMs: 1000, maxAgeMs: MAX })).toBe('report')
+  })
+
+  it('BOUNDED CHAIN: a restart DURING a resume turn does NOT re-resume — loop-guard fires', () => {
+    // Simulate the chain the coordinator flagged:
+    //   A: real work, interrupted → resume R1 (turn B created from R1's text)
+    //   restart lands during B → pending is B, whose preview IS the synthetic
+    //   resume prompt. We must NOT mint a second resume (endless loop risk).
+    const r1 = buildResumeInterruptedInbound({ turn: makeTurn({ user_prompt_preview: 'real work' }) })
+    const turnB = makeTurn({ ended_via: 'restart', user_prompt_preview: r1.text.slice(0, 200) })
+    // Even though NOT suppressed (would normally resume), the loop-guard wins:
+    expect(decideBootResumeKind({ pending: turnB, suppressed: false, ageMs: 1000, maxAgeMs: MAX })).toBe('defer-loop')
+  })
+
+  it('BOUNDED CHAIN: a restart during a deferred-report turn stays capped (still defer-loop, never resume)', () => {
+    // Depth does not grow: a report-of-report is still a passive report, never
+    // a resume — so no unbounded restart→resume→restart chain can form.
+    const deferred = buildResumeDeferredReportInbound({ turn: makeTurn(), reason: 'loop-guard' })
+    const turnC = makeTurn({ ended_via: 'restart', user_prompt_preview: deferred.text.slice(0, 200) })
+    const kind = decideBootResumeKind({ pending: turnC, suppressed: false, ageMs: 1000, maxAgeMs: MAX })
+    expect(kind).toBe('defer-loop')
+    expect(kind).not.toBe('resume')
+  })
+
+  it('loop-guard takes precedence over suppression too (synthetic turn never resumes or double-reports as resume)', () => {
+    const r1 = buildResumeInterruptedInbound({ turn: makeTurn() })
+    const turnB = makeTurn({ ended_via: 'restart', user_prompt_preview: r1.text.slice(0, 200) })
+    expect(decideBootResumeKind({ pending: turnB, suppressed: true, ageMs: 1000, maxAgeMs: MAX })).toBe('defer-loop')
+  })
+
+  it('stale in-flight work downgrades to report when older than maxAgeMs', () => {
+    const pending = makeTurn({ ended_via: 'restart', user_prompt_preview: 'stale work' })
+    expect(decideBootResumeKind({ pending, suppressed: false, ageMs: MAX + 1, maxAgeMs: MAX })).toBe('report')
+  })
+})

package/telegram-plugin/tests/session-model-source.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Pins the /status session-model freshness contract (#2982 + live-model PR):
+ * the FRESHEST observation wins between the transcript's `message.model` and
+ * the /model override, arbitrated by a shared monotonic sequence. This is the
+ * "model display must never be stale" invariant:
+ *
+ *   - override set AFTER the last transcript observation (idle-time /model
+ *     switch, no assistant line yet) → /status shows the override;
+ *   - a new assistant line after that → the transcript wins again.
+ */
+import { describe, it, expect } from 'vitest'
+import { createSessionModelSource } from '../gateway/session-model-source.js'
+
+describe('createSessionModelSource — freshest observation wins', () => {
+  it('returns null when neither source has reported', () => {
+    const s = createSessionModelSource()
+    expect(s.resolve()).toBeNull()
+    expect(s.getOverride()).toBeNull()
+  })
+
+  it('transcript-only → transcript', () => {
+    const s = createSessionModelSource()
+    s.noteTranscriptModel('claude-opus-4-8')
+    expect(s.resolve()).toEqual({ model: 'claude-opus-4-8', source: 'transcript' })
+  })
+
+  it('override-only → override (fresh boot before the first assistant line)', () => {
+    const s = createSessionModelSource()
+    s.setOverride('sr-glm-5')
+    expect(s.resolve()).toEqual({ model: 'sr-glm-5', source: 'override' })
+  })
+
+  it('idle-after-switch window: an override set AFTER the last transcript line wins', () => {
+    // The #2982 regression this pins: /model switch while idle — the
+    // transcript still holds the OLD model, the override holds the NEW one.
+    const s = createSessionModelSource()
+    s.noteTranscriptModel('claude-opus-4-8') // old model's last assistant line
+    s.setOverride('Sonnet 5') // confirmed switch, no assistant line yet
+    expect(s.resolve()).toEqual({ model: 'Sonnet 5', source: 'override' })
+  })
+
+  it('a NEW assistant line after the switch reclaims the transcript as the source', () => {
+    const s = createSessionModelSource()
+    s.noteTranscriptModel('claude-opus-4-8')
+    s.setOverride('Sonnet 5')
+    s.noteTranscriptModel('claude-sonnet-5') // first line under the new model
+    expect(s.resolve()).toEqual({ model: 'claude-sonnet-5', source: 'transcript' })
+  })
+
+  it('clearing the override (null) falls back to the transcript', () => {
+    const s = createSessionModelSource()
+    s.noteTranscriptModel('claude-opus-4-8')
+    s.setOverride('sr-glm-5')
+    s.setOverride(null)
+    expect(s.getOverride()).toBeNull()
+    expect(s.resolve()).toEqual({ model: 'claude-opus-4-8', source: 'transcript' })
+  })
+
+  it('getOverride reports the override independent of freshness', () => {
+    const s = createSessionModelSource()
+    s.setOverride('sr-glm-5')
+    s.noteTranscriptModel('claude-opus-4-8') // transcript is now fresher
+    expect(s.resolve()?.source).toBe('transcript')
+    // ...but the override record itself is still readable (menu "session" marker).
+    expect(s.getOverride()).toBe('sr-glm-5')
+  })
+})