switchroom 0.14.20 → 0.14.22

package/telegram-plugin/gateway/resume-inbound-builder.ts

@@ -0,0 +1,180 @@
+/**
+ * Pure builders for the synthetic inbounds the gateway injects at boot
+ * when it inherits an interrupted turn from the previous process.
+ *
+ * Two shapes, selected by how the prior turn ended (see
+ * `selectResumeBuilder`):
+ *
+ *   - `resume_interrupted` — the turn was cut off mid-flight by an
+ *     operator restart / SIGTERM / crash while it was still making
+ *     progress. The agent should pick the work back up and tell the user
+ *     it's resuming. Blanket resume regardless of how long ago — the
+ *     elapsed time rides along so the model can frame it ("picking up the
+ *     X you asked ~3h ago").
+ *
+ *   - `resume_watchdog_timeout` — the turn stalled with no tool progress
+ *     for the full hang-watchdog window and was (or would have been)
+ *     killed as a hang. The agent must NOT silently resume; it reports
+ *     what happened honestly and asks whether to retry or take a
+ *     different angle. The honest cause is "no observable progress for N
+ *     minutes" — the framework deliberately does not invent a deeper root
+ *     cause, and neither should the model.
+ *
+ * Why a separate module (mirrors `vault-grant-inbound-builders.ts`): the
+ * InboundMessage shape is load-bearing. `meta.source` is what the bridge
+ * forwards verbatim and Claude Code renders as `<channel source="…">`, so
+ * the model keys on it to know this is a boot-resume turn rather than a
+ * human message. `meta.resume_turn_key` is the dedup anchor the spool
+ * uses (see `spoolId`) so a multi-restart sequence resumes a given turn
+ * exactly once. Pinning the builders against fixture tests keeps that
+ * contract honest without booting a real gateway.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+import type { Turn, TurnEndedVia } from '../registry/turns-schema.js'
+
+/** Render an elapsed duration as a coarse, human-friendly approximation
+ *  the model can drop straight into prose ("~3h ago"). Deliberately
+ *  coarse — minute/hour/day buckets, never "2h 47m" precision the user
+ *  doesn't care about on a resume. */
+export function humanizeElapsed(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) return 'an unknown amount of time'
+  const sec = Math.round(ms / 1000)
+  if (sec < 45) return 'moments'
+  const min = Math.round(sec / 60)
+  if (min < 60) return `~${min} min`
+  const hr = Math.round(min / 60)
+  if (hr < 24) return `~${hr}h`
+  const days = Math.round(hr / 24)
+  return `~${days} day${days === 1 ? '' : 's'}`
+}
+
+export interface ResumeInboundContext {
+  /** The interrupted turn, straight from the registry. */
+  turn: Turn
+  /** Wall-clock ms. Drives `ts`, `messageId`, and the elapsed framing.
+   *  Defaults to Date.now(). */
+  nowMs?: number
+}
+
+function threadIdNum(turn: Turn): number | undefined {
+  if (turn.thread_id == null) return undefined
+  const n = Number(turn.thread_id)
+  return Number.isFinite(n) ? n : undefined
+}
+
+function promptClause(turn: Turn): string {
+  const p = turn.user_prompt_preview?.trim()
+  if (!p) return ''
+  // Quote-trim so a long preview doesn't bloat the channel body.
+  const snippet = p.length > 160 ? p.slice(0, 160) + '…' : p
+  return ` The request was: "${snippet}".`
+}
+
+/**
+ * Build the `resume_interrupted` inbound — a clean mid-flight interrupt
+ * the agent should pick back up.
+ */
+export function buildResumeInterruptedInbound(ctx: ResumeInboundContext): InboundMessage {
+  const ts = ctx.nowMs ?? Date.now()
+  const elapsed = humanizeElapsed(ts - ctx.turn.started_at)
+  const meta: Record<string, string> = {
+    source: 'resume_interrupted',
+    resume_turn_key: ctx.turn.turn_key,
+    interrupted_via: ctx.turn.ended_via ?? 'restart',
+    started_at: String(ctx.turn.started_at),
+  }
+  if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  const threadId = threadIdNum(ctx.turn)
+  return {
+    type: 'inbound',
+    chatId: ctx.turn.chat_id,
+    ...(threadId != null ? { threadId } : {}),
+    messageId: ts,
+    user: 'switchroom',
+    userId: 0,
+    ts,
+    text:
+      `You just restarted. Your previous turn was interrupted ${elapsed} ago, ` +
+      `before it finished — it was cut off by a restart, not completed.` +
+      promptClause(ctx.turn) +
+      ` Pick that work back up now and continue it through to completion. ` +
+      `In your first message, briefly let the user know you're resuming what ` +
+      `was interrupted (mention roughly how long ago in plain language) so ` +
+      `they're not left wondering — then carry on with the actual task. Do ` +
+      `not ask whether to resume; just resume. If you genuinely can't tell ` +
+      `what the work was, say so and ask.`,
+    meta,
+  }
+}
+
+/**
+ * Build the `resume_watchdog_timeout` inbound — a stalled turn the agent
+ * must report (not silently resume).
+ *
+ * `idleMs` is the no-progress duration the boot classifier measured (the
+ * marker age). It is passed explicitly rather than read off the turn so
+ * the caller can recover it from the persisted `interrupt_reason` on a
+ * later boot when the live marker is gone.
+ */
+export function buildResumeWatchdogReportInbound(
+  ctx: ResumeInboundContext & { idleMs: number },
+): InboundMessage {
+  const ts = ctx.nowMs ?? Date.now()
+  const idle = humanizeElapsed(ctx.idleMs)
+  const since = humanizeElapsed(ts - ctx.turn.started_at)
+  const toolClause =
+    ctx.turn.tool_call_count != null && ctx.turn.tool_call_count > 0
+      ? ` You'd run ${ctx.turn.tool_call_count} tool call${ctx.turn.tool_call_count === 1 ? '' : 's'} before it stalled.`
+      : ''
+  const meta: Record<string, string> = {
+    source: 'resume_watchdog_timeout',
+    resume_turn_key: ctx.turn.turn_key,
+    interrupted_via: 'timeout',
+    idle_ms: String(ctx.idleMs),
+    started_at: String(ctx.turn.started_at),
+  }
+  if (ctx.turn.tool_call_count != null) meta.tool_call_count = String(ctx.turn.tool_call_count)
+  if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  const threadId = threadIdNum(ctx.turn)
+  return {
+    type: 'inbound',
+    chatId: ctx.turn.chat_id,
+    ...(threadId != null ? { threadId } : {}),
+    messageId: ts,
+    user: 'switchroom',
+    userId: 0,
+    ts,
+    text:
+      `You just restarted. Your previous turn (started ${since} ago) was ` +
+      `killed by the hang-watchdog: it made no observable progress for ${idle} ` +
+      `and the watchdog restarts a turn that goes that long without activity.` +
+      toolClause +
+      promptClause(ctx.turn) +
+      ` Do NOT silently resume it — it may hang again the same way. Instead, ` +
+      `tell the user plainly what happened: that your last turn was killed ` +
+      `after ${idle} of no progress, and roughly what it was doing. Then ask ` +
+      `whether they want you to retry it or take a different angle. Report ` +
+      `only the honest cause — no observable progress for that long — don't ` +
+      `speculate about a deeper root cause you can't see.`,
+    meta,
+  }
+}
+
+/**
+ * Decide which resume inbound (if any) a given interrupt warrants. Pure —
+ * the gateway calls this with the classified `ended_via` so the
+ * report-vs-resume policy lives in one testable place.
+ *
+ *   - 'timeout'                         → 'report'  (watchdog kill)
+ *   - 'restart' | 'sigterm' | 'unknown' → 'resume'  (clean interrupt)
+ *   - 'stop'                            → null      (finished; nothing to do)
+ */
+export function selectResumeBuilder(
+  endedVia: TurnEndedVia | null,
+): 'resume' | 'report' | null {
+  if (endedVia === 'timeout') return 'report'
+  if (endedVia === 'restart' || endedVia === 'sigterm' || endedVia === 'unknown') return 'resume'
+  if (endedVia == null) return 'resume' // still-open at boot = killed mid-flight
+  return null
+}

package/telegram-plugin/registry/turns-schema.ts

@@ -28,11 +28,12 @@
  *     updated_at            INTEGER NOT NULL
  *
  * Boot-time usage:
- *   On every gateway boot, call `markOrphanedAsRestarted(db)` immediately
- *   after opening the DB. Any turn with `ended_at IS NULL` was killed
- *   mid-flight (SIGKILL, OOM, power loss) — it never got a chance to write
- *   a clean-shutdown marker. Stage 3 of simplify-restart will wire this up
- *   from the gateway entry point.
+ *   On every gateway boot, call `markOrphanedWithTimeoutClassification(db, …)`
+ *   immediately after opening the DB. Any turn with `ended_at IS NULL` was
+ *   killed mid-flight (SIGKILL, OOM, power loss, operator restart) — it never
+ *   got a chance to write a clean-shutdown marker. The classifier stamps the
+ *   in-flight turn `'timeout'` when its hang-marker is stale and `'restart'`
+ *   otherwise; the gateway then resumes or reports accordingly.
  */
 
 import { chmodSync, mkdirSync } from 'fs'
@@ -98,6 +99,15 @@ export interface Turn {
   user_prompt_preview: string | null
   assistant_reply_preview: string | null
   tool_call_count: number | null
+  /**
+   * Forensic snapshot persisted by the boot-time classifier when a turn is
+   * stamped `ended_via='timeout'` (the hang-watchdog window elapsed with no
+   * tool progress). Carries the idle duration so a *later* boot can rebuild
+   * the watchdog-report inbound after the on-disk turn-active marker — the
+   * only live source of the idle age — has already been swept. Null for
+   * cleanly-restarted (`'restart'`) orphans.
+   */
+  interrupt_reason: string | null
   created_at: number
   updated_at: number
 }
@@ -137,6 +147,7 @@ const SCHEMA_SQL = `
     user_prompt_preview     TEXT,
     assistant_reply_preview TEXT,
     tool_call_count         INTEGER,
+    interrupt_reason        TEXT,
     created_at              INTEGER NOT NULL,
     updated_at              INTEGER NOT NULL
   );
@@ -151,13 +162,21 @@ const PHASE1_MIGRATIONS = [
   `ALTER TABLE turns ADD COLUMN tool_call_count INTEGER`,
 ]
 
+// Column added for honest-restart-resume. Persists the idle snapshot the
+// boot classifier captures when stamping a turn 'timeout' (see
+// `markOrphanedWithTimeoutClassification`).
+const PHASE2_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN interrupt_reason TEXT`,
+]
+
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
   db.exec(SCHEMA_SQL)
-  // Run migrations for Phase 1 columns. SQLite doesn't support
-  // "ADD COLUMN IF NOT EXISTS", so we swallow the "duplicate column" error.
-  for (const sql of PHASE1_MIGRATIONS) {
+  // Run migrations. SQLite doesn't support "ADD COLUMN IF NOT EXISTS", so
+  // we swallow the "duplicate column" error to stay idempotent on
+  // pre-existing registry.db files.
+  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS]) {
     try {
       db.exec(sql)
     } catch (err) {
@@ -225,6 +244,7 @@ interface RawTurnRow {
   user_prompt_preview: string | null
   assistant_reply_preview: string | null
   tool_call_count: number | null
+  interrupt_reason: string | null
   created_at: number
   updated_at: number
 }
@@ -244,6 +264,7 @@ function mapRow(row: RawTurnRow): Turn {
     user_prompt_preview: row.user_prompt_preview,
     assistant_reply_preview: row.assistant_reply_preview,
     tool_call_count: row.tool_call_count,
+    interrupt_reason: row.interrupt_reason,
     created_at: row.created_at,
     updated_at: row.updated_at,
   }
@@ -283,7 +304,7 @@ export function recordTurnStart(db: SqliteDatabase, args: RecordTurnStartArgs):
  * tool-call count.
  *
  * No-ops gracefully if `turnKey` is not found (turn may have already been
- * swept by `markOrphanedAsRestarted` on a prior boot).
+ * swept by `markOrphanedWithTimeoutClassification` on a prior boot).
  */
 export function recordTurnEnd(db: SqliteDatabase, args: RecordTurnEndArgs): void {
   const now = Date.now()
@@ -327,27 +348,96 @@ export function findOrphanedTurns(db: SqliteDatabase, chatId: string): Turn[] {
   return rows.map(mapRow)
 }
 
+export interface OrphanClassifyOpts {
+  /**
+   * `turnKey` from the on-disk `turn-active.json` marker — the single
+   * in-flight turn the hang-watchdog tracks. Null when no marker is
+   * present at boot (the previous process exited cleanly between turns).
+   */
+  markerTurnKey?: string | null
+  /**
+   * Age in ms of the `turn-active.json` marker's mtime at boot, or null
+   * when no marker is present. The marker's mtime is bumped on every
+   * tool_use, so this is "ms since the last observable progress" of the
+   * in-flight turn.
+   */
+  markerAgeMs?: number | null
+  /**
+   * Hang-watchdog threshold in ms (`TURN_HANG_SECS * 1000`, default
+   * 300_000). A marker older than this means the in-flight turn made no
+   * tool progress for at least the watchdog window — i.e. it was (or,
+   * under Docker where the watchdog is disabled, *would have been*)
+   * killed as a hang rather than cleanly restarted. That distinction is
+   * the whole point: a hung turn is reported, a live one is resumed.
+   */
+  hangThresholdMs: number
+  /**
+   * Opaque snapshot persisted to `interrupt_reason` for the
+   * timeout-classified turn so a later boot can rebuild the watchdog
+   * report after the marker has been swept.
+   */
+  reasonSnapshot?: string | null
+  /** Injectable clock for tests. */
+  now?: number
+}
+
+export interface OrphanClassifyResult {
+  /** Total rows stamped (timeout + restart). */
+  reaped: number
+  /** turn_key stamped 'timeout', or null if none qualified as a hang. */
+  timeoutTurnKey: string | null
+}
+
 /**
- * Boot-time reaper. Sweeps ALL turns (across all chats) that have
- * `ended_at IS NULL` and stamps them with `ended_via = 'restart'` and
- * `ended_at = now()`.
+ * Boot-time reaper + classifier. Sweeps ALL turns with `ended_at IS NULL`
+ * (killed mid-flight: SIGKILL / OOM / hard reboot / operator restart) and
+ * stamps an `ended_via`:
  *
- * Call this once, immediately after `openTurnsDb`, before any new turns
- * are recorded for the current boot. That way the current boot's turns
- * are cleanly separable from orphans inherited from the prior process.
+ *   - the in-flight turn (matched by `markerTurnKey`) is stamped
+ *     `'timeout'` IFF its marker is older than `hangThresholdMs` — it
+ *     stalled with no tool progress for the full watchdog window, so it's
+ *     reported-not-resumed; its `interrupt_reason` carries `reasonSnapshot`.
+ *   - every other open turn (and the in-flight one when it was making
+ *     progress) is stamped `'restart'` — a clean interrupt, eligible for
+ *     blanket resume.
  *
- * Returns the number of rows updated.
+ * Call this once immediately after `openTurnsDb`, BEFORE any new turns are
+ * recorded for the current boot, and BEFORE the turn-active marker is
+ * swept (the classifier needs the marker's mtime).
  */
-export function markOrphanedAsRestarted(db: SqliteDatabase): number {
-  const now = Date.now()
-  const result = db.prepare(`
+export function markOrphanedWithTimeoutClassification(
+  db: SqliteDatabase,
+  opts: OrphanClassifyOpts,
+): OrphanClassifyResult {
+  const now = opts.now ?? Date.now()
+  const isHang =
+    opts.markerAgeMs != null &&
+    opts.markerAgeMs >= opts.hangThresholdMs &&
+    opts.markerTurnKey != null &&
+    opts.markerTurnKey.length > 0
+
+  let timeoutTurnKey: string | null = null
+  if (isHang) {
+    const r = db.prepare(`
+      UPDATE turns
+      SET ended_at         = ?,
+          ended_via        = 'timeout',
+          interrupt_reason = ?,
+          updated_at       = ?
+      WHERE turn_key = ? AND ended_at IS NULL
+    `).run(now, opts.reasonSnapshot ?? null, now, opts.markerTurnKey) as { changes: number }
+    if (r.changes > 0) timeoutTurnKey = opts.markerTurnKey ?? null
+  }
+
+  const rest = db.prepare(`
     UPDATE turns
     SET ended_at   = ?,
         ended_via  = 'restart',
         updated_at = ?
     WHERE ended_at IS NULL
   `).run(now, now) as { changes: number }
-  return result.changes
+
+  return { reaped: (timeoutTurnKey ? 1 : 0) + rest.changes, timeoutTurnKey }
 }
 
 /**
@@ -392,26 +482,41 @@ export function listTurnsForAgent(
   return rows.map(mapRow)
 }
 
+/** ended_via values that mean "this turn did not finish on its own". */
+const INTERRUPTED_VIA: ReadonlySet<TurnEndedVia> = new Set<TurnEndedVia>([
+  'restart',
+  'sigterm',
+  'timeout',
+  'unknown',
+])
+
 /**
- * Find the single most-recently-started turn that ended via an interrupt
- * (`'restart'` | `'sigterm'` | `'timeout'`) OR is still open
- * (`ended_at IS NULL`). Used by Stage 4 to surface "you had pending work"
- * to the agent on cold start.
+ * Return the single most-recently-started turn IFF it was interrupted
+ * (`ended_at IS NULL`, or `ended_via` in {restart, sigterm, timeout,
+ * unknown}). Returns null when the latest turn ended cleanly (`'stop'`)
+ * or there are no turns at all.
  *
- * Returns null if no such turn exists (clean boot — last turn ended 'stop').
+ * This is the resume gate. Keying on the *latest* turn (not "latest
+ * interrupted turn anywhere in history") is deliberate: once the agent
+ * resumes and that follow-up turn ends `'stop'`, the latest turn is clean
+ * and this returns null — so a completed resume is never re-fired on the
+ * next restart. The older `findMostRecentInterruptedTurn` had the inverse
+ * bug: a clean latest turn didn't shadow a stale interrupted one, so it
+ * would resurface already-handled work indefinitely.
  *
- * Note on ordering: we use `started_at DESC` (not `updated_at`) so the
- * boot-time reaper (which mass-stamps orphans with the SAME `ended_at` /
- * `updated_at`) doesn't reorder them; the temporal "last turn" is what
- * the user remembers, and that's `started_at`.
+ * Ordering uses `started_at DESC` (not `updated_at`) so the boot reaper,
+ * which mass-stamps orphans with identical timestamps, can't reorder the
+ * temporal "last turn" the user actually remembers.
  */
-export function findMostRecentInterruptedTurn(db: SqliteDatabase): Turn | null {
+export function findLatestTurnIfInterrupted(db: SqliteDatabase): Turn | null {
   const row = db.prepare(`
     SELECT * FROM turns
-    WHERE ended_at IS NULL
-       OR ended_via IN ('restart', 'sigterm', 'timeout')
     ORDER BY started_at DESC
     LIMIT 1
   `).get() as RawTurnRow | undefined
-  return row ? mapRow(row) : null
+  if (!row) return null
+  const turn = mapRow(row)
+  if (turn.ended_at == null) return turn
+  if (turn.ended_via != null && INTERRUPTED_VIA.has(turn.ended_via)) return turn
+  return null
 }

package/telegram-plugin/stream-reply-handler.ts

@@ -8,7 +8,7 @@
  *
  * Contract:
  *   - First call for a chat+thread: creates a stream via
- *     createStreamController, optionally prepending a handoff prefix.
+ *     createStreamController.
  *   - Subsequent calls: reuse the existing stream, push the new text.
  *   - `done=true`: finalize, delete the map entry, fire status-reaction
  *     completion, and (if history enabled) record the final message.
@@ -171,8 +171,6 @@ export interface StreamReplyDeps {
   escapeMarkdownV2: (text: string) => string
   /** Whitespace repair applied to the raw caller text. */
   repairEscapedWhitespace: (text: string) => string
-  /** Resolves the handoff prefix for a first-chunk stream. Empty string if none. */
-  takeHandoffPrefix: (format: 'html' | 'markdownv2' | 'text') => string
   /** Validates the chat id against the access list. Throws on deny. */
   assertAllowedChat: (chatId: string) => void
   /** Resolves the effective thread id (explicit, last-inbound, or undefined). */
@@ -445,14 +443,6 @@ export async function handleStreamReply(
     streamExisted,
   })
 
-  // First chunk of a session: consume any pending handoff prefix.
-  if (!stream) {
-    const prefix = deps.takeHandoffPrefix(
-      format === 'html' ? 'html' : format === 'markdownv2' ? 'markdownv2' : 'text',
-    )
-    if (prefix.length > 0) effectiveText = prefix + effectiveText
-  }
-
   if (!stream) {
     // Resolve the effective quote-reply target. Explicit `reply_to` wins;
     // otherwise (unless the caller opted out with `quote:false`) fall back

package/telegram-plugin/tests/agent-dir.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { resolveAgentDirFromEnv } from "../agent-dir.js";
+
+describe("resolveAgentDirFromEnv", () => {
+  const prior = process.env.TELEGRAM_STATE_DIR;
+  afterEach(() => {
+    if (prior === undefined) delete process.env.TELEGRAM_STATE_DIR;
+    else process.env.TELEGRAM_STATE_DIR = prior;
+  });
+
+  it("returns dirname of TELEGRAM_STATE_DIR", () => {
+    process.env.TELEGRAM_STATE_DIR = "/foo/bar/agent/telegram";
+    expect(resolveAgentDirFromEnv()).toBe("/foo/bar/agent");
+  });
+
+  it("returns null when env unset", () => {
+    delete process.env.TELEGRAM_STATE_DIR;
+    expect(resolveAgentDirFromEnv()).toBeNull();
+  });
+
+  it("returns null when env is empty string", () => {
+    process.env.TELEGRAM_STATE_DIR = "   ";
+    expect(resolveAgentDirFromEnv()).toBeNull();
+  });
+});

package/telegram-plugin/tests/coalesce-attachments.test.ts

@@ -2,22 +2,40 @@
  * Unit tests for the A2 multi-attachment helpers
  * (telegram-plugin/gateway/coalesce-attachments.ts).
  *
- * These pin the two pure pieces of the multi-attachment fold-in that live
+ * These pin the pure pieces of the multi-attachment fold-in that live
  * outside gateway.ts so they can be exercised without loadAccess()/IPC:
- *   1. splitCoalescedAttachments — primary + capped extras, arrival order.
- *   2. buildExtraAttachmentMeta — numbered meta fields starting at _2.
+ *   1. resolveCoalesceMaxAttachments — the runtime cap default (10).
+ *   2. splitCoalescedAttachments — primary + capped extras, arrival order.
+ *   3. buildExtraAttachmentMeta — numbered meta fields starting at _2.
  *
- * The default cap (1) MUST reproduce the historical single-attachment shape:
- * primary only, no extras, no numbered meta.
+ * A cap of 1 reproduces the historical single-attachment shape: primary
+ * only, no extras, no numbered meta.
  */
 
 import { describe, expect, it } from 'vitest'
 import {
   splitCoalescedAttachments,
   buildExtraAttachmentMeta,
+  resolveCoalesceMaxAttachments,
+  DEFAULT_MAX_ATTACHMENTS,
   type ResolvedExtraAttachment,
 } from '../gateway/coalesce-attachments.js'
 
+describe('resolveCoalesceMaxAttachments (default 10 = full album)', () => {
+  it('defaults to 10 when unset', () => {
+    expect(resolveCoalesceMaxAttachments(undefined)).toBe(10)
+    expect(DEFAULT_MAX_ATTACHMENTS).toBe(10)
+  })
+  it('honours an explicit operator cap', () => {
+    expect(resolveCoalesceMaxAttachments(1)).toBe(1)
+    expect(resolveCoalesceMaxAttachments(25)).toBe(25)
+  })
+  it('floors a 0 / negative cap at 1 (never strips the only attachment)', () => {
+    expect(resolveCoalesceMaxAttachments(0)).toBe(1)
+    expect(resolveCoalesceMaxAttachments(-5)).toBe(1)
+  })
+})
+
 interface Entry {
   text: string
   att?: string
@@ -26,7 +44,7 @@ interface Entry {
 const has = (e: Entry): boolean => e.att != null
 
 describe('splitCoalescedAttachments', () => {
-  it('default cap 1: keeps only the first attachment as primary, no extras', () => {
+  it('cap 1: keeps only the first attachment as primary, no extras', () => {
     const entries: Entry[] = [
       { text: 'a', att: 'photo-1' },
       { text: 'b', att: 'photo-2' },

package/telegram-plugin/tests/e2e.test.ts

@@ -10,7 +10,7 @@
  * of this test file and brittle w.r.t. upstream churn.
  *
  * Instead, following the existing project convention
- * (see steering.test.ts, handoff-continuity.test.ts), we exercise each
+ * (see steering.test.ts), we exercise each
  * specified scenario through the same pure helper modules that server.ts
  * calls. Where a scenario lives inside server.ts's in-memory state
  * (activeTurnStartedAt, activeStatusReactions, suppressPtyPreview), we
@@ -18,23 +18,13 @@
  * server.ts uses. The helpers and the state shape are the contract —
  * if they don't regress, the integrated behaviour doesn't regress.
  */
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 
 import {
   parseQueuePrefix,
   formatPriorAssistantPreview,
   buildChannelMetaAttributes,
 } from '../steering.js'
-import {
-  consumeHandoffTopic,
-  readHandoffTopic,
-  formatHandoffLine,
-  shouldShowHandoffLine,
-  HANDOFF_TOPIC_FILENAME,
-} from '../handoff-continuity.js'
 import {
   isContextExhaustionText,
   shouldArmOrphanedReplyTimeout,
@@ -64,7 +54,6 @@ interface PluginState {
   currentSessionChatId: string | null
   currentSessionThreadId: number | undefined
   currentTurnStartedAt: number
-  handoffTopicUsed: boolean
 }
 
 function freshState(): PluginState {
@@ -75,7 +64,6 @@ function freshState(): PluginState {
     currentSessionChatId: null,
     currentSessionThreadId: undefined,
     currentTurnStartedAt: 0,
-    handoffTopicUsed: false,
   }
 }
 
@@ -271,69 +259,6 @@ describe('E2E: turn lifecycle cleanup', () => {
   })
 })
 
-// ---------------------------------------------------------------------------
-// Handoff continuity
-// ---------------------------------------------------------------------------
-
-describe('E2E: handoff continuity', () => {
-  let tmp: string
-  const priorEnv = { ...process.env }
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'handoff-e2e-'))
-  })
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true })
-    process.env = { ...priorEnv }
-  })
-
-  it('bootstrap with sidecar + show-line=true → first reply prepends the line', () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), 'shipped the feature\n', 'utf8')
-    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = 'true'
-    expect(shouldShowHandoffLine()).toBe(true)
-    const topic = consumeHandoffTopic(tmp)
-    expect(topic).toBe('shipped the feature')
-    const line = formatHandoffLine(topic!, 'html')
-    expect(line).toContain('shipped the feature')
-    expect(line).toMatch(/^<i>/)
-  })
-
-  it('bootstrap with sidecar + show-line=false → no prefix', () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), 'x\n', 'utf8')
-    process.env.SWITCHROOM_HANDOFF_SHOW_LINE = 'false'
-    expect(shouldShowHandoffLine()).toBe(false)
-  })
-
-  it('bootstrap with no sidecar → no prefix', () => {
-    expect(readHandoffTopic(tmp)).toBeNull()
-    expect(consumeHandoffTopic(tmp)).toBeNull()
-  })
-
-  it('consuming topic is one-shot — second call returns null + sidecar deleted', () => {
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), 'topic\n', 'utf8')
-    expect(consumeHandoffTopic(tmp)).toBe('topic')
-    expect(existsSync(join(tmp, HANDOFF_TOPIC_FILENAME))).toBe(false)
-    expect(consumeHandoffTopic(tmp)).toBeNull()
-  })
-
-  it('stream_reply: once topic consumed, subsequent stream chunks do not re-prefix', () => {
-    // Model: the plugin tracks handoffTopicUsed after first reply/stream_reply
-    // use. The second and later stream edits on the same stream read the flag
-    // and skip prepending.
-    writeFileSync(join(tmp, HANDOFF_TOPIC_FILENAME), 't\n', 'utf8')
-    const s = freshState()
-    expect(s.handoffTopicUsed).toBe(false)
-    // first chunk
-    const topic = consumeHandoffTopic(tmp)
-    expect(topic).toBe('t')
-    s.handoffTopicUsed = true
-    // simulate next chunk arriving — should not consume
-    expect(consumeHandoffTopic(tmp)).toBeNull()
-    expect(s.handoffTopicUsed).toBe(true)
-  })
-})
-
 // ---------------------------------------------------------------------------
 // Context exhaustion
 // ---------------------------------------------------------------------------