switchroom 0.19.44 → 0.19.46

package/telegram-plugin/flushed-turn-supersede.ts

@@ -26,7 +26,9 @@
  *
  * NOT fully deterministic — a residual race remains. The flush→reply direction
  * this registry covers, plus the controller's fire-time recount for the
- * reply→flush direction, close the COMMON ~10 s replay-gap case; but if a reply
+ * reply→flush direction, close the COMMON replay-gap case (~10 s for a
+ * tool-call replay; unbounded for the Stop-hook-nudged recompose after a
+ * proactive /compact — see the turn-completion window below, #4173); but if a reply
  * and a flush interleave so the reply's `take()` runs BEFORE the flush's
  * `record()` (a much smaller window), `take` finds no record and the duplicate
  * can still slip through. We deliberately trade that residual window for the
@@ -46,10 +48,85 @@
  * `now`. Fully unit-testable; the gateway wires the actual delete/send.
  */
 
-/** TTL after which a recorded flush is forgotten. 60 s comfortably spans the
- *  observed ~10 s flush→reply replay gap with margin, and matches the outbound
- *  dedup window so the two mechanisms age out together. */
-export const DEFAULT_SUPERSEDE_TTL_MS = 60_000
+/**
+ * ## The supersede window is a TURN-COMPLETION SIGNAL, not a fixed TTL (#4173)
+ *
+ * The window in which a landing reply may claim a flushed turn used to be a
+ * single constant (`DEFAULT_SUPERSEDE_TTL_MS = 60_000`). That constant was
+ * sized for the ~10 s tool-replay gap and missed the SLOW variant of the exact
+ * class this module exists for (2026-08-01, klanker DM, msgs 25680/25682): the
+ * quiescence flush delivered the composed answer, the Stop hook told the model
+ * its prose never reached the user, and the model recomposed and called
+ * `reply` — but a proactive `/compact` ran in between (occupancy ~393 k), so
+ * the canonical reply landed **2 m 24 s** after the flush. Every layer keyed
+ * on the 60 s TTL had aged out and the reply shipped as a second bubble
+ * (#4166). Widening the constant (the first attempt: 5 min) merely moves the
+ * cliff — a longer compaction reproduces the duplicate — while ALSO holding
+ * the destructive window open for foreign late repliers (#4172).
+ *
+ * The framework already holds the right signal. The flush fires a
+ * SYNTHETIC turn_end (it nulls the gateway's turn atom so the session can
+ * move on), but the claude session's REAL turn_end arrives later, when the
+ * model actually stops. A `reply` landing on the MAIN session bridge BETWEEN
+ * those two events is that turn's own answer still being composed — PROVIDED
+ * nothing else on that bridge can emit a reply in the span. Two things can, and
+ * neither is covered by this window; each is closed by its own deterministic
+ * gate, and the window is only sound in combination with them:
+ *
+ *   - a FOREIGN session (a Tier-1 cheap-cron bridge, an unregistered client) —
+ *     closed by caller identity at the send path (`replyCallerIsForeignSession`,
+ *     gateway/cron-session.ts, #4172);
+ *   - a background `Task` SUB-AGENT, which runs concurrently with the parent
+ *     loop and calls `reply` over the SAME main bridge, so identity cannot see
+ *     it — closed by gateway-observed sub-agent liveness refusing the
+ *     content-gate bypass (gateway/subagent-reply-authority.ts, #4176). The
+ *     claude session's own loop is serial; its sub-agents are not, and the
+ *     earlier revision of this header asserted the stronger, false claim that
+ *     "no other work can run on the serial session in that span".
+ *
+ * So the record's lifetime is now three-phase:
+ *
+ *   1. OPEN (`completedAt == null`) — the flush delivered, the real turn_end
+ *      has not been observed yet. The turn is still composing (Stop-hook
+ *      nudge, /compact, recompose all live here). A same-session reply
+ *      supersedes REGARDLESS of how long this takes — a 20-minute compaction
+ *      no longer reproduces #4166. Bounded only by the
+ *      `SUPERSEDE_OPEN_WINDOW_CAP_MS` crash backstop below, and — for a reply
+ *      the two gates above cannot positively attribute to the session's own
+ *      loop — by the #3429 content gate, which this phase does NOT relax.
+ *   2. COMPLETED (`completedAt` set) — the real turn_end (or a proxy for it:
+ *      a new turn minting, or the bridge dying) was observed. The turn's own
+ *      answer either already landed or can only arrive as a bounded REPLAY of
+ *      an un-acked tool_call (~10 s after a bridge reconnect), so the record
+ *      stays claimable for `SUPERSEDE_COMPLETED_GRACE_MS` and then expires.
+ *   3. EXPIRED — no supersede; a genuinely late duplicate ships as a second
+ *      visible bubble (safe direction — never an edit-over).
+ *
+ * In the COMMON case (real turn_end lands seconds after the flush) this is
+ * STRICTLY NARROWER than any widened TTL — the destructive window closes ~60 s
+ * after the session actually stopped — while being unbounded-correct in the
+ * slow case. The `FlushCompletionTracker` below carries the same signal onto
+ * the ended TURN ATOM (`realEndObservedAt`) so the latest-ended owner tier
+ * (`reply-owner-resolve.ts`) applies the identical three-phase rule.
+ */
+
+/** Crash backstop for an OPEN record: if the real turn_end signal is LOST
+ *  (every loss path — bridge death, new-turn mint, gateway restart dropping
+ *  the in-memory registry — normally closes the window explicitly), an open
+ *  record is forgotten after this long. Generous by design: it exists only
+ *  for signal loss, and the failure past it is a visible duplicate, never a
+ *  silent edit-over. Operator override: `SWITCHROOM_SUPERSEDE_OPEN_CAP_MS`
+ *  (resolved in gateway.ts — this module stays env-free/pure). */
+export const SUPERSEDE_OPEN_WINDOW_CAP_MS = 30 * 60_000
+
+/** How long a COMPLETED record stays claimable after the real turn_end was
+ *  observed. Sized for the bounded replay class the original 60 s TTL was
+ *  built for: claude-code re-sending an un-acked `reply` tool_call after a
+ *  bridge reconnect (~10 s), with margin. The exact-text #546 dedup keeps its
+ *  own 60 s window (`recent-outbound-dedup.ts`) — byte-identical replays, a
+ *  different class. Operator override: `SWITCHROOM_SUPERSEDE_GRACE_MS`
+ *  (resolved in gateway.ts). */
+export const SUPERSEDE_COMPLETED_GRACE_MS = 60_000
 
 export interface FlushedTurnRecord {
   /** The per-turn `turnId` nonce (`deriveTurnId` shape) of the flushed turn.
@@ -68,6 +145,13 @@ export interface FlushedTurnRecord {
   text: string
   /** Wall-clock ms when recorded. */
   ts: number
+  /** #4173 — wall-clock ms the flushed turn's REAL turn_end (or a proxy: new
+   *  turn mint / bridge death) was observed, or null while the session is
+   *  still composing (the OPEN phase — see the module header). Null records
+   *  are claimable indefinitely up to the `openCapMs` crash backstop; once
+   *  set, the record expires `completedGraceMs` later (the bounded
+   *  tool-call-replay window). */
+  completedAt: number | null
 }
 
 /**
@@ -186,12 +270,24 @@ export function decideSupersede(
     replyText?: string | null
     positiveAttribution?: boolean
     now: number
-    ttlMs?: number
+    /** OPEN-phase crash backstop (see module header). */
+    openCapMs?: number
+    /** COMPLETED-phase replay grace (see module header). */
+    completedGraceMs?: number
   },
 ): SupersedeDecision {
-  const ttlMs = args.ttlMs ?? DEFAULT_SUPERSEDE_TTL_MS
+  const openCapMs = args.openCapMs ?? SUPERSEDE_OPEN_WINDOW_CAP_MS
+  const completedGraceMs = args.completedGraceMs ?? SUPERSEDE_COMPLETED_GRACE_MS
   if (record == null) return { supersede: false, deleteMessageIds: [], reason: 'no-record' }
-  if (args.now - record.ts > ttlMs) {
+  // #4173 three-phase freshness (module header): an OPEN record (real turn_end
+  // not yet observed — the session is still composing this turn's answer) is
+  // claimable up to the crash-backstop cap; a COMPLETED record only for the
+  // bounded tool-call-replay grace after the observed completion.
+  const expired =
+    record.completedAt == null
+      ? args.now - record.ts > openCapMs
+      : args.now - record.completedAt > completedGraceMs
+  if (expired) {
     return { supersede: false, deleteMessageIds: [], reason: 'expired' }
   }
   const sameTurn =
@@ -312,20 +408,26 @@ function turnKey(turnId: string | null): string {
  */
 export class FlushedTurnSupersedeRegistry {
   private readonly entries = new Map<string, Map<string, FlushedTurnRecord>>()
-  private readonly ttlMs: number
+  private readonly openCapMs: number
+  private readonly completedGraceMs: number
 
-  constructor(opts: { ttlMs?: number } = {}) {
-    this.ttlMs = opts.ttlMs ?? DEFAULT_SUPERSEDE_TTL_MS
+  constructor(opts: { openCapMs?: number; completedGraceMs?: number } = {}) {
+    this.openCapMs = opts.openCapMs ?? SUPERSEDE_OPEN_WINDOW_CAP_MS
+    this.completedGraceMs = opts.completedGraceMs ?? SUPERSEDE_COMPLETED_GRACE_MS
   }
 
   /** Record a flush's posted message(s) so a later same-turn reply supersedes
    *  them, keyed on the flush's `turnId` within the chat/thread lane. No record
    *  is kept when the flush posted zero messages. Sweeps expired records first
-   *  (lightweight active GC — LOW-2) so orphan records never accumulate. */
+   *  (lightweight active GC — LOW-2) so orphan records never accumulate.
+   *  `completedAt` (#4173): the flush's async send can outlast the real
+   *  turn_end, so the record site passes the turn atom's `realEndObservedAt` —
+   *  a window that was closed BEFORE the record existed is born completed
+   *  (grace-bounded), never resurrected as open. */
   record(
     chatId: string,
     threadId: number | undefined,
-    rec: { turnId: string | null; messageIds: number[]; text: string },
+    rec: { turnId: string | null; messageIds: number[]; text: string; completedAt?: number | null },
     now: number,
   ): void {
     if (rec.messageIds.length === 0) return
@@ -341,9 +443,23 @@ export class FlushedTurnSupersedeRegistry {
       messageIds: [...rec.messageIds],
       text: rec.text,
       ts: now,
+      completedAt: rec.completedAt ?? null,
     })
   }
 
+  /** #4173 — the real-turn-end signal (or a proxy: new turn mint / bridge
+   *  death) was observed. Close every OPEN record's window: from `now` each
+   *  has `completedGraceMs` (the bounded replay window) left to be claimed by
+   *  its own late replay, then expires. Records already completed keep their
+   *  original (earlier) completion — the signal only ever narrows. */
+  completeAll(now: number): void {
+    for (const laneMap of this.entries.values()) {
+      for (const rec of laneMap.values()) {
+        if (rec.completedAt == null) rec.completedAt = now
+      }
+    }
+  }
+
   /** Decide supersede for a landing reply WITHOUT consuming the record. Selects
    *  the record whose turnId matches the reply's resolved `liveTurnId` (or the
    *  null-turnId record when `liveTurnId == null`). `replyText` (#3429) enables
@@ -364,7 +480,8 @@ export class FlushedTurnSupersedeRegistry {
       replyText: args.replyText,
       positiveAttribution: args.positiveAttribution,
       now: args.now,
-      ttlMs: this.ttlMs,
+      openCapMs: this.openCapMs,
+      completedGraceMs: this.completedGraceMs,
     })
   }
 
@@ -404,11 +521,16 @@ export class FlushedTurnSupersedeRegistry {
     this.entries.clear()
   }
 
-  /** Evict every record past its TTL and prune emptied lanes. */
+  /** Evict every record past its window (three-phase rule, module header) and
+   *  prune emptied lanes. */
   private sweep(now: number): void {
     for (const [lane, laneMap] of this.entries) {
       for (const [tk, rec] of laneMap) {
-        if (now - rec.ts > this.ttlMs) laneMap.delete(tk)
+        const expired =
+          rec.completedAt == null
+            ? now - rec.ts > this.openCapMs
+            : now - rec.completedAt > this.completedGraceMs
+        if (expired) laneMap.delete(tk)
       }
       if (laneMap.size === 0) this.entries.delete(lane)
     }
@@ -426,3 +548,55 @@ export class FlushedTurnSupersedeRegistry {
 function makeKey(chatId: string, threadId: number | undefined): string {
   return threadId == null ? chatId : `${chatId}|${threadId}`
 }
+
+/**
+ * #4173 — carries the turn-completion signal onto the flushed TURN ATOMS, the
+ * registry's sibling surface. The registry above bounds the RECORD (message
+ * ids); the latest-ended owner tier (`reply-owner-resolve.ts`) is bounded by
+ * the TURN's `realEndObservedAt`, and this tracker is what stamps it:
+ *
+ *   - `open(turn)` at flush-fire time (stream-render's turn-flush branch, the
+ *     one path that ends a turn SYNTHETICALLY before the session stopped):
+ *     nulls `realEndObservedAt` and holds the atom pending.
+ *   - `closeAll(now)` when the real turn_end signal (or a proxy: a new turn
+ *     minting on the session, the bridge dying) is observed: stamps every
+ *     pending atom's `realEndObservedAt = now` and releases it. Every other
+ *     turn-end path stamps `realEndObservedAt` directly in
+ *     `endCurrentTurnAtomic` (turn-end.ts) — for a normally-ended turn the
+ *     real end IS its end.
+ *
+ * Serial-session note: claude processes one turn at a time, so pending atoms
+ * are naturally few (normally exactly one); `closeAll` closing every pending
+ * window on any completion signal is deliberate — closing early is the SAFE
+ * direction (a too-short window costs a visible duplicate, never an
+ * edit-over). Pure: no clock reads beyond the caller-supplied `now`, no I/O.
+ */
+export class FlushCompletionTracker {
+  private pending: Array<{ realEndObservedAt: number | null }> = []
+
+  /** Hold `turn` pending until the real-turn-end signal; marks its window
+   *  open (`realEndObservedAt = null`). */
+  open(turn: { realEndObservedAt: number | null }): void {
+    turn.realEndObservedAt = null
+    if (!this.pending.includes(turn)) this.pending.push(turn)
+  }
+
+  /** The real-turn-end signal (or a proxy) was observed: stamp every pending
+   *  atom and release it. Returns how many windows were closed. */
+  closeAll(now: number): number {
+    let closed = 0
+    for (const turn of this.pending) {
+      if (turn.realEndObservedAt == null) {
+        turn.realEndObservedAt = now
+        closed++
+      }
+    }
+    this.pending = []
+    return closed
+  }
+
+  /** Test/diagnostics: number of atoms still awaiting their real turn_end. */
+  pendingCount(): number {
+    return this.pending.length
+  }
+}

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

@@ -65,6 +65,8 @@ export type ParsedAuthCommand =
       replace: boolean
       /** Google `--write` (Drive write scope). */
       write: boolean
+      /** Google `--calendar` (read-only Calendar scope). */
+      calendar: boolean
       /** Microsoft `--org-mode`. */
       orgMode: boolean
     }
@@ -251,7 +253,7 @@ export function parseAuthCommand(text: string): ParsedAuthCommand | null {
  * wired; anything else is a help-with-reason so the operator sees the shape.
  *
  * Flags mirror the CLI:
- *   google:    `add <email> [--replace] [--write]`
+ *   google:    `add <email> [--replace] [--write] [--calendar]`
  *   microsoft: `add <email> [--replace] [--org-mode]`
  */
 export function parseProviderVerb(
@@ -265,7 +267,7 @@ export function parseProviderVerb(
   if (sub !== 'add') {
     const usage =
       provider === 'google'
-        ? 'Usage: /auth google add <email> [--replace] [--write]'
+        ? 'Usage: /auth google add <email> [--replace] [--write] [--calendar]'
         : 'Usage: /auth microsoft add <email> [--replace] [--org-mode]'
     return {
       kind: 'help',
@@ -280,7 +282,7 @@ export function parseProviderVerb(
   if (!email) {
     const usage =
       provider === 'google'
-        ? 'Usage: /auth google add <email> [--replace] [--write]'
+        ? 'Usage: /auth google add <email> [--replace] [--write] [--calendar]'
         : 'Usage: /auth microsoft add <email> [--replace] [--org-mode]'
     return { kind: 'help', reason: usage }
   }
@@ -288,7 +290,7 @@ export function parseProviderVerb(
   if (emailErr) return { kind: 'help', reason: emailErr }
   // Reject unknown flags so a typo (`--replaced`) isn't silently dropped.
   const allowed = provider === 'google'
-    ? new Set(['--replace', '--write'])
+    ? new Set(['--replace', '--write', '--calendar'])
     : new Set(['--replace', '--org-mode'])
   for (const f of flags) {
     if (!allowed.has(f)) {
@@ -304,6 +306,7 @@ export function parseProviderVerb(
     email,
     replace: flags.has('--replace'),
     write: provider === 'google' && flags.has('--write'),
+    calendar: provider === 'google' && flags.has('--calendar'),
     orgMode: provider === 'microsoft' && flags.has('--org-mode'),
   }
 }

package/telegram-plugin/gateway/auth-loopback-relay.ts

@@ -84,6 +84,8 @@ export interface SpawnRelayOpts {
   replace?: boolean
   /** Google `--write` (Drive write scope). */
   write?: boolean
+  /** Google `--calendar` (read-only Calendar scope). */
+  calendar?: boolean
   /** Microsoft `--org-mode`. */
   orgMode?: boolean
   /** Override the CLI binary (tests / non-default install). */
@@ -96,6 +98,42 @@ export type SpawnRelay = (
   opts: SpawnRelayOpts,
 ) => RelayChild
 
+/**
+ * Build the `switchroom auth <provider> account add` argv the relay spawns.
+ *
+ * Pure + exported so the flag plumbing is unit-pinned: every opt-in flag
+ * the chat command accepts has to actually reach the CLI, and a flag that
+ * was NOT requested must never appear (the relay is the only path most
+ * operators use, so a dropped `--calendar` here is indistinguishable from
+ * the feature not existing, and a spurious one silently widens a grant).
+ */
+export function buildRelayArgs(
+  provider: LoopbackProvider,
+  email: string,
+  opts: SpawnRelayOpts,
+): string[] {
+  return provider === 'google'
+    ? [
+        'auth',
+        'google',
+        'account',
+        'add',
+        email,
+        ...(opts.replace ? ['--replace'] : []),
+        ...(opts.write ? ['--write'] : []),
+        ...(opts.calendar ? ['--calendar'] : []),
+      ]
+    : [
+        'auth',
+        'microsoft',
+        'account',
+        'add',
+        email,
+        ...(opts.replace ? ['--replace'] : []),
+        ...(opts.orgMode ? ['--org-mode'] : []),
+      ]
+}
+
 /**
  * Default spawn: the real `switchroom` CLI, stdout+stderr piped, stdin
  * ignored. `BROWSER=/bin/true` suppresses any browser auto-open; the Drive
@@ -109,26 +147,7 @@ export function defaultSpawnRelay(
   opts: SpawnRelayOpts,
 ): RelayChild {
   const binary = opts.binary ?? 'switchroom'
-  const args =
-    provider === 'google'
-      ? [
-          'auth',
-          'google',
-          'account',
-          'add',
-          email,
-          ...(opts.replace ? ['--replace'] : []),
-          ...(opts.write ? ['--write'] : []),
-        ]
-      : [
-          'auth',
-          'microsoft',
-          'account',
-          'add',
-          email,
-          ...(opts.replace ? ['--replace'] : []),
-          ...(opts.orgMode ? ['--org-mode'] : []),
-        ]
+  const args = buildRelayArgs(provider, email, opts)
   const child: ChildProcess = spawn(binary, args, {
     stdio: ['ignore', 'pipe', 'pipe'],
     env: {

package/telegram-plugin/gateway/cron-session.ts

@@ -35,6 +35,37 @@ export function baseAgent(name: string): string {
   return isCronIdentity(name) ? name.slice(0, -CRON_IDENTITY_SUFFIX.length) : name;
 }
 
+/**
+ * #4172 — is a `reply` tool call arriving on this IPC client identity a
+ * FOREIGN-SESSION reply, i.e. one that can NEVER be the main claude session's
+ * own (possibly late/reworded) answer to a turn the gateway attributed?
+ *
+ * The whole flushed-turn supersede/bypass/latch machinery
+ * (`outbound-send-path.ts`) rests on the premise that a decoupled late reply
+ * resolving an ended turn is that turn's own answer unless a handback marker
+ * says otherwise. That premise only holds for replies from the MAIN agent
+ * bridge — the one whose session the turns belong to. A Tier-1 cheap-cron
+ * fire's reply arrives on the derived `<agent>-cron` bridge: it never mints a
+ * gateway turn (its session events are dropped in `onSessionEvent`), never
+ * traverses `pendingInboundBuffer.push` (so it cannot stamp the handback
+ * marker), and lands decoupled with foreign content — the measured #4172
+ * failure was such a reply EDITING OVER a flushed answer (double loss: the
+ * flushed answer destroyed, the cron digest delivered as a silent edit).
+ * Identity is the one deterministic signal that separates it.
+ *
+ * Returns true (foreign — refuse supersede/bypass/latch authority, always
+ * send fresh) for:
+ *   - a cron-session identity (`<agent>-cron`);
+ *   - a null/absent identity (an unregistered client — it owns no session,
+ *     so fail SAFE: a visible fresh message, never destructive authority).
+ * Returns false only for a registered non-cron agent bridge — the main
+ * session.
+ */
+export function replyCallerIsForeignSession(name: string | null | undefined): boolean {
+  if (name == null || name === "") return true;
+  return isCronIdentity(name);
+}
+
 /**
  * True iff an inject_inbound fire is a scheduled cron fire — Tier-1 cheap-cron
  * (`meta.session='cron'`, routed to the derived `<agent>-cron` bridge) OR a