switchroom 0.18.19 → 0.18.21

package/dist/cli/ms-365-write-pretool.mjs

@@ -16,31 +16,89 @@ var GATEWAY_SOCKET = process.env.SWITCHROOM_GATEWAY_SOCKET ?? (process.env.TELEG
 var KERNEL_SOCKET = process.env.SWITCHROOM_KERNEL_SOCKET ?? "/run/switchroom/kernel/sock";
 var TOOL_PREFIX = "mcp__ms-365__";
 var GATED_MS365_WRITE_TOOLS = new Set([
+  "create-calendar",
+  "update-calendar",
+  "delete-calendar",
+  "create-calendar-event",
+  "create-specific-calendar-event",
+  "update-calendar-event",
+  "update-specific-calendar-event",
+  "delete-calendar-event",
+  "delete-specific-calendar-event",
+  "accept-calendar-event",
+  "decline-calendar-event",
+  "tentatively-accept-calendar-event",
+  "cancel-calendar-event",
+  "forward-calendar-event",
+  "dismiss-calendar-event-reminder",
+  "snooze-calendar-event-reminder",
+  "create-my-calendar-permission",
+  "update-my-calendar-permission",
+  "delete-my-calendar-permission",
+  "send-mail",
+  "send",
+  "update-mail-message",
+  "delete-mail-message",
+  "move-mail-message",
+  "copy-mail-message",
+  "reply-mail-message",
+  "reply-all-mail-message",
+  "forward-mail-message",
+  "create-mail-attachment-upload-session",
+  "add-mail-attachment",
+  "delete-mail-attachment",
+  "create-mail-folder",
+  "create-mail-child-folder",
+  "update-mail-folder",
+  "delete-mail-folder",
+  "create-mail-rule",
+  "update-mail-rule",
+  "delete-mail-rule",
+  "update-mailbox-settings",
   "upload-file-content",
   "create-upload-session",
-  "create-event",
-  "update-event",
-  "delete-event",
-  "update-message",
-  "delete-message"
+  "create-onedrive-folder",
+  "delete-onedrive-file",
+  "move-rename-onedrive-item",
+  "copy-drive-item",
+  "share-drive-item",
+  "create-drive-item-share-link",
+  "delete-drive-item-permission"
 ]);
 var KNOWN_SAFE_MS365_READ_TOOLS = new Set([
-  "list-files",
-  "list-drive-items",
-  "get-drive-item",
-  "download-bytes",
-  "search-files",
-  "list-events",
-  "get-event",
   "list-calendars",
-  "get-calendar",
-  "list-messages",
-  "get-message",
-  "search-mail",
+  "get-calendar-view",
+  "get-specific-calendar-view",
+  "list-calendar-events",
+  "list-specific-calendar-events",
+  "get-calendar-event",
+  "get-specific-calendar-event",
+  "list-calendar-event-instances",
+  "list-calendar-events-delta",
+  "list-calendar-view-delta",
+  "list-my-calendar-permissions",
+  "list-mail-messages",
+  "get-mail-message",
+  "get-mail-message-mime",
   "list-mail-folders",
-  "get-mail-folder",
-  "whoami",
-  "get-current-user"
+  "list-mail-child-folders",
+  "list-mail-folder-messages",
+  "list-mail-folder-messages-delta",
+  "list-mail-attachments",
+  "list-mail-rules",
+  "get-mail-tips",
+  "get-mailbox-settings",
+  "create-draft-email",
+  "get-drive-item",
+  "get-drive-root-item",
+  "download-bytes",
+  "list-drives",
+  "list-folder-files",
+  "search-onedrive-files",
+  "get-drive-delta",
+  "login",
+  "verify-login",
+  "list-accounts"
 ]);
 function isGatedMs365Tool(toolName) {
   if (!toolName.startsWith(TOOL_PREFIX))
@@ -52,6 +110,18 @@ function isGatedMs365Tool(toolName) {
     return false;
   return true;
 }
+function loadAllowFrom() {
+  const stateDir = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), ".claude", "channels", "telegram");
+  const accessPath = join(stateDir, "access.json");
+  try {
+    const raw = readFileSync(accessPath, "utf8");
+    const j = JSON.parse(raw);
+    if (Array.isArray(j.allowFrom)) {
+      return j.allowFrom.filter((s) => typeof s === "string");
+    }
+  } catch {}
+  return [];
+}
 function readStdin() {
   try {
     return readFileSync(0, "utf8");
@@ -254,9 +324,10 @@ async function main() {
   }
   const requestId = response.requestId;
   const deadline = response.expiresAtMs ?? Date.now() + HOOK_TIMEOUT_MS;
+  const approverSet = loadAllowFrom();
   while (Date.now() < deadline) {
     await new Promise((r) => setTimeout(r, KERNEL_POLL_INTERVAL_MS));
-    const lookup = await approvalLookupByRequest(agentName, requestId, []);
+    const lookup = await approvalLookupByRequest(agentName, requestId, approverSet);
     if (!lookup)
       continue;
     const state = lookup.state;
@@ -275,6 +346,7 @@ if (__require.main == __require.module) {
   });
 }
 export {
+  loadAllowFrom,
   isGatedMs365Tool,
   extractMs365Preview,
   KNOWN_SAFE_MS365_READ_TOOLS,

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.18.19", COMMIT_SHA = "34c72776";
+var VERSION = "0.18.21", COMMIT_SHA = "c237ff59";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -15464,11 +15464,12 @@ async function injectSlashCommand(agentName, command, opts = {}) {
     session,
     command: command.trim(),
     settleMs,
-    timeoutMs
+    timeoutMs,
+    precondition: opts.precondition
   }));
 }
 async function injectSlashCommandWith(runner, args) {
-  const { socket, session, command, settleMs, timeoutMs } = args;
+  const { socket, session, command, settleMs, timeoutMs, precondition } = args;
   let bareVerb;
   try {
     bareVerb = validateInjectCommand(command);
@@ -15498,6 +15499,17 @@ async function injectSlashCommandWith(runner, args) {
       errorMessage: `tmux session "${session}" on socket "${socket}" not found. ` + `Is the agent running under the tmux supervisor (the default)? ` + `If experimental.legacy_pty=true is set, inject is unsupported.`
     };
   }
+  if (precondition && !precondition()) {
+    return {
+      outcome: "skipped",
+      output: "",
+      truncated: false,
+      command: bareVerb,
+      meta,
+      errorCode: "precondition_failed",
+      errorMessage: "inject precondition returned false at write time; send aborted " + "(no keys sent)."
+    };
+  }
   const before = runner.capture(socket, session) ?? "";
   try {
     runner.send(socket, session, ["send-keys", "-l", command]);
@@ -23787,6 +23799,14 @@ function renderDevProtocolFragment(context = {}, profilesRoot = PROFILES_ROOT) {
   const template = import_handlebars.default.compile(source, { noEscape: true });
   return template(context).trimEnd();
 }
+function renderDelegationGoldenRuleFragment(context = {}, profilesRoot = PROFILES_ROOT) {
+  const fragPath = join4(resolve4(profilesRoot, "_shared"), "delegation-golden-rule.md.hbs");
+  if (!existsSync7(fragPath))
+    return "";
+  const source = readFileSync7(fragPath, "utf-8");
+  const template = import_handlebars.default.compile(source, { noEscape: true });
+  return template(context).trimEnd();
+}
 function renderReplyDisciplineFragment(context = {}, profilesRoot = PROFILES_ROOT) {
   const fragPath = join4(resolve4(profilesRoot, "_shared"), "reply-discipline.md.hbs");
   if (!existsSync7(fragPath))
@@ -27567,6 +27587,13 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
             rendered = rendered.trimEnd() + `
 
 ` + devProtocol + `
+`;
+          }
+          const delegationGoldenRule = renderDelegationGoldenRuleFragment(context);
+          if (delegationGoldenRule) {
+            rendered = rendered.trimEnd() + `
+
+` + delegationGoldenRule + `
 `;
           }
         }
@@ -28450,6 +28477,13 @@ ${baseAppend}` : TELEGRAM_FORMATTING_FLOOR_CARD;
         rendered = rendered.trimEnd() + `
 
 ` + devProtocol + `
+`;
+      }
+      const delegationGoldenRule = renderDelegationGoldenRuleFragment(claudeContext);
+      if (delegationGoldenRule) {
+        rendered = rendered.trimEnd() + `
+
+` + delegationGoldenRule + `
 `;
       }
       if (agentConfig.claude_md_raw) {
@@ -63192,7 +63226,15 @@ function detectTurnFindings(agent, turns) {
     const dur = typeof t.duration_ms === "number" ? t.duration_ms : 0;
     const synthetic = tid.includes("synthetic-");
     const ts = isoFromTs(t.ts);
-    if (st !== "complete" && st !== "no_reply") {
+    if (st === "send_failed") {
+      findings.push({
+        signal: "send-failed-delivery",
+        agent,
+        turn_id: tid,
+        log_pointer: `turns.jsonl:${tid} status=send_failed`,
+        ts
+      });
+    } else if (st !== "complete" && st !== "no_reply") {
       findings.push({
         signal: "killed-incomplete-turn",
         agent,
@@ -63268,7 +63310,7 @@ function scanAgent(agent, turnsText, gatewayText) {
   const turnFindings = detectTurnFindings(agent, turns);
   const { findings: gwFindings, gw_hits } = detectGatewayFindings(agent, gatewayText);
   const findings = [...turnFindings, ...gwFindings];
-  const escalate = turnFindings.some((f) => f.signal === "killed-incomplete-turn" || f.signal === "hang-long-stalled" || f.signal === "silent-no-op-candidate") || gw_hits["duplicate-delivery-represent"] > 0 || gw_hits["reply-delivery-failure"] > 0;
+  const escalate = turnFindings.some((f) => f.signal === "killed-incomplete-turn" || f.signal === "hang-long-stalled" || f.signal === "silent-no-op-candidate" || f.signal === "send-failed-delivery") || gw_hits["duplicate-delivery-represent"] > 0 || gw_hits["reply-delivery-failure"] > 0;
   return { agent, turns: turns.length, status_mix, findings, gw_hits, escalate };
 }
 var HANG_MS = 360000, HANG_MAXTOOLS = 2, GATEWAY_SIGNATURES;
@@ -63346,6 +63388,12 @@ var init_mapping = __esm(() => {
       job_spec: "steer-or-queue-mid-flight",
       signature: "killed:incomplete-turn"
     },
+    "send-failed-delivery": {
+      failure_mode: "success-theater",
+      severity: 3,
+      job_spec: "talk-to-agents-from-anywhere",
+      signature: "send-failed:turn-flush-backstop"
+    },
     "represent-escalation": {
       failure_mode: "drift",
       severity: 1,
@@ -66775,6 +66823,10 @@ Scaffolding agent: ${name}
         }
         return;
       }
+      if (result.outcome === "skipped") {
+        console.log(source_default.yellow(`\u21b7 ${result.command} \u2014 skipped (precondition not met at send time)`));
+        return;
+      }
       const code = result.errorCode ?? "tmux_failed";
       const msg = result.errorMessage ?? "unknown error";
       console.error(source_default.red(`inject failed (${code}): ${msg}`));
@@ -78749,6 +78801,7 @@ function applySubagentsSchema(db) {
     db.exec("ALTER TABLE subagents ADD COLUMN model TEXT");
   }
   db.exec("CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS subagents_parent_agent ON subagents(parent_agent_id)");
 }
 function mapSubagentRow(row) {
   return {
@@ -81332,7 +81385,7 @@ async function onHermesMessage(ctx, raw) {
           sendResponse(ctx, rpcErr(id, -32603, msg));
           break;
         }
-        const output = injectResult.outcome === "ok" ? injectResult.output ?? "" : `*(${fullCommand} sent)*`;
+        const output = injectResult.outcome === "ok" ? injectResult.output ?? "" : injectResult.outcome === "skipped" ? `*(${fullCommand} skipped \u2014 precondition not met)*` : `*(${fullCommand} sent)*`;
         sendResponse(ctx, rpcOk(id, { ok: true, output }));
         break;
       }

package/dist/host-control/main.js

@@ -26605,7 +26605,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:f
 import { dirname as dirname4, join as join7 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.18.19";
+var VERSION = "0.18.21";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.18.19",
+  "version": "0.18.21",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_shared/delegation-golden-rule.md.hbs

@@ -0,0 +1,9 @@
+## Delegation — the last word
+
+This is the tail reminder on purpose: whatever the grounding, execution-bias, and development-protocol guidance above told you to *do*, the default way to do execution-class work is to **delegate it, not to run it inline.**
+
+- **Golden rule: when in doubt, delegate.** Any code change, research spanning 3+ file reads, file/report generation, build/deploy, or a task needing 3+ sequential tool calls without user input goes to a sub-agent (`@worker` for changes, `@researcher` for research, `@reviewer` for review) — per the Sub-Agent Delegation section. Unnecessary delegation costs a few tokens; a blocked foreground session costs the user's attention.
+- **The main session is for conversation.** Keep your own turns short — dispatch and acknowledge. The user should never wait more than 10 seconds for a response. "Act in-turn" is satisfied by dispatching the worker, not by doing the work yourself.
+- **Anti-pattern:** starting a task inline "because it's almost done", then racking up 5+ tool calls in the foreground. If it's execution-class, hand it off at the first tool call, not the fifth.
+
+If no sub-agents are configured, do the work yourself.

package/profiles/_shared/dev-protocol.md.hbs

@@ -2,6 +2,8 @@
 
 How development work gets done here — orient, clarify, align, ship, communicate. These are procedural rules for any substantive coding, infra, or debugging task. For the long-form playbook (design reports, adversarial review structure, re-review verdicts), load the bundled `dev-protocol` skill before starting substantive development work.
 
+**This protocol governs HOW delegated work is done, not a license to do it inline.** Substantive dev work is execution-class — per the Sub-Agent Delegation section it is dispatched to `@worker`/sub-agents so the foreground session stays free for the user. The orient / clarify / design-align / pipeline / communicate rules below bind that delegated work (and the sub-agent doing it); they are not an invitation for the main session to start editing, building, and testing in-turn instead of delegating.
+
 ### Orient — ground before you build
 
 - **Validate, don't assume.** Read the actual code, config, and system state before forming a theory. Never assert a fact you haven't checked this turn.

package/profiles/_shared/execution-discipline.md.hbs

@@ -14,5 +14,5 @@ When you genuinely can't verify something this turn, say so plainly ("I haven't
 
 How you should decide what to do next. These are procedural rules, not vibe.
 
-- **Act in-turn.** If the request is actionable, do it this turn. Don't finish with a plan or promise when tools can move it forward.
-- **Non-final turn:** use tools to advance, or ask the one clarifying question that unblocks safe progress. One question, not five.
+- **Act in-turn.** If the request is actionable, move it forward this turn. Don't finish with a plan or promise when tools can advance it. **But "act" composes with the Sub-Agent Delegation rules — it does not override them:** for an execution-class task (any code change, research spanning 3+ file reads, multi-step infra, report generation — see that section), the in-turn act IS dispatching the sub-agent, not doing the work inline. Acting immediately and delegating are the same move here; keep your own turn short and let the worker execute.
+- **Non-final turn:** use tools to advance (dispatch the worker when the task is execution-class), or ask the one clarifying question that unblocks safe progress. One question, not five.

package/profiles/coding/CLAUDE.md.hbs

@@ -49,7 +49,7 @@ Save proactively: architecture decisions, codebase patterns, conventions, known
 
 ## Sub-Agent Delegation
 
-If sub-agents are configured, delegate implementation to `@worker` (background, own worktree) and research to `@researcher` (background). Keep your turns short — dispatch and acknowledge quickly so you stay available for the user.
+**Golden rule: when in doubt, delegate.** The main session is for conversation; execution belongs in sub-agents. If sub-agents are configured, delegate implementation to `@worker` (background, own worktree), research spanning 3+ file reads to `@researcher` (background), and review to `@reviewer`. Unnecessary delegation costs a few tokens; a blocked foreground session costs the user's attention. Keep your turns short — dispatch and acknowledge quickly so you stay available for the user; the user should never wait more than 10 seconds for a response. Acting in-turn on an execution-class task means dispatching the worker, not doing the work inline.
 
 If the user amends in-flight delegated work mid-turn, steer the running worker now (`SendMessage` to the worker by name, or by the agent id from its spawn result) instead of holding the update for handback — and say in your reply whether you folded the update into the running worker or queued it as a separate task; never classify silently. If unsure whether a message amends in-flight work, queue it and say so — queue is the default. If the steer lands too late (worker effectively done), say so and apply the update yourself.
 

package/telegram-plugin/answer-ready-flush.ts

@@ -0,0 +1,187 @@
+/**
+ * Answer-ready quiescence flush (PR A — "late-delivery" fix).
+ *
+ * A "silent no-op" turn ends by emitting its final answer as plain transcript
+ * `text` (never calling the reply tool). Today that answer is only delivered
+ * when claude's `turn_duration`/`turn_end` signal lands — a signal that is
+ * KNOWN-UNRELIABLE for terminal-text turns (gateway.ts:13616-13618,
+ * 12992-12993). When it doesn't land, delivery falls to the orphaned-reply
+ * backstop, whose fuse is itself re-armed by the very answer text it is waiting
+ * on (the terminal text stamps `lastStreamEventAt`, so `recentlyStreaming`
+ * keeps deferring the ~30 s fuse across the full ~120 s window). Net: a fully
+ * composed answer sits ~150-196 s of dead wait AFTER it was ready.
+ *
+ * This module provides the DETERMINISTIC positive signal that closes that gap:
+ * once a turn has a genuine composed terminal answer AND goes quiescent (no
+ * in-flight tool, no pending async/background dispatch, no new stream event)
+ * for a short debounce (~1 s), a per-turn timer fires and routes the answer
+ * into the SAME existing turn-flush send path immediately — instead of waiting
+ * on the unreliable turn_end or the multi-minute backstop.
+ *
+ * The arm/fire decision is factored here as a pure, injectable predicate so the
+ * oracle asserts real behavior (mirrors `turn-record-status.ts` /
+ * `context-exhaustion.ts`). The gateway feeds it the SAME `decideTurnFlush`
+ * classifier the turn-flush branch uses, so a working-preamble, an ack, a tool
+ * preamble, or a genuine NO_REPLY turn never arms a spurious flush.
+ */
+
+import { decideTurnFlush, type FlushDecisionInput } from './turn-flush-safety.js'
+
+/** Default answer-ready quiescence debounce (ms). Ken approved ~1 s as
+ *  "immediate". Env-tunable via SWITCHROOM_ANSWER_READY_FLUSH_MS; 0 (or any
+ *  non-positive value) is the kill-switch that disables the flush entirely,
+ *  matching the repo's env-flag convention. */
+export const ANSWER_READY_FLUSH_MS = 1000
+
+/**
+ * Resolve the debounce window from the environment. Returns a positive integer
+ * ms, or 0 when disabled (kill-switch) / unparseable / non-positive. The
+ * gateway treats 0 as "never arm", so a bad env value fails safe to the default
+ * rather than to a hot-loop.
+ */
+export function resolveAnswerReadyFlushMs(
+  env: Record<string, string | undefined>,
+): number {
+  const raw = env.SWITCHROOM_ANSWER_READY_FLUSH_MS
+  if (raw == null || raw.trim() === '') return ANSWER_READY_FLUSH_MS
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return ANSWER_READY_FLUSH_MS
+  // Explicit 0 (or negative) = operator kill-switch → disabled.
+  if (n <= 0) return 0
+  return Math.floor(n)
+}
+
+export interface AnswerReadyArmInput {
+  /** The exact `decideTurnFlush` inputs the turn-flush branch resolves at
+   *  turn_end. Reusing the classifier is what guarantees the debounce only
+   *  fires on a genuine composed final answer — never a silent marker, an
+   *  empty turn, a reply-already-served turn, or a sub-agent turn. */
+  flush: FlushDecisionInput
+  /** `toolFlightTracker.inFlightCount()` — a live surface tool means the model
+   *  is still working, not quiescent. */
+  inFlightToolCount: number
+  /** `pendingProgress.hasPendingAsyncDispatch(key)` — a detached background
+   *  dispatch (Bash run_in_background, async tool) means work is still pending
+   *  even though `inFlightCount` is 0. */
+  hasPendingAsyncDispatch: boolean
+  /** The resolved debounce window; 0 disables (kill-switch). */
+  flushWindowMs: number
+}
+
+/**
+ * Should the answer-ready quiescence timer be armed / fired right now?
+ *
+ * True iff the kill-switch is off AND the turn has a genuine flushable answer
+ * (`decideTurnFlush` → `flush`) AND the turn is genuinely quiescent (no
+ * in-flight surface tool, no pending async/background dispatch). This same
+ * predicate gates BOTH the arm (in the `text` handler) AND the fire-time
+ * re-verification (in the timer callback) — so a tool that started after the
+ * arm, or a reply that landed in the interim, deterministically cancels the
+ * flush at fire time even if the explicit disarm was somehow missed.
+ */
+export function shouldArmAnswerReadyFlush(input: AnswerReadyArmInput): boolean {
+  if (input.flushWindowMs <= 0) return false
+  if (input.inFlightToolCount > 0) return false
+  if (input.hasPendingAsyncDispatch) return false
+  return decideTurnFlush(input.flush).kind === 'flush'
+}
+
+/** Opaque timer handle. Real code passes Node's `setTimeout` return; tests can
+ *  inject fake-timer handles. */
+export type FlushTimerHandle = ReturnType<typeof setTimeout>
+
+/**
+ * Injectable dependencies for {@link AnswerReadyFlushController}. Everything the
+ * orchestration needs from the gateway is threaded through here so the REAL
+ * arm / debounce / rollover-guard / fire-time-re-verify / disarm logic is
+ * unit-testable without importing the 30k-line gateway module (which has a
+ * top-level startup IIFE and cannot be imported). `Turn` is the gateway's
+ * `CurrentTurn`; the controller only touches it through these accessors.
+ */
+export interface AnswerReadyFlushDeps<Turn> {
+  /** The live turn atom (gateway `currentTurn`). Read at arm time and re-read at
+   *  fire time so a superseded turn's timer never fires against a fresh atom. */
+  getCurrentTurn(): Turn | null
+  /** Resolve the `shouldArmAnswerReadyFlush` inputs for a turn (chat/reply/
+   *  captured-text + live tool-flight + pending-async + the window). */
+  getArmInput(turn: Turn): AnswerReadyArmInput
+  /** Read / write the per-turn timer handle (stored on the `CurrentTurn`). */
+  getTimerHandle(turn: Turn): FlushTimerHandle | null
+  setTimerHandle(turn: Turn, handle: FlushTimerHandle | null): void
+  /**
+   * Deliver the composed answer — dispatch the positive `answer-ready-quiescence`
+   * synthetic turn_end that routes through the EXISTING turn-flush send path
+   * (endCurrentTurnAtomic → send-gated IIFE → PR-B honest record). The controller
+   * calls this AT MOST ONCE per turn (guarded by the rollover + timer-cleared
+   * checks). endCurrentTurnAtomic then nulls the atom, so a later real turn_end
+   * short-circuits — the exactly-once guarantee.
+   */
+  onFlush(turn: Turn): void
+  /** Injectable timer primitives (default to the globals). */
+  setTimeoutFn?: (fn: () => void, ms: number) => FlushTimerHandle
+  clearTimeoutFn?: (handle: FlushTimerHandle) => void
+  log?: (msg: string) => void
+}
+
+/**
+ * The deterministic answer-ready quiescence flush orchestration, extracted from
+ * the gateway so it is testable as a unit (mirrors `withTurnEndGateBackstop`).
+ *
+ * - `reset()` — called from `case 'text'`: clear any pending timer, then (re)arm
+ *   iff the turn currently classifies as a genuine flushable answer AND is
+ *   quiescent. Each text chunk re-arms → the debounce.
+ * - `clear(turn)` — the DISARM: called on any tool activity and from
+ *   `endCurrentTurnAtomic`. A real turn_end that lands first cancels a pending
+ *   flush (exactly-once), and a resumed turn (tool started) cancels a stale one.
+ *
+ * On fire the controller re-pins `getCurrentTurn() === turn` (rollover guard),
+ * clears the handle, RE-VERIFIES quiescence (a tool that started / a reply that
+ * landed since the arm cancels the flush deterministically), then dispatches
+ * exactly one `onFlush`.
+ */
+export class AnswerReadyFlushController<Turn> {
+  constructor(private readonly deps: AnswerReadyFlushDeps<Turn>) {}
+
+  private get setTimeoutFn(): (fn: () => void, ms: number) => FlushTimerHandle {
+    return this.deps.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms))
+  }
+
+  private get clearTimeoutFn(): (handle: FlushTimerHandle) => void {
+    return this.deps.clearTimeoutFn ?? ((h) => clearTimeout(h))
+  }
+
+  /** Disarm the flush timer for a turn (idempotent). */
+  clear(turn: Turn | null): void {
+    if (turn == null) return
+    const handle = this.deps.getTimerHandle(turn)
+    if (handle != null) {
+      this.clearTimeoutFn(handle)
+      this.deps.setTimerHandle(turn, null)
+    }
+  }
+
+  /** (Re)arm the flush timer for the current turn — the debounce. */
+  reset(): void {
+    const turn = this.deps.getCurrentTurn()
+    this.clear(turn)
+    if (turn == null) return
+    const armInput = this.deps.getArmInput(turn)
+    if (!shouldArmAnswerReadyFlush(armInput)) return
+    const handle = this.setTimeoutFn(() => this.onExpiry(turn), armInput.flushWindowMs)
+    this.deps.setTimerHandle(turn, handle)
+  }
+
+  /** Timer-expiry callback. Re-pins the turn, re-verifies quiescence, fires once. */
+  private onExpiry(armedTurn: Turn): void {
+    const live = this.deps.getCurrentTurn()
+    // Rollover guard: a superseded turn's timer must not fire against a fresh atom.
+    if (live == null || live !== armedTurn) return
+    this.deps.setTimerHandle(live, null)
+    // Fire-time re-verification: a tool that started (or a reply that landed)
+    // since the arm deterministically cancels the flush even if the explicit
+    // disarm was somehow missed.
+    if (!shouldArmAnswerReadyFlush(this.deps.getArmInput(live))) return
+    this.deps.log?.('answer-ready quiescence flush — delivering composed terminal answer')
+    this.deps.onFlush(live)
+  }
+}