switchroom 0.18.6 → 0.18.8

package/telegram-plugin/gateway/busy-ack.ts

@@ -0,0 +1,106 @@
+// #2995 — mid-flight busy ack.
+//
+// A mid-turn inbound that is neither a steer nor an interrupt is buffered
+// until the running turn goes idle (`buffer-until-idle`). When the turn is
+// sitting inside ONE long blocking tool call (`gh pr checks --watch`, a
+// long `sleep`, a slow build), that wait can be minutes — from the phone
+// the question reads as ignored. The user's message got only a 👀 reaction
+// and then silence until the blocking step returned (observed live
+// 2026-07-10: a trivial "are any agents working?" waited 2 minutes behind
+// a `--watch`).
+//
+// This module is the PURE half of the fix: a deterministic, model-free
+// decision — should the gateway post a silent "⏳ Queued — currently
+// inside <tool> …" card into the inbound's own chat/topic right now? No
+// tokens, no model calls; the gateway supplies live readings (delivery-gate
+// decision, tool-flight state, current step age, dedupe state) and this
+// module answers. Extracted so the policy is unit-testable without the
+// gateway IIFE (same pattern as `interrupt-defer.ts` / `feed-reopen-gate.ts`).
+//
+// Wording contract: the buffered-path card MUST say "Queued" — the
+// steer-or-queue job spec (`reference/jobs/steer-or-queue-mid-flight.md`)
+// requires the chosen classification to be visible in the chat, never
+// inferred. A steer-path card must NOT say "Queued" (it wasn't queued);
+// it says the steer was noted and will fold in at the step boundary.
+
+/** How the inbound was classified/handled by the delivery gate. Only the
+ *  two mid-turn shapes are ack-eligible; a plain fresh-turn `deliver`
+ *  needs no busy ack (the turn starts immediately). */
+export type BusyAckGateDecision = 'buffer-until-idle' | 'steer' | 'deliver'
+
+/**
+ * Minimum age of the CURRENT tool step before a busy ack fires. Below
+ * this the step is about to return anyway and the buffered inbound will
+ * flush in a beat — an ack would fire when the agent was seconds from
+ * answering (the job spec's explicit Bad bullet). 12s sits well above the
+ * common fast-tool envelope (reads/greps/short bashes finish in <5s) and
+ * well below the "reads as ignored" horizon (~30s+); it also matches the
+ * UAT latency promise (visible ack <10s of the ping, for a step that has
+ * already proven itself long).
+ */
+export const BUSY_ACK_STEP_AGE_THRESHOLD_MS = 12_000
+
+export interface BusyAckDecisionInput {
+  /** Delivery-gate outcome for this inbound ('steer' when it was
+   *  delivered mid-turn as a steering amend). */
+  gateDecision: BusyAckGateDecision
+  /** Live `ToolFlightTracker.isMidToolCall()` reading — at least one
+   *  top-level tool call currently open. */
+  midToolCall: boolean
+  /** Age (ms) of the LONGEST-running in-flight tool step, or null when no
+   *  step is tracked (e.g. the turn is thinking between tools). */
+  stepAgeMs: number | null
+  /** True when a busy-ack/queued-status card already exists (or was
+   *  already posted this turn) for the inbound's chat/topic — at most one
+   *  card per turn per chat/topic; a second ping gets no second card. */
+  alreadyAcked: boolean
+}
+
+/**
+ * Pure decision: post the busy-ack card now?
+ *
+ *  - only for mid-turn shapes (buffered, or delivered as a steer)
+ *  - only while genuinely mid-tool-call
+ *  - only once the current step is older than the threshold (a young
+ *    step returns soon; the normal flush covers it)
+ *  - at most once per turn per chat/topic (dedupe)
+ */
+export function shouldPostBusyAck(input: BusyAckDecisionInput): boolean {
+  if (input.gateDecision !== 'buffer-until-idle' && input.gateDecision !== 'steer') return false
+  if (!input.midToolCall) return false
+  if (input.stepAgeMs == null || input.stepAgeMs < BUSY_ACK_STEP_AGE_THRESHOLD_MS) return false
+  if (input.alreadyAcked) return false
+  return true
+}
+
+export interface BusyAckTextInput {
+  gateDecision: 'buffer-until-idle' | 'steer'
+  /** Bare tool name as tracked (e.g. "Bash"). Null when unknown. */
+  toolName: string | null
+  /** Natural-language descriptor from the PreToolUse sidecar's
+   *  `toolLabel()` (e.g. `sleep 90`), or null. */
+  toolLabel: string | null
+}
+
+/**
+ * Render the card text. Deterministic, no model. The buffered variant
+ * says "Queued" (classification-visibility invariant); the steer variant
+ * says the steer is noted — never "Queued".
+ *
+ * Deliberately carries NO elapsed figure: the card is posted once and
+ * never re-rendered while the blocking step runs, so any point-in-time
+ * number ("2m elapsed") would silently go stale on screen — a decaying
+ * claim on a card whose whole point is honesty. The activity name alone
+ * is time-invariant.
+ */
+export function formatBusyAckText(input: BusyAckTextInput): string {
+  const name = input.toolName ?? 'a long-running step'
+  const activity =
+    input.toolLabel != null && input.toolLabel.length > 0
+      ? `${name}: ${input.toolLabel}`
+      : name
+  if (input.gateDecision === 'steer') {
+    return `⏳ Steer noted — currently inside \`${activity}\`; I'll fold it in when this step finishes.`
+  }
+  return `⏳ Queued — currently inside \`${activity}\`; I'll answer when this step finishes.`
+}

package/telegram-plugin/gateway/clean-shutdown-marker.ts

@@ -182,44 +182,92 @@ export function resolveShutdownMarker(
   return { ts: now, signal, reason: EXTERNAL_RESTART_FALLBACK_REASON };
 }
 
+/**
+ * Boot-resume policy, from `session_continuity.boot_resume`
+ * (SWITCHROOM_BOOT_RESUME env). Governs whether a clean/deliberate
+ * shutdown suppresses auto-resume of a genuinely in-flight turn:
+ *
+ *   - 'always'   — always resume interrupted work, even after a clean
+ *                  shutdown (equivalent to SWITCHROOM_BOOT_RESUME_ALWAYS=1).
+ *   - 'in-flight' — (DEFAULT) resume work that was genuinely in flight at
+ *                  shutdown, even after a deliberate/operator restart. This
+ *                  is the whole point: a sanctioned restart that lands mid-
+ *                  turn must not silently drop the work. The boot-resume
+ *                  block only runs when a pending interrupted turn exists —
+ *                  i.e. when there IS in-flight work — so in this mode the
+ *                  clean-shutdown gate never swallows real work.
+ *   - 'never'    — the #2585 quota-saving posture: suppress AUTO-resume on a
+ *                  fresh clean shutdown. NOTE the caller still delivers a
+ *                  passive REPORT inbound in this case (silence is never
+ *                  acceptable when work was in flight); this flag only
+ *                  downgrades an active resume to a passive notice.
+ */
+export type BootResumeMode = 'always' | 'in-flight' | 'never';
+
+/** The product default (2026-07): resume genuinely in-flight work even
+ *  after a deliberate restart. Restores the pre-#2585 recovery of real
+ *  work while keeping #2585's "don't replay abandoned work" intent for the
+ *  no-in-flight-turn case (which is a no-op — the boot block never runs
+ *  without a pending turn). */
+export const DEFAULT_BOOT_RESUME_MODE: BootResumeMode = 'in-flight';
+
+/**
+ * Parse the SWITCHROOM_BOOT_RESUME env value into a BootResumeMode. Unknown
+ * / empty / undefined falls back to the default ('in-flight'). Case- and
+ * separator-insensitive ("in_flight", "inflight", "IN-FLIGHT" all map to
+ * 'in-flight') so a config typo degrades to the safe default rather than a
+ * silent misparse.
+ */
+export function parseBootResumeMode(raw: string | undefined | null): BootResumeMode {
+  if (typeof raw !== 'string') return DEFAULT_BOOT_RESUME_MODE;
+  const norm = raw.trim().toLowerCase().replace(/[_\s]+/g, '-');
+  if (norm === 'always') return 'always';
+  if (norm === 'never') return 'never';
+  if (norm === 'in-flight' || norm === 'inflight') return 'in-flight';
+  return DEFAULT_BOOT_RESUME_MODE;
+}
+
 /**
  * Pure decision: should the boot-resume path SUPPRESS the active
  * resume_interrupted inbound because the prior shutdown was clean?
  *
- * A clean marker present and fresh (<= maxAgeMs, default 60s) means the
- * prior shutdown was operator/roll/CLI-initiated — NOT a crash. In that
- * case auto-resuming interrupted work is wasteful: the agent was asked to
- * stop, it stopped cleanly, and the "interrupted" turn was implicitly
- * abandoned by that decision. Burning a full model turn to replay it on
- * every operator restart wastes subscription quota for no user benefit.
+ * This block is only ever consulted when a pending INTERRUPTED turn
+ * exists — i.e. there IS genuinely in-flight work to recover. The product
+ * decision (2026-07, superseding #2585) is that a deliberate restart must
+ * NOT silently drop that work, so the DEFAULT mode ('in-flight') never
+ * suppresses. #2585's quota-saving posture survives only as the opt-in
+ * 'never' mode — and even then the caller downgrades to a passive REPORT
+ * rather than going silent.
  *
- * Returns true ONLY when:
+ * Returns true (suppress the ACTIVE resume) ONLY when:
+ *   - mode === 'never', AND
  *   - a clean marker is present, AND
  *   - the marker is younger than maxAgeMs (default 60s), AND
- *   - the SWITCHROOM_BOOT_RESUME_ALWAYS escape hatch is not set.
- *
- * Returns false when:
- *   - no marker (crash / OOM / unexpected kill — resume normally), OR
- *   - marker is stale (>= maxAgeMs — something stalled; treat as crash), OR
- *   - forceAlways is true (the escape hatch is active).
+ *   - neither forceAlways nor mode 'always' is set.
  *
- * The forceAlways parameter maps to the env var
- * SWITCHROOM_BOOT_RESUME_ALWAYS=1, which restores the pre-gate behaviour
- * unconditionally. Pass it in as a parsed boolean so this function stays
- * pure and testable without touching process.env.
+ * Returns false (resume normally) when:
+ *   - mode is 'always' or 'in-flight' (the default), OR
+ *   - forceAlways is true (SWITCHROOM_BOOT_RESUME_ALWAYS=1 escape hatch), OR
+ *   - no marker (crash / OOM / unexpected kill), OR
+ *   - marker is stale (>= maxAgeMs — clean shutdown that stalled mid-drain;
+ *     preserves the ">60s slow-rollout already resumes" behaviour).
  *
- * Keeping this pure makes the decision unit-testable in bun test without
- * spinning up the gateway.
+ * forceAlways maps to SWITCHROOM_BOOT_RESUME_ALWAYS=1 and is preserved for
+ * back-compat: it forces resume regardless of mode. Passed in as a parsed
+ * boolean + mode so this function stays pure and testable.
  */
 export function shouldSuppressBootResume(
   marker: CleanShutdownMarker | null,
   now: number,
-  { maxAgeMs = DEFAULT_MAX_AGE_MS, forceAlways = false }: {
+  { maxAgeMs = DEFAULT_MAX_AGE_MS, forceAlways = false, mode = DEFAULT_BOOT_RESUME_MODE }: {
     maxAgeMs?: number;
     forceAlways?: boolean;
+    mode?: BootResumeMode;
   } = {},
 ): boolean {
   if (forceAlways) return false;
+  if (mode === 'always' || mode === 'in-flight') return false;
+  // mode === 'never': the legacy #2585 clean-shutdown gate.
   if (marker === null) return false;
   const age = now - marker.ts;
   if (age < 0) return false; // clock skew defence — treat as stale