switchroom 0.15.45 → 0.16.4

package/telegram-plugin/gateway/current-turn-map.ts

@@ -0,0 +1,188 @@
+/**
+ * current-turn-map.ts — per-topic `currentTurn` store behind the
+ * emission-authority kill-switch (PR-4e).
+ *
+ * ## What 4e changes (and, crucially, what it does NOT)
+ *
+ * The `claude` CLI is genuinely SEQUENTIAL: never two foreground turns
+ * executing CPU-simultaneously. So 4e is NOT about concurrent execution.
+ * It is about the ISOLATION of per-topic emission STATE.
+ *
+ * Before 4e the gateway tracked the live foreground turn in ONE ambient
+ * module-scope singleton (`let currentTurn`). That is correct for the
+ * synchronous-to-the-live-turn reads — but it is WRONG for the LATE async
+ * events that fire AFTER the live turn has flipped to a different topic:
+ *
+ *   - a deferred card drain captured for topic A,
+ *   - the orphaned-reply backstop for A,
+ *   - an over-ping decision for A,
+ *   - the answer-stream suppressor for A,
+ *
+ * any of which can fire AFTER `currentTurn` flipped from A to B. A bare
+ * `currentTurn === turnA` liveness check then reads B and FALSIFIES A's own
+ * liveness (or, worse, a teardown keyed on the ambient singleton clobbers B's
+ * card / ping / single-flight state). 4e keys the store by chat+thread so a
+ * late A-captured callback resolves A's authority, never contaminating B.
+ *
+ * ## Defining property: flag-OFF ≡ flag-ON ≡ base
+ *
+ * The kill-switch (`SWITCHROOM_EMISSION_AUTHORITY`, default OFF) is read ONCE
+ * here, mirroring `emission-authority.ts`'s `EMISSION_AUTHORITY_ENABLED`:
+ *
+ *   - **Flag OFF (default):** the accessors operate on the singleton ONLY.
+ *     `byKey` is never written (stays empty, zero alloc). Every read returns
+ *     the singleton. Byte-equivalent to base — there is no map.
+ *   - **Flag ON:** the per-topic `byKey` map is the source of truth, AND the
+ *     singleton is retained as a "most-recent-set" MIRROR so every GLOBAL
+ *     liveness read (`isBusy`, the `if (currentTurn != null) return` poke
+ *     guards, the orphaned-reply guard) stays byte-identical: under the
+ *     sequential-CLI invariant the most-recently-set turn IS the live turn,
+ *     so the mirror answers "is anything live" exactly as the old singleton.
+ *
+ * No lock is added here. Map ops are synchronous `Map.get/set/delete` — no
+ * await, no lock — so the PR-4d no-deadlock invariant is untouched.
+ *
+ * ## Why a standalone module (not inline in gateway.ts)
+ *
+ * The gateway IIFE cannot be instantiated in-process, so the multi-topic
+ * non-contamination behaviour would be untestable if this lived inline. As a
+ * standalone module with a flag-read-once seam (mirroring
+ * emission-authority-card-drain-gate.test.ts's `loadFacade` re-import idiom),
+ * the per-topic isolation is driven directly in tests/per-topic-current-turn.test.ts.
+ */
+
+import { chatIdOfChatKey, type ChatKey } from './chat-key.js'
+
+/**
+ * Kill-switch — read ONCE at module top, `=== '1'` (default OFF), mirroring
+ * `emission-authority.ts`'s `EMISSION_AUTHORITY_ENABLED`. The same flag governs
+ * both modules: under it OFF the singleton is the only store; under it ON the
+ * per-topic map is authoritative with the singleton kept as a most-recent mirror.
+ */
+export const EMISSION_AUTHORITY_ENABLED =
+  process.env.SWITCHROOM_EMISSION_AUTHORITY === '1'
+
+/**
+ * Per-topic `currentTurn` store. Generic over the gateway's turn type (which is
+ * module-local to gateway.ts and not exported) so this module stays decoupled.
+ *
+ * - `byKey` is the FLAG-ON store, keyed by `statusKey(chatId, threadId)`.
+ * - `singleton` is the FLAG-OFF store AND, under flag-ON, the most-recent-set
+ *   MIRROR that serves global "is anything live" reads byte-identically.
+ *
+ * The two thin accessors flag-branch in EXACTLY one place each.
+ */
+export class CurrentTurnMap<T> {
+  /** Flag-ON store. Never written under flag OFF (stays empty, zero alloc). */
+  readonly byKey = new Map<string, T>()
+
+  /** Flag-OFF store AND flag-ON most-recent-set mirror. */
+  private singleton: T | null = null
+
+  /**
+   * Read the live turn.
+   *
+   *  - Flag OFF: the singleton.
+   *  - Flag ON: `byKey.get(key)` when a key is given (per-topic liveness);
+   *    otherwise the singleton mirror (global "is anything live" read).
+   */
+  get(key?: string): T | null {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      if (key != null) return this.byKey.get(key) ?? null
+      return this.singleton
+    }
+    return this.singleton
+  }
+
+  /**
+   * Set the live turn for `key`.
+   *
+   *  - Flag OFF: assign the singleton (key ignored).
+   *  - Flag ON: set `byKey[key]` AND update the singleton mirror to
+   *    most-recent-set, so global liveness reads stay byte-identical.
+   */
+  set(turn: T, key: string): void {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      this.byKey.set(key, turn)
+      this.singleton = turn
+      return
+    }
+    this.singleton = turn
+  }
+
+  /**
+   * Is `turn` still the live turn FOR ITS OWN topic `key`?
+   *
+   *  - Flag OFF: `singleton === turn` (the ambient liveness check, verbatim).
+   *  - Flag ON: `byKey.get(key) === turn` — so a B-flip never falsifies A's
+   *    own liveness. This is the load-bearing cross-topic isolation read.
+   */
+  isLiveForKey(turn: T, key: string): boolean {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      return this.byKey.get(key) === turn
+    }
+    return this.singleton === turn
+  }
+
+  /**
+   * End (delete) `turn` for `key`, iff `key` still maps to `turn` — the
+   * leak-close-at-origin used by `endCurrentTurnAtomic` and the silence-poke
+   * fallback.
+   *
+   *  - Flag OFF: clear the singleton iff it still points at `turn`.
+   *  - Flag ON: `byKey.delete(key)` iff `byKey.get(key) === turn`, AND clear
+   *    the singleton mirror iff it STILL points at `turn` (i.e. no later turn
+   *    has flipped the mirror). Returns true iff a delete happened.
+   */
+  endTurnForKey(turn: T, key: string): boolean {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      if (this.byKey.get(key) !== turn) return false
+      this.byKey.delete(key)
+      if (this.singleton === turn) this.singleton = null
+      return true
+    }
+    if (this.singleton !== turn) return false
+    this.singleton = null
+    return true
+  }
+
+  /**
+   * Clear EVERYTHING — every entry is a ghost (the disconnect-flush /
+   * bridge-died sweep). Drops the whole `byKey` map and the singleton mirror.
+   */
+  clearAll(): void {
+    this.byKey.clear()
+    this.singleton = null
+  }
+
+  /**
+   * Self-heal backstop: drop any `byKey` entries whose key belongs to `chatId`
+   * AND pass the per-sibling `isStale` gate — mirroring `purgeStaleTurnsForChat`
+   * (turn-state-purge.ts) exactly, including its `:`-prefix chat match and the
+   * one-agent-owns-supergroup safety (a LIVE sibling topic of the same chatId is
+   * spared unless it is itself stale). Also clears the singleton mirror iff it
+   * pointed at one of the swept entries. No-op under flag OFF (the map is empty).
+   *
+   * @param isStale per-sibling staleness gate; defaults to always-stale for the
+   *   DM / single-topic case (every sibling is genuinely dangling), matching the
+   *   `purgeStaleTurnsForChat` default.
+   * @returns the keys swept.
+   */
+  purgeChatStale(chatId: string, isStale: (key: string) => boolean = () => true): string[] {
+    if (!chatId) return []
+    const swept: string[] = []
+    for (const key of [...this.byKey.keys()]) {
+      // A bare chatId (no `:`) cannot belong to a chat+thread keyspace —
+      // chatIdOfChatKey returns the whole string in that case, which can never
+      // equal `${chatId}:...`-derived keys, so it is correctly skipped.
+      if (!key.includes(':')) continue
+      if (chatIdOfChatKey(key as ChatKey) !== chatId) continue
+      if (!isStale(key)) continue // live sibling topic — leave its turn intact
+      const victim = this.byKey.get(key)
+      this.byKey.delete(key)
+      swept.push(key)
+      if (this.singleton === victim) this.singleton = null
+    }
+    return swept
+  }
+}

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -157,10 +157,12 @@ export function flushOnAgentDisconnect<
   // dangling-sweep above for activeTurnStartedAt.
   if (claudeBusyKeys.size > 0) {
     const orphanCount = claudeBusyKeys.size
+    const orphanKeys = [...claudeBusyKeys]
     claudeBusyKeys.clear()
     log(
       `telegram gateway: disconnect-flush cleared ${orphanCount} orphan claudeBusyKeys ` +
-      `entr${orphanCount === 1 ? 'y' : 'ies'} (synthetic-inbound deliveries that never turn_ended)`,
+      `entr${orphanCount === 1 ? 'y' : 'ies'} (synthetic-inbound deliveries that never turn_ended)` +
+      ` keys=${orphanKeys.join(',')}`,
     )
   }
 

package/telegram-plugin/gateway/effort-command.ts

@@ -6,9 +6,14 @@
  * inline keyboard of the five levels the CLI offers
  * (`low · medium · high · xhigh · max`, faster→smarter), the live level
  * marked ✅. A tap types claude's own `/effort <level>` into the agent's
- * tmux pane via the allowlisted inject primitive (`/effort` is on the
- * inject allowlist) — the Claude-native mechanism: the unmodified CLI's
- * REPL command, no API, no SDK, no config mutation.
+ * tmux pane via the dedicated `applyEffort` driver
+ * (src/agents/effort-picker.ts) — the Claude-native mechanism: the
+ * unmodified CLI's REPL command, no API, no SDK, no config mutation.
+ * `applyEffort` (NOT the bare inject primitive) is used deliberately: it
+ * answers the "Change effort level?" confirmation modal so the pane never
+ * wedges. `/effort` is therefore on the inject BLOCKLIST (#2471) — raw
+ * `/inject /effort` would leave that modal open — and this command is the
+ * only sanctioned path.
  *
  * `/effort <level>` does the same non-interactively.
  *

package/telegram-plugin/gateway/emission-authority.ts

@@ -0,0 +1,369 @@
+/**
+ * Per-foreground-turn EMISSION-AUTHORITY façade (kill-switched no-op seam).
+ *
+ * This is the SEAM the message-emission-determinism refactor (PR-4 series,
+ * `docs/message-emission-determinism.md` §9 "deeper architectural move") routes
+ * the foreground-lane card/ping emission call sites through. It mirrors the
+ * one-concern-per-file precedent of `feed-open-gate.ts`: a single place that
+ * will eventually OWN the WHEN of foreground emission. The gateway constructs
+ * exactly ONE instance per foreground turn, alongside the `CurrentTurn` object,
+ * and passes the chat/thread key in EXPLICITLY (even though today it is sourced
+ * from the `currentTurn` singleton) — that explicit key is the seam PR-4e uses
+ * to swap the singleton for a per-topic map. The façade must NOT persist across
+ * turns: it is per-turn only, because cross-turn persistence would pre-empt the
+ * per-chat scoping decision PR-4e owns.
+ *
+ * ## PR-4a is a behaviourally-IDENTICAL no-op
+ *
+ * In PR-4a NO decision logic moves in. Every method is a THIN DELEGATE: it
+ * invokes the same statements the call site ran before, via an `apply` thunk
+ * the caller hands in (so the load-bearing literals — `drainActivitySummary`,
+ * `clearActivitySummary`, `decideOverPing`, the `finalAnswerEverDelivered`
+ * latch-set — stay AT THE CALL SITE and remain visible to the source-read
+ * wiring oracles). Framing (A) "construct-but-bypass": each method body branches
+ * on the kill-switch, and in PR-4a BOTH branches execute the SAME delegate, so
+ * the seam is a provable no-op even when the flag is ON. The flag's real teeth
+ * (moving `mayOpenActivityCard` / `decideOverPing` decisions INTO the façade)
+ * start in PR-4b — NOT here.
+ *
+ * ## PR-4d deadlock invariant (ship as a standing doc-comment)
+ *
+ * `mayDrain` is a PURE READ; it must NOT acquire `chatLock`. PR-4d acquires
+ * `chatLock` strictly INSIDE the deliver-before-drain gate decision (gateway.ts
+ * component-1, ref ~`:2730`), never the reverse, because a synthetic represent
+ * turn starts `finalAnswerDelivered=false` and would wedge the gate (ref
+ * ~`:1646`) if a card OPEN held the lock across the gate's release. Keep
+ * `mayDrain` lock-free so PR-4d has a clean read to build on.
+ *
+ * ## PR-4d ships: `mayDrainCardNow` unifies the card-drain path with the #2137
+ * deliver-before-drain gate
+ *
+ * PR-4d adds `mayDrainCardNow` — the card-path counterpart of the deliver-before-
+ * drain decision in `serialize-drain-gate.ts`. It is ALSO a pure, lock-free read:
+ *
+ *  - Flag OFF (default): returns exactly the `mayDrain` single-flight read —
+ *    byte-equivalent to base. The card single-flight gate is unchanged.
+ *  - Flag ON: returns the `mayDrain` read AND-ed with `mayDrainBufferedInbound`,
+ *    importing the PURE `mayDrainBufferedInbound` from `./serialize-drain-gate.js`
+ *    (the façade imports the pure helper, NEVER the gateway). The card path
+ *    threads `endingTurnFinalAnswerDelivered: null` so the deliver-before-drain
+ *    predicate degenerates to `!turnInFlight`: the card single-flight is governed
+ *    by `activityInFlight` (via `mayDrain`), NOT by an ending turn's delivery
+ *    state. A synthetic represent turn (finalAnswerDelivered=false) therefore can
+ *    never wedge the live foreground card path.
+ *
+ * The LOCK is acquired by the GATEWAY around the gate decision (a centralized
+ * `chatLock.run(statusKey(...), …)` helper that consults this method then kicks
+ * off `openOrEditCard`). `mayDrainCardNow` itself, like `mayDrain`, acquires NO
+ * lock — it is a pure read the gateway calls from inside the lock. The lock spans
+ * only the gate decision + the synchronous `openOrEditCard` kick-off (which only
+ * ASSIGNS `turn.activityInFlight = drainActivitySummary(...)`; the async send is
+ * NOT awaited inside the lock), so a card OPEN never holds `chatLock` across the
+ * gate's release.
+ */
+
+import {
+  computeFeedOpenVerdict,
+  type FeedOpenGateView,
+  type FeedOpenGateDeps,
+} from './feed-open-gate.js'
+import {
+  decideOverPing,
+  type OverPingDecision,
+} from '../over-ping-safety-net.js'
+import { mayDrainBufferedInbound } from './serialize-drain-gate.js'
+
+/**
+ * Kill-switch. Read ONCE at module top, `=== '1'` (default OFF), following the
+ * existing flag convention (`SWITCHROOM_FEED_HEARTBEAT` etc. in gateway.ts's
+ * flag region). In PR-4a this gates nothing behaviourally — both branches of
+ * every façade method run the same delegate — so unset and set are identical.
+ * It exists now so the seam is in place; PR-4b is where ON starts to differ.
+ */
+export const EMISSION_AUTHORITY_ENABLED =
+  process.env.SWITCHROOM_EMISSION_AUTHORITY === '1'
+
+/** Which producer triggered a card OPEN/EDIT — carried for the PR-4b seam. */
+export type EmissionProducer = 'narrative' | 'tool' | 'liveness'
+
+/**
+ * The minimal per-turn surface the façade needs. A structural subset of
+ * `CurrentTurn` — keeps this module decoupled from gateway.ts's giant turn type
+ * (and out of an import cycle) while still typing the reads it performs.
+ */
+export interface EmissionTurnView {
+  /** Single-flight slot: a drain Promise is in flight when non-null. */
+  activityInFlight: Promise<void> | null
+}
+
+/** Inputs to the over-ping claim/downgrade decision (carried for PR-4b). */
+export interface PingClaimInput {
+  /** The model asked for a device ping (`disable_notification: false`). */
+  modelRequestedPing: boolean
+  /** This reply is a substantive final answer (`isSubstantiveFinalReply`). */
+  substantive: boolean
+}
+
+/**
+ * The live per-turn ping-slot state the over-ping decision reads (PR-4c seam).
+ *
+ * A structural subset of `CurrentTurn` threaded in EXPLICITLY so the façade can
+ * call `decideOverPing` in its enabled branch without importing gateway.ts's
+ * turn type. These are READS only — the façade decides; the call-site
+ * `applyDecision` thunk performs the atomic `firstPingAt`/`firstPingWasSubstantive`
+ * pair-set (the #2562 atomicity invariant: two adjacent assignments, no await
+ * between, so a racing second reply reads a consistent pair).
+ */
+export interface PingClaimCtx {
+  /** Wall-clock ms of the FIRST ping this turn, or null if none has landed. */
+  firstPingAt: number | null
+  /** True iff the send that CLAIMED the slot was itself a substantive answer. */
+  firstPingWasSubstantive: boolean
+  /** Deterministic clock for the decision (the call site's `Date.now()`). */
+  nowMs: number
+}
+
+/**
+ * The deliver-before-drain inputs the PR-4d card-drain gate threads into the
+ * pure `mayDrainBufferedInbound` predicate. A small structural subset (mirrors
+ * the `PingClaimCtx` / `FeedOpenGateDeps` shape) so the façade never imports the
+ * gateway's turn type — the gateway sources these and passes them in.
+ *
+ * `endingTurnFinalAnswerDelivered` is fixed to `null` on the card path (§5
+ * modeling decision): the predicate degenerates to `!turnInFlight`, so the card
+ * single-flight is governed by `activityInFlight` (via `mayDrain`), not by an
+ * ending turn's delivery state — a synthetic represent turn cannot wedge it.
+ */
+export interface CardDrainGateCtx {
+  /** A turn is in flight RIGHT NOW (`turnInFlightForGate()`), evaluated at the
+   *  gate site. When true, never drain the card — claude is busy. */
+  turnInFlight: boolean
+  /** The ending turn's `finalAnswerDelivered`. Threaded `null` for the CARD
+   *  path so the deliver-before-drain predicate degenerates to `!turnInFlight`
+   *  (the card single-flight is governed by `activityInFlight`, not delivery). */
+  endingTurnFinalAnswerDelivered: boolean | null
+  /** Serialize-until-replied kill-switch state (`SERIALIZE_UNTIL_REPLIED_ENABLED`). */
+  enabled: boolean
+}
+
+/**
+ * Per-foreground-turn emission-authority façade.
+ *
+ * Constructed once per turn with the chat/thread key passed in explicitly (the
+ * PR-4e seam). In PR-4a every method just runs the caller's delegate — no
+ * decision logic lives here yet.
+ */
+export class EmissionAuthority {
+  /**
+   * @param chatKey  The chat/thread key this façade governs, passed in
+   *   EXPLICITLY by the gateway (today sourced from the `currentTurn`
+   *   singleton). PR-4e swaps the singleton for a per-topic map keyed on this.
+   *   Unused in PR-4a beyond being held — it is the seam, not yet a decision
+   *   input.
+   */
+  constructor(private readonly chatKey: string) {}
+
+  /**
+   * PR-4b OPEN-gate wiring. The gateway centralizes it in `emissionAuthorityFor`
+   * (one place) so the 6 `openOrEditCard` call sites stay byte-identical
+   * `(producer, apply)` — the façade reads the live turn view + injected history
+   * deps from HERE, not per-call. `viewProvider` is a thunk so the verdict reads
+   * the CURRENT card/latch/tool-count at gate time (they mutate during the turn).
+   * Lazily set on every `emissionAuthorityFor`; the disabled branch never reads
+   * it, so a turn that never wires it is harmless (only `openOrEditCard`'s
+   * EMISSION_AUTHORITY_ENABLED branch consults it).
+   */
+  private feedOpenView?: () => FeedOpenGateView
+  private feedOpenDeps?: FeedOpenGateDeps
+
+  /**
+   * Wire the PR-4b OPEN-gate inputs (idempotent). Called by the gateway's
+   * `emissionAuthorityFor` accessor so every routed turn's façade can compute
+   * the open verdict in its enabled branch. No-op-equivalent under the flag OFF.
+   */
+  wireFeedOpenGate(
+    viewProvider: () => FeedOpenGateView,
+    deps: FeedOpenGateDeps,
+  ): void {
+    this.feedOpenView = viewProvider
+    this.feedOpenDeps = deps
+  }
+
+  /** The chat/thread key this façade was constructed for (PR-4e seam read). */
+  get key(): string {
+    return this.chatKey
+  }
+
+  /**
+   * Card OPEN-or-EDIT for the foreground turn (delegates to
+   * `drainActivitySummary` at the call site via `apply`).
+   *
+   * PR-4b — the OPEN-gate decision RELOCATES here, behind the kill-switch:
+   *
+   *  - **Disabled branch (default):** unchanged from PR-4a — `apply()` runs
+   *    unconditionally. The drain's own inline OPEN gate is what refuses (and
+   *    `break`s) a disallowed OPEN, exactly as on main. Byte-identical to main.
+   *  - **Enabled branch:** compute the OPEN verdict from the live turn view +
+   *    injected history deps (`computeFeedOpenVerdict`) and run `apply()` IFF
+   *    `!(isOpen && !mayOpen)` is FALSE-y in the refuse sense — concretely
+   *    `apply()` runs iff `isOpen || mayOpen`. That is EXACTLY the set of cases
+   *    main did NOT `break` (main refuses iff `activityMessageId == null &&
+   *    !mayOpenActivityCard(...)`, i.e. `!isOpen && !mayOpen`). Same pure inputs
+   *    ⇒ same verdict, so flag-ON ≡ flag-OFF ≡ main: no emitted message differs.
+   *
+   * On flag-ON the drain still re-evaluates the SAME gate (now redundant) — an
+   * intentional, safe double-check: both are pure over identical inputs, and it
+   * also covers the documented in-flight-send race (a send already PAST the
+   * drain's check). A refused OPEN never calls `apply()`, so `activityInFlight`
+   * stays null and the pending render stays unadvanced — matching main's `break`
+   * + `finally` end-state. The delegate keeps the `turn.activityInFlight =
+   * drainActivitySummary(turn, <producer>)` assignment AT THE CALL SITE so the
+   * source-read wiring oracles still see it.
+   */
+  openOrEditCard(
+    producer: EmissionProducer,
+    apply: () => void,
+  ): void {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      // The OPEN-gate inputs are wired by `emissionAuthorityFor` (centralized).
+      // If a turn somehow reaches here unwired, fall back to delegating (no
+      // behaviour change — the drain's own gate still governs the OPEN).
+      if (this.feedOpenView != null && this.feedOpenDeps != null) {
+        const { isOpen, mayOpen } = computeFeedOpenVerdict(
+          this.feedOpenView(),
+          producer,
+          this.feedOpenDeps,
+        )
+        // Refuse (skip apply) iff main would have `break`-refused the OPEN:
+        // `!isOpen && !mayOpen`. Apply otherwise (an EDIT — isOpen — is never
+        // gated; an OPEN-eligible producer — mayOpen — opens).
+        if (!isOpen && !mayOpen) return
+      }
+      apply()
+      return
+    }
+    apply()
+  }
+
+  /**
+   * Finalize the card before a substantive reply send (delegates to
+   * `clearActivitySummary` at the call site via `apply`).
+   *
+   * PR-4a: a pure pass-through. Both branches run `apply`.
+   */
+  finalizeCard(apply: () => void): void {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      apply()
+      return
+    }
+    apply()
+  }
+
+  /**
+   * Mark that a substantive final answer was delivered this turn — the sticky
+   * lever-1 latch (delegates to the `finalAnswerEverDelivered = true` set at the
+   * call site via `apply`).
+   *
+   * PR-4a: a pure pass-through. Both branches run `apply`.
+   */
+  markSubstantiveFinalDelivered(apply: () => void): void {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      apply()
+      return
+    }
+    apply()
+  }
+
+  /**
+   * Claim-or-downgrade the turn's one notification ping.
+   *
+   * PR-4c — the over-ping DECISION relocates here, behind the kill-switch, the
+   * same structural way PR-4b moved the OPEN gate. Nothing new is extracted:
+   * `decideOverPing` is already a pure predicate in `over-ping-safety-net.ts`;
+   * PR-4c only relocates the *call* into the enabled branch and keeps the
+   * *effects* (stderr, metric, the atomic `firstPingAt`/`firstPingWasSubstantive`
+   * pair-set, the `disableNotification`/`wasOverPingSuppressed` closure writes)
+   * at the call site, parameterized by the decision the façade hands back.
+   *
+   *  - **Disabled branch (default):** unchanged from PR-4a — `disabled()` runs,
+   *    and that thunk holds its OWN literal `decideOverPing(...)` call + the full
+   *    effects block, VERBATIM from PR-4b-base. The disabled path is therefore
+   *    provably byte-identical to base: nothing about the decision moves out of
+   *    the call site when the flag is OFF.
+   *  - **Enabled branch:** compute the decision HERE via `decideOverPing` (the
+   *    SAME pure predicate, the SAME inputs threaded through `ctx` + `input`) and
+   *    hand it to `applyDecision(decision)`, which performs the identical effects
+   *    at the call site. Same pure inputs ⇒ same decision ⇒ flag-ON ≡ flag-OFF ≡
+   *    base: not one device ping differs.
+   *
+   * SYNCHRONOUS by contract — no `async`, no `await`. The
+   * `decideOverPing → applyDecision → pair-set` chain runs in one synchronous
+   * block so the #2562 atomicity invariant holds across the façade boundary: the
+   * façade decides whether to claim/upgrade; the call-site `applyDecision` thunk
+   * performs the two-adjacent-line `firstPingAt`/`firstPingWasSubstantive`
+   * pair-set with no await between.
+   */
+  claimOrDowngradePing(
+    input: PingClaimInput,
+    ctx: PingClaimCtx,
+    applyDecision: (decision: OverPingDecision) => void,
+    disabled: () => void,
+  ): void {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      const decision = decideOverPing({
+        modelRequestedPing: input.modelRequestedPing,
+        firstPingAt: ctx.firstPingAt,
+        substantive: input.substantive,
+        firstPingWasSubstantive: ctx.firstPingWasSubstantive,
+        nowMs: ctx.nowMs,
+      })
+      applyDecision(decision)
+      return
+    }
+    disabled()
+  }
+
+  /**
+   * Single-flight read: may a drain start? Returns `turn.activityInFlight ==
+   * null` — the EXACT guard every drain call site already performs.
+   *
+   * PURE READ, NO lock acquisition (see the PR-4d deadlock invariant in this
+   * module's header). PR-4d needs this read clean so it can acquire `chatLock`
+   * elsewhere without the lattice inverting.
+   */
+  mayDrain(turn: EmissionTurnView): boolean {
+    return turn.activityInFlight == null
+  }
+
+  /**
+   * PR-4d card-drain gate: may the card drain start RIGHT NOW, unifying the
+   * single-flight read with the #2137 deliver-before-drain serialization gate.
+   *
+   *  - **Flag OFF (default):** returns exactly `this.mayDrain(turn)` — the card
+   *    single-flight read, byte-equivalent to base. Nothing else is consulted.
+   *  - **Flag ON:** returns `this.mayDrain(turn) && mayDrainBufferedInbound(ctx)`
+   *    — the single-flight read AND the pure deliver-before-drain predicate
+   *    (imported from `./serialize-drain-gate.js`). The gateway threads
+   *    `endingTurnFinalAnswerDelivered: null` for the card path (§5 modeling
+   *    decision), so `mayDrainBufferedInbound` degenerates to `!turnInFlight`:
+   *    the card single-flight stays governed by `activityInFlight` (via
+   *    `mayDrain`), NOT by an ending turn's delivery state.
+   *
+   * PURE READ — see the PR-4d deadlock invariant in this module's header. The
+   * GATEWAY serializes this decision via the chat mutex AROUND the call; this
+   * method only reads. Routes the single-flight via the pure `this.mayDrain`.
+   */
+  mayDrainCardNow(turn: EmissionTurnView, ctx: CardDrainGateCtx): boolean {
+    if (EMISSION_AUTHORITY_ENABLED) {
+      return (
+        this.mayDrain(turn) &&
+        mayDrainBufferedInbound({
+          turnInFlight: ctx.turnInFlight,
+          endingTurnFinalAnswerDelivered: ctx.endingTurnFinalAnswerDelivered,
+          enabled: ctx.enabled,
+        })
+      )
+    }
+    return this.mayDrain(turn)
+  }
+}