switchroom 0.17.6 → 0.18.3

package/telegram-plugin/stream-controller.ts

@@ -21,6 +21,7 @@
 
 import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
+import { maybeRenderOutbound } from './render/rich-render.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -224,12 +225,22 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // control previews via entity detection), so strip it for the rich path.
   const doSend = (text: string, opts: StreamSendOpts) => {
     if (literalText) return bot.api.sendMessage(chatId, text, opts)
+    // Flag-gated rich render (`SWITCHROOM_RICH_RENDER`, default OFF — returns
+    // the text untouched as markdown when off, so this is a no-op for every
+    // agent until an operator opts in). A `plain` result (oversized/unsafe
+    // content renderSafe declined to emit as rich) sends WITHOUT the wrapper.
+    const rendered = maybeRenderOutbound(text)
+    if (rendered.mode === 'plain') return bot.api.sendMessage(chatId, rendered.text, opts)
     const richOpts = { ...opts }
     delete richOpts.link_preview_options
-    return bot.api.sendRichMessage(chatId, richMessage(text), richOpts)
+    return bot.api.sendRichMessage(chatId, richMessage(rendered.text), richOpts)
+  }
+  const doEdit = (id: number, text: string, opts: StreamSendOpts) => {
+    if (literalText) return bot.api.editMessageText(chatId, id, text, opts)
+    const rendered = maybeRenderOutbound(text)
+    if (rendered.mode === 'plain') return bot.api.editMessageText(chatId, id, rendered.text, opts)
+    return bot.api.editMessageText(chatId, id, richMessage(rendered.text), opts)
   }
-  const doEdit = (id: number, text: string, opts: StreamSendOpts) =>
-    bot.api.editMessageText(chatId, id, literalText ? text : richMessage(text), opts)
 
   return createDraftStream(
     async (text) => {

package/telegram-plugin/subagent-watcher.ts

@@ -211,6 +211,24 @@ export interface SubagentWatcherConfig {
    * an agent's home pollutes the watcher with phantom registrations).
    */
   agentCwd?: string
+  /**
+   * Additional cwds (beyond `agentCwd`) whose Claude-Code project-dir slug
+   * should also be watched. Gap 2 of `deterministic-turn-liveness.md`: a
+   * sub-agent dispatched with worktree isolation (`switchroom worktree
+   * claim`) runs with a *different* cwd than the parent agent, so its
+   * `agent-*.jsonl` lands under a different `.claude/projects/<slug>/`
+   * tree than `expectedProjectSlug` — the #1116 foreign-slug filter then
+   * silently skips it forever (no activity stamp, no `🛠 Worker` feed).
+   *
+   * Called fresh on every rescan tick (cheap — reads a handful of small
+   * JSON records from the worktree registry) so a worktree claimed or
+   * released mid-run is picked up/dropped without a watcher restart.
+   * Deterministic guarantee this preserves: only cwds this agent's own
+   * sub-agents can legitimately run in are ever added — a worktree record
+   * not owned by this agent is never included, so this does not widen the
+   * #1116 foreign-project protection into a wildcard watch.
+   */
+  extraWatchCwdsProvider?: () => string[]
   /**
    * How often to re-scan for new subagent dirs (ms). Default 1000.
    */
@@ -1173,6 +1191,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
   const expectedProjectSlug = config.agentCwd != null
     ? sanitizeCwdToProjectName(config.agentCwd)
     : null
+  const extraWatchCwdsProvider = config.extraWatchCwdsProvider ?? null
   // One-shot logging: warn the first time a foreign slug is observed
   // so silent regressions are visible without re-running with debug.
   const warnedForeignSlugs = new Set<string>()
@@ -1706,17 +1725,52 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       projectDirs = fs.readdirSync(projectsRoot) as string[]
     } catch { return }
 
+    // Gap 2 (deterministic-turn-liveness.md): re-derive the set of
+    // worktree-isolated slugs this agent's own sub-agents may legitimately
+    // run in, fresh on every tick. Best-effort — a registry read hiccup
+    // (e.g. the worktree dir not existing on an agent that never uses
+    // worktrees) must never break the tail loop, so it just yields no
+    // extra slugs for this tick.
+    let allowedSlugs: Set<string> | null = null
+    // Did the extra-cwd provider run cleanly this tick? A transient failure
+    // (registry read hiccup) must NOT permanently mislabel an owned worktree
+    // slug as "foreign": we still skip it this tick (it isn't provably ours
+    // right now), but we do NOT latch the one-shot warning, so the next clean
+    // tick re-includes and re-derives it instead of staying silently excluded.
+    let providerOk = true
+    if (expectedProjectSlug != null) {
+      allowedSlugs = new Set([expectedProjectSlug])
+      if (extraWatchCwdsProvider != null) {
+        try {
+          for (const cwd of extraWatchCwdsProvider()) {
+            allowedSlugs.add(sanitizeCwdToProjectName(cwd))
+          }
+        } catch (err) {
+          providerOk = false
+          log?.(`subagent-watcher: extraWatchCwdsProvider error: ${(err as Error).message}`)
+        }
+      }
+    }
+
     for (const pDir of projectDirs) {
-      // Issue #1116: filter to the agent's own slug. Skip foreign
-      // project dirs so their stale subagent JSONLs (which Claude
-      // Code reaps mid-session) don't pollute the watcher's registry.
-      if (expectedProjectSlug != null && pDir !== expectedProjectSlug) {
-        if (!warnedForeignSlugs.has(pDir)) {
+      // Issue #1116: filter to the agent's own slug (plus, per Gap 2, any
+      // worktree-isolated slugs this agent's own sub-agents may run in).
+      // Skip foreign project dirs so their stale subagent JSONLs (which
+      // Claude Code reaps mid-session) don't pollute the watcher's registry.
+      if (allowedSlugs != null && !allowedSlugs.has(pDir)) {
+        // A slug that is now allowed must clear any stale "foreign" latch, so a
+        // slug that was transiently excluded (or later genuinely goes foreign)
+        // re-warns rather than staying mislabeled forever.
+        if (providerOk && !warnedForeignSlugs.has(pDir)) {
           warnedForeignSlugs.add(pDir)
-          log?.(`subagent-watcher: skipping foreign project dir ${pDir} (expected ${expectedProjectSlug})`)
+          const allowed = [...allowedSlugs].join(', ')
+          log?.(`subagent-watcher: skipping foreign project dir ${pDir} (allowed: ${allowed})`)
         }
         continue
       }
+      // Owned/allowed this tick — drop any prior foreign latch so a future
+      // genuine foreign appearance of the same slug re-warns.
+      warnedForeignSlugs.delete(pDir)
       const projectPath = join(projectsRoot, pDir)
       let sessionDirs: string[]
       try {

package/telegram-plugin/tests/activity-card-store.test.ts

@@ -0,0 +1,530 @@
+/**
+ * activity-card-store.test.ts — outcome-based tests for the mid-turn
+ * activity-card restart-survivability fix (Known Gap 1,
+ * `reference/rfcs/deterministic-turn-liveness.md`).
+ *
+ * PRE-FIX PROOF: before this PR, no persistence existed for
+ * `CurrentTurn.activityMessageId` at all — `../gateway/activity-card-store.js`
+ * did not exist, so `import` itself failed at collection time:
+ *
+ *   Error: Cannot find module '../gateway/activity-card-store.js'
+ *   (or its corresponding .ts source) imported from
+ *   telegram-plugin/tests/activity-card-store.test.ts
+ *
+ * i.e. every test below fails on today's (pre-fix) base — there was no seam
+ * to test. Recorded run against `origin/main` (this PR's parent commit)
+ * before the module was added:
+ *
+ *   FAIL  telegram-plugin/tests/activity-card-store.test.ts
+ *   [vitest] Cannot find module '../gateway/activity-card-store.js'
+ *
+ * This file exercises the REAL exported store + boot-reaper functions (not a
+ * structural grep), mirroring `status-pin-store.test.ts`'s in-memory fs seam
+ * convention, plus a transport-boundary reaper test (mirrors
+ * `silent-end-transport.test.ts`'s spy-transport convention) proving the
+ * exact outcome contract: (a) card open persists a record; (b) clean close
+ * clears it; (c) a boot reaper run against a leftover record performs
+ * EXACTLY ONE finalizing edit + one unpin and deletes the record; (d) a
+ * second boot performs ZERO edits and ZERO unpins; (e) a corrupt state file
+ * never crashes boot and is dropped without an edit.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  loadActivityCards,
+  persistActivityCards,
+  writeActivityCardRecord,
+  clearActivityCardRecord,
+  runActivityCardBootReaper,
+  runActivityCardMidSessionReaper,
+  restartOrphanCardFinalizeText,
+  type ActivityCardRecord,
+  type ActivityCardStoreFsSeam,
+} from '../gateway/activity-card-store.js'
+
+/** In-memory fs seam with an atomic rename — same convention as
+ *  status-pin-store.test.ts's memFs, so the tmp→rename crash-safety
+ *  contract is exercised without touching real disk. */
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed))
+  const calls: string[] = []
+  const fs: ActivityCardStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`)
+      return files.get(p)!
+    },
+    writeFileSync: (p, d) => {
+      calls.push(`write:${p}`)
+      files.set(p, d)
+    },
+    renameSync: (a, b) => {
+      calls.push(`rename:${a}->${b}`)
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`)
+      files.set(b, files.get(a)!)
+      files.delete(a)
+    },
+    existsSync: (p) => files.has(p),
+  }
+  return { fs, files, calls }
+}
+
+const PATH = '/state/agent/telegram/activity-cards-pending.json'
+
+function card(over: Partial<ActivityCardRecord> = {}): ActivityCardRecord {
+  return {
+    turnKey: 'c:_',
+    chatId: '-100123',
+    threadId: null,
+    activityMessageId: 715,
+    startedAt: Date.now() - 60_000,
+    pinned: true,
+    ...over,
+  }
+}
+
+describe('activity-card-store — persistence primitives', () => {
+  it('loads [] when no file exists (fresh boot)', () => {
+    const { fs } = memFs()
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('(a) card open → state persisted (round-trips a written record)', () => {
+    const { fs } = memFs()
+    // Construct ONCE — card() stamps `startedAt: Date.now() - 60_000`, so two
+    // separate calls can straddle a millisecond and flake the deep-equal.
+    const record = card()
+    writeActivityCardRecord(PATH, fs, record)
+    const loaded = loadActivityCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]).toEqual(record)
+  })
+
+  it('a fresh OPEN for the same topic replaces (upserts) the stale row, not appends', () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ activityMessageId: 715 }))
+    writeActivityCardRecord(PATH, fs, card({ activityMessageId: 900 }))
+    const loaded = loadActivityCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.activityMessageId).toBe(900)
+  })
+
+  it('(b) clean close → state cleared', () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card())
+    expect(loadActivityCards(PATH, fs)).toHaveLength(1)
+    clearActivityCardRecord(PATH, fs, 'c:_')
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('clearing an absent/mismatched turnKey is a no-op (never throws)', () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:other' }))
+    clearActivityCardRecord(PATH, fs, 'c:_')
+    expect(loadActivityCards(PATH, fs)).toHaveLength(1)
+  })
+
+  it('writes via tmp + atomic rename (crash-safe)', () => {
+    const { fs, calls } = memFs()
+    persistActivityCards(PATH, fs, [card()])
+    expect(calls).toEqual([`write:${PATH}.tmp`, `rename:${PATH}.tmp->${PATH}`])
+  })
+
+  it('(e) corrupt state file: boot survives, loads as [] (fail-open, never throws)', () => {
+    const { fs } = memFs({ [PATH]: '{not json' })
+    expect(() => loadActivityCards(PATH, fs)).not.toThrow()
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('fail-open: wrong envelope version / malformed shape loads as []', () => {
+    const { fs: f1 } = memFs({ [PATH]: JSON.stringify({ v: 2, cards: [card()] }) })
+    expect(loadActivityCards(PATH, f1)).toEqual([])
+    const { fs: f2 } = memFs({ [PATH]: JSON.stringify({ v: 1, cards: 'nope' }) })
+    expect(loadActivityCards(PATH, f2)).toEqual([])
+  })
+
+  it('drops malformed rows but keeps valid ones', () => {
+    const { fs } = memFs({
+      [PATH]: JSON.stringify({
+        v: 1,
+        cards: [
+          card({ activityMessageId: 715 }),
+          { turnKey: '', chatId: 'c', threadId: null, activityMessageId: 1, startedAt: 1 },
+          { turnKey: 'k', chatId: 'c', threadId: null, startedAt: 1 }, // missing activityMessageId
+        ],
+      }),
+    })
+    const loaded = loadActivityCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.activityMessageId).toBe(715)
+  })
+
+  it('persist never throws on a failing fs (durability degrades, live path unaffected)', () => {
+    const throwingFs: ActivityCardStoreFsSeam = {
+      readFileSync: () => {
+        throw new Error('boom')
+      },
+      writeFileSync: () => {
+        throw new Error('disk full')
+      },
+      renameSync: () => {
+        throw new Error('nope')
+      },
+      existsSync: () => false,
+    }
+    const logs: string[] = []
+    expect(() => persistActivityCards(PATH, throwingFs, [card()], (l) => logs.push(l))).not.toThrow()
+    expect(logs.join('')).toContain('persist FAILED')
+  })
+})
+
+/**
+ * Boot reaper — transport-boundary outcome tests (mirrors
+ * silent-end-transport.test.ts's spy-transport convention): a spy stands in
+ * for `bot.api.editMessageText` / `bot.api.unpinChatMessage`, asserting an
+ * actual finalizing edit + unpin land, not a stubbed decision callback.
+ */
+describe('runActivityCardBootReaper — transport-boundary outcome tests', () => {
+  it('(c) leftover record → exactly one finalizing edit + one unpin, record deleted', async () => {
+    const { fs } = memFs()
+    const startedAt = Date.now() - 90_000
+    writeActivityCardRecord(PATH, fs, card({ startedAt }))
+
+    const edits: Array<{ chatId: string; messageId: number; text: string }> = []
+    const unpins: Array<{ chatId: string; messageId: number }> = []
+
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async (record) => {
+        edits.push({
+          chatId: record.chatId,
+          messageId: record.activityMessageId,
+          text: restartOrphanCardFinalizeText(record.startedAt),
+        })
+        // A truthy result models a REAL delivered edit (grammy returns the
+        // edited Message); a benign-400 would resolve to undefined instead.
+        return { message_id: record.activityMessageId }
+      },
+      unpinCard: async (record) => {
+        unpins.push({ chatId: record.chatId, messageId: record.activityMessageId })
+      },
+    })
+
+    expect(edits).toHaveLength(1)
+    expect(edits[0]!.chatId).toBe('-100123')
+    expect(edits[0]!.messageId).toBe(715)
+    expect(edits[0]!.text).toContain('Interrupted by a gateway restart')
+    expect(edits[0]!.text).toContain('was running')
+
+    expect(unpins).toHaveLength(1)
+    expect(unpins[0]).toEqual({ chatId: '-100123', messageId: 715 })
+
+    expect(res).toEqual({ finalized: 1, vanished: 0, unpinned: 1, total: 1 })
+    // Record gone — nothing left for a future boot to re-finalize.
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('(d) second boot with an already-empty store → zero edits, zero unpins', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card())
+
+    let edits = 0
+    let unpins = 0
+    // First boot reaps the one leftover record.
+    await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        edits++
+        return { ok: true }
+      },
+      unpinCard: async () => {
+        unpins++
+      },
+    })
+    expect(edits).toBe(1)
+    expect(unpins).toBe(1)
+
+    // Second boot re-reads the (now empty) file — the idempotency guarantee.
+    const res2 = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        edits++
+        return { ok: true }
+      },
+      unpinCard: async () => {
+        unpins++
+      },
+    })
+    expect(edits).toBe(1) // unchanged
+    expect(unpins).toBe(1) // unchanged
+    expect(res2).toEqual({ finalized: 0, vanished: 0, unpinned: 0, total: 0 })
+  })
+
+  it('a record with pinned:false (or absent) is finalized but never unpinned', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ pinned: false }))
+    let unpins = 0
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => ({ ok: true }),
+      unpinCard: async () => {
+        unpins++
+      },
+    })
+    expect(res.finalized).toBe(1)
+    expect(unpins).toBe(0)
+  })
+
+  it('no-op on a fresh boot with no persisted cards (zero edits, zero unpins)', async () => {
+    const { fs } = memFs()
+    let calls = 0
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        calls++
+        return { ok: true }
+      },
+      unpinCard: async () => {
+        calls++
+      },
+    })
+    expect(res).toEqual({ finalized: 0, vanished: 0, unpinned: 0, total: 0 })
+    expect(calls).toBe(0)
+  })
+
+  it('a failing finalize edit is non-fatal, still attempts the unpin, and the store is still emptied', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card())
+    let unpinCalled = false
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        throw new Error('message to edit not found')
+      },
+      unpinCard: async () => {
+        unpinCalled = true
+      },
+    })
+    expect(res).toEqual({ finalized: 0, vanished: 0, unpinned: 1, total: 1 })
+    expect(unpinCalled).toBe(true)
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('a failing unpin (already unpinned / no rights) is non-fatal and does not re-run the edit', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card())
+    let editCalls = 0
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        editCalls++
+        return { ok: true }
+      },
+      unpinCard: async () => {
+        throw new Error('message to unpin not found')
+      },
+    })
+    expect(res).toEqual({ finalized: 1, vanished: 0, unpinned: 0, total: 1 })
+    expect(editCalls).toBe(1)
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('reaps multiple leftover records from distinct topics independently', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:1', chatId: '-100111', activityMessageId: 1 }))
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:2', chatId: '-100222', activityMessageId: 2 }))
+    const edited: number[] = []
+    const unpinned: number[] = []
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async (r) => {
+        edited.push(r.activityMessageId)
+        return { message_id: r.activityMessageId }
+      },
+      unpinCard: async (r) => {
+        unpinned.push(r.activityMessageId)
+      },
+    })
+    expect(res).toEqual({ finalized: 2, vanished: 0, unpinned: 2, total: 2 })
+    expect(edited.sort()).toEqual([1, 2])
+    expect(unpinned.sort()).toEqual([1, 2])
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('idempotency guard: the record is removed from disk BEFORE the finalize/unpin calls run (crash-mid-reap safety)', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card())
+    let onDiskDuringFinalize: ActivityCardRecord[] = []
+    await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        onDiskDuringFinalize = loadActivityCards(PATH, fs)
+      },
+      unpinCard: async () => {},
+    })
+    // At the moment finalizeCard ran, the record was ALREADY gone from disk —
+    // so a crash right here (or a concurrent second boot) can never re-reap it.
+    expect(onDiskDuringFinalize).toEqual([])
+  })
+
+  it('a benign-400 (finalizeCard resolves undefined) counts as vanished, not finalized', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ pinned: false }))
+    // robustApiCall swallows "message to edit not found" / "not modified" and
+    // resolves to undefined — nothing was delivered, so it must not be counted
+    // as a finalize (the pre-fix boot log over-reported the guarantee).
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => undefined,
+      unpinCard: async () => {},
+    })
+    expect(res).toEqual({ finalized: 0, vanished: 1, unpinned: 0, total: 1 })
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('reap-race guard: an id-scoped clear leaves a live turn\'s fresh upsert (same turnKey) intact', async () => {
+    const { fs } = memFs()
+    // The reaper loads this OLD card (id=715) and finalizes it…
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:_', activityMessageId: 715 }))
+    await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        // …but MID-REAP (e.g. during a 429 flood-wait) a fresh live turn opens a
+        // NEW card under the same topic key (id=999). Its record must survive.
+        writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:_', activityMessageId: 999 }))
+        return { ok: true }
+      },
+      unpinCard: async () => {},
+    })
+    // The id-scoped clear removed only the OLD (715) row; the live 999 row is
+    // still protected. A turnKey-only clear would have wiped it.
+    const remaining = loadActivityCards(PATH, fs)
+    expect(remaining).toHaveLength(1)
+    expect(remaining[0]!.activityMessageId).toBe(999)
+  })
+
+  it('clearActivityCardRecord with a mismatched id is a no-op (does not drop a same-turnKey different-id row)', () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:_', activityMessageId: 999 }))
+    clearActivityCardRecord(PATH, fs, 'c:_', 715) // wrong id
+    expect(loadActivityCards(PATH, fs)).toHaveLength(1)
+    clearActivityCardRecord(PATH, fs, 'c:_', 999) // matching id
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+})
+
+describe('restartOrphanCardFinalizeText', () => {
+  it('is honest about elapsed time', () => {
+    const text = restartOrphanCardFinalizeText(Date.now() - 45_000)
+    expect(text).toContain('Interrupted by a gateway restart')
+    expect(text).toMatch(/was running \d+s/)
+  })
+
+  it('omits a nonsensical elapsed clause for a degenerate startedAt', () => {
+    const text = restartOrphanCardFinalizeText(Date.now() + 10_000) // future — negative elapsed
+    expect(text).toContain('Interrupted by a gateway restart')
+    expect(text).not.toContain('was running')
+  })
+})
+
+describe('runActivityCardMidSessionReaper (#2918 mid-session sweep)', () => {
+  const NOW = 2_000_000_000_000
+  const TTL = 15 * 60_000
+
+  it('finalizes + unpins an ownerless stale card, and deletes its record', async () => {
+    const dead = card({ turnKey: 'c:dead', activityMessageId: 715, startedAt: NOW - 30 * 60_000 })
+    const { fs, files } = memFs()
+    writeActivityCardRecord(PATH, fs, dead)
+    const finalized: number[] = []
+    const unpinned: number[] = []
+    const res = await runActivityCardMidSessionReaper({
+      path: PATH, fs,
+      isLive: () => false, // process gone, no live owner
+      ttlMs: TTL, now: NOW,
+      finalizeCard: async (r) => { finalized.push(r.activityMessageId); return { message_id: r.activityMessageId } },
+      unpinCard: async (r) => { unpinned.push(r.activityMessageId); return true },
+    })
+    expect(res).toEqual({ finalized: 1, vanished: 0, unpinned: 1, total: 1 })
+    expect(finalized).toEqual([715])
+    expect(unpinned).toEqual([715])
+    // Record deleted BEFORE the edit (at-most-once idempotency guard).
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+    void files
+  })
+
+  it('NEVER touches a live card (isLive true) — spinner keeps spinning', async () => {
+    const live = card({ turnKey: 'c:live', activityMessageId: 900, startedAt: NOW - 6 * 60 * 60_000 })
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, live)
+    let edits = 0
+    const res = await runActivityCardMidSessionReaper({
+      path: PATH, fs,
+      isLive: (r) => r.turnKey === 'c:live',
+      ttlMs: TTL, now: NOW,
+      finalizeCard: async () => { edits++; return {} },
+      unpinCard: async () => true,
+    })
+    expect(res.total).toBe(0)
+    expect(edits).toBe(0)
+    // Live record untouched on disk.
+    expect(loadActivityCards(PATH, fs)).toHaveLength(1)
+  })
+
+  it('does not reap an ownerless card younger than the TTL (race guard)', async () => {
+    const fresh = card({ turnKey: 'c:fresh', startedAt: NOW - 60_000 })
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, fresh)
+    let edits = 0
+    const res = await runActivityCardMidSessionReaper({
+      path: PATH, fs,
+      isLive: () => false,
+      ttlMs: TTL, now: NOW,
+      finalizeCard: async () => { edits++; return {} },
+      unpinCard: async () => true,
+    })
+    expect(res.total).toBe(0)
+    expect(edits).toBe(0)
+    expect(loadActivityCards(PATH, fs)).toHaveLength(1)
+  })
+
+  it('reaps the dead card while sparing a concurrently-live one', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:dead', activityMessageId: 1, startedAt: NOW - 30 * 60_000 }))
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:live', activityMessageId: 2, startedAt: NOW - 30 * 60_000 }))
+    const finalized: number[] = []
+    const res = await runActivityCardMidSessionReaper({
+      path: PATH, fs,
+      isLive: (r) => r.turnKey === 'c:live',
+      ttlMs: TTL, now: NOW,
+      finalizeCard: async (r) => { finalized.push(r.activityMessageId); return {} },
+      unpinCard: async () => true,
+    })
+    expect(res.total).toBe(1)
+    expect(finalized).toEqual([1])
+    const remaining = loadActivityCards(PATH, fs)
+    expect(remaining).toHaveLength(1)
+    expect(remaining[0]!.turnKey).toBe('c:live')
+  })
+
+  it('counts a benign-400 (vanished) card as vanished, not finalized', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(PATH, fs, card({ turnKey: 'c:gone', pinned: false, startedAt: NOW - 30 * 60_000 }))
+    const res = await runActivityCardMidSessionReaper({
+      path: PATH, fs,
+      isLive: () => false,
+      ttlMs: TTL, now: NOW,
+      finalizeCard: async () => undefined, // robustApiCall swallowed a benign 400
+      unpinCard: async () => true,
+    })
+    expect(res).toEqual({ finalized: 0, vanished: 1, unpinned: 0, total: 1 })
+  })
+})