switchroom 0.18.26 → 0.18.28

package/telegram-plugin/gateway/ms365-write-approval.ts

@@ -57,10 +57,27 @@ export interface Ms365WritePreview {
   /** Byte delta — present only for OneDrive uploads with known sizes. */
   sizeBytesBefore?: number;
   sizeBytesAfter?: number;
+  /**
+   * "start → end" human string for calendar events, resolved from Graph.
+   * Present only when the opaque event id resolved successfully (#3267).
+   */
+  eventWhen?: string;
+  /**
+   * Structural before→after diff for the fields the mutation changes
+   * (calendar body/location/time). Present only when resolved (#3267).
+   */
+  changes?: Ms365PreviewChange[];
   /** 1-line agent rationale — advisory; operator should not over-trust. */
   agentRationale?: string;
 }
 
+/** A single before→after change rendered on the card. */
+export interface Ms365PreviewChange {
+  field: string;
+  before?: string;
+  after?: string;
+}
+
 /**
  * Validate a wire payload into a typed Ms365WritePreview. Returns null
  * on malformed input (defense in depth — the hook is trusted but the
@@ -84,10 +101,32 @@ export function validateMs365Preview(input: unknown): Ms365WritePreview | null {
   if (typeof o.deepLink === "string") out.deepLink = o.deepLink;
   if (typeof o.sizeBytesBefore === "number") out.sizeBytesBefore = o.sizeBytesBefore;
   if (typeof o.sizeBytesAfter === "number") out.sizeBytesAfter = o.sizeBytesAfter;
+  if (typeof o.eventWhen === "string") out.eventWhen = o.eventWhen;
+  const changes = sanitizeChanges(o.changes);
+  if (changes) out.changes = changes;
   if (typeof o.agentRationale === "string") out.agentRationale = o.agentRationale;
   return out;
 }
 
+/**
+ * Validate the wire `changes` array into typed before→after entries. Drops
+ * malformed entries defensively; returns undefined when nothing usable.
+ */
+function sanitizeChanges(input: unknown): Ms365PreviewChange[] | undefined {
+  if (!Array.isArray(input)) return undefined;
+  const out: Ms365PreviewChange[] = [];
+  for (const raw of input) {
+    if (!raw || typeof raw !== "object") continue;
+    const c = raw as Record<string, unknown>;
+    if (typeof c.field !== "string" || c.field.length === 0) continue;
+    const entry: Ms365PreviewChange = { field: c.field };
+    if (typeof c.before === "string") entry.before = c.before;
+    if (typeof c.after === "string") entry.after = c.after;
+    out.push(entry);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
 // ────────────────────────────────────────────────────────────────────────
 // Handler — DI shape mirrors DriveApprovalHandlerDeps
 // ────────────────────────────────────────────────────────────────────────
@@ -168,6 +207,9 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
     lines.push(`ID:   ${truncate(p.itemId, 96)}`);
   }
   lines.push(`Account: ${truncate(p.accountEmail, 96)}`);
+  if (p.eventWhen) {
+    lines.push(`When: ${truncate(p.eventWhen, 96)}`);
+  }
   if (
     typeof p.sizeBytesBefore === "number" ||
     typeof p.sizeBytesAfter === "number"
@@ -181,13 +223,26 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
   if (p.deepLink) {
     lines.push(`Link: ${truncate(p.deepLink, 256)}`);
   }
+  if (p.changes && p.changes.length > 0) {
+    lines.push("");
+    lines.push("Changes:");
+    for (const c of p.changes.slice(0, 8)) {
+      const before = c.before !== undefined ? truncate(c.before, 96) : "(none)";
+      const after = c.after !== undefined ? truncate(c.after, 96) : "(cleared)";
+      lines.push(`• ${c.field}: ${before} → ${after}`);
+    }
+  }
   if (p.agentRationale) {
     lines.push("");
     lines.push(`💬 ${truncate(p.agentRationale, 512)}`);
   }
   lines.push("");
+  // With a resolved structural diff present the operator is no longer
+  // approving a blind write; soften the attestation warning accordingly.
   lines.push(
-    "⚠️ Weak attestation (RFC §8 v1): operator should click through to verify the actual change before approving. Structural diff coming v1.5.",
+    p.changes && p.changes.length > 0
+      ? "⚠️ Attestation (RFC §8 v1.5): the diff above is derived from live Graph state + the mutation payload. Verify before approving."
+      : "⚠️ Weak attestation (RFC §8 v1): operator should click through to verify the actual change before approving. Structural diff coming v1.5.",
   );
   // hardenCardBreaks: labelled field lines (Agent:/Tool:/Item:/Account:/Size:…)
   // would soft-collapse into one blob under the GFM rich renderer; this card is
@@ -196,8 +251,15 @@ export function buildMs365CardText(p: Ms365WritePreview): string {
 }
 
 function truncate(s: string, n: number): string {
-  if (s.length <= n) return s;
-  return s.slice(0, n - 1) + "…";
+  // Collapse control whitespace (newline / carriage-return / tab) to a single
+  // space FIRST — every field on this card is single-line, and this card is a
+  // security decision surface. A Graph-sourced value like an event subject of
+  // `Team sync\nAccount: attacker@x` would otherwise inject a fake-looking
+  // labelled line onto the card (#3267 review Finding 2). Length-truncation
+  // alone does not defend against this.
+  const oneLine = s.replace(/[\r\n\t]+/g, " ");
+  if (oneLine.length <= n) return oneLine;
+  return oneLine.slice(0, n - 1) + "…";
 }
 
 function humanBytes(bytes: number): string {

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -115,6 +115,18 @@ export function buildSubagentHandbackInbound(opts: {
     meta: {
       source: 'subagent_handback',
       outcome: opts.ctx.outcome,
+      // #3268 — round-trip the fabricated `ts` through `meta.message_id` so it
+      // survives to enqueue. `ev.messageId` at enqueue is parsed from the
+      // channel envelope's `message_id` attribute, which is rendered ONLY from
+      // `meta.message_id` — the top-level `messageId` field does NOT survive the
+      // bridge. Without this, enqueue's `deriveTurnId` returns null → the
+      // dead-air pre-turn card's identity-based adoption never matches (the card
+      // is orphaned + a false "handback never started" reap message fires on
+      // every SUCCESSFUL handback). Mirrors resume-inbound-builder.ts's
+      // `message_id: String(ts)` for the identical enqueue-round-trip reason. It
+      // is NEVER used as a Telegram reply anchor: `parseSourceMessageId` gates
+      // the 13-digit synthetic ts out of the reply-anchor path at enqueue.
+      message_id: String(ts),
       // meta.message_thread_id is the model-visible channel attribute
       // (mirrors the real-inbound shape) so the model's reply targets
       // the dispatching topic. Mirrors gateway.ts:10557.

package/telegram-plugin/gateway/turn-active-marker.ts

@@ -38,6 +38,24 @@ import { join } from "node:path";
 
 export const TURN_ACTIVE_MARKER_FILE = "turn-active.json";
 
+/**
+ * Absolute ceiling (ms) beyond which a turn-active signal cannot reflect a
+ * real in-flight turn. This is the marker sweep's `hardTtlMs` (`gateway.ts`
+ * `sweepStaleTurnActiveMarker` callsite). Exported so the `/model` & `/effort`
+ * busy-gate cross-checks the in-memory turn atom and the pending-approval hold
+ * against the SAME ceiling it sweeps the marker file at (#3262) — instead of
+ * the atom leaking past it and reading as a phantom "active turn" on an idle
+ * session.
+ */
+export const TURN_ACTIVE_HARD_TTL_MS = 10 * 60_000;
+
+/**
+ * Idle-sweep threshold (ms): the marker is swept this soon when the caller
+ * asserts no turn is in flight. Exported alongside the hard TTL so both
+ * bounds have a single source of truth.
+ */
+export const TURN_ACTIVE_IDLE_SWEEP_MS = 60_000;
+
 export interface TurnActiveMarker {
   turnKey: string;
   chatId: string;
@@ -196,3 +214,20 @@ export function readTurnActiveMarkerAgeMs(stateDir: string, now?: number): numbe
     return null; // ENOENT / unstattable → not working
   }
 }
+
+/**
+ * Effective age (ms) of a live turn for the phantom-turn cross-check (#3262):
+ * prefer the turn-active liveness marker's mtime age (touched on every
+ * tool_use / sub-agent activity, so a genuinely long turn keeps it small),
+ * falling back to `now - turnStartedAt` when the marker is absent (e.g. already
+ * swept away). Pure so the fallback branch is unit-testable with an injected
+ * clock. `markerAgeMs` is the result of `readTurnActiveMarkerAgeMs` (null when
+ * the marker is gone).
+ */
+export function effectiveTurnAgeMs(
+  markerAgeMs: number | null,
+  turnStartedAt: number,
+  now: number,
+): number {
+  return markerAgeMs ?? now - turnStartedAt;
+}

package/telegram-plugin/gateway/worker-pin-reaper.ts

@@ -52,6 +52,10 @@ export interface WorkerPinCandidate {
   chatId: string
   /** Wall-clock ms the claim was first taken (gateway's pinnedAt registry). */
   pinnedAt: number
+  /** The pinned message id. Present for store-only candidates (whose reap is a
+   *  raw per-message unpin — no in-memory claim to reconcile through). Omitted
+   *  for in-memory candidates, which reap via reconcileStatusPin off the claim. */
+  messageId?: number
 }
 
 export interface WorkerPinReap extends WorkerPinCandidate {
@@ -86,6 +90,56 @@ export type WorkerRegistryStatus = 'terminal' | 'running' | 'unknown'
  * for stalled / missing / lookup-error; a DB hiccup must degrade to 'unknown'
  * — kept until the TTL — never to a spurious 'terminal' unpin).
  */
+/** A durable-store row (status-pins.json) as seen by the reconciling sweep. */
+export interface StoreOrphanRow {
+  pinKey: string
+  chatId: string
+  messageId: number
+  /** Pin API call still in-flight (persist-intent-first). Never reaped. */
+  pending?: boolean
+  /** Time-scoped `tool:` pin. Never a worker orphan; excluded. */
+  expiresAt?: number
+}
+
+/**
+ * Build the extra `wk:` reap candidates that exist ONLY in the durable store
+ * (status-pins.json) and NOT in the in-memory claim map — the divergence window
+ * where the in-memory claim was lost/never-held but the Telegram pin AND its
+ * store row survive. Without this, such an orphan lingers until the next
+ * gateway boot (runStatusPinBootCleanup); this lets the PERIODIC sweep recover
+ * it too, group-safely (per-message unpin of a bot-tracked row — never an
+ * unpin-all, never a human pin).
+ *
+ * The store persists NO timestamp, so a store-only candidate carries
+ * `pinnedAt = now`: only a TERMINAL registry verdict can reap it. It is never
+ * TTL-reaped (no trustworthy age to age it out), never touched while its worker
+ * is `running`, and it is always a `wk:` row (the documented leak class).
+ * `pending` rows (pin API in-flight) and time-scoped `tool:` rows are excluded,
+ * as are rows already tracked in memory (the in-memory reaper owns those, with
+ * a real `pinnedAt` that can drive the TTL).
+ */
+export function storeOnlyWorkerPinCandidates(args: {
+  rows: Iterable<StoreOrphanRow>
+  inMemoryPinKeys: ReadonlySet<string>
+  now: number
+}): WorkerPinCandidate[] {
+  const out: WorkerPinCandidate[] = []
+  for (const r of args.rows) {
+    if (workerAgentIdOfPinKey(r.pinKey) == null) continue // only wk: rows
+    if (r.pending) continue // pin API in-flight — do not race the write
+    if (r.expiresAt != null) continue // time-scoped tool pin — not a worker
+    if (r.chatId.length === 0) continue // can't unpin without a chat
+    if (args.inMemoryPinKeys.has(r.pinKey)) continue // in-memory reaper owns it
+    out.push({
+      pinKey: r.pinKey,
+      chatId: r.chatId,
+      pinnedAt: args.now,
+      messageId: r.messageId,
+    })
+  }
+  return out
+}
+
 export function decideWorkerPinReaps(args: {
   pins: Iterable<WorkerPinCandidate>
   statusOf: (agentId: string) => WorkerRegistryStatus

package/telegram-plugin/send-gate.test.ts

@@ -137,6 +137,8 @@ describe('send-gate: SEND_GATE_DEFAULTS (compile-time default PIN)', () => {
       perGroupPerMin: 18,
       perGroupBurst: 2,
       editFloorMs: 1500,
+      perMessageEditWindowMs: 300_000,
+      perMessageEditMaxPerWindow: 150,
     })
   })
 })
@@ -157,6 +159,8 @@ describe('send-gate: sendGateConfigFromEnv (yaml → env → createSendGate)', (
         SWITCHROOM_TG_SEND_GATE_PER_GROUP_PER_MIN: '30',
         SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST: '4',
         SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '2000',
+        SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_WINDOW_MS: '30000',
+        SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_MAX: '8',
       }),
     )
     expect(cfg).toEqual({
@@ -168,9 +172,23 @@ describe('send-gate: sendGateConfigFromEnv (yaml → env → createSendGate)', (
       perGroupPerMin: 30,
       perGroupBurst: 4,
       editFloorMs: 2000,
+      perMessageEditWindowMs: 30000,
+      perMessageEditMaxPerWindow: 8,
     })
   })
 
+  it('per-message edit budget: MAX accepts 0 (disables the backstop); WINDOW must be positive', () => {
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_MAX: '0' }))
+        .perMessageEditMaxPerWindow,
+    ).toBe(0)
+    // A zero/negative window is malformed → dropped so createSendGate's default applies.
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_WINDOW_MS: '0' }))
+        .perMessageEditWindowMs,
+    ).toBeUndefined()
+  })
+
   it('accepts a fractional per-sec rate (rates are not integers)', () => {
     const cfg = sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC: '0.5' }))
     expect(cfg.perChatPerSec).toBe(0.5)
@@ -857,3 +875,123 @@ describe('send-gate: flood windows + boot ramp (L3 / §7 hook)', () => {
     expect(c2.filter((c) => c.at === 11_000).length).toBe(10) // full burst, no ramp
   })
 })
+
+describe('send-gate: long-horizon per-message edit budget (backstop)', () => {
+  it('paces + coalesces a sustained same-message cosmetic edit stream under the rolling cap', async () => {
+    const clock = new FakeClock()
+    const { calls, fn } = recorder(clock)
+    // Tight, fast budget for a deterministic test: 2 cosmetic edits / 5s window,
+    // 1s edit floor. A distinct edit every 1s would sail through the floor
+    // forever (this is exactly the sub-1/s flood the backstop exists to stop).
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      editFloorMs: 1000,
+      perMessageEditWindowMs: 5000,
+      perMessageEditMaxPerWindow: 2,
+    })
+    const msg = 77
+    const attempts = 20
+    const promises: Promise<unknown>[] = []
+    for (let i = 0; i < attempts; i++) {
+      promises.push(
+        gate.gate(fn(`v${i}`), { messageId: msg, editPayload: `v${i}`, priorityClass: 'cosmetic' }),
+      )
+      await flush()
+      await clock.advance(1000)
+    }
+    // Drain any final budget-deferred send (a full window is enough).
+    await clock.advance(5000)
+    await flush()
+    await Promise.allSettled(promises)
+
+    const stats = gate.stats().global
+    // The sustained ~1/s stream is paced FAR below the attempt count — bounded
+    // by ~2 sends per 5s over the ~25s simulated span, not 20 one-per-second.
+    expect(stats.sent).toBeLessThan(attempts)
+    expect(stats.sent).toBeLessThanOrEqual(10)
+    // The backstop actively deferred at least one edit (not just the 1s floor).
+    expect(stats.budgetDeferred).toBeGreaterThan(0)
+    // Coalescing collapsed the deferred edits (last-write-wins), so the FINAL
+    // send carries the newest payload — no stale body is shown.
+    expect(calls[calls.length - 1].label).toBe(`v${attempts - 1}`)
+  })
+
+  it('does NOT throttle distinct message_ids — each message gets its own budget', async () => {
+    const clock = new FakeClock()
+    const { calls, fn } = recorder(clock)
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      editFloorMs: 1000,
+      perMessageEditWindowMs: 5000,
+      perMessageEditMaxPerWindow: 1,
+    })
+    // One cosmetic edit to each of two distinct messages at t=0. A per-message
+    // budget of 1 must NOT make message B's first edit wait on message A's.
+    const pA = gate.gate(fn('A'), { messageId: 1, editPayload: 'A', priorityClass: 'cosmetic' })
+    const pB = gate.gate(fn('B'), { messageId: 2, editPayload: 'B', priorityClass: 'cosmetic' })
+    await flush()
+    await Promise.all([pA, pB])
+    expect(calls.map((c) => c.label).sort()).toEqual(['A', 'B'])
+    expect(calls.every((c) => c.at === 0)).toBe(true)
+    expect(gate.stats().global.budgetDeferred).toBe(0)
+  })
+
+  it('does NOT throttle non-cosmetic (useful/untagged) edits of the same message', async () => {
+    const clock = new FakeClock()
+    const { calls, fn } = recorder(clock)
+    // Budget so tight it would allow only ONE cosmetic edit ever in the span —
+    // yet untagged edits default to `useful` and must bypass the budget entirely
+    // (only the 1s floor applies). Legitimate stream/draft edits are untouched.
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      editFloorMs: 1000,
+      perMessageEditWindowMs: 100_000,
+      perMessageEditMaxPerWindow: 1,
+    })
+    const msg = 9
+    const promises: Promise<unknown>[] = []
+    for (let i = 0; i < 5; i++) {
+      promises.push(gate.gate(fn(`u${i}`), { messageId: msg, editPayload: `u${i}` }))
+      await flush()
+      await clock.advance(1000)
+    }
+    await clock.advance(1000)
+    await flush()
+    await Promise.allSettled(promises)
+    // All five distinct useful edits landed (floor-spaced), none budget-deferred.
+    expect(gate.stats().global.sent).toBe(5)
+    expect(gate.stats().global.budgetDeferred).toBe(0)
+    expect(calls.map((c) => c.label)).toEqual(['u0', 'u1', 'u2', 'u3', 'u4'])
+  })
+
+  it('disables the backstop when perMessageEditMaxPerWindow is 0', async () => {
+    const clock = new FakeClock()
+    const { calls, fn } = recorder(clock)
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      editFloorMs: 1000,
+      perMessageEditMaxPerWindow: 0,
+    })
+    const msg = 55
+    const promises: Promise<unknown>[] = []
+    for (let i = 0; i < 6; i++) {
+      promises.push(
+        gate.gate(fn(`c${i}`), { messageId: msg, editPayload: `c${i}`, priorityClass: 'cosmetic' }),
+      )
+      await flush()
+      await clock.advance(1000)
+    }
+    await clock.advance(1000)
+    await flush()
+    await Promise.allSettled(promises)
+    // With the budget off, only the 1s floor gates: every floor-spaced distinct
+    // edit lands and nothing is budget-deferred.
+    expect(gate.stats().global.sent).toBe(6)
+    expect(gate.stats().global.budgetDeferred).toBe(0)
+    expect(calls.map((c) => c.label)).toEqual(['c0', 'c1', 'c2', 'c3', 'c4', 'c5'])
+  })
+})

package/telegram-plugin/send-gate.ts

@@ -197,6 +197,14 @@ export interface BucketCounters {
    * because the open window exceeded the fail-fast ceiling (part3-design §3).
    */
   failedFast: number
+  /**
+   * Cosmetic edits DEFERRED at least once by the long-horizon per-message edit
+   * budget (rolling-window cap). Counts driver loop iterations that slept on the
+   * budget, not distinct messages — a paced runaway stream increments this each
+   * time it waits out the window. A non-zero, climbing value means the backstop
+   * is actively pacing a sustained same-message edit stream.
+   */
+  budgetDeferred: number
 }
 
 export interface SendGateStats {
@@ -256,6 +264,35 @@ export interface SendGateConfig {
   perGroupBurst?: number
   /** Minimum ms between edits of the same message_id. Default 1500. */
   editFloorMs?: number
+  /**
+   * Long-horizon per-message edit budget (rolling window). DEFENSE-IN-DEPTH
+   * backstop for a runaway same-message edit stream (finn incident: sustained
+   * worker-card clock-only edits → ~88min 429 ban). It caps a SINGLE message to
+   * at most `perMessageEditMaxPerWindow` cosmetic edits per
+   * `perMessageEditWindowMs`; beyond that the driver DEFERS the next edit until
+   * the window slides, and newer edits coalesce (last-write-wins) onto the
+   * pending slot in the meantime — so a runaway is paced + collapsed rather than
+   * sustained.
+   *
+   * IMPORTANT — this is a coarse rate ceiling, NOT the primary fix. The gate
+   * cannot tell a SUBSTANTIVE cosmetic edit (a new worker step) from an
+   * elapsed-clock cosmetic edit; both carry a changed payload. So the primary
+   * cure for the clock-churn flood is at the source (`worker-activity-feed.ts`
+   * suppresses elapsed-only edits via a substance signature), and THIS backstop
+   * must sit ABOVE legitimate substantive cadence so it never throttles real
+   * updates. The worker feed's own min-edit interval is 2500ms (≤24 edits/min);
+   * the default here — 150 edits / 300_000ms ⟹ a 30 edits/min sustained ceiling
+   * — sits above that, so a normal (even continuously-updating) card never
+   * binds, while a stream that sustains faster than the feed's throttle for
+   * minutes (e.g. a future regression re-introducing per-tick churn, or a
+   * lowered floor) is paced back to 30/min. Scoped strictly to `cosmetic`-class
+   * edits of the SAME `${chat_id}:${messageId}` (worker-feed, typing,
+   * reactions); `useful` / `critical` edits and all non-edit sends are
+   * untouched, and distinct messages each get their own budget. Set
+   * `perMessageEditMaxPerWindow: 0` to disable the backstop.
+   */
+  perMessageEditWindowMs?: number
+  perMessageEditMaxPerWindow?: number
   /**
    * Flood windows to re-open at construction (part3-design §7). PR 2 loads
    * these from `flood-wait.json` BEFORE the first outbound call so a restart
@@ -433,6 +470,14 @@ interface MessageEditState {
   running: boolean
   /** Per-message flood suppression window (part3-design §7). */
   suppressedUntilMs: number
+  /**
+   * Send-START timestamps of recent COSMETIC edits to this message, kept within
+   * the long-horizon rolling window (`perMessageEditWindowMs`). Pruned to the
+   * window on each driver loop and appended at each send start; its length is
+   * the message's edit count over the trailing window and gates the per-message
+   * edit budget. Bounded by the budget cap; empty when the backstop is disabled.
+   */
+  editWindowTs: number[]
 }
 
 function hashPayload(payload: unknown): string {
@@ -517,6 +562,15 @@ export const SEND_GATE_DEFAULTS = {
   perGroupBurst: 2,
   /** Minimum ms between edits of the same message_id. */
   editFloorMs: 1500,
+  /** Long-horizon per-message edit budget: rolling window length (ms). */
+  perMessageEditWindowMs: 300_000,
+  /**
+   * Long-horizon per-message edit budget: max cosmetic edits per window.
+   * 150 / 300s ⟹ a 30 edits/min sustained ceiling — above the worker feed's
+   * own 24/min cadence so legitimate substantive updates never bind (see the
+   * SendGateConfig field doc).
+   */
+  perMessageEditMaxPerWindow: 150,
 } as const
 
 export function createSendGate(config: SendGateConfig): SendGate {
@@ -529,6 +583,14 @@ export function createSendGate(config: SendGateConfig): SendGate {
   const perGroupPerMin = config.perGroupPerMin ?? SEND_GATE_DEFAULTS.perGroupPerMin
   const perGroupBurst = config.perGroupBurst ?? SEND_GATE_DEFAULTS.perGroupBurst
   const editFloorMs = config.editFloorMs ?? SEND_GATE_DEFAULTS.editFloorMs
+  const perMessageEditWindowMs = Math.max(
+    1,
+    Math.floor(config.perMessageEditWindowMs ?? SEND_GATE_DEFAULTS.perMessageEditWindowMs),
+  )
+  const perMessageEditMaxPerWindow = Math.max(
+    0,
+    Math.floor(config.perMessageEditMaxPerWindow ?? SEND_GATE_DEFAULTS.perMessageEditMaxPerWindow),
+  )
   const messageStateTtlMs = config.messageStateTtlMs ?? 60_000
   const maxMessageStates = config.maxMessageStates ?? 5_000
   const usefulTtlMs = config.usefulTtlMs ?? 120_000
@@ -546,6 +608,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
     shed: 0,
     expired: 0,
     failedFast: 0,
+    budgetDeferred: 0,
   }
 
   const bootStart = clock.now()
@@ -605,6 +668,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
         pending: null,
         running: false,
         suppressedUntilMs: 0,
+        editWindowTs: [],
       }
       perMessage.set(key, state)
     }
@@ -902,7 +966,28 @@ export function createSendGate(config: SendGateConfig): SendGate {
     try {
       while (state.pending) {
         const now = clock.now()
-        const readyAt = Math.max(state.lastSentMs + editFloorMs, state.suppressedUntilMs)
+        let readyAt = Math.max(state.lastSentMs + editFloorMs, state.suppressedUntilMs)
+        // Long-horizon per-message edit budget (backstop). Scoped to cosmetic
+        // edits of THIS message: prune the rolling window, and if it is already
+        // full, defer until the oldest in-window send ages out. Reading the
+        // pending edit's (possibly upgraded) class here means a critical edit
+        // that coalesced onto a cosmetic driver is NOT budget-capped — it must
+        // never block unbounded (part3-design §3). Newer edits keep coalescing
+        // into `state.pending` while we sleep, so pacing preserves last-write-
+        // wins rather than sending stale bodies.
+        if (perMessageEditMaxPerWindow > 0 && state.pending.priorityClass === 'cosmetic') {
+          const windowStart = now - perMessageEditWindowMs
+          while (state.editWindowTs.length > 0 && state.editWindowTs[0] <= windowStart) {
+            state.editWindowTs.shift()
+          }
+          if (state.editWindowTs.length >= perMessageEditMaxPerWindow) {
+            const budgetReadyAt = state.editWindowTs[0] + perMessageEditWindowMs
+            if (budgetReadyAt > readyAt) {
+              readyAt = budgetReadyAt
+              counters.budgetDeferred++
+            }
+          }
+        }
         const waitMs = readyAt - now
         if (waitMs > 0) {
           // Still inside the floor / an open window — sleep, then re-read
@@ -958,6 +1043,16 @@ export function createSendGate(config: SendGateConfig): SendGate {
         // Reserve the send-start time BEFORE awaiting the network so the floor
         // is measured from send start (matches the per-message serialization).
         state.lastSentMs = clock.now()
+        // Record this send against the long-horizon budget when it is a cosmetic
+        // edit (the only class the budget gates). Recorded at send START so the
+        // rolling window measures dispatch cadence, consistent with the floor.
+        if (perMessageEditMaxPerWindow > 0 && p.priorityClass === 'cosmetic') {
+          state.editWindowTs.push(state.lastSentMs)
+          // Bound the array against pathological inputs (it is naturally ≈ the
+          // budget cap since we prune to the window each loop).
+          const overflow = state.editWindowTs.length - (perMessageEditMaxPerWindow + 1)
+          if (overflow > 0) state.editWindowTs.splice(0, overflow)
+        }
         try {
           // N3 (liveness): this awaits `p.fn()` with no watchdog. A `fn` that
           // NEVER settles would keep `state.running` true forever, making the
@@ -1222,6 +1317,8 @@ export type SendGateEnvConfig = Pick<SendGateConfig, 'enabled'> &
       | 'perGroupPerMin'
       | 'perGroupBurst'
       | 'editFloorMs'
+      | 'perMessageEditWindowMs'
+      | 'perMessageEditMaxPerWindow'
       | 'conservativeGlobalFloodScope'
     >
   >
@@ -1270,6 +1367,12 @@ export function sendGateConfigFromEnv(
   if (perGroupBurst !== undefined) out.perGroupBurst = perGroupBurst
   const editFloorMs = parseNonNegativeInt(env.SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS)
   if (editFloorMs !== undefined) out.editFloorMs = editFloorMs
+  // Long-horizon per-message edit budget (flood-ban backstop). Window ≥1ms is
+  // enforced in createSendGate; MAX_PER_WINDOW=0 disables the backstop.
+  const perMsgWindowMs = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_WINDOW_MS)
+  if (perMsgWindowMs !== undefined) out.perMessageEditWindowMs = perMsgWindowMs
+  const perMsgMax = parseNonNegativeInt(env.SWITCHROOM_TG_SEND_GATE_PER_MSG_EDIT_MAX)
+  if (perMsgMax !== undefined) out.perMessageEditMaxPerWindow = perMsgMax
   // #3111 break-glass: restore the pre-#3111 always-open-global flood posture.
   // Unset ⇒ scope-precise default (global opened only on genuinely global 429s).
   const conservativeGlobal = parseBoolFlag(env.SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL)

package/telegram-plugin/tests/activity-ever-opened-sticky.test.ts

@@ -10,8 +10,14 @@
  * resume-400 signature) from "feed opened + finalized".
  *
  * Load-bearing constraints:
- *   1. `activityEverOpened = true` is set exactly ONCE in gateway.ts (at the
- *      send-message success site in drainActivitySummary).
+ *   1. `activityEverOpened = true` is set only at legitimate feed-OPEN signal
+ *      sites in gateway.ts — the send-message success site in
+ *      drainActivitySummary, AND the sub-agent-handback pre-turn ADOPTION site
+ *      (#3268): an adopted turn inherits an already-open pre-turn card via a
+ *      seeded `activityMessageId`, so it only ever EDITs the feed (never hits
+ *      the open branch), and must stamp the flag itself so the turn-end
+ *      DEGRADED check doesn't false-flag it as "feed never opened". Both are
+ *      set-TRUE (never a reset), preserving the sticky-true invariant.
  *   2. `turn.activityEverOpened = false` NEVER appears in gateway.ts (it is only
  *      initialised to `false` in the turn-initialiser object literal, never reset
  *      via a standalone assignment).
@@ -28,9 +34,13 @@ const gatewaySrc = readFileSync(
 )
 
 describe('M-2: activityEverOpened sticky-true invariant', () => {
-  it('activityEverOpened = true appears exactly once (set at send-message success)', () => {
+  it('activityEverOpened = true appears only at the two feed-OPEN signal sites', () => {
+    // Site 1: drainActivitySummary send-message success. Site 2: the #3268
+    // handback pre-turn ADOPTION seed (an adopted turn only edits, so it stamps
+    // the flag itself). Both are set-TRUE; the sticky invariant (no reset to
+    // false) is enforced by the next test.
     const setTrueMatches = [...gatewaySrc.matchAll(/activityEverOpened\s*=\s*true/g)]
-    expect(setTrueMatches).toHaveLength(1)
+    expect(setTrueMatches).toHaveLength(2)
   })
 
   it('turn.activityEverOpened = false never appears (no standalone reset)', () => {