switchroom 0.18.14 → 0.18.17

package/telegram-plugin/stream-controller.ts

@@ -19,9 +19,14 @@
  * entire server.ts top-level initialization.
  */
 
-import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
+import {
+  createDraftStream,
+  makeDraftEditShedError,
+  type DraftStreamHandle,
+} from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
 import { renderOutboundChunks } from './render/rich-render.js'
+import { isSendGateShed, type SendGateOpts } from './send-gate.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -77,9 +82,21 @@ export interface StreamSendOpts {
   disable_notification?: boolean
 }
 
+/**
+ * Options a stream-controller call passes to its retry wrapper. A structural
+ * superset of `SendGateOpts` (send-gate.ts) plus the retry policy's own
+ * `threadId`, and assignable to `RetryCallOpts` (retry-api-call.ts) — so the
+ * production wrapper (`robustApiCall` = send gate over `createRetryApiCall`)
+ * receives `messageId` / `editPayload` / `priorityClass` and the gate's
+ * per-message edit floor, last-write-wins coalescing, no-op skip and
+ * cosmetic shedding govern the draft/answer stream (#3110; part3-design §4
+ * names rapid same-message editMessageText as the #1 flood-ban trigger).
+ */
+export type RetryPolicyOpts = SendGateOpts & { threadId?: number }
+
 export type RetryPolicy = <T>(
   fn: () => Promise<T>,
-  opts?: { threadId?: number; chat_id?: string },
+  opts?: RetryPolicyOpts,
 ) => Promise<T>
 
 export interface StreamControllerConfig {
@@ -251,6 +268,70 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
   }
 
+  // ---- Send-gate wiring for the edit path (#3110) -------------------------
+  //
+  // Every edit call passes `messageId` / `editPayload` / `priorityClass`
+  // through the retry wrapper so the send gate's per-message edit floor
+  // (>=1.5s), last-write-wins coalescing, and no-op skip govern the draft
+  // stream — previously these edits carried only `{ threadId, chat_id }`,
+  // so the gate treated them as ordinary sends and the stream's own 400 ms
+  // DM throttle drove same-message editMessageText well under the floor
+  // (the #1 documented flood-ban trigger, part3-design §4; production ban
+  // 2026-07-12 on #3110). The local per-surface throttle stays as a cheap
+  // pre-filter; the gate is the authority.
+  //
+  // Priority classes: intermediate draft edits are `cosmetic` (part3-design
+  // §2 lists "stream updates" there) — shed under pressure / an open flood
+  // window; the next flush carries full state. The FINALIZE flush (the edit
+  // that renders the completed answer) is `critical`, mirroring the reply
+  // path's preview-finalize convention (gateway.ts editPreview): never shed,
+  // waits out a short window, fails fast with a structured FLOOD_WAIT_ACTIVE
+  // on a long one. SENDS stay untagged (the gate admits untagged non-edit
+  // sends as `critical`) — a shed send would resolve the gate's shed
+  // sentinel instead of `{ message_id }` and break message-id capture, and
+  // the anchor/tail sends ARE the answer surface.
+  //
+  // `handleRef.isFinal()` is true from the moment finalize() is entered
+  // (draft-stream sets `final` before its last flush), so the closures below
+  // classify exactly the finalize flush — and anything after it — as
+  // critical. The ref is assigned right after createDraftStream returns,
+  // before any closure can run (closures only fire from update/finalize).
+  //
+  // KNOWN MISSED BENEFIT (review F5, deliberate): the gate's last-write-wins
+  // coalescing never engages for THIS surface, because draft-stream
+  // serializes its flushes — it awaits each edit before issuing the next, so
+  // at most one edit per message is ever inside the gate. Consequence: a
+  // stale draft sleeping on the gate's floor still lands (one API call the
+  // coalescer would have replaced) before the newer snapshot, and a finalize
+  // issued mid-floor can trail by up to ~2x editFloorMs (floor wait for the
+  // stale draft, then floor wait for the final). Correctness is unaffected —
+  // the latest state always lands, floor-paced — and the gate coalescing
+  // remains live protection for CONCURRENT writers to one message (e.g. a
+  // re-attached #626 controller racing its predecessor).
+  let handleRef: DraftStreamHandle | null = null
+  const editGateOpts = (id: number, payload: unknown): RetryPolicyOpts => ({
+    threadId,
+    chat_id: chatId,
+    messageId: id,
+    editPayload: payload,
+    priorityClass: handleRef?.isFinal() === true ? 'critical' : 'cosmetic',
+  })
+  // The rendered payload the gate hashes for the no-op skip / coalescing —
+  // exactly what goes over the wire (rich wrapper included), so a plain
+  // fallback of the same text never hashes equal to its rich form.
+  const piecePayload = (piece: { text: string; rich: boolean }): unknown =>
+    piece.rich ? richMessage(piece.text) : piece.text
+  // Shed detection (#3110 review F1): keyed EXACTLY off the gate's
+  // SEND_GATE_SHED sentinel — never off `undefined`, which is overloaded
+  // (gate no-op drop; robustApiCall's swallowed benign 400s like "message is
+  // not modified"). Those benign cases mean the payload is ALREADY on screen
+  // and are treated as delivered, exactly as before this wiring existed. A
+  // true shed means the edit did NOT land: draft-stream must not record the
+  // snapshot as on-screen (its dedupe would skip a later flush of the same
+  // text — the completed answer would never render), so the edit closure
+  // throws the marker error draft-stream recognizes and recovers from
+  // (`makeDraftEditShedError` → snapshot preserved for finalize, review F2).
+
   // Overflow-tail bookkeeping, shared across the send + edit closures for the
   // whole stream lifetime. A body large enough to split into several
   // wire-cap pieces anchors on piece[0] (edited in place by draft-stream) and
@@ -269,12 +350,25 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // text) thereafter. A non-parse failure is logged as a partial-delivery
   // warning and swallowed so the remaining tail pieces still get a chance to
   // land — never a silent drop, never an abort of pieces K..N (concern C1).
-  const upsertTail = async (ti: number, piece: { text: string; rich: boolean }): Promise<void> => {
+  //
+  // Returns TRUE when this piece's edit was SHED by the send gate (did not
+  // land): the caller must then report the whole flush as shed so
+  // draft-stream does not record the full body as delivered while a tail is
+  // stale (review F3). The piece's own tailLastText stays stale too, so the
+  // recovery flush re-attempts exactly the shed piece.
+  const upsertTail = async (
+    ti: number,
+    piece: { text: string; rich: boolean },
+  ): Promise<boolean> => {
     const existingId = tailIds[ti]
     if (existingId != null) {
-      if (tailLastText[ti] === piece.text) return // unchanged — skip the API call
+      if (tailLastText[ti] === piece.text) return false // unchanged — skip the API call
       try {
-        await retry(() => editPiece(existingId, piece, baseOpts), { threadId, chat_id: chatId })
+        const res = await retry(
+          () => editPiece(existingId, piece, baseOpts),
+          editGateOpts(existingId, piecePayload(piece)),
+        )
+        if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
         tailLastText[ti] = piece.text
         onEdit?.(existingId, piece.text.length)
       } catch (err) {
@@ -282,10 +376,11 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           warn?.(
             `stream-controller: tail-piece #${ti + 1} edit parse-entities rejected — retrying same id=${existingId} as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, existingId, piece.text, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(existingId, piece.text),
           )
+          if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
           tailLastText[ti] = piece.text
           onEdit?.(existingId, piece.text.length)
         } else {
@@ -296,7 +391,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           )
         }
       }
-      return
+      return false
     }
     // First emission of this tail piece → a fresh follow-up message.
     try {
@@ -324,9 +419,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
         )
       }
     }
+    // First-emission SENDS are untagged (critical) — the gate never sheds
+    // them, so this path can only land or fail (handled above).
+    return false
   }
 
-  return createDraftStream(
+  const handle = createDraftStream(
     async (text) => {
       // Render → 1+ cap-respecting pieces. The FIRST piece's message_id anchors
       // the stream (later edits target it); any overflow pieces are parked as
@@ -378,14 +476,26 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     async (id, text) => {
       const pieces = renderPieces(text)
       const head = pieces[0]
+      // Whether any piece of THIS flush was shed by the gate (did not land).
+      // Decided at the very end — AFTER the tail loop — so a benign anchor
+      // outcome (or even a shed anchor) never starves the tail pieces of
+      // their own upsert attempt (review F1: an anchor whose payload stopped
+      // changing resolves benignly every flush while only the tail grows).
+      let anchorShed = false
       // Edit the anchor message in place with the FIRST piece.
       try {
-        await retry(
-          () => editPiece(id, head, baseOpts),
-          { threadId, chat_id: chatId },
-        )
-        // C2: report the actual head-piece length, not the full body length.
-        onEdit?.(id, head.text.length)
+        const res = await retry(() => editPiece(id, head, baseOpts), editGateOpts(id, piecePayload(head)))
+        if (isSendGateShed(res)) {
+          // Shed by the gate (cosmetic under pressure / an open flood
+          // window) — did NOT land. Benign `undefined` resolutions (gate
+          // no-op drop, robustApiCall's swallowed "message is not modified")
+          // deliberately do NOT take this branch: the payload is already on
+          // screen and the flush proceeds as delivered.
+          anchorShed = true
+        } else {
+          // C2: report the actual head-piece length, not the full body length.
+          onEdit?.(id, head.text.length)
+        }
       } catch (err) {
         if (!literalText && head.rich && isParseEntitiesError(err)) {
           // Edit rejected because the markdown couldn't be parsed — DO NOT
@@ -400,11 +510,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           // contract). For a single-piece stream (common case) this is the
           // whole body; a rare oversize split edits the head piece's body.
           const fallbackBody = pieces.length === 1 ? text : head.text
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, id, fallbackBody, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(id, fallbackBody),
           )
-          onEdit?.(id, head.text.length)
+          if (isSendGateShed(res)) anchorShed = true
+          else onEdit?.(id, head.text.length)
         } else {
           throw err
         }
@@ -414,10 +525,20 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       // that only just came into existence) — we never re-send tails already
       // emitted on a prior flush. This is the fix for the duplicate-flood
       // blocker: the previous code re-sent pieces[1..n] as brand-new messages
-      // on each throttled edit tick.
+      // on each throttled edit tick. Runs BEFORE the shed decision below so a
+      // shed (or benign) anchor never starves the tails (review F1).
+      let anyTailShed = false
       for (let pi = 1; pi < pieces.length; pi++) {
-        await upsertTail(pi - 1, pieces[pi])
+        if (await upsertTail(pi - 1, pieces[pi])) anyTailShed = true
       }
+      // Review F3: ANY shed piece — anchor or tail — means this flush did not
+      // fully land. Throw the marker error so draft-stream does not record
+      // the body as delivered (its dedupe would freeze the shed piece
+      // forever) and instead preserves the snapshot for the finalize
+      // re-flush. Pieces that DID land are unaffected on that re-flush: the
+      // gate's no-op skip drops their identical payloads before the API, and
+      // landed tails short-circuit on tailLastText.
+      if (anchorShed || anyTailShed) throw makeDraftEditShedError(id)
     },
     {
       ...(throttleMs != null ? { throttleMs } : {}),
@@ -429,4 +550,6 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       chatId,
     },
   )
+  handleRef = handle
+  return handle
 }

package/telegram-plugin/stream-reply-handler.ts

@@ -516,10 +516,20 @@ export async function handleStreamReply(
     state.activeDraftStreams.set(sKey, stream)
   }
 
-  await stream.update(effectiveText)
+  if (!done) {
+    // Intermediate snapshot — an ordinary throttled draft update.
+    await stream.update(effectiveText)
+  }
 
   if (done) {
-    await stream.finalize()
+    // #3110: route the FINAL text through finalize(text) so the flush that
+    // renders the completed answer runs with the stream already final —
+    // stream-controller then classifies that edit `critical` for the send
+    // gate (never shed; fails fast with a structured FLOOD_WAIT_ACTIVE on a
+    // long flood window) while intermediate draft edits stay `cosmetic`
+    // (sheddable). The previous update()-then-finalize() pair flushed the
+    // final text inside update(), i.e. as an ordinary sheddable draft edit.
+    await stream.finalize(effectiveText)
     state.activeDraftStreams.delete(sKey)
     // #1713: stream_reply done=true is a NON-EVENT for the status
     // reaction. The reaction reflects current turn activity, not

package/telegram-plugin/tests/bot-api.harness.ts

@@ -84,7 +84,11 @@ export function createMockBot(startMessageId = 500): MockBot {
   const api: MockBotApi = {
     sendMessage: vi.fn(async () => ({ message_id: state.nextMessageId++ })),
     sendRichMessage: vi.fn(async () => ({ message_id: state.nextMessageId++ })),
-    editMessageText: vi.fn(async () => undefined),
+    // Faithful to grammy: editMessageText resolves `Message | true`, NEVER
+    // undefined. An `undefined` from the production retry stack means the
+    // send gate shed/skipped the call (#3110) — stream-controller treats it
+    // as not-landed — so the mock default must not be undefined.
+    editMessageText: vi.fn(async () => true as const),
     deleteMessage: vi.fn(async () => true as const),
     setMessageReaction: vi.fn(async () => true as const),
     editMessageReplyMarkup: vi.fn(async () => undefined),
@@ -122,7 +126,8 @@ export function installBotResetHook(bot: MockBot): void {
     bot.api.sendRichMessage.mockImplementation(async () => ({
       message_id: bot.nextMessageId++,
     }))
-    bot.api.editMessageText.mockImplementation(async () => undefined)
+    // Faithful to grammy: `Message | true`, never undefined (see above).
+    bot.api.editMessageText.mockImplementation(async () => true as const)
     bot.api.deleteMessage.mockImplementation(async () => true as const)
     bot.api.setMessageReaction.mockImplementation(async () => true as const)
     bot.api.editMessageReplyMarkup.mockImplementation(async () => undefined)

package/telegram-plugin/tests/draft-stream.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { createDraftStream } from '../draft-stream.js'
+import { createDraftStream, makeDraftEditShedError } from '../draft-stream.js'
 
 interface MockTelegram {
   send: (text: string) => Promise<number>
@@ -137,6 +137,115 @@ describe('createDraftStream', () => {
     expect(stream.isFinal()).toBe(true)
   })
 
+  it('finalize(finalText) flushes the supplied snapshot with the stream already final (#3110)', async () => {
+    const m = makeMock()
+    // Capture what isFinal() reads AT EDIT TIME — the transport layer
+    // (stream-controller) classifies the send-gate priority from exactly
+    // this signal, so the final snapshot MUST flush with final=true.
+    const finalAtEdit: boolean[] = []
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        finalAtEdit.push(stream.isFinal())
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('initial')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    // A stale draft is pending; finalize(text) supersedes it (last-write-wins).
+    void stream.update('stale draft')
+    await microtaskFlush()
+    await stream.finalize('the completed answer')
+
+    expect(m.editCalls.length).toBe(1)
+    expect(m.editCalls[0].text).toBe('the completed answer')
+    expect(finalAtEdit).toEqual([true])
+    expect(stream.isFinal()).toBe(true)
+  })
+
+  it('a shed flush preserves the snapshot; argument-less finalize() re-delivers it (#3110 F2)', async () => {
+    const m = makeMock()
+    let shedNext = true
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        if (shedNext) {
+          shedNext = false
+          throw makeDraftEditShedError(id)
+        }
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('v1')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    void stream.update('v2 — shed by the gate')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    // The edit was shed: nothing landed, and the snapshot must NOT be
+    // recorded as sent.
+    expect(m.editCalls.length).toBe(0)
+
+    // The gateway's cleanup paths finalize with NO argument — the shed
+    // snapshot must be re-flushed as the stream's final state, not lost.
+    await stream.finalize()
+    expect(m.editCalls.length).toBe(1)
+    expect(m.editCalls[0].text).toBe('v2 — shed by the gate')
+  })
+
+  it('a newer landed flush supersedes an earlier shed snapshot (no stale resurrect)', async () => {
+    const m = makeMock()
+    let shedNext = true
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        if (shedNext) {
+          shedNext = false
+          throw makeDraftEditShedError(id)
+        }
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('v1')
+    await microtaskFlush()
+    void stream.update('v2 — shed')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    expect(m.editCalls.length).toBe(0)
+
+    // A NEWER snapshot lands normally — the shed one is now stale.
+    void stream.update('v3 — landed')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    expect(m.editCalls.map((c) => c.text)).toEqual(['v3 — landed'])
+
+    // finalize() must NOT resurrect the superseded shed snapshot.
+    await stream.finalize()
+    expect(m.editCalls.map((c) => c.text)).toEqual(['v3 — landed'])
+  })
+
+  it('finalize(finalText) still dedupes against text that actually landed', async () => {
+    const m = makeMock()
+    const stream = createDraftStream(m.send, m.edit, { throttleMs: 1000 })
+
+    void stream.update('the answer')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    // Same text again as the final snapshot → already on screen, no edit.
+    await stream.finalize('the answer')
+    expect(m.editCalls.length).toBe(0)
+  })
+
   it('updates after finalize are silently dropped', async () => {
     const m = makeMock()
     const stream = createDraftStream(m.send, m.edit, { throttleMs: 1000 })

package/telegram-plugin/tests/effort-command.test.ts

@@ -107,7 +107,7 @@ describe("effort-command: handler", () => {
     const { deps } = makeDeps({ getConfiguredEffort: () => "medium" });
     const r = await handleEffortCommand({ kind: "show" }, deps);
     expect(r.text).toContain("medium");
-    expect(r.text).toMatch(/persists across restarts and deploys/);
+    expect(r.text).toMatch(/lasts until the agent’s next restart/);
   });
 
   it("show falls back to low when effort is unreadable", async () => {
@@ -121,7 +121,7 @@ describe("effort-command: handler", () => {
     const r = await handleEffortCommand({ kind: "set", level: "high" }, deps);
     expect(calls).toEqual([{ agent: "carrie", level: "high" }]);
     expect(r.text).toContain("Set effort level to high");
-    expect(r.text).toMatch(/persists across restarts and deploys/);
+    expect(r.text).toMatch(/lasts until the agent’s next restart/);
   });
 
   it("set notes the re-read cost when a confirmation was needed", async () => {
@@ -249,9 +249,9 @@ describe("effort-command: /effort default (#3039)", () => {
     expect(marked?.text).toBe("✅ max");
   });
 
-  it("help text advertises /effort default and the sticky contract", async () => {
+  it("help text advertises /effort default and the session-only contract", async () => {
     const r = await handleEffortCommand({ kind: "help" }, makeDeps().deps);
     expect(r.text).toContain("/effort default");
-    expect(r.text).toContain("persists across restarts and deploys");
+    expect(r.text).toContain("lasts until the agent’s next restart");
   });
 });

package/telegram-plugin/tests/flood-windows-persistence.test.ts

@@ -14,7 +14,7 @@ import {
   FLOOD_STATE_MODE,
   FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
 } from '../flood-circuit-breaker.js'
-import { createSendGate, type Clock } from '../send-gate.js'
+import { createSendGate, SEND_GATE_SHED, type Clock } from '../send-gate.js'
 
 /**
  * #3084 PR 2 — restart-proof SCOPED flood windows (part3-design §7). Verifies
@@ -119,7 +119,7 @@ describe('#3084 scoped flood-window persistence', () => {
       chat_id: '7',
       priorityClass: 'cosmetic',
     })
-    expect(res).toBeUndefined()
+    expect(res).toBe(SEND_GATE_SHED) // shed sentinel (#3110 F1)
     expect(gate2.stats().global.shed).toBe(1)
 
     // And a critical into the still-long window fails fast — restart did not

package/telegram-plugin/tests/gateway-pending-command-wiring.test.ts

@@ -89,36 +89,50 @@ describe('gateway: unconfirmed queued model tokens are gated before durable pers
   })
 })
 
-describe('gateway: /restart keeps the session-model override (#3039)', () => {
-  it('the /restart chat command stamps keep, never revert', () => {
-    expect(GATEWAY_SRC).toContain("writeRelaunchModelIntent(smDir, 'keep', 'user: /restart from chat')")
-    expect(GATEWAY_SRC).not.toContain("writeRelaunchModelIntent(smDir, 'revert'")
+describe('gateway: /restart reverts the session-model override (rev 4, session-scoped)', () => {
+  it('no restart verb stamps a relaunch-model intent (the subsystem is retired)', () => {
+    expect(GATEWAY_SRC).not.toContain('writeRelaunchModelIntent')
   })
 })
 
-describe('gateway: /effort persistence choke point (#3039)', () => {
-  it('buildEffortDeps persists a confirmed apply to .session-effort and wires clearSessionEffort', () => {
+describe('gateway: /effort is session-scoped (#3186)', () => {
+  it('buildEffortDeps records a confirmed live apply IN MEMORY only — no durable carrier write', () => {
     const fnIdx = GATEWAY_SRC.indexOf('function buildEffortDeps(')
     expect(fnIdx).toBeGreaterThan(0)
     const win = GATEWAY_SRC.slice(fnIdx, fnIdx + 2500)
-    expect(win).toContain('writeSessionEffortFile(')
+    expect(win).not.toContain('writeSessionEffortFile(')
+    expect(win).toContain('sessionEffortOverride = level')
+    // /effort default clears the in-memory level AND any leftover carrier.
+    expect(win).toContain('sessionEffortOverride = null')
     expect(win).toContain('clearSessionEffortFile(')
-    expect(win).toContain('readSessionEffortFile(')
   })
-})
 
-describe('gateway: keep-intent stamp narrowing (#3018 finding 4)', () => {
-  it('the shutdown keep-intent stamp carries the gateway-shutdown reason prefix', () => {
-    expect(GATEWAY_SRC).toContain(
-      "writeRelaunchModelIntent(smDir, 'keep', `${GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX} graceful ${signal} shutdown",
-    )
+  it('the queued-command shutdown persist is the ONLY .session-effort writer', () => {
+    const writes = [...GATEWAY_SRC.matchAll(/writeSessionEffortFile\(/g)]
+    expect(writes.length).toBe(1)
+    const fnIdx = GATEWAY_SRC.indexOf('function persistQueuedCommandForRestart(')
+    expect(fnIdx).toBeGreaterThan(0)
+    expect(writes[0].index).toBeGreaterThan(fnIdx)
+    expect(writes[0].index).toBeLessThan(fnIdx + 3000)
   })
 
-  it('boot clears a stale gateway-shutdown-stamped intent (gateway-only bounce never runs start.sh)', () => {
-    const idx = GATEWAY_SRC.indexOf('clearStaleGatewayShutdownIntent(bootSmDir)')
+  it('boot re-hydrates the in-memory effort override from .active-session-effort', () => {
+    const idx = GATEWAY_SRC.indexOf("join(smAgentDir, '.active-session-effort')")
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 800)
+    expect(win).toContain('getConfiguredEffortForPersist()')
+    expect(win).toContain('sessionEffortOverride =')
+  })
+})
+
+describe('gateway: graceful shutdown no longer preserves a session model (rev 4)', () => {
+  it('the shutdown handler stamps no keep-intent — a deploy reverts to config', () => {
+    const idx = GATEWAY_SRC.indexOf('async function shutdown(signal: string)')
     expect(idx).toBeGreaterThan(0)
-    // The cleanup runs at module top-level (gateway boot), BEFORE the shutdown
-    // handler could stamp a fresh one for THIS process's own exit.
-    expect(idx).toBeLessThan(GATEWAY_SRC.indexOf('async function shutdown(signal: string)'))
+    const win = GATEWAY_SRC.slice(idx, idx + 6000)
+    expect(win).not.toContain('writeRelaunchModelIntent')
+    expect(win).not.toContain('GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX')
+    // The queued-command persist at shutdown still writes a consume-once carrier.
+    expect(win).toContain('persistQueuedCommandForRestart')
   })
 })