switchroom 0.19.39 → 0.19.41

package/telegram-plugin/dist/server.js

@@ -17627,6 +17627,14 @@ function projectTranscriptLine(line) {
       { kind: "turn_end", durationMs: obj.durationMs ?? 0 }
     ];
   }
+  if (type === "system" && obj.subtype === "compact_boundary") {
+    const meta = obj.compactMetadata;
+    return [{
+      kind: "compact_boundary",
+      trigger: typeof meta?.trigger === "string" ? meta.trigger : null,
+      compactDurationMs: typeof meta?.durationMs === "number" ? meta.durationMs : null
+    }];
+  }
   return [];
 }
 function projectSubagentLine(line, agentId, state) {
@@ -24999,7 +25007,7 @@ var init_bridge = __esm(async () => {
     },
     {
       name: "send_checklist",
-      description: 'Send a native Telegram checklist (interactive task list) to a chat. Users can tick tasks directly in the Telegram app. Returns the message_id of the created checklist. The bot is notified when tasks are ticked \u2014 these arrive as channel events with kind="checklist_task_changed". Limit: 30 tasks per checklist.',
+      description: 'Send a checklist (task list) to a chat. Native interactive Telegram checklists require a Business-account connection, which most deployments do not have \u2014 in that normal case the checklist is sent as a formatted TEXT message (bold title + \u2705/\u2b1c task lines) and the result carries degraded:"text": tasks are NOT tappable, and you tick them yourself via update_checklist (task ids are 1..N in send order). With a Business connection configured, the checklist is sent natively and tick events arrive as channel events with kind="checklist_task_changed". Returns JSON with message_id and mode. Limit: 30 tasks.',
       inputSchema: {
         type: "object",
         properties: {
@@ -25084,7 +25092,7 @@ var init_bridge = __esm(async () => {
     },
     {
       name: "update_checklist",
-      description: "Patch an existing native Telegram checklist. Supports updating the title, adding new tasks, removing tasks, or marking tasks done/undone. Tasks with an id target existing items; tasks without an id are appended. Preserves existing task ids across edits.",
+      description: `Patch a checklist previously sent with send_checklist: update the title, append tasks, or mark tasks done/undone. Tasks with an id target existing items (ids are 1..N in send order for text-mode checklists); tasks without an id are appended. Removal is not supported. The edit re-renders in the mode the checklist was sent in (text for most deployments). Returns JSON { ok, ... }; after a gateway restart the stored task state may be gone \u2014 then it returns ok:false with reason "unknown_checklist" unless you pass a full replacement (title + every task's text).`,
       inputSchema: {
         type: "object",
         properties: {

package/telegram-plugin/gateway/backstop-delivery.ts

@@ -322,6 +322,28 @@ export interface BackstopDeliveryDeps {
     messageIds: readonly number[],
     text: string,
   ) => Promise<ReadBackResult>
+  /**
+   * Exactly-once SEND-ACK claim (duplicate-message race fix). Fired EXACTLY ONCE,
+   * the first moment every chunk has landed a fresh non-card receipt — i.e. the
+   * same condition that makes {@link BackstopDeliveryResult.delivered} true — and
+   * crucially BEFORE the read-back probe (step 2 below) is awaited.
+   *
+   * Why before the probe: the probe is issued at COSMETIC priority and, when the
+   * edit-flood-fuse is deferring cosmetic edits, `await deps.readBack` can block
+   * ~30s. The caller's durable exactly-once claim (`journalExternalDelivery`)
+   * used to run only in its post-`await deliverAnswer` bookkeeping, i.e. AFTER
+   * that probe resolved. The out-of-band outbox sweep only waits `OUTBOX_QUIET_MS`
+   * (5s) before checking the delivered-keys journal, so during that 5–30s gap it
+   * saw no journal entry and sent a SECOND copy of the same answer. Claiming here,
+   * at send-ack, closes that window deterministically regardless of probe timing.
+   *
+   * A later `absent` read-back (positive silent-drop) is recovered by THIS
+   * orchestrator's own in-process re-send below — the nonce is NEVER reopened to
+   * the sweep, so a possibly-delivered answer is never handed to a second sender.
+   * `sentIds` is the landed fresh-receipt set at claim time. Best-effort; a throw
+   * is swallowed and never demotes the delivery.
+   */
+  onAckClaim?: (sentIds: number[]) => void
   /** Optional stderr sink for progress/resume logging. */
   stderr?: (s: string) => void
 }
@@ -406,6 +428,8 @@ export async function runBackstopDelivery(
   const stderr = deps.stderr ?? (() => {})
   const chunkCount = chunks.length
   let attempts = 0
+  // Fires the send-ack claim (see BackstopDeliveryDeps.onAckClaim) at most once.
+  let ackClaimed = false
 
   for (let attempt = 1; attempt <= Math.max(1, maxAttempts); attempt++) {
     attempts = attempt
@@ -437,6 +461,30 @@ export async function runBackstopDelivery(
       }
     }
 
+    // 1b. EXACTLY-ONCE SEND-ACK CLAIM (duplicate-message race fix). The instant
+    //     every chunk has landed a fresh non-card receipt, fire the caller's
+    //     claim — BEFORE the read-back probe below, which can be deferred ~30s
+    //     by the edit-flood-fuse (cosmetic priority). This is the same predicate
+    //     as the final `delivered` verdict (all-landed + fresh receipt); the only
+    //     way `delivered` can subsequently go false is a POSITIVE `absent` probe
+    //     demoting a chunk, which this orchestrator re-sends in-process (never
+    //     reopening the nonce to the out-of-band sweep). See onAckClaim.
+    if (!ackClaimed && deps.onAckClaim != null) {
+      const allLandedNow =
+        chunkCount > 0 && ledger.unsentIndices(turnId, chunkCount).length === 0
+      if (allLandedNow && backstopReceiptIds(ledger.sentIds(turnId), cardMessageId).length > 0) {
+        ackClaimed = true
+        try {
+          deps.onAckClaim(ledger.sentIds(turnId))
+        } catch (err) {
+          stderr(
+            `telegram gateway: backstop send-ack claim callback threw for turn ${turnId} ` +
+            `(non-fatal): ${err instanceof Error ? err.message : String(err)}\n`,
+          )
+        }
+      }
+    }
+
     // 2. CONFIRM landed-unconfirmed chunks via read-back (#3278). Without a probe
     //    wired, landing IS confirmation (pre-#3278) — the fresh-non-card receipt
     //    filter below still rejects a card-only "delivery".

package/telegram-plugin/gateway/checklist-fallback.ts

@@ -0,0 +1,370 @@
+/**
+ * Checklist send/update with graceful degradation.
+ *
+ * Telegram's native `sendChecklist` / `editMessageChecklist` (Bot API 9.1)
+ * are **Business-account-only**: both REQUIRE a `business_connection_id`,
+ * and the payload nests `title`/`tasks` inside a single `checklist` object
+ * (`InputChecklist`) whose tasks each carry a REQUIRED integer `id` and NO
+ * completion flag (`InputChecklistTask = { id, text }` — a native checklist
+ * cannot be pre-marked done). The original wrapper sent a FLAT
+ * `{ chat_id, title, tasks: [{ text, is_completed? }] }` payload, which
+ * Telegram rejected with `400: parameter "checklist" is required` — and even
+ * a well-formed payload fails for ordinary bot DMs/groups (no business
+ * connection), which is every chat this fleet uses.
+ *
+ * So the tool degrades gracefully instead of surfacing a raw 400:
+ *   1. If a business connection id is configured AND the Bot API supports
+ *      checklists → build the CORRECT native payload and send natively.
+ *   2. Otherwise (the normal case) → render the checklist as a formatted
+ *      text message (bold title + ✅/⬜ task lines — text CAN show the
+ *      `done` flag) and send via the normal message path. The tool result
+ *      carries `degraded: "text"` so the caller knows it is not interactive.
+ *   3. A failed native attempt falls back to text rather than erroring.
+ *
+ * Updates work against a per-message in-memory state store (the gateway has
+ * no other record of a text-rendered checklist's tasks): a patch is applied
+ * to the stored state and the message is edited (natively or as text to
+ * match how it was sent). State is process-local — after a gateway restart
+ * an update to a pre-restart checklist returns a graceful
+ * `unknown_checklist` result unless the patch itself carries a full
+ * replacement (title + all task texts), never a raw Telegram error.
+ *
+ * Pure/deps-injected so the orchestration is unit-testable without a bot
+ * (same pattern as checklist-message-handler.ts).
+ */
+
+export interface ChecklistTaskState {
+  /** 1-based sequential id assigned at send time (mirrors the native API's
+   *  required per-task integer id; doubles as the patch handle in text mode). */
+  id: number
+  text: string
+  done: boolean
+}
+
+export interface ChecklistState {
+  title: string
+  tasks: ChecklistTaskState[]
+  /** How the message was actually delivered — updates must match it. */
+  mode: 'native' | 'text'
+}
+
+export interface ChecklistPatchTask {
+  id?: string | number
+  text?: string
+  done?: boolean
+}
+
+export interface ChecklistPatch {
+  title?: string
+  tasks?: ChecklistPatchTask[]
+}
+
+export const CHECKLIST_MAX_TASKS = 30
+
+/** Assign sequential 1-based ids and normalize the `done` flag. */
+export function buildChecklistTasks(
+  tasks: ReadonlyArray<{ text: string; done?: boolean }>,
+): ChecklistTaskState[] {
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return tasks.map((t, i) => ({ id: i + 1, text: t.text, done: t.done === true }))
+}
+
+/**
+ * Render a checklist as a text message: title header + one ✅/⬜ line per
+ * task. Rich (default) output is GFM markdown for `richMessage()`; pass
+ * `literal: true` when the access config pins `parseMode: 'text'` (plain
+ * sends, no markdown parsing) so the title doesn't ship raw asterisks.
+ */
+export function renderChecklistText(
+  cl: { title: string; tasks: ReadonlyArray<{ text: string; done: boolean }> },
+  opts?: { literal?: boolean },
+): string {
+  const header = opts?.literal ? cl.title : `**${cl.title}**`
+  const lines = cl.tasks.map((t) => `${t.done ? '✅' : '⬜'} ${t.text}`)
+  return [header, ...lines].join('\n')
+}
+
+/**
+ * Apply an update_checklist patch: `title` replaces the title; a task with
+ * an `id` matching an existing task updates its text/done in place; a task
+ * without an `id` (or with an unknown id) is appended. Returns a NEW state
+ * (input untouched). Removal is not supported by the patch shape.
+ */
+export function applyChecklistPatch(
+  cl: { title: string; tasks: ReadonlyArray<ChecklistTaskState> },
+  patch: ChecklistPatch,
+): { title: string; tasks: ChecklistTaskState[] } {
+  const tasks = cl.tasks.map((t) => ({ ...t }))
+  for (const p of patch.tasks ?? []) {
+    const pid = p.id != null ? Number(p.id) : undefined
+    const existing = pid != null ? tasks.find((t) => t.id === pid) : undefined
+    if (existing) {
+      if (p.text != null) existing.text = p.text
+      if (p.done != null) existing.done = p.done
+    } else {
+      const nextId = pid != null && Number.isFinite(pid)
+        ? pid
+        : tasks.reduce((m, t) => Math.max(m, t.id), 0) + 1
+      tasks.push({ id: nextId, text: p.text ?? '', done: p.done === true })
+    }
+  }
+  if (tasks.length > CHECKLIST_MAX_TASKS) {
+    throw new Error(`checklist exceeds ${CHECKLIST_MAX_TASKS}-task limit (got ${tasks.length})`)
+  }
+  return { title: patch.title ?? cl.title, tasks }
+}
+
+/**
+ * Build a CORRECT native `sendChecklist` payload per Bot API 9.1:
+ * `business_connection_id` is required, `title`/`tasks` nest inside a single
+ * `checklist` object (`InputChecklist`), each task carries its integer `id`,
+ * and there is NO completion field (`InputChecklistTask` has none).
+ */
+export function buildNativeChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+  replyToMessageId?: number
+  protectContent?: boolean
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+    ...(p.replyToMessageId != null ? { reply_parameters: { message_id: p.replyToMessageId } } : {}),
+    ...(p.protectContent === true ? { protect_content: true } : {}),
+  }
+}
+
+/**
+ * Build a native `editMessageChecklist` payload. The native edit REPLACES
+ * the whole checklist, so the FULL post-patch state is sent; reusing the
+ * stored task ids preserves user tick state for unchanged tasks.
+ */
+export function buildNativeEditChecklistPayload(p: {
+  businessConnectionId: string
+  chatId: number
+  messageId: number
+  title: string
+  tasks: ReadonlyArray<ChecklistTaskState>
+}): Record<string, unknown> {
+  return {
+    business_connection_id: p.businessConnectionId,
+    chat_id: p.chatId,
+    message_id: p.messageId,
+    checklist: {
+      title: p.title,
+      tasks: p.tasks.map((t) => ({ id: t.id, text: t.text })),
+    },
+  }
+}
+
+/** Bounded per-message checklist state store (insertion-order eviction). */
+export interface ChecklistStore {
+  get(key: string): ChecklistState | undefined
+  set(key: string, state: ChecklistState): void
+}
+
+export function createChecklistStore(cap = 500): ChecklistStore {
+  const map = new Map<string, ChecklistState>()
+  return {
+    get: (key) => map.get(key),
+    set: (key, state) => {
+      if (map.has(key)) map.delete(key) // refresh insertion order
+      map.set(key, state)
+      while (map.size > cap) {
+        const oldest = map.keys().next().value as string | undefined
+        if (oldest == null) break
+        map.delete(oldest)
+      }
+    },
+  }
+}
+
+export function checklistStoreKey(chatId: string, messageId: string | number): string {
+  return `${chatId}:${messageId}`
+}
+
+// ─── Orchestration (deps-injected, unit-testable) ─────────────────────────
+
+export interface SendChecklistDeps {
+  /** Business connection id, when the operator has one configured. Native
+   *  checklists are impossible without it (required API parameter). */
+  businessConnectionId: string | undefined
+  /** Boot-probe result: the connected grammY/Bot API exposes sendChecklist. */
+  nativeAvailable: boolean
+  sendNative: (payload: Record<string, unknown>) => Promise<{ message_id: number }>
+  sendText: (text: string) => Promise<{ message_id: number }>
+  /** access.parseMode === 'text' — render without markdown. */
+  literalText: boolean
+  log: (line: string) => void
+}
+
+export interface SendChecklistResult {
+  message_id: number
+  mode: 'native' | 'text'
+  state: ChecklistState
+}
+
+/**
+ * Send a checklist: natively when possible, degrading to a formatted text
+ * message otherwise. NEVER lets a native-send failure escape — the fallback
+ * is the text render. (A text-send failure still throws: there is nothing
+ * further to degrade to, and the caller's normal error path applies.)
+ */
+export async function performSendChecklist(
+  deps: SendChecklistDeps,
+  args: {
+    title: string
+    tasks: ReadonlyArray<{ text: string; done?: boolean }>
+    chatId: number
+    replyToMessageId?: number
+    protectContent?: boolean
+  },
+): Promise<SendChecklistResult> {
+  const tasks = buildChecklistTasks(args.tasks)
+  if (deps.nativeAvailable && deps.businessConnectionId) {
+    try {
+      const sent = await deps.sendNative(buildNativeChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: args.chatId,
+        title: args.title,
+        tasks,
+        replyToMessageId: args.replyToMessageId,
+        protectContent: args.protectContent,
+      }))
+      return {
+        message_id: sent.message_id,
+        mode: 'native',
+        state: { title: args.title, tasks, mode: 'native' },
+      }
+    } catch (err) {
+      deps.log(`native sendChecklist failed — falling back to text render: ${err}\n`)
+    }
+  }
+  const text = renderChecklistText({ title: args.title, tasks }, { literal: deps.literalText })
+  const sent = await deps.sendText(text)
+  return {
+    message_id: sent.message_id,
+    mode: 'text',
+    state: { title: args.title, tasks, mode: 'text' },
+  }
+}
+
+/** Tool-result text for send_checklist. The degraded shape carries
+ *  `degraded: "text"` + a note so the calling agent knows the checklist is a
+ *  formatted message, not a natively tickable one. */
+export function sendChecklistToolText(r: SendChecklistResult): string {
+  return JSON.stringify(
+    r.mode === 'native'
+      ? { ok: true, message_id: r.message_id, mode: 'native' }
+      : {
+          ok: true,
+          message_id: r.message_id,
+          mode: 'text',
+          degraded: 'text',
+          note: 'rendered as a formatted text message (native Telegram checklists require a Business connection) — tasks are not tappable; use update_checklist with task ids 1..N to tick them',
+        },
+  )
+}
+
+export interface UpdateChecklistDeps {
+  /** Stored state for this chat:message, if the gateway still has it. */
+  state: ChecklistState | undefined
+  businessConnectionId: string | undefined
+  nativeAvailable: boolean
+  editNative: (payload: Record<string, unknown>) => Promise<void>
+  editText: (text: string) => Promise<void>
+  literalText: boolean
+  log: (line: string) => void
+  chatId: number
+  messageId: number
+}
+
+export type UpdateChecklistResult =
+  | { ok: true; mode: 'native' | 'text'; state: ChecklistState }
+  | { ok: false; reason: 'unknown_checklist' | 'edit_failed'; hint: string }
+
+/**
+ * Update a checklist message. Applies the patch to the stored state and
+ * re-renders in the mode the message was originally sent in. Failures come
+ * back as structured `{ ok: false, reason, hint }` results — never a raw
+ * Telegram error thrown at the caller.
+ */
+export async function performUpdateChecklist(
+  deps: UpdateChecklistDeps,
+  patch: ChecklistPatch,
+): Promise<UpdateChecklistResult> {
+  let base = deps.state
+  if (!base) {
+    // State lost (gateway restart / evicted). If the patch is a full
+    // replacement — a title plus tasks that all carry text — we can rebuild
+    // and edit as text (the fleet-normal mode). Otherwise we cannot know
+    // the existing tasks; degrade gracefully.
+    const fullReplacement =
+      patch.title != null &&
+      (patch.tasks?.length ?? 0) > 0 &&
+      (patch.tasks ?? []).every((t) => t.text != null)
+    if (!fullReplacement) {
+      return {
+        ok: false,
+        reason: 'unknown_checklist',
+        hint: 'no stored state for this checklist (gateway restarted?). Re-send it with send_checklist, or pass a full replacement (title + every task\'s text) to update_checklist.',
+      }
+    }
+    base = { title: patch.title!, tasks: [], mode: 'text' }
+  }
+  let next: { title: string; tasks: ChecklistTaskState[] }
+  try {
+    next = applyChecklistPatch(base, patch)
+  } catch (err) {
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+  const state: ChecklistState = { title: next.title, tasks: next.tasks, mode: base.mode }
+  if (base.mode === 'native') {
+    // A native checklist message cannot be edited into plain text — there is
+    // no text fallback here; a failure surfaces as a structured result.
+    if (!deps.nativeAvailable || !deps.businessConnectionId) {
+      return {
+        ok: false,
+        reason: 'edit_failed',
+        hint: 'this checklist was sent natively but the business connection / checklist API is no longer available.',
+      }
+    }
+    try {
+      await deps.editNative(buildNativeEditChecklistPayload({
+        businessConnectionId: deps.businessConnectionId,
+        chatId: deps.chatId,
+        messageId: deps.messageId,
+        title: state.title,
+        tasks: state.tasks,
+      }))
+      return { ok: true, mode: 'native', state }
+    } catch (err) {
+      deps.log(`native editMessageChecklist failed: ${err}\n`)
+      return { ok: false, reason: 'edit_failed', hint: String(err) }
+    }
+  }
+  try {
+    await deps.editText(renderChecklistText(state, { literal: deps.literalText }))
+    return { ok: true, mode: 'text', state }
+  } catch (err) {
+    deps.log(`checklist text edit failed: ${err}\n`)
+    return { ok: false, reason: 'edit_failed', hint: String(err) }
+  }
+}
+
+/** Tool-result text for update_checklist — structured for both outcomes. */
+export function updateChecklistToolText(r: UpdateChecklistResult, messageId: number): string {
+  return JSON.stringify(
+    r.ok
+      ? { ok: true, message_id: messageId, mode: r.mode, ...(r.mode === 'text' ? { degraded: 'text' } : {}) }
+      : { ok: false, reason: r.reason, hint: r.hint },
+  )
+}

package/telegram-plugin/gateway/compaction-marker.ts

@@ -0,0 +1,84 @@
+/**
+ * Compaction-in-flight marker (#4058 — spurious 300s silence-fallback fire
+ * during mid-turn auto-compaction).
+ *
+ * The blind spot this closes: when Claude Code hits mid-turn auto-compaction
+ * (the session ran out of context and spends minutes summarizing), the model
+ * emits ZERO output and runs ZERO tools — the gateway sees pure silence, so
+ * the silence-poke 300s framework fallback fired on a perfectly healthy turn:
+ * a spurious "⚠️ no output for 5 min — the framework ended that stalled turn"
+ * card plus an obligation re-present, right before the turn completed
+ * normally. Observed live: ~1m50s of tools then ~3m25s compacting = 304s of
+ * "silence" → false fire.
+ *
+ * The signal problem: the transcript JSONL carries a compaction record ONLY
+ * at the END (`{"type":"system","subtype":"compact_boundary",...}` — it
+ * embeds the compaction's own durationMs, so it cannot exist before the
+ * compaction finishes). Nothing observable lands at the START from the
+ * stream. The START therefore comes from Claude Code's PreCompact hook
+ * (`hooks/compaction-marker-precompact.mjs`), which writes
+ * `<STATE_DIR>/compaction-in-flight.json` the moment compaction begins —
+ * the same sidecar-file pattern as `turn-active-marker.ts` and the
+ * tool-label sidecar (#783).
+ *
+ * Consumers:
+ *   - `liveness-wiring.ts` wires `isCompactionInFlight` into the silence-poke
+ *     deps: marker present AND younger than the fallback hard ceiling ⇒ the
+ *     300s fallback is DEFERRED via the exact same `underCeiling` mechanism
+ *     as the #1292/#3519 in-flight-tool defers — a genuinely-wedged
+ *     compaction still unwedges once silence crosses `fallbackHardCeiling`.
+ *   - `silence-poke-session-event.ts` removes the marker on the
+ *     `compact_boundary` session event (the deterministic END) and counts
+ *     the boundary as production, so the resumed turn gets a fresh 300s
+ *     window instead of firing on the very next tick.
+ *
+ * Staleness is double-bounded: the reader treats an old marker as absent
+ * (age bound supplied by the caller — the hard ceiling), so a marker leaked
+ * by a crash between compaction start and boundary can never defer a future
+ * genuine wedge for more than one ceiling window.
+ *
+ * Pure file I/O; clock injectable for tests; never throws.
+ */
+
+import { statSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export const COMPACTION_MARKER_FILE = 'compaction-in-flight.json'
+
+/**
+ * The gateway's state dir — same resolution as gateway.ts (`STATE_DIR`).
+ * Exported so `silence-poke-session-event.ts` (which is handed no stateDir)
+ * can clear the marker without widening its call signature.
+ */
+export function resolveTelegramStateDir(): string {
+  return process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
+}
+
+/**
+ * Age (ms) of the compaction marker's mtime, or null when absent/unstattable.
+ * The PreCompact hook (re)writes the file at compaction start, so a small age
+ * means a compaction began recently and may still be running. Never throws.
+ */
+export function readCompactionMarkerAgeMs(stateDir: string, now?: number): number | null {
+  try {
+    const st = statSync(join(stateDir, COMPACTION_MARKER_FILE))
+    return (now ?? Date.now()) - st.mtimeMs
+  } catch {
+    return null // ENOENT / unstattable → no compaction in flight
+  }
+}
+
+/**
+ * Remove the marker — called on the `compact_boundary` session event (the
+ * compaction's deterministic END record in the transcript). Idempotent;
+ * ENOENT and any other unlink failure are swallowed (the age bound in the
+ * reader is the correctness backstop, removal is the fast path).
+ */
+export function removeCompactionMarker(stateDir: string): void {
+  try {
+    unlinkSync(join(stateDir, COMPACTION_MARKER_FILE))
+  } catch {
+    // best-effort — staleness bound in readCompactionMarkerAgeMs self-heals
+  }
+}