switchroom 0.19.22 → 0.19.24

package/telegram-plugin/tests/stream-controller-send-gate.test.ts

@@ -16,12 +16,16 @@
  *     collapse; the latest snapshot lands floor-paced
  *   - the floor is per-message (stream A does not delay stream B)
  *   - the gate's no-op skip drops a repeat payload for the same message
- *   - an open flood window sheds draft edits with ZERO API calls, and the
- *     stream recovers with full state after the window closes
- *   - a shed draft is NOT recorded as delivered — a later flush of the
- *     SAME text (the completed answer) still lands
+ *   - an open flood window COALESCES draft edits with ZERO API calls, and the
+ *     newest state lands once the window closes (#3716 — cosmetic edits are
+ *     never shed; the last edit of a burst is the one still on screen, so
+ *     dropping it stranded the message on a stale body)
+ *   - a draft held through a window still renders the completed answer — a
+ *     later flush of the SAME text is then a benign no-op, not a loss
  *   - the finalize flush is `critical`: never shed; waits out a short
  *     window; fails fast (structured, logged) on a long one
+ *   - shed-honesty (F2+F3) remains wired for any `SEND_GATE_SHED` the retry
+ *     policy does return, pinned directly rather than through the gate
  *   - regression pin: the controller passes messageId / editPayload /
  *     priorityClass through the retry policy on every edit
  *
@@ -32,7 +36,7 @@
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { createStreamController, type RetryPolicy } from '../stream-controller.js'
-import { createSendGate, type Clock, type SendGateConfig } from '../send-gate.js'
+import { createSendGate, SEND_GATE_SHED, type Clock, type SendGateConfig } from '../send-gate.js'
 import { isFloodWaitActiveError } from '../retry-api-call.js'
 import { renderOutboundChunks } from '../render/rich-render.js'
 import { createMockBot, installBotResetHook } from './bot-api.harness.js'
@@ -221,7 +225,7 @@ describe('stream-controller × send gate (#3110)', () => {
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
   })
 
-  it('open flood window: draft edits shed with ZERO API calls; full state lands after it closes', async () => {
+  it('open flood window: draft edits COALESCE with ZERO API calls; newest state lands after it closes (#3716)', async () => {
     const { clock, gate, retry } = makeGatedRetry({ editFloorMs: 1500 })
     const stream = createStreamController({
       bot, chatId: '1', throttleMs: 250, retry, initialMessageId: 7777,
@@ -233,17 +237,24 @@ describe('stream-controller × send gate (#3110)', () => {
     await flush()
     void stream.update('draft b')
     await tick()
-    // Both drafts shed as cosmetic — nothing reached the API.
+    // Flood safety is unchanged — still ZERO API calls while the window is
+    // open. What changed is the mechanism: the drafts are HELD (last-write-
+    // wins), not discarded, so no state is lost.
     expect(bot.api.editMessageText).not.toHaveBeenCalled()
-    expect(gate.stats().global.shed).toBe(2)
+    expect(gate.stats().global.shed).toBe(0)
 
-    await clock.advance(30_000) // window closes
+    await clock.advance(30_000) // window closes → the held draft lands
     void stream.update('draft c — full state')
     await tick()
-    expect(editBodies()).toEqual(['draft c — full state'])
+    await clock.advance(1_500) // clear the per-message edit floor
+
+    // The guarantee is the newest state reaches the screen, never that some
+    // intermediate was dropped to get there.
+    expect(editBodies().at(-1)).toBe('draft c — full state')
+    expect(gate.stats().global.shed).toBe(0)
   })
 
-  it('a shed draft is NOT recorded as delivered: a later finalize of the SAME text still lands', async () => {
+  it('a draft held through a window still renders: the completed answer reaches the screen exactly once', async () => {
     const { clock, gate, retry } = makeGatedRetry({ editFloorMs: 1500 })
     const stream = createStreamController({
       bot, chatId: '1', throttleMs: 250, retry, initialMessageId: 7777,
@@ -253,12 +264,16 @@ describe('stream-controller × send gate (#3110)', () => {
     void stream.update('the completed answer')
     await flush()
     expect(bot.api.editMessageText).not.toHaveBeenCalled()
-    expect(gate.stats().global.shed).toBe(1)
+    expect(gate.stats().global.shed).toBe(0)
 
-    await clock.advance(30_000)
-    // stream_reply done=true with the same text → finalize(text). If the shed
-    // draft had been recorded as on-screen, draft-stream's dedupe would skip
-    // this flush and the completed answer would never render.
+    await clock.advance(30_000) // window closes → the held draft lands
+
+    // stream_reply done=true with the same text → finalize(text). Pre-#3716
+    // the draft was SHED here, and the guarantee was that the stream must not
+    // record it as on-screen so this flush could re-deliver it. Now the draft
+    // is never dropped, so it renders on its own and the identical finalize is
+    // a benign no-op. Either way the user sees the completed answer — and now
+    // it costs one API call instead of two.
     await stream.finalize('the completed answer')
     expect(editBodies()).toEqual(['the completed answer'])
   })
@@ -277,7 +292,7 @@ describe('stream-controller × send gate (#3110)', () => {
     gate.openFloodWindow('global', clock.now() + 30_000) // short: <= 60s fail-fast ceiling
     void stream.update('draft while banned')
     await flush()
-    expect(bot.api.editMessageText).not.toHaveBeenCalled() // draft shed
+    expect(bot.api.editMessageText).not.toHaveBeenCalled() // draft held, not sent
 
     const fin = stream.finalize('the answer')
     await flush()
@@ -286,9 +301,12 @@ describe('stream-controller × send gate (#3110)', () => {
 
     await clock.advance(30_000)
     await fin
+    // The critical finalize coalesced ONTO the held draft and upgraded its
+    // class, so the whole burst resolves as a single send carrying the final
+    // body — the draft is superseded rather than dropped.
     expect(editBodies()).toEqual(['the answer'])
     expect(editTimes).toEqual([30_000])
-    expect(gate.stats().global.shed).toBe(1) // only the draft
+    expect(gate.stats().global.shed).toBe(0) // nothing is shed any more
   })
 
   it('finalize under a LONG window fails fast (structured FLOOD_WAIT_ACTIVE, logged) — no API call, no hang', async () => {
@@ -316,6 +334,40 @@ describe('stream-controller × send gate (#3110)', () => {
     }
   })
 
+  /**
+   * REGRESSION PIN for the trap #3716 opened. Once cosmetic edits stopped
+   * shedding they began OCCUPYING the driver, and draft-stream serializes its
+   * own flushes — so a draft parked behind a 6h ban held the finalize upstream
+   * of the gate, where the fail-fast path could never see it. `failedFast` went
+   * to 0 and the reply path wedged for the length of the ban: the exact failure
+   * the gate was built to eliminate, reintroduced by the fix for a different
+   * one. The preceding test does NOT catch this — it finalizes with no draft in
+   * flight.
+   */
+  it('a draft parked behind a LONG window never wedges the finalize behind it (#3716)', async () => {
+    const { clock, gate, retry } = makeGatedRetry({ editFloorMs: 1500 })
+    const logs: string[] = []
+    const stream = createStreamController({
+      bot, chatId: '1', throttleMs: 250, retry, initialMessageId: 7777,
+      log: (m) => logs.push(m),
+    })
+
+    gate.openFloodWindow('global', clock.now() + 21_397_000) // the 2026-07-12 ban: ~5.9h
+    void stream.update('draft while banned')
+    await flush()
+    expect(gate.stats().global.shed).toBe(0) // held, not dropped
+
+    // The cosmetic draft settles its caller as soon as it is queued, so the
+    // finalize reaches the gate. If it did not, this await never returns.
+    const fin = stream.finalize('the answer')
+    await tick()
+    await fin
+
+    expect(gate.stats().global.failedFast).toBe(1)
+    expect(bot.api.editMessageText).not.toHaveBeenCalled()
+    expect(logs.some((m) => m.includes('FLOOD_WAIT_ACTIVE'))).toBe(true)
+  })
+
   it('REGRESSION PIN: every edit passes messageId / editPayload / priorityClass to the retry policy', async () => {
     // Spy retry with NO gate — pins exactly what the controller hands to
     // robustApiCall (the #3110 bypass was these fields being absent).
@@ -474,7 +526,7 @@ describe('stream-controller × send gate (#3110)', () => {
     expect(bot.api.editMessageText.mock.calls.length).toBe(editCalls)
   })
 
-  it('a shed TAIL is not recorded as delivered: argument-less finalize() re-flushes and lands it (F2+F3)', async () => {
+  it('a TAIL suppressed by a msg-scoped window is HELD, not lost: the completed answer lands when it closes', async () => {
     const { clock, gate, retry } = makeGatedRetry({
       editFloorMs: 1500,
       globalPerSec: 1000, globalBurst: 100, perChatPerSec: 1000, perChatBurst: 100,
@@ -495,27 +547,81 @@ describe('stream-controller × send gate (#3110)', () => {
     const lastTailId = anchorId + pieceCount - 1
 
     // Flood window scoped to the LAST tail message only (H1 msg-edit scope):
-    // its edit sheds; the anchor and other pieces are unaffected.
+    // its edit is suppressed; the anchor and other pieces are unaffected.
     gate.openFloodWindow(`msg-edit:1:${lastTailId}`, clock.now() + 30_000)
 
     void stream.update(b2)
     await tick()
-    // The changed piece is the suppressed tail → shed, zero edits landed on
-    // it; the flush is reported shed and the snapshot preserved (F2), NOT
-    // recorded as delivered (F3).
+    // The changed piece is the suppressed tail → zero edits land on it while
+    // the window is open. Pre-#3716 it was SHED and the completed answer only
+    // survived because the stream refused to record it as delivered; now the
+    // edit is held by the gate, so the content is safe by construction.
     const tailEdits = () =>
       bot.api.editMessageText.mock.calls.filter(([, id]) => id === lastTailId)
     expect(tailEdits()).toHaveLength(0)
-    expect(gate.stats().global.shed).toBe(1)
-    expect(logs.some((m) => m.includes('shed by send gate'))).toBe(true)
+    expect(gate.stats().global.shed).toBe(0)
+    expect(logs.some((m) => m.includes('shed by send gate'))).toBe(false)
 
-    // Window closes; the gateway-style ARGUMENT-LESS finalize (the
-    // disconnect-flush / turn-end cleanup path) must re-deliver the shed
-    // snapshot — pre-F2 the content was silently lost here.
+    // Window closes → the held tail edit lands on its own. The gateway-style
+    // ARGUMENT-LESS finalize (disconnect-flush / turn-end cleanup) is then a
+    // no-op rather than a rescue.
     await clock.advance(31_000)
     await stream.finalize()
     expect(tailEdits()).toHaveLength(1)
     const [, , tailBody] = tailEdits()[0]
     expect(String(tailBody)).toContain('tail v2')
   })
+
+  /**
+   * #3716 removed the gate's cosmetic-EDIT shed, so no edit the stream makes
+   * can return `SEND_GATE_SHED` any more. The sentinel is still the contract
+   * for non-edit cosmetic sends, and the controller's F2/F3 shed-honesty
+   * handling is the guard if any edit path is ever re-tagged — so pin it
+   * directly against the retry seam instead of through the gate, where it
+   * would silently rot into an assertion about behaviour that cannot occur.
+   */
+  it('F2+F3 shed-honesty is still wired: a SHED tail is not recorded as delivered and re-flushes', async () => {
+    const base = ('a_b_c_d_e ').repeat(3000)
+    const b1 = `${base}tail v1`
+    const b2 = `${base}tail v2 — the completed answer`
+    const pieceCount = renderOutboundChunks(b1).length
+    expect(pieceCount).toBeGreaterThan(1)
+
+    // Shed exactly one message id, chosen after the first flush assigns ids.
+    let shedId: number | null = null
+    const retry: RetryPolicy = async (fn, opts) => {
+      if (shedId != null && opts?.messageId === shedId) {
+        return SEND_GATE_SHED as never
+      }
+      return await fn()
+    }
+
+    const logs: string[] = []
+    const stream = createStreamController({
+      bot, chatId: '1', throttleMs: 250, retry, log: (m) => logs.push(m),
+    })
+    void stream.update(b1)
+    await flush()
+    const anchorId = stream.getMessageId() as number
+    shedId = anchorId + pieceCount - 1
+
+    const tailEdits = () =>
+      bot.api.editMessageText.mock.calls.filter(([, id]) => id === shedId)
+
+    void stream.update(b2)
+    await tick()
+    expect(tailEdits()).toHaveLength(0)
+    expect(logs.some((m) => m.includes('shed by send gate'))).toBe(true)
+
+    // The shed piece must NOT have been recorded as on screen: an
+    // argument-less finalize re-delivers the preserved snapshot.
+    shedId = null
+    await stream.finalize()
+    const landed = bot.api.editMessageText.mock.calls.filter(
+      ([, id]) => id === anchorId + pieceCount - 1,
+    )
+    expect(landed).toHaveLength(1)
+    const [, , tailBody] = landed[0]
+    expect(String(tailBody)).toContain('tail v2')
+  })
 })

package/telegram-plugin/tests/stream-render-golden.test.ts

@@ -39,6 +39,28 @@ import {
   TYPING_REFRESH_MS,
 } from '../typing-emitter.js'
 import type { CurrentTurn } from '../gateway/gateway.js'
+import type { ReplyOwnerTier } from '../reply-owner-resolve.js'
+
+/** The owner-resolution shape `resolveReplyOwnerTurn` returns, including the
+ *  candidate set the content-gate bypass corroborates against. These fixtures
+ *  never exercise the supersede path, so the candidates mirror the resolved turn
+ *  (the corroborated shape) with no override needed. */
+function ownerRes(turn: CurrentTurn | null, tier: ReplyOwnerTier) {
+  const id = turn?.turnId ?? null
+  return {
+    turn,
+    tier,
+    candidates: {
+      liveTurnId: tier === 'live' ? id : null,
+      originTurnId: null,
+      quotedTurnId: null,
+      latestEndedTurnId: id,
+      latestEndedAgeMs: 1_000,
+      latestEndedTtlMs: 60_000,
+    },
+  }
+}
+
 
 const CHAT = '1001'
 
@@ -251,7 +273,7 @@ function makeSendReplyDeps(dedup: OutboundDedupCache, sharedSupersede?: FlushedT
     assertSendable: () => {},
     statusKey: key,
     streamKey: key,
-    resolveReplyOwnerTurn: () => ({ turn: null, tier: 'none' as const }),
+    resolveReplyOwnerTurn: () => ownerRes(null, 'none'),
     getLastSubagentHandbackAt: () => null,
     findTurnByOriginId: () => null,
     findTurnByQuotedMessageId: () => null,
@@ -443,7 +465,7 @@ describe('F3 — flush record() → same-turn reworded reply collapse (end-to-en
     // The model's REAL reply lands late with a REWORDED version of the same
     // answer: no live turn, latest-ended tier, NO handback in flight (CASE A).
     const s = makeSendReplyDeps(new OutboundDedupCache(), supersede)
-    s.deps.resolveReplyOwnerTurn = () => ({ turn, tier: 'latest-ended' as const })
+    s.deps.resolveReplyOwnerTurn = () => ownerRes(turn, 'latest-ended')
     // (getLastSubagentHandbackAt returns null in the base deps → own answer.)
 
     const res = await sendReply(s.deps, req(REWORDED))
@@ -496,7 +518,7 @@ describe('F5 — take()-before-record() interleaving delivers exactly one messag
     ).toBe('no-record') // record genuinely not written yet
 
     const s = makeSendReplyDeps(new OutboundDedupCache(), supersede)
-    s.deps.resolveReplyOwnerTurn = () => ({ turn, tier: 'latest-ended' as const })
+    s.deps.resolveReplyOwnerTurn = () => ownerRes(turn, 'latest-ended')
     // The same answer landing again in the race window → latch backstop suppresses.
     const res = await sendReply(s.deps, req(ANSWER))
 

package/telegram-plugin/tests/turns-jsonl-rotate.test.ts

@@ -1,6 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import { describe, expect, it, vi } from 'vitest'
 
-import { maybeRotate, TURNS_JSONL_MAX_BYTES, type RotateFs } from '../gateway/turns-jsonl-rotate.js'
+import {
+  maybeRotate,
+  resolveAgentStateDir,
+  resolveTurnsJsonlPath,
+  DEFAULT_AGENT_STATE_DIR,
+  TURNS_JSONL_MAX_BYTES,
+  type RotateFs,
+} from '../gateway/turns-jsonl-rotate.js'
+
+const GATEWAY_SRC = readFileSync(
+  resolve(fileURLToPath(new URL('.', import.meta.url)), '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
 
 describe('maybeRotate — turns.jsonl size cap', () => {
   const mkFs = (size: number | undefined) => {
@@ -37,3 +53,78 @@ describe('maybeRotate — turns.jsonl size cap', () => {
     expect(rename).toHaveBeenNthCalledWith(2, '/a/turns.jsonl', '/a/turns.jsonl.1')
   })
 })
+
+describe('resolveTurnsJsonlPath — the turn record must follow the state dir', () => {
+  // Regression: the path was hard-coded to `/state/agent/turns.jsonl`, so a test
+  // that isolated TELEGRAM_STATE_DIR / SWITCHROOM_AGENT_STATE_DIR into a tmpdir
+  // still appended its synthetic turn rows into the PRODUCTION turn record of
+  // whichever agent container it ran in — which the fleet-health L0 sensor then
+  // scored as that agent's real production failures.
+  it('honours SWITCHROOM_AGENT_STATE_DIR', () => {
+    expect(resolveTurnsJsonlPath({ SWITCHROOM_AGENT_STATE_DIR: '/tmp/iso-123' })).toBe(
+      '/tmp/iso-123/turns.jsonl',
+    )
+  })
+
+  it('strips a trailing slash rather than doubling it', () => {
+    expect(resolveTurnsJsonlPath({ SWITCHROOM_AGENT_STATE_DIR: '/tmp/iso-123/' })).toBe(
+      '/tmp/iso-123/turns.jsonl',
+    )
+  })
+
+  it('falls back to the container default when unset or blank', () => {
+    expect(resolveTurnsJsonlPath({})).toBe(`${DEFAULT_AGENT_STATE_DIR}/turns.jsonl`)
+    expect(resolveTurnsJsonlPath({ SWITCHROOM_AGENT_STATE_DIR: '   ' })).toBe(
+      `${DEFAULT_AGENT_STATE_DIR}/turns.jsonl`,
+    )
+  })
+})
+
+describe('resolveAgentStateDir — ONE normaliser for every writer in the state dir', () => {
+  // The gateway had two writers into this dir 26 lines apart reading the env
+  // var two different ways: the turn record via the normaliser, the
+  // context-occupancy snapshot via a bare `process.env.X ?? '/state/agent'`.
+  // For a value like `/x/ ` those resolve to different directories, so the two
+  // artifacts of the same turn land in two places.
+  it('trims, strips a trailing slash, and treats blank as unset', () => {
+    expect(resolveAgentStateDir({ SWITCHROOM_AGENT_STATE_DIR: '/x' })).toBe('/x')
+    expect(resolveAgentStateDir({ SWITCHROOM_AGENT_STATE_DIR: '  /x/  ' })).toBe('/x')
+    expect(resolveAgentStateDir({ SWITCHROOM_AGENT_STATE_DIR: '/x///' })).toBe('/x')
+    expect(resolveAgentStateDir({ SWITCHROOM_AGENT_STATE_DIR: '  ' })).toBe(DEFAULT_AGENT_STATE_DIR)
+    expect(resolveAgentStateDir({})).toBe(DEFAULT_AGENT_STATE_DIR)
+  })
+
+  it('the turn record and the state dir agree for any messy value', () => {
+    const env = { SWITCHROOM_AGENT_STATE_DIR: ' /tmp/iso-9/ ' }
+    expect(resolveTurnsJsonlPath(env)).toBe(`${resolveAgentStateDir(env)}/turns.jsonl`)
+  })
+})
+
+describe('gateway.ts call sites — the defect site itself, not just the helper', () => {
+  // The bug was a hard-coded literal at the CALLSITE. A unit test of the pure
+  // helper passes with the literal re-inlined, so these read the real source.
+  // Source-text assertions are the repo's cheap deterministic pattern for
+  // pinning a callsite (see per-topic-current-turn.test.ts).
+  it('emitTurnRecord resolves the path — the hard-coded literal is gone', () => {
+    const body = GATEWAY_SRC.split('function emitTurnRecord(')[1]?.split('\n}')[0] ?? ''
+    expect(body.length).toBeGreaterThan(50)
+    expect(body).toMatch(/const turnsPath = resolveTurnsJsonlPath\(\)/)
+    // The append + the rotate both use the RESOLVED path, not a literal.
+    expect(body).toMatch(/appendFileSync\(turnsPath, /)
+    expect(body).toMatch(/maybeRotate\(turnsPath, /)
+    expect(body).not.toMatch(/turns\.jsonl/)
+  })
+
+  it('no hard-coded turns.jsonl path survives anywhere in gateway.ts', () => {
+    const hits = GATEWAY_SRC.match(/['"`][^'"`\n]*\/turns\.jsonl['"`]/g) ?? []
+    expect(hits, `hard-coded turns.jsonl path(s): ${JSON.stringify(hits)}`).toEqual([])
+  })
+
+  it('every state-dir read in gateway.ts goes through resolveAgentStateDir', () => {
+    // Consistency, not style: a second inline `process.env.X ?? '/state/agent'`
+    // silently opts that writer out of trim + trailing-slash normalisation.
+    const inline = GATEWAY_SRC.match(/process\.env\.SWITCHROOM_AGENT_STATE_DIR/g) ?? []
+    expect(inline, `inline state-dir read(s) in gateway.ts: ${inline.length}`).toEqual([])
+    expect(GATEWAY_SRC).toMatch(/resolveAgentStateDir\(\)/)
+  })
+})

package/vendor/hindsight-memory/scripts/drain_pending.py

@@ -5,8 +5,12 @@ SessionStart calls into ``drain()`` to retry any retain payloads that
 ``session_end.py`` queued on failure (#1071). Each entry is retried up
 to ``MAX_ATTEMPTS`` (5) times; after that a **permanently** failing entry
 (a 4xx that a re-POST cannot fix — see ``pending.is_permanent_failure``)
-is renamed to ``.dead`` so the queue no longer drains it but the operator
-can still inspect via ``switchroom doctor``. An entry failing on anything
+is retired into the ``pending-dead/`` archive so the queue no longer
+drains it but the operator can still inspect via ``switchroom doctor``.
+The marker deliberately does NOT stay in the live queue directory: it is
+the only remaining copy of that memory, and leaving it among the live
+entries put it in the path of every janitor that sweeps that
+directory. An entry failing on anything
 else — a 5xx, a timeout, a connection error — stays queued past the
 attempt budget: a transient upstream is never evidence that the memory
 is unsaveable, and retiring it would lose content the user believes was
@@ -53,8 +57,30 @@ of that loop, not of lost memory: a full sweep of 5,751 queued entries on
 this fleet (2026-07-25) found **4,048 (70.4%) already existed as
 documents**, 3,815 of them with facts extracted.
 
-``--backlog`` is therefore a two-phase, out-of-hook replay:
-
+``--backlog`` is therefore a three-phase, out-of-hook replay:
+
+* **Phase 0 — collapse duplicates (free, no network).** Queued entries
+  sharing ``(bank_id, part_position, sha256(content))`` are the same
+  memory; the redundant copies are archived so the phases below never pay
+  for one memory twice. Measured 2026-07-26: 1,060 queued files across 11
+  agents fell into ~368 distinct groups — ~65% of the queue was duplicate,
+  with one group repeated 32 times. At ~168 s per phase-2 extraction that
+  one group alone was 90 minutes of LLM lane time for a single memory.
+* **Phase 0b — relocate legacy ``.dead`` markers (free, no network).**
+  Markers written by an older build into the live queue directory are moved
+  into ``pending-dead/``. ``mark_dead`` no longer produces such a marker, so
+  after this phase has run once the live queue holds only live entries and no
+  janitor glob over it can match a memory. Note the CONDITION: phases 0b and
+  0c run in BACKLOG mode only (``drain_backlog``, and not under
+  ``--dry-run``). The SessionStart ``drain()`` never calls them, so on a host
+  where the backlog drain has not run, legacy markers are still sitting in
+  the queue directory.
+* **Phase 0c — re-split over-bound entries (free, no network).** An entry
+  whose content exceeds ``retain_content_limit()`` needs more sequential
+  extraction calls than fit the client deadline, so it can never be drained
+  as-is; splitting it makes every part drainable. Measured 2026-07-26: 18 of
+  211 queued entries exceeded 100,000 chars, the largest 744,546. Backlog
+  mode only, same as 0b.
 * **Phase 1 — reconcile (free).** GET the document. If it exists, the
   memory is already durable; retire the queue entry without a POST. No
   LLM work, no cost, idempotent, resumable at any point. Only for
@@ -84,7 +110,7 @@ reports the upstream is already slow.
 Standalone usage::
 
     python3 drain_pending.py               # bounded in-hook drain
-    python3 drain_pending.py --backlog     # two-phase backlog replay
+    python3 drain_pending.py --backlog     # three-phase backlog replay
     python3 drain_pending.py --backlog --phase reconcile   # free pass only
     python3 drain_pending.py --backlog --dry-run
 """
@@ -105,13 +131,16 @@ from lib.config import debug_log, load_config
 from lib.pending import (
     MAX_ATTEMPTS,
     archive_reconciled,
+    collapse_duplicates,
     is_content_derived_document_id,
     is_permanent_failure,
     iter_entries,
     mark_dead,
+    resplit_over_bound_entries,
+    sweep_legacy_dead_markers,
     update_attempt,
 )
-from lib.retain_split import retain_client_deadline
+from lib.retain_split import retain_client_deadline, retain_content_limit
 
 
 STALL_THRESHOLD = 3
@@ -531,17 +560,24 @@ def _new_summary() -> dict:
         # so it must not be counted as drained/reconciled, which would
         # report a retire that did not happen.
         "archive_failed": 0,
+        # Redundant copies retired by `pending.collapse_duplicates` before
+        # any network work. Backlog mode only — see `_drain_backlog_impl`.
+        "collapsed": 0,
+        "dead_relocated": 0,
+        "resplit": 0,
+        "resplit_parts": 0,
         "stalled": False,
         "budget_exceeded": False,
     }
 
 
 def drain_backlog(config: dict | None = None, **kw) -> dict:
-    """Two-phase backlog replay, off the SessionStart budget entirely.
+    """Three-phase backlog replay, off the SessionStart budget entirely.
 
     See the module docstring. Summary shape is ``drain()``'s plus
-    ``reconciled`` (already durable — no POST issued) and ``unknown``
-    (presence could not be established; left queued).
+    ``reconciled`` (already durable — no POST issued), ``unknown``
+    (presence could not be established; left queued) and ``collapsed``
+    (redundant duplicate copies archived before any network work).
     """
     return drain(config, backlog=True, **kw)
 
@@ -566,6 +602,10 @@ def drain(
          "unknown": int,   # presence unknown, left queued
          "archive_failed": int,  # durable, but the archive was unwritable
                                  # so the entry is STILL QUEUED
+         "collapsed": int, # duplicate copies archived (backlog mode only)
+         "dead_relocated": int,  # legacy .dead markers moved out of the queue dir
+         "resplit":   int, # over-bound entries split into drainable parts
+         "resplit_parts": int,  # parts those entries became
          "stalled": bool,  # stall guard tripped
          "budget_exceeded": bool}
     """
@@ -784,9 +824,65 @@ def _wait_for_upstream(backoff_ms: int, started: float, budget: float) -> bool:
 def _drain_backlog_impl(
     config: dict, phase: str = "both", dry_run: bool = False
 ) -> dict:
-    """Concurrent-capable, long-budget, two-phase backlog replay."""
+    """Concurrent-capable, long-budget, three-phase backlog replay."""
     summary = _new_summary()
 
+    # PHASE 0 — collapse duplicates (local, free, no network at all).
+    #
+    # Runs FIRST because every later phase is per-entry: a GET in phase 1
+    # and, worse, a ~168 s LLM-backed extraction in phase 2. On the measured
+    # 2026-07-26 fleet backlog ~65% of queued files were byte-identical
+    # copies of another queued file (top group 32x), so skipping this pass
+    # means paying phase 2 up to 32 times over for one memory.
+    #
+    # DELIBERATELY NOT run by the in-hook drain. It reads every queued entry
+    # to recompute identity from content — bounded, but not instant — and
+    # the SessionStart drain's whole contract is a hard wall-clock ceiling
+    # on hook latency. New duplicates cannot accumulate there anyway:
+    # `pending.enqueue`'s filename-keyed guard stops those at the producer.
+    if not dry_run:
+        summary["collapsed"] = collapse_duplicates()
+        if summary["collapsed"]:
+            _blog(
+                f"phase 0: collapsed {summary['collapsed']} duplicate entries "
+                f"(byte-identical content already queued under another entry); "
+                f"archived, not deleted"
+            )
+
+        # PHASE 0b — relocate any legacy `.dead` markers out of the live
+        # queue directory. Free, local, and an UPGRADE step: markers written
+        # by an older build sit in the directory external janitors sweep, and
+        # a marker is the only remaining copy of its memory.
+        moved = sweep_legacy_dead_markers()
+        if moved:
+            summary["dead_relocated"] = moved
+            _blog(
+                f"phase 0b: relocated {moved} legacy .dead marker(s) out of "
+                f"the live queue directory; the queue now holds only live "
+                f"entries, so no janitor glob over it can match a memory"
+            )
+
+        # PHASE 0c — re-split entries the drain provably CANNOT retain.
+        #
+        # An entry over `retain_content_limit()` needs more sequential
+        # extraction calls than fit the deadline, so every POST is guaranteed
+        # waste; if the server rejects the body as a 4xx it is classified
+        # permanent and the memory goes `.dead`. Splitting it makes every
+        # part drainable, which is the difference between a lost memory and a
+        # slow one. Runs after the duplicate collapse so a duplicated
+        # over-bound entry is split ONCE, not once per copy.
+        entries_split, parts_written = resplit_over_bound_entries()
+        if entries_split:
+            summary["resplit"] = entries_split
+            summary["resplit_parts"] = parts_written
+            _blog(
+                f"phase 0c: re-split {entries_split} entr"
+                f"{'y' if entries_split == 1 else 'ies'} over the "
+                f"{retain_content_limit()}-char retain bound into "
+                f"{parts_written} drainable part(s); the originals are "
+                f"archived, not deleted"
+            )
+
     if phase in ("reconcile", "both"):
         _reconcile_phase(config, summary, dry_run)
     if phase == "reconcile":
@@ -935,7 +1031,7 @@ def _parse_args(argv: list[str] | None):
     ap.add_argument(
         "--backlog",
         action="store_true",
-        help="two-phase backlog replay, off the SessionStart budget",
+        help="three-phase backlog replay, off the SessionStart budget",
     )
     ap.add_argument(
         "--phase",
@@ -967,6 +1063,9 @@ def main(argv: list[str] | None = None) -> int:
     if any(
         summary[k]
         for k in (
+            "collapsed",
+            "dead_relocated",
+            "resplit",
             "drained",
             "retried",
             "dead",
@@ -978,6 +1077,9 @@ def main(argv: list[str] | None = None) -> int:
         print(
             f"[Hindsight] drain_pending{'(backlog)' if args.backlog else ''}: "
             f"drained={summary['drained']} reconciled={summary['reconciled']} "
+            f"collapsed={summary['collapsed']} "
+            f"dead_relocated={summary['dead_relocated']} "
+            f"resplit={summary['resplit']}(+{summary['resplit_parts']} parts) "
             f"retried={summary['retried']} dead={summary['dead']} "
             f"unknown={summary['unknown']} "
             f"archive_failed={summary['archive_failed']} "