switchroom 0.20.0 → 0.20.2

package/telegram-plugin/gateway/access-store.test.ts

@@ -0,0 +1,234 @@
+/**
+ * Unit tests for access-store.ts — the access/allowlist file layer extracted
+ * from gateway.ts (switchroom#4248).
+ *
+ * These lock in the behavior that used to be inline in gateway.ts, in
+ * particular the init-time-only static-mode snapshot (BOOT_ACCESS): in static
+ * mode the allowlist is read ONCE when the store is built and frozen for the
+ * life of the store, so a later edit to access.json on disk is NOT observed.
+ * That timing is the whole reason the store is a factory rather than a set of
+ * lazy free functions — this suite is the outcome guard for it.
+ *
+ * Run with: npx vitest run telegram-plugin/gateway/access-store.test.ts
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createAccessStore, type AccessStoreDeps } from './access-store.js'
+import type { Access } from './gateway.js'
+
+function makeDeps(dir: string, isStatic: boolean): AccessStoreDeps {
+  return {
+    accessFile: join(dir, 'access.json'),
+    peopleFile: join(dir, 'people.json'),
+    stateDir: dir,
+    isStatic,
+  }
+}
+
+describe('access-store', () => {
+  let dir: string
+  let stderrSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'access-store-'))
+    stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  })
+
+  afterEach(() => {
+    stderrSpy.mockRestore()
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  // ─── defaultAccess ─────────────────────────────────────────────────────────
+
+  it('defaultAccess returns a pairing-mode empty allowlist', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.defaultAccess()).toEqual({
+      dmPolicy: 'pairing',
+      allowFrom: [],
+      groups: {},
+      pending: {},
+    })
+  })
+
+  // ─── readAccessFile ────────────────────────────────────────────────────────
+
+  it('readAccessFile returns defaultAccess when the file is missing (ENOENT)', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile()).toEqual(store.defaultAccess())
+  })
+
+  it('readAccessFile parses a valid access.json and projects known fields', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'allowlist',
+        allowFrom: ['111'],
+        groups: { '-100': { requireMention: true, allowFrom: ['222'] } },
+        pending: {},
+        parseMode: 'text',
+        historyEnabled: false,
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    const a = store.readAccessFile()
+    expect(a.dmPolicy).toBe('allowlist')
+    expect(a.allowFrom).toEqual(['111'])
+    expect(a.groups['-100']).toEqual({ requireMention: true, allowFrom: ['222'] })
+    expect(a.parseMode).toBe('text')
+    expect(a.historyEnabled).toBe(false)
+  })
+
+  it('readAccessFile fails closed on number-array fields (the hand-edit bug)', () => {
+    // Unquoted IDs parse as numbers; validateStringArray must drop them.
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: [12345], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile().allowFrom).toEqual([])
+    expect(stderrSpy).toHaveBeenCalled()
+  })
+
+  it('readAccessFile moves a corrupt file aside and returns defaultAccess', () => {
+    writeFileSync(join(dir, 'access.json'), '{ not valid json')
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readAccessFile()).toEqual(store.defaultAccess())
+    // Original replaced by a .corrupt-* sibling.
+    expect(existsSync(join(dir, 'access.json'))).toBe(false)
+    const corrupt = readdirSync(dir).filter((f) => f.startsWith('access.json.corrupt-'))
+    expect(corrupt.length).toBe(1)
+  })
+
+  // ─── loadAccess — non-static re-reads live ─────────────────────────────────
+
+  it('loadAccess re-reads the file on every call in non-static mode', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['111'], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+    // Edit on disk is observed immediately (no snapshot in non-static mode).
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['222'], groups: {}, pending: {} }),
+    )
+    expect(store.loadAccess().allowFrom).toEqual(['222'])
+  })
+
+  // ─── Static-mode BOOT_ACCESS snapshot (init-time semantics) ────────────────
+
+  it('static mode snapshots at build time: downgrades pairing→allowlist and clears pending', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'pairing',
+        allowFrom: ['111'],
+        groups: {},
+        pending: { code123: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: 2, replies: 0 } },
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, true))
+    const a = store.loadAccess()
+    expect(a.dmPolicy).toBe('allowlist')
+    expect(a.pending).toEqual({})
+    expect(a.allowFrom).toEqual(['111'])
+  })
+
+  it('static mode freezes the allowlist: an on-disk edit after build is NOT observed', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['111'], groups: {}, pending: {} }),
+    )
+    const store = createAccessStore(makeDeps(dir, true))
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+    // Change the file after the store was built.
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({ dmPolicy: 'allowlist', allowFrom: ['999'], groups: {}, pending: {} }),
+    )
+    // Still the boot snapshot — this is the init-time-only guarantee.
+    expect(store.loadAccess().allowFrom).toEqual(['111'])
+  })
+
+  // ─── saveAccess ────────────────────────────────────────────────────────────
+
+  it('saveAccess writes access.json atomically in non-static mode', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    const a: Access = { dmPolicy: 'allowlist', allowFrom: ['abc'], groups: {}, pending: {} }
+    store.saveAccess(a)
+    const written = JSON.parse(readFileSync(join(dir, 'access.json'), 'utf8'))
+    expect(written.allowFrom).toEqual(['abc'])
+    // No leftover temp file.
+    expect(existsSync(join(dir, 'access.json.tmp'))).toBe(false)
+  })
+
+  it('saveAccess is a no-op in static mode', () => {
+    const store = createAccessStore(makeDeps(dir, true))
+    store.saveAccess({ dmPolicy: 'allowlist', allowFrom: ['abc'], groups: {}, pending: {} })
+    expect(existsSync(join(dir, 'access.json'))).toBe(false)
+  })
+
+  // ─── pruneExpired ──────────────────────────────────────────────────────────
+
+  it('pruneExpired removes expired pending entries and reports whether it changed', () => {
+    const now = Date.now()
+    const store = createAccessStore(makeDeps(dir, false))
+    const a: Access = {
+      dmPolicy: 'pairing',
+      allowFrom: [],
+      groups: {},
+      pending: {
+        old: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: now - 1000, replies: 0 },
+        fresh: { senderId: 's', chatId: 'c', createdAt: 1, expiresAt: now + 100000, replies: 0 },
+      },
+    }
+    expect(store.pruneExpired(a)).toBe(true)
+    expect(Object.keys(a.pending)).toEqual(['fresh'])
+    // Second pass: nothing expired now → no change.
+    expect(store.pruneExpired(a)).toBe(false)
+  })
+
+  // ─── assertAllowedChat ─────────────────────────────────────────────────────
+
+  it('assertAllowedChat permits an allowFrom chat, a group chat, and rejects others', () => {
+    writeFileSync(
+      join(dir, 'access.json'),
+      JSON.stringify({
+        dmPolicy: 'allowlist',
+        allowFrom: ['111'],
+        groups: { '-100': { requireMention: false, allowFrom: [] } },
+        pending: {},
+      }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(() => store.assertAllowedChat('111')).not.toThrow()
+    expect(() => store.assertAllowedChat(111)).not.toThrow() // number coerced
+    expect(() => store.assertAllowedChat('-100')).not.toThrow()
+    expect(() => store.assertAllowedChat('404')).toThrow(/not allowlisted/)
+  })
+
+  // ─── readPeopleFile ────────────────────────────────────────────────────────
+
+  it('readPeopleFile returns entries for a valid people.json', () => {
+    writeFileSync(
+      join(dir, 'people.json'),
+      JSON.stringify({ entries: [{ telegramUserId: '5', personId: 'p1' }] }),
+    )
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readPeopleFile()).toEqual([{ telegramUserId: '5', personId: 'p1' }])
+  })
+
+  it('readPeopleFile fails open to [] on missing or corrupt file', () => {
+    const store = createAccessStore(makeDeps(dir, false))
+    expect(store.readPeopleFile()).toEqual([]) // ENOENT
+    writeFileSync(join(dir, 'people.json'), 'not json')
+    expect(store.readPeopleFile()).toEqual([]) // corrupt
+    writeFileSync(join(dir, 'people.json'), JSON.stringify({ entries: 'nope' }))
+    expect(store.readPeopleFile()).toEqual([]) // entries not an array
+  })
+})

package/telegram-plugin/gateway/access-store.ts

@@ -0,0 +1,194 @@
+/**
+ * Access / allowlist file layer for the Telegram gateway.
+ *
+ * This module owns the read/write side of `access.json` (the per-agent DM
+ * allowlist + group policy + pairing state) and the read-only `people.json`
+ * projection. It was extracted verbatim out of `gateway.ts` (switchroom#4248)
+ * to relieve the gateway line-ratchet; the behavior is byte-identical to the
+ * inline version.
+ *
+ * Init-time semantics preserved: in static-access mode the gateway snapshots
+ * `access.json` ONCE at module-init time (the `BOOT_ACCESS` constant below),
+ * downgrades a `pairing` dmPolicy to `allowlist`, and clears pending pairings —
+ * so a static agent's allowlist is frozen for the life of the process. That
+ * snapshot must happen at the same point in startup as before, so the store is
+ * built by a factory (`createAccessStore`) that the gateway calls at the
+ * original `BOOT_ACCESS` site; the snapshot runs eagerly inside the factory,
+ * NOT lazily on first `loadAccess()`.
+ *
+ * The gateway-internal dependencies (`ACCESS_FILE`, `PEOPLE_FILE`, `STATE_DIR`
+ * path constants and the `STATIC` mode flag) are injected as explicit params so
+ * this module holds no runtime import of gateway.ts. The only back-reference is
+ * the `Access` / `GroupPolicy` types, imported type-only (erased under
+ * `isolatedModules`, so no runtime cycle) — the same seam
+ * `turn-start-surfaces.ts` already uses.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { validateStringArray } from './access-validator.js'
+import type { RawPersonEntry } from './resolve-person.js'
+import type { Access } from './gateway.js'
+
+/** The per-group policy shape, derived from the exported `Access` type so the
+ *  store needs no extra symbol export from gateway.ts. */
+type GroupPolicy = Access['groups'][string]
+
+/** Gateway-internal deps the store needs, injected at build time. */
+export interface AccessStoreDeps {
+  /** Absolute path to `access.json` (gateway's `ACCESS_FILE`). */
+  accessFile: string
+  /** Absolute path to `people.json` (gateway's `PEOPLE_FILE`). */
+  peopleFile: string
+  /** State dir created (mode 0o700) before an atomic access.json write. */
+  stateDir: string
+  /** Static-access mode (`TELEGRAM_ACCESS_MODE === 'static'`). Freezes the
+   *  allowlist at init and turns `saveAccess` into a no-op. */
+  isStatic: boolean
+}
+
+/** The access/allowlist file layer, bound to one set of paths + mode. */
+export interface AccessStore {
+  defaultAccess(): Access
+  readAccessFile(): Access
+  loadAccess(): Access
+  readPeopleFile(): RawPersonEntry[]
+  assertAllowedChat(chat_id: string | number): void
+  saveAccess(a: Access): void
+  pruneExpired(a: Access): boolean
+}
+
+/**
+ * Build the access store. The `BOOT_ACCESS` snapshot happens eagerly here, so
+ * call this at the same point in gateway startup where `BOOT_ACCESS` used to be
+ * initialized — that keeps the static-mode freeze timing identical.
+ */
+export function createAccessStore(deps: AccessStoreDeps): AccessStore {
+  const { accessFile, peopleFile, stateDir, isStatic } = deps
+
+  function defaultAccess(): Access {
+    return { dmPolicy: 'pairing', allowFrom: [], groups: {}, pending: {} }
+  }
+
+  function readAccessFile(): Access {
+    try {
+      const raw = readFileSync(accessFile, 'utf8')
+      const parsed = JSON.parse(raw) as Partial<Access>
+      const allowFrom = validateStringArray('allowFrom', parsed.allowFrom ?? [])
+      const groups: Record<string, GroupPolicy> = {}
+      for (const [chatId, policy] of Object.entries(parsed.groups ?? {})) {
+        groups[chatId] = {
+          ...policy,
+          allowFrom: validateStringArray(`groups.${chatId}.allowFrom`, policy.allowFrom ?? []),
+        }
+      }
+      return {
+        dmPolicy: parsed.dmPolicy ?? 'pairing',
+        allowFrom,
+        groups,
+        pending: parsed.pending ?? {},
+        mentionPatterns: parsed.mentionPatterns,
+        ackReaction: parsed.ackReaction,
+        replyToMode: parsed.replyToMode,
+        textChunkLimit: parsed.textChunkLimit,
+        chunkMode: parsed.chunkMode,
+        parseMode: parsed.parseMode,
+        disableLinkPreview: parsed.disableLinkPreview,
+        coalescingGapMs: parsed.coalescingGapMs,
+        litellmNoticeWindowMs: parsed.litellmNoticeWindowMs,
+        coalesceMaxAttachments: parsed.coalesceMaxAttachments,
+        interruptSafeBoundary: parsed.interruptSafeBoundary,
+        interruptMaxWaitMs: parsed.interruptMaxWaitMs,
+        statusReactions: parsed.statusReactions,
+        historyEnabled: parsed.historyEnabled,
+        historyRetentionDays: parsed.historyRetentionDays,
+        // #596: telegram features projected into access.json by scaffold.
+        // Without these passthroughs, gateway readers (`access.voice_in`,
+        // `access.telegraph`, `access.stickers`) silently see undefined.
+        stickers: parsed.stickers,
+        voice_in: parsed.voice_in,
+        voice_out: parsed.voice_out,
+        telegraph: parsed.telegraph,
+        // #789: button-choice-confirmation config projected by scaffold.
+        button_choice_confirmation: parsed.button_choice_confirmation,
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return defaultAccess()
+      try { renameSync(accessFile, `${accessFile}.corrupt-${Date.now()}`) } catch {}
+      process.stderr.write(`telegram gateway: access.json is corrupt, moved aside. Starting fresh.\n`)
+      return defaultAccess()
+    }
+  }
+
+  const BOOT_ACCESS: Access | null = isStatic
+    ? (() => {
+        const a = readAccessFile()
+        if (a.dmPolicy === 'pairing') {
+          process.stderr.write('telegram gateway: static mode — dmPolicy "pairing" downgraded to "allowlist"\n')
+          a.dmPolicy = 'allowlist'
+        }
+        a.pending = {}
+        return a
+      })()
+    : null
+
+  function loadAccess(): Access {
+    return BOOT_ACCESS ?? readAccessFile()
+  }
+
+  /**
+   * Read `people.json` (the scaffold's plain projection of `users:` entries
+   * that carry a `person_id`). Fail-open: ENOENT or corrupt/malformed JSON
+   * returns an empty array rather than throwing — this feature must never
+   * block startup. Unlike `access.json` this file is never gateway-mutated,
+   * so there's no "move corrupt file aside" concern; the scaffold owns and
+   * regenerates it on every reconcile.
+   */
+  function readPeopleFile(): RawPersonEntry[] {
+    try {
+      const raw = readFileSync(peopleFile, 'utf8')
+      const parsed = JSON.parse(raw) as { entries?: unknown }
+      if (!Array.isArray(parsed.entries)) return []
+      return parsed.entries as RawPersonEntry[]
+    } catch {
+      return []
+    }
+  }
+
+  function assertAllowedChat(chat_id: string | number): void {
+    const id = String(chat_id)
+    const access = loadAccess()
+    if (access.allowFrom.includes(id)) return
+    if (id in access.groups) return
+    throw new Error(`chat ${id} is not allowlisted — add via /telegram:access`)
+  }
+
+  function saveAccess(a: Access): void {
+    if (isStatic) return
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+    const tmp = accessFile + '.tmp'
+    writeFileSync(tmp, JSON.stringify(a, null, 2) + '\n', { mode: 0o600 })
+    renameSync(tmp, accessFile)
+  }
+
+  function pruneExpired(a: Access): boolean {
+    const now = Date.now()
+    let changed = false
+    for (const [code, p] of Object.entries(a.pending)) {
+      if (p.expiresAt < now) {
+        delete a.pending[code]
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  return {
+    defaultAccess,
+    readAccessFile,
+    loadAccess,
+    readPeopleFile,
+    assertAllowedChat,
+    saveAccess,
+    pruneExpired,
+  }
+}

package/telegram-plugin/gateway/boot-briefing-builder.ts

@@ -244,15 +244,37 @@ export function collectBriefingSurfaces(
   }
 }
 
-/** Codepoint-safe truncation (mirrors resume-inbound-builder's
- *  `truncatePrompt` — a naive .slice can split a surrogate pair). Also
- *  collapses whitespace runs so each message renders as one line. */
+/**
+ * Slice `s` to AT MOST `maxUnits` UTF-16 code units without ever bisecting a
+ * surrogate pair. `max` in this module is a UTF-16 `.length` budget (that is
+ * what Telegram / the char-budget invariant measure), so truncation MUST be
+ * expressed in UTF-16 units — measuring codepoints against a UTF-16 budget
+ * lets astral-plane input (each 😀 is 1 codepoint but 2 UTF-16 units) blow the
+ * bound. If the cut would land between a high and low surrogate we step back
+ * one unit, dropping the lone high surrogate rather than emitting a broken
+ * pair. Guarantees `result.length <= maxUnits`.
+ */
+function sliceUtf16Safe(s: string, maxUnits: number): string {
+  if (maxUnits <= 0) return ''
+  if (s.length <= maxUnits) return s
+  let end = maxUnits
+  // A high surrogate (0xD800–0xDBFF) at the last kept position means its low
+  // half sits at index `end` and would be severed — drop the high surrogate.
+  const code = s.charCodeAt(end - 1)
+  if (code >= 0xd800 && code <= 0xdbff) end -= 1
+  return s.slice(0, end)
+}
+
+/** UTF-16-safe truncation (a naive .slice can split a surrogate pair, and
+ *  measuring codepoints against a UTF-16 `max` can overflow it for astral
+ *  input). Also collapses whitespace runs so each message renders as one
+ *  line. Guarantees `result.length <= max`. */
 function truncateOneLine(s: string, max: number): string {
   const t = s.replace(/\s+/g, ' ').trim()
   if (t.length <= max) return t
-  const points = Array.from(t)
-  if (points.length <= max) return t
-  return points.slice(0, max - 1).join('').trimEnd() + '…'
+  if (max <= 0) return ''
+  // Reserve one UTF-16 unit for the ellipsis ('…' is a single BMP unit).
+  return sliceUtf16Safe(t, max - 1).trimEnd() + '…'
 }
 
 function surfaceLabel(s: { chatId: string; threadId: number | null }): string {
@@ -269,6 +291,35 @@ function renderMessageLine(
   return `- [${age} ago] ${label}: ${truncateOneLine(m.text, perMessageMax)}`
 }
 
+/**
+ * One Hindsight recall result, as folded into the briefing's Hindsight
+ * section. Mirrors the `.results[]` shape `bin/handoff-briefing.sh` reads:
+ * a `text` body and an optional `timestamp` string. `text` may be empty —
+ * rendered as `(no text)` to match the shell's `.text // "(no text)"`.
+ */
+export interface HindsightRecallResult {
+  text: string
+  timestamp?: string | null
+}
+
+/**
+ * Today's daily-memory input for the briefing — the `date` (agent-local
+ * `YYYY-MM-DD`, used only in the section header) and the file `content`.
+ * Absent/empty content renders no section (no empty header).
+ */
+export interface BriefingDailyMemory {
+  date: string
+  content: string
+}
+
+/** Section title for the Hindsight-recall block (mirrors the shell). */
+const HINDSIGHT_SECTION_TITLE = '## Hindsight recall (recent context)'
+
+/** Minimum chars of room a trailing (Hindsight / daily-memory) section
+ *  needs before it is worth appending at all — below this, a truncated
+ *  section would be just a header + a sliver, so skip it whole. */
+const TRAILING_SECTION_MIN_ROOM = 64
+
 export interface RenderBriefingOptions {
   nowMs: number
   /** Restart-reason breadcrumb (`.restart-reason` / SWITCHROOM_PENDING_*),
@@ -276,6 +327,64 @@ export interface RenderBriefingOptions {
   restartReason?: string | null
   charBudget?: number
   perMessageMax?: number
+  /** Hindsight recall results (source 2 of the legacy handoff contract).
+   *  Empty / absent → no Hindsight section. */
+  hindsight?: HindsightRecallResult[] | null
+  /** Today's daily memory (source 3). Absent / empty content → no section. */
+  dailyMemory?: BriefingDailyMemory | null
+}
+
+/** Render the Hindsight recall body (the lines under the section header).
+ *  Mirrors the shell's jq: `- <text> (<timestamp>)`, `(no text)` when the
+ *  text is blank, and no trailing ` (…)` when there is no timestamp.
+ *  Returns '' when there are no results (caller then emits no header). */
+function renderHindsightBody(results: HindsightRecallResult[]): string {
+  const lines: string[] = []
+  for (const r of results) {
+    const text = (r.text ?? '').replace(/\s+/g, ' ').trim() || '(no text)'
+    const ts = r.timestamp && String(r.timestamp).trim() ? ` (${String(r.timestamp).trim()})` : ''
+    lines.push(`- ${text}${ts}`)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Append a `## title` + body section to `base`, but only within the char
+ * budget. If the whole section fits, append it. If not, append the header
+ * plus as much body as fits (so an over-long daily memory truncates rather
+ * than vanishing) — unless there isn't even `TRAILING_SECTION_MIN_ROOM`
+ * left, in which case the section is skipped whole. Guarantees the result
+ * is always <= budget. A blank body is a no-op (no empty header).
+ */
+function appendSectionWithinBudget(
+  base: string,
+  title: string,
+  body: string,
+  budget: number,
+): string {
+  const trimmedBody = body.trimEnd()
+  if (!trimmedBody) return base
+  const sep = '\n\n'
+  const full = `${base}${sep}${title}${sep}${trimmedBody}`
+  if (full.length <= budget) return full
+  // Room left for the body after the base + separators + title.
+  const room = budget - base.length - sep.length - title.length - sep.length
+  if (room < TRAILING_SECTION_MIN_ROOM) return base
+  const truncated = truncateOneLineOrBlock(trimmedBody, room)
+  return `${base}${sep}${title}${sep}${truncated}`
+}
+
+/** UTF-16-safe hard truncation preserving newlines (unlike `truncateOneLine`,
+ *  which collapses whitespace to one line). Used for block sections (daily
+ *  memory / Hindsight) where line structure matters. Bounds the result in
+ *  UTF-16 units — measuring codepoints against a UTF-16 `max` overflows the
+ *  budget for astral input (each 😀 is 2 UTF-16 units). Guarantees
+ *  `result.length <= max`. */
+function truncateOneLineOrBlock(s: string, max: number): string {
+  if (s.length <= max) return s
+  if (max <= 0) return ''
+  // Reserve one UTF-16 unit for the ellipsis ('…' is a single BMP unit).
+  return sliceUtf16Safe(s, max - 1).trimEnd() + '…'
 }
 
 /**
@@ -351,7 +460,26 @@ export function renderBootBriefing(
     if (assemble(kept, [...secondaries, block]).length > charBudget) break
     secondaries.push(block)
   }
-  return assemble(kept, secondaries)
+
+  // Sources 2 + 3 of the legacy handoff contract, appended after the durable
+  // Telegram slice and within the SAME char budget (Telegram history is the
+  // freshest context, so it keeps priority; Hindsight then daily memory fill
+  // the remaining room, truncating rather than blowing the budget). Order
+  // mirrors bin/handoff-briefing.sh: telegram → hindsight → daily memory.
+  let out = assemble(kept, secondaries)
+  const hindsightBody = opts.hindsight && opts.hindsight.length > 0
+    ? renderHindsightBody(opts.hindsight)
+    : ''
+  out = appendSectionWithinBudget(out, HINDSIGHT_SECTION_TITLE, hindsightBody, charBudget)
+  if (opts.dailyMemory && opts.dailyMemory.content.trim()) {
+    out = appendSectionWithinBudget(
+      out,
+      `## Today's memory (${opts.dailyMemory.date})`,
+      opts.dailyMemory.content,
+      charBudget,
+    )
+  }
+  return out
 }
 
 /**

package/telegram-plugin/gateway/boot-briefing-capability.ts

@@ -0,0 +1,31 @@
+/**
+ * Capability sentinel for the start.sh ↔ gateway-bundle version handshake
+ * (#4245). This is a DEPENDENCY-FREE leaf module on purpose: it is imported
+ * both by the gateway (`boot-briefing-wiring.ts`, which references it so the
+ * un-minified bundle carries the literal) AND by `src/agents/scaffold.ts`
+ * (which templates the value into the generated start.sh). Keeping it free of
+ * `bun:sqlite` / history imports lets the node-side scaffold import it without
+ * pulling in bun-only runtime deps.
+ *
+ * ## The skew it closes
+ *
+ * A freshly-scaffolded start.sh sets `SWITCHROOM_SESSION_BRIEFING=gateway` AND
+ * skips the legacy shell handoff-briefing assembler for that mode. If the
+ * deployed `/opt/switchroom/telegram-plugin/dist/gateway/gateway.js` bundle
+ * PREDATES the boot-briefing builder, the gateway path is dead too — the agent
+ * gets a SILENT no-briefing until the image is updated. The stale bundle cannot
+ * self-report a feature it doesn't contain, so the FRESH component (start.sh)
+ * performs the handshake: it greps the deployed bundle for this literal before
+ * trusting the flag. On a miss it warns loudly and drops a marker so the inner
+ * pass runs the legacy handoff assembler as a fallback (see
+ * `profiles/_base/start.sh.hbs`), rather than leaving the boot with nothing.
+ *
+ * The gateway bundle is built UN-minified (`telegram-plugin/scripts/build.mjs`:
+ * `bun build --target node`, no `--minify`), so this string literal survives
+ * verbatim into `gateway.js`.
+ *
+ * Bump the version suffix ONLY on a breaking change to the boot-briefing
+ * capability contract that an older start.sh must not treat as present. Both
+ * sides of the handshake read this single constant, so a bump stays in sync.
+ */
+export const GATEWAY_BOOT_BRIEFING_CAPABILITY = 'switchroom-cap:boot-briefing:v1'