switchroom 0.19.30 → 0.19.31

package/telegram-plugin/edit-flood-fuse.ts

@@ -69,12 +69,16 @@
  * lost". Two rules follow, and both are load-bearing:
  *   - per-MESSAGE over-budget edits SUPERSEDE (newest wins, older frame is
  *     discarded) — safe, because the frame that killed it will paint;
- *   - per-CHAT over-budget edits may only be DROPPED while a NEWER frame for
- *     that same message is still in flight to repaint it. When the waiting
- *     frame is the only one for its card (a turn-final `finalize`, say) it is
- *     RELEASED late instead of dropped. Dropping it would freeze the card
- *     mid-run AND return `true` to the send gate, which would then record a
- *     never-painted payload as on-screen and no-op-skip every retry.
+ *   - an over-budget edit may only be DROPPED AT THE DEFER DEADLINE while a
+ *     NEWER frame for that same message is still in flight to repaint it. When
+ *     the waiting frame is the only one for its card (a turn-final `finalize`,
+ *     say) it is RELEASED late instead of dropped. Dropping it would freeze the
+ *     card mid-run AND return `true` to the send gate, which would then record a
+ *     never-painted payload as on-screen and no-op-skip every retry. This rule
+ *     (`dropGuard`) binds on ALL THREE tiers — per-message included. It was
+ *     originally wired into the two per-chat tiers only, which left the
+ *     per-message tier dropping a lone terminal frame unconditionally at
+ *     `maxDeferMs` and freezing the card by exactly the route R1 forbids.
  *
  * ── 2026-07-27: the fuse existed and the ban happened anyway ──────────────
  * The ceilings above were sized against the in-repo pacers, not against what
@@ -599,8 +603,35 @@ export function editFloodFuseConfigFromEnv(
   return cfg
 }
 
-/** grammY resolves an edit with `true` when there is nothing to return. */
-const DROPPED_RESULT = true
+/**
+ * What a DROPPED call resolves to.
+ *
+ * `apply` is a grammY **transformer**, and a transformer's contract is the raw
+ * `ApiResponse` ENVELOPE (`{ok: true, result}` / `{ok: false, error_code,
+ * description}`) — not the unwrapped result. grammY's `Api.callApi` does:
+ *
+ * ```js
+ * const data = await this.call(method, payload, signal)
+ * if (data.ok) return data.result
+ * else throw toGrammyError(data, method, payload)
+ * ```
+ * (grammy `out/core/client.js`)
+ *
+ * This constant used to be the bare `true` — the *result* an edit resolves to,
+ * with the envelope omitted. `(true).ok` is `undefined`, so every deliberate
+ * fuse drop took the `else` branch and surfaced as
+ * `GrammyError: Call to 'editMessageText' failed! (undefined: undefined)`
+ * (`err.error_code` / `err.description` are both absent on a boolean). Callers
+ * then counted the fuse's INTENDED rate-limiting as a transport failure — which
+ * is how a healthy turn reached `activityDrainFailures=8` and was flagged
+ * DEGRADED for behaving exactly as designed (narrative-lane.ts drain catch).
+ *
+ * Wrapping it in the envelope restores the contract the rest of this file
+ * already documents: a dropped call resolves as the benign no-op described in
+ * the header ("A superseded or over-deferred edit is DROPPED (resolved as a
+ * benign no-op)") and returns `true` to the send gate, as the R1 note assumes.
+ */
+const DROPPED_RESULT = { ok: true as const, result: true }
 
 interface Window {
   ts: number[]
@@ -961,11 +992,15 @@ export function createEditFloodFuse(config: EditFloodFuseConfig = {}) {
     maxFor: (now: number) => number,
     method: string, mode: WaitMode, cls: OutboundClass,
     /**
-     * Consulted ONLY at the defer deadline for `mode: 'drop'`. Returning false
-     * converts the drop into a late release: this call is the last thing that
-     * will ever paint its message, so losing it is not "shedding a stale
-     * frame", it is freezing a card. Absent ⇒ drop unconditionally (the
-     * pre-review behaviour).
+     * Consulted ONLY at the defer deadline, for every non-`release` mode
+     * (`drop` AND `supersede`). Returning false converts the drop into a late
+     * release: this call is the last thing that will ever paint its message, so
+     * losing it is not "shedding a stale frame", it is freezing a card. Absent
+     * ⇒ drop unconditionally (the pre-review behaviour).
+     *
+     * Note this is the DEADLINE guard only. In `supersede` mode a genuinely
+     * newer frame still kills a waiter outright via `w.waiter.kill()` — that is
+     * last-write-wins and is unaffected by this guard.
      */
     dropGuard: (() => boolean) | undefined,
     /**
@@ -1118,21 +1153,36 @@ export function createEditFloodFuse(config: EditFloodFuseConfig = {}) {
       // Counted BEFORE the first await so a frame that arrives while an older
       // one is waiting is visible to that older one's `dropGuard`.
       mw.inflight++
+      // R1: only drop while something newer for THIS message is still in
+      // flight to repaint it. `> 1` = this frame plus at least one newer.
+      const dropGuard = (): boolean => mw.inflight > 1
+      // Cosmetic frames share ONE overshoot budget per chat across the
+      // per-message and per-chat tiers, so a frame cannot late-release twice on
+      // its way out.
+      const lateKey = cls === 'cosmetic' ? `lr:${chat}` : undefined
       try {
+        // R1 applies to the per-MESSAGE tier too. `supersede` mode still lets a
+        // genuinely-newer frame kill this one mid-wait (last-write-wins, the
+        // `killed` path), but at the DEFER DEADLINE this tier used to pass
+        // `dropGuard: undefined`, which `awaitRoom` reads as "drop
+        // unconditionally". A LONE frame — the terminal `finalize` of a card,
+        // whose whole job is to replace "→ in-progress" with the done state and
+        // which by definition has nothing newer coming — was therefore dropped
+        // here after `maxDeferMs`, freezing the card mid-step. That is the exact
+        // failure R1 was written to prevent; it was only ever wired into the two
+        // per-chat tiers. Passing the same guard makes a lone frame LATE-RELEASE
+        // instead, bounded for cosmetic traffic by the shared `lateKey`
+        // overshoot budget (non-cosmetic edits — finalize, approval cards — are
+        // low-cadence by nature and already late-release unbounded on both
+        // per-chat tiers, so this adds no new class of overshoot).
         const msgSlot = await awaitRoom(
           msgKey, perMessageWindowMs,
           cls === 'cosmetic'
             ? (t) => ceiling(cosmeticPerMessageMax, t)
             : (t) => classCeiling(perMessageMax, cls, t),
-          method, 'supersede', cls, undefined, deadline,
+          method, 'supersede', cls, dropGuard, deadline, lateKey,
         )
         if (msgSlot === null) return DROPPED_RESULT as unknown as R
-        // R1: only drop while something newer for THIS message is still in
-        // flight to repaint it. `> 1` = this frame plus at least one newer.
-        const dropGuard = (): boolean => mw.inflight > 1
-        // Cosmetic frames share ONE overshoot budget per chat across both
-        // per-chat tiers, so a frame cannot late-release twice on its way out.
-        const lateKey = cls === 'cosmetic' ? `lr:${chat}` : undefined
         const reserved: Array<[string, number]> = [[msgKey, msgSlot]]
         const giveBack = (): void => { for (const [k, at] of reserved) unreserve(k, at) }
 

package/telegram-plugin/gateway/boot-beacon.ts

@@ -0,0 +1,364 @@
+/**
+ * Gateway boot beacon — write-only forensic evidence for the NEXT boot.
+ *
+ * The problem this exists to feed
+ * ------------------------------
+ * When an agent's container dies, the next boot cannot tell WHY. Every open
+ * turn that isn't classified as a hang is blanket-stamped `ended_via='restart'`
+ * (`registry/turns-schema.ts` `sweepOpenTurns`), so an OOM kill, a bare
+ * SIGKILL, an operator restart and a host power loss are indistinguishable —
+ * and the user gets told "the hang-watchdog killed it" for what was actually a
+ * power cut.
+ *
+ * NOTHING READS THIS BEACON YET. This module is deliberately write-only: it
+ * lays down the evidence a later classifier will read, so that the classifier
+ * lands with real historical data behind it instead of shipping blind. Keeping
+ * the write and the read in separate changes also means this one carries zero
+ * behaviour risk — there is no decision anywhere in the tree that depends on it.
+ *
+ * What each field will later discriminate
+ * ---------------------------------------
+ *   bootId       Fresh UUID per gateway PROCESS. A beacon whose bootId differs
+ *                from ours proves the file was written by a previous process
+ *                (i.e. it is genuinely evidence about a death, not our own
+ *                in-flight state).
+ *   hostBootId   `/proc/sys/kernel/random/boot_id` — regenerated by the kernel
+ *                on every host boot. THE load-bearing field: at next boot, an
+ *                UNCHANGED host boot_id plus a missing clean-shutdown marker
+ *                means OUR process died (SIGKILL/OOM/crash) on a host that kept
+ *                running; a CHANGED boot_id means the HOST rebooted (power loss,
+ *                kernel panic, hypervisor stop). It is the only clean
+ *                discriminator between those two.
+ *   pid          Distinguishes "same process still alive" from a respawn when
+ *                bootId alone is ambiguous (e.g. a beacon restored from a
+ *                snapshot).
+ *   wallMs       Last-known-alive wall clock. Bounds the time of death to
+ *                within one beacon interval.
+ *   monotonicMs  Monotonic ms since process start. Compared against the wallMs
+ *                delta, a divergence reveals a wall-clock jump (NTP step, host
+ *                suspend/resume) rather than a real elapsed gap.
+ *   oomKillCount The cgroup v2 `oom_kill` counter, SAMPLED LIVE. See below.
+ *   memCurrent   `/sys/fs/cgroup/memory.current` at the last sample — how close
+ *                to the limit we were moments before death.
+ *   memMax       `/sys/fs/cgroup/memory.max`; the literal string `'max'` when
+ *                the cgroup is unlimited (a real, distinct state from "could
+ *                not read", which omits the field entirely).
+ *
+ * Why oomKillCount MUST be sampled live rather than read at boot
+ * -------------------------------------------------------------
+ * The cgroup `oom_kill` counter resets when the cgroup is recreated, which is
+ * exactly what happens when a container restarts. Read cold at boot it is
+ * therefore always 0 and carries no information. Sampled by the LIVE gateway
+ * into this beacon and compared against the PRIOR beacon, an increment is
+ * direct proof of an OOM kill — including the case that is otherwise invisible,
+ * where a child process (the `claude` process) is OOM-killed while PID 1
+ * survives and the container never restarts at all.
+ *
+ * Degradation contract (hard requirement)
+ * ---------------------------------------
+ * Every `/proc` and cgroup read is individually try/catch'd and each field is
+ * independently optional. A cgroup v1 host, a kernel without
+ * `random/boot_id`, a read-only or namespaced `/sys`, a permission error, a
+ * truncated file — all degrade to OMITTING that one field. This module must
+ * NEVER throw into the gateway tick: a crash here would take down every agent
+ * in the fleet on rollout.
+ */
+
+import { randomUUID } from 'node:crypto'
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+/** Filename under `TELEGRAM_STATE_DIR`. */
+export const BOOT_BEACON_FILE = 'gateway-beacon.json'
+
+/** How often the live gateway refreshes the beacon. 5s is the accepted
+ *  loss window: the beacon bounds the time of death to within one interval,
+ *  and a sub-5s cadence buys resolution nobody consumes. */
+export const BOOT_BEACON_INTERVAL_MS = 5_000
+
+export const HOST_BOOT_ID_PATH = '/proc/sys/kernel/random/boot_id'
+export const CGROUP_MEMORY_EVENTS_PATH = '/sys/fs/cgroup/memory.events'
+export const CGROUP_MEMORY_CURRENT_PATH = '/sys/fs/cgroup/memory.current'
+export const CGROUP_MEMORY_MAX_PATH = '/sys/fs/cgroup/memory.max'
+
+/** Defensive cap on how much of a `/proc`/cgroup value we keep. These files are
+ *  tens of bytes; anything larger is a host we don't understand and we'd rather
+ *  drop the field than serialise junk into the beacon. */
+const MAX_FIELD_CHARS = 256
+
+export interface BootBeacon {
+  /** Fresh UUID per gateway process. Always present. */
+  bootId: string
+  /** `/proc/sys/kernel/random/boot_id`. Omitted when unreadable. */
+  hostBootId?: string
+  /** Gateway process pid. Always present. */
+  pid: number
+  /** `Date.now()` at sample time. Always present. */
+  wallMs: number
+  /** Monotonic ms since process start. Always present. */
+  monotonicMs: number
+  /** cgroup v2 `oom_kill` counter. Omitted when unreadable. */
+  oomKillCount?: number
+  /** `/sys/fs/cgroup/memory.current` in bytes. Omitted when unreadable. */
+  memCurrent?: number
+  /** `/sys/fs/cgroup/memory.max` in bytes, or the literal `'max'` when the
+   *  cgroup is unlimited. Omitted when unreadable. */
+  memMax?: number | 'max'
+}
+
+/** The host/cgroup half of a beacon — every field independently optional. */
+export interface BeaconHostSample {
+  hostBootId?: string
+  oomKillCount?: number
+  memCurrent?: number
+  memMax?: number | 'max'
+}
+
+// ─── Pure parsers ─────────────────────────────────────────────────────────
+// Each takes the RAW file contents and returns `undefined` for anything it
+// can't confidently interpret. They never throw, so a malformed file degrades
+// to an omitted field rather than a crash.
+
+/**
+ * Parse `/proc/sys/kernel/random/boot_id`: a single UUID line. Anything that
+ * isn't a plausible non-empty single-line token is rejected, so a cgroup v1 /
+ * non-Linux host that somehow returns HTML or an empty file omits the field
+ * instead of poisoning the classifier's "did the host reboot?" comparison —
+ * the one question this field exists to answer.
+ */
+export function parseHostBootId(raw: string | null | undefined): string | undefined {
+  if (typeof raw !== 'string') return undefined
+  const trimmed = raw.trim()
+  if (trimmed.length === 0 || trimmed.length > MAX_FIELD_CHARS) return undefined
+  if (/\s/.test(trimmed)) return undefined
+  return trimmed
+}
+
+/**
+ * Parse the `oom_kill` counter out of cgroup v2 `memory.events`, which is a
+ * `key value` table:
+ *
+ *     low 0
+ *     high 0
+ *     max 0
+ *     oom 0
+ *     oom_kill 3
+ *     oom_group_kill 0
+ *
+ * Returns `undefined` when the key is absent (older kernels predate
+ * `oom_kill`) or the value isn't a non-negative integer. Deliberately reads
+ * `oom_kill`, NOT `oom`: `oom` counts times the cgroup hit its limit and
+ * entered OOM handling, which reclaim can resolve without killing anything;
+ * `oom_kill` counts processes actually killed, which is the event we need to
+ * attribute a death to.
+ */
+export function parseOomKillCount(raw: string | null | undefined): number | undefined {
+  if (typeof raw !== 'string') return undefined
+  for (const line of raw.split('\n')) {
+    const parts = line.trim().split(/\s+/)
+    if (parts.length !== 2 || parts[0] !== 'oom_kill') continue
+    return parseNonNegativeInt(parts[1])
+  }
+  return undefined
+}
+
+/**
+ * Parse a cgroup v2 byte-count file (`memory.current`). Returns `undefined`
+ * for empty, non-numeric, negative or non-integer contents.
+ */
+export function parseMemoryBytes(raw: string | null | undefined): number | undefined {
+  if (typeof raw !== 'string') return undefined
+  return parseNonNegativeInt(raw.trim())
+}
+
+/**
+ * Parse `memory.max`, which is either a byte count or the literal `max`
+ * meaning "no limit". `'max'` is returned as itself rather than folded to
+ * `undefined` so the later classifier can tell "unlimited cgroup, a
+ * limit-triggered OOM is impossible" apart from "we couldn't read the file".
+ */
+export function parseMemoryMax(raw: string | null | undefined): number | 'max' | undefined {
+  if (typeof raw !== 'string') return undefined
+  const trimmed = raw.trim()
+  if (trimmed === 'max') return 'max'
+  return parseNonNegativeInt(trimmed)
+}
+
+function parseNonNegativeInt(text: string | undefined): number | undefined {
+  if (typeof text !== 'string') return undefined
+  const trimmed = text.trim()
+  if (trimmed.length === 0 || trimmed.length > MAX_FIELD_CHARS) return undefined
+  if (!/^\d+$/.test(trimmed)) return undefined
+  const value = Number(trimmed)
+  return Number.isSafeInteger(value) ? value : undefined
+}
+
+// ─── Pure assembly + serialisation ────────────────────────────────────────
+
+/**
+ * Assemble a beacon from an already-taken host sample. Pure: no clock, no fs,
+ * no pid lookup — every input is an argument, so the exact bytes that hit disk
+ * are unit-testable. Optional sample fields are omitted from the object rather
+ * than emitted as `undefined`/`null`, keeping "absent" a single unambiguous
+ * shape for the future reader.
+ */
+export function buildBootBeacon(input: {
+  bootId: string
+  pid: number
+  wallMs: number
+  monotonicMs: number
+  sample?: BeaconHostSample
+}): BootBeacon {
+  const beacon: BootBeacon = {
+    bootId: input.bootId,
+    pid: input.pid,
+    wallMs: input.wallMs,
+    monotonicMs: input.monotonicMs,
+  }
+  const sample = input.sample ?? {}
+  if (sample.hostBootId !== undefined) beacon.hostBootId = sample.hostBootId
+  if (sample.oomKillCount !== undefined) beacon.oomKillCount = sample.oomKillCount
+  if (sample.memCurrent !== undefined) beacon.memCurrent = sample.memCurrent
+  if (sample.memMax !== undefined) beacon.memMax = sample.memMax
+  return beacon
+}
+
+/** Serialise to the exact bytes written to disk (single line + trailing \n). */
+export function serializeBootBeacon(beacon: BootBeacon): string {
+  return `${JSON.stringify(beacon)}\n`
+}
+
+// ─── Impure edges ─────────────────────────────────────────────────────────
+
+/** Read a small text file, returning `null` on ANY failure (missing, EACCES,
+ *  EIO, a directory, cgroup v1 layout, …). */
+function readTextOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Sample the host + cgroup v2 state. Every read is independently try/catch'd
+ * (via `readTextOrNull`) and every parse independently returns `undefined`, so
+ * a cgroup v1 host degrades to a beacon carrying only bootId/pid/wall/monotonic
+ * rather than throwing.
+ */
+export function sampleBeaconHost(paths: {
+  hostBootId?: string
+  memoryEvents?: string
+  memoryCurrent?: string
+  memoryMax?: string
+} = {}): BeaconHostSample {
+  const sample: BeaconHostSample = {}
+  const hostBootId = parseHostBootId(readTextOrNull(paths.hostBootId ?? HOST_BOOT_ID_PATH))
+  if (hostBootId !== undefined) sample.hostBootId = hostBootId
+  const oomKillCount = parseOomKillCount(readTextOrNull(paths.memoryEvents ?? CGROUP_MEMORY_EVENTS_PATH))
+  if (oomKillCount !== undefined) sample.oomKillCount = oomKillCount
+  const memCurrent = parseMemoryBytes(readTextOrNull(paths.memoryCurrent ?? CGROUP_MEMORY_CURRENT_PATH))
+  if (memCurrent !== undefined) sample.memCurrent = memCurrent
+  const memMax = parseMemoryMax(readTextOrNull(paths.memoryMax ?? CGROUP_MEMORY_MAX_PATH))
+  if (memMax !== undefined) sample.memMax = memMax
+  return sample
+}
+
+/**
+ * Durably write the beacon: tmp file → write → `fsync` → `rename`. The fsync
+ * is the point of the whole exercise — this file's only consumer is the boot
+ * AFTER a hard kill or a host power loss, so contents still sitting in the page
+ * cache at power-off would be exactly the evidence we lose in the case we most
+ * need it. `rename` over the same directory is atomic, so a reader can never
+ * observe a torn beacon.
+ *
+ * (We do not additionally fsync the containing directory. That would harden the
+ * rename's own durability, but the beacon is refreshed every 5s and losing the
+ * final rename costs at most one interval of resolution — the same loss window
+ * we already accept.)
+ *
+ * Returns true when the beacon landed. Never throws.
+ */
+export function writeBootBeaconFile(stateDir: string, beacon: BootBeacon): boolean {
+  const path = join(stateDir, BOOT_BEACON_FILE)
+  const tmp = `${path}.tmp-${process.pid}`
+  let fd: number | undefined
+  try {
+    // mode 0o700 matters: STATE_DIR also holds access.json / .env, and the
+    // gateway creates it 0o700 at boot. If it were ever missing here, a
+    // default-mode recreate by this 5s tick would silently loosen the
+    // permissions on that whole directory.
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+    fd = openSync(tmp, 'w', 0o600)
+    // writeFileSync (not writeSync) on the fd: it loops internally, so a short
+    // write can't leave a truncated beacon that we then fsync and rename into
+    // place as if it were whole.
+    writeFileSync(fd, serializeBootBeacon(beacon))
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+    renameSync(tmp, path)
+    return true
+  } catch {
+    if (fd !== undefined) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+    try { unlinkSync(tmp) } catch { /* best effort — tmp may not exist */ }
+    return false
+  }
+}
+
+/** This gateway process's boot id. Stable for the process lifetime; a change
+ *  across two beacons proves a respawn happened between them. */
+export const GATEWAY_BOOT_ID = randomUUID()
+
+/**
+ * Take one sample and write it. Safe to call from a shared gateway tick: it
+ * swallows every failure and returns false rather than letting anything escape
+ * into a `setInterval` callback (which would reach `uncaughtException`).
+ */
+export function tickBootBeacon(stateDir: string, bootId: string = GATEWAY_BOOT_ID): boolean {
+  try {
+    return writeBootBeaconFile(stateDir, buildBootBeacon({
+      bootId,
+      pid: process.pid,
+      wallMs: Date.now(),
+      monotonicMs: Math.round(performance.now()),
+      sample: sampleBeaconHost(),
+    }))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Attach the beacon to an EXISTING gateway tick rather than starting a second
+ * timer. Writes one beacon immediately (so a gateway that dies inside the first
+ * interval still leaves a record of which host boot it was living on), and
+ * returns a tick function that writes the beacon and then runs `next`.
+ *
+ * The beacon is written BEFORE `next` so a throw from the host tick's own work
+ * can never starve the forensic write — and this wrapper deliberately does not
+ * catch on `next`'s behalf: swallowing the host tick's errors would change
+ * existing behaviour, which is exactly what this write-only change must not do.
+ *
+ * Composed here rather than inline in `gateway.ts` so the wiring is one call
+ * site in that file (#2996 anti-inflation ratchet) and so this shape is
+ * unit-testable without booting the gateway module.
+ */
+export function attachBootBeacon(stateDir: string, next: () => void): () => void {
+  tickBootBeacon(stateDir)
+  return () => {
+    tickBootBeacon(stateDir)
+    next()
+  }
+}

package/telegram-plugin/gateway/boot-sweep-gate.ts

@@ -1,3 +1,6 @@
+import type { SweepTarget } from './stale-pin-sweep.js'
+import { sweepTargetKey } from './stale-pin-sweep-store.js'
+
 /**
  * boot-sweep-gate.ts — control flow for the boot pin sweep (#3664): WHEN it may
  * start (`createBootSweepGate`, the two-condition arming gate) and HOW its steps
@@ -5,7 +8,7 @@
  *
  * Why this exists
  * ---------------
- * The boot orphan sweep (`runBootPinCleanupAndDmSweep` → `statusPinBootCleanup`
+ * The boot orphan sweep (`runBootPinCleanupAndStalePinSweep` → `statusPinBootCleanup`
  * → `unpinChatMessage`) has TWO independent preconditions, and they are
  * satisfied at two different points of the gateway's boot:
  *
@@ -91,16 +94,16 @@ export function createBootSweepGate(args: {
 /** Dependencies of {@link runBootPinSweepSteps}. All side effects are injected
  *  so the sequencing contract is provable without a gateway. */
 export interface BootPinSweepSteps {
-  /** Pure fs scan for DM chat ids with a prior-session pin record. MUST run
-   *  BEFORE the reapers, which empty those same stores. */
-  scanDmChatIds: () => string[]
+  /** Pure fs scan for the `(chat, thread)` targets with a prior-session pin
+   *  record. MUST run BEFORE the reapers, which empty those same stores. */
+  scanSweepTargets: () => SweepTarget[]
   statusPinCleanup: () => Promise<unknown>
   activityCardReaper: () => Promise<unknown>
   queuedCardReaper: () => Promise<unknown>
-  /** Flips the flag authorising the DM unpin-all path — for this sweep AND for
+  /** Flips the flag authorising the stale-pin drain — for this sweep AND for
    *  later lazy first-inbound sweeps. */
-  enableDmSweep: () => void
-  sweepDm: (chatId: string) => Promise<unknown>
+  enableSweep: () => void
+  sweepTarget: (target: SweepTarget) => Promise<unknown>
   log?: (line: string) => void
 }
 
@@ -133,9 +136,9 @@ async function step(name: string, fn: () => Promise<unknown>, log: (line: string
  * bare sequential `await` chain. `runStatusPinBootCleanup` absorbs its own
  * per-row throws, but the two card reapers issue real Bot API calls and can
  * reject outright — and a rejection there did not merely skip the later
- * reapers, it skipped `enableDmSweep()`. That flag authorises the DM
- * unpin-all path for the WHOLE SESSION (the boot sweep AND every later lazy
- * first-inbound sweep), so one throwing reaper silently disabled DM stale-pin
+ * reapers, it skipped `enableSweep()`. That flag authorises the stale-pin
+ * drain for the WHOLE SESSION (the boot sweep AND every later lazy
+ * first-inbound sweep), so one throwing reaper silently disabled stale-pin
  * cleanup entirely.
  *
  * That was unreachable before #3664 only because the sweep never actually ran
@@ -149,9 +152,9 @@ async function step(name: string, fn: () => Promise<unknown>, log: (line: string
 export async function runBootPinSweepSteps(deps: BootPinSweepSteps): Promise<void> {
   const log = deps.log ?? ((l: string) => process.stderr.write(l))
 
-  let dmChatIds: string[] = []
-  await step('dm-chat-scan', async () => {
-    dmChatIds = deps.scanDmChatIds()
+  let targets: SweepTarget[] = []
+  await step('sweep-target-scan', async () => {
+    targets = deps.scanSweepTargets()
   }, log)
 
   await step('status-pin-cleanup', deps.statusPinCleanup, log)
@@ -159,6 +162,8 @@ export async function runBootPinSweepSteps(deps: BootPinSweepSteps): Promise<voi
   await step('queued-card-reaper', deps.queuedCardReaper, log)
 
   // Unconditional: reached even when every step above threw. See the docblock.
-  await step('enable-dm-sweep', async () => deps.enableDmSweep(), log)
-  for (const id of dmChatIds) await step(`dm-sweep:${id}`, () => deps.sweepDm(id), log)
+  await step('enable-sweep', async () => deps.enableSweep(), log)
+  for (const t of targets) {
+    await step(`stale-pin-sweep:${sweepTargetKey(t.chatId, t.threadId)}`, () => deps.sweepTarget(t), log)
+  }
 }