switchroom 0.12.16 → 0.12.18

package/telegram-plugin/gateway/compact-notify.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure transition selector for the proactive-compaction user
+ * notification (a single Telegram card edited START → FINISH). Kept
+ * side-effect-free so the lifecycle — the part prone to double-post /
+ * stale-edit / spurious-finish — is unit-testable in isolation. The
+ * impure shell (send/editMessageText, the wall-clock timeout) lives in
+ * gateway.ts.
+ *
+ * The "finished" signal is the proactive-compaction state machine's
+ * re-arm edge (`armed: false → true`, which the decider only produces
+ * when post-`/compact` occupancy drops below 0.6×cap — i.e. context
+ * verifiably shrank). This module does NOT own the wall-clock timeout
+ * (an idle agent produces no evaluations, so a dangling card must be
+ * resolved by a real timer in the shell, independent of this loop).
+ *
+ * Session reset/rotation (`session.max_idle` / `max_turns`) is
+ * deliberately silent and is not represented here.
+ */
+
+export interface CompactNotifyState {
+  phase: "idle" | "awaiting";
+  /**
+   * The active session file when START was posted. FINISH is only
+   * accepted if the re-arm edge is observed against this SAME file —
+   * a sub-agent transcript briefly leading session-tail's currentFile
+   * can read a small occupancy and spuriously satisfy the re-arm
+   * condition; gating on the start-file rejects that false positive.
+   */
+  fileAtStart: string | null;
+}
+
+/**
+ * - `none`              — no card action this evaluation.
+ * - `start`             — post a fresh START card.
+ * - `start-superseding` — a prior card is still outstanding; mark it
+ *                         superseded, then post a fresh START card.
+ * - `finish`            — edit the outstanding card to FINISHED.
+ */
+export type CompactNotifyAction =
+  | "none"
+  | "start"
+  | "start-superseding"
+  | "finish";
+
+export interface CompactNotifyEvent {
+  /** The proactive-compaction decider fired `/compact` this eval. */
+  fired: boolean;
+  /** Decider re-arm edge this eval (wasArmed=false → state.armed=true). */
+  rearmed: boolean;
+  /** session-tail's active file used for the occupancy read this eval. */
+  activeFile: string | null;
+}
+
+export function idleCompactNotifyState(): CompactNotifyState {
+  return { phase: "idle", fileAtStart: null };
+}
+
+/**
+ * Select the card action for this idle evaluation and the next state.
+ * Pure: same inputs → same outputs, no I/O.
+ *
+ * Precedence:
+ *  1. A fire always (re)starts a card. If one was still outstanding,
+ *     supersede it first (single-outstanding-card invariant).
+ *  2. While awaiting, a re-arm edge ON THE SAME start-file → FINISH.
+ *  3. Otherwise hold (the shell's wall-clock timeout resolves a card
+ *     that never gets a re-arm — e.g. a compaction that didn't shrink
+ *     context, or an agent that went idle right after START).
+ */
+export function nextCompactNotify(
+  state: CompactNotifyState,
+  ev: CompactNotifyEvent,
+): { state: CompactNotifyState; action: CompactNotifyAction } {
+  if (ev.fired) {
+    const superseding = state.phase === "awaiting";
+    return {
+      state: { phase: "awaiting", fileAtStart: ev.activeFile },
+      action: superseding ? "start-superseding" : "start",
+    };
+  }
+
+  if (state.phase === "awaiting") {
+    if (
+      ev.rearmed &&
+      ev.activeFile != null &&
+      ev.activeFile === state.fileAtStart
+    ) {
+      return { state: idleCompactNotifyState(), action: "finish" };
+    }
+    return { state, action: "none" };
+  }
+
+  return { state, action: "none" };
+}

package/telegram-plugin/gateway/gateway.ts

@@ -228,6 +228,9 @@ import { handleInjectCommand } from './inject-handler.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
+import { readTurnUsages } from '../../src/agents/perf.js'
+import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
+import { nextCompactNotify, idleCompactNotifyState, type CompactNotifyState } from './compact-notify.js'
 import {
   tryHostdDispatch,
   hostdRequestId,
@@ -1062,6 +1065,47 @@ const chatAvailableReactions = new Map<string, Set<string> | null>()
 const chatProbesInFlight = new Set<string>()
 const activeTurnStartedAt = new Map<string, number>()
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
+
+// ─── Proactive context compaction (session.max_context_tokens) ──────────
+//
+// Opt-in: when the resolved agent config sets session.max_context_tokens,
+// we fire `/compact` once the live context-window occupancy of the latest
+// assistant turn reaches that many tokens. Evaluated ONLY at the
+// model-idle gate inside purgeReactionTracking (activeTurnStartedAt.size
+// === 0) — never mid-turn — mirroring the pendingRestarts drain. The
+// `/compact` verb is allowlisted in src/agents/inject.ts and runs via the
+// tmux send-keys path (the only path that actually executes the slash
+// command; inject_inbound would deliver it as literal text).
+//
+// `lastSessionActiveFile` is the session-tail's tracked currentFile,
+// forwarded by the bridge on every session_event — we read occupancy from
+// exactly that file (never an independent findActiveSessionFile re-scan).
+let lastSessionActiveFile: string | null = null
+// Anti-spam state machine lives in ./proactive-compact (pure, unit
+// tested). `compactDispatching` is a synchronous re-entrancy guard for
+// the async tmux send — purgeReactionTracking can run several times per
+// turn and we must not double-dispatch before the first send settles.
+let compactState: CompactState = initialCompactState()
+let compactDispatching = false
+
+// User-facing proactive-compaction notification (single Telegram card
+// edited START → FINISH; transition selection is pure in
+// ./compact-notify). Session reset/rotation stays silent — not here.
+// The wall-clock timer is owned HERE (not the pure helper): an idle
+// agent produces no idle evaluations, so a card that never gets a
+// re-arm edge must be resolved by a real timer, independent of the
+// eval loop, or it would dangle forever.
+const COMPACT_CARD_TIMEOUT_MS = 15 * 60 * 1000
+interface OutstandingCompactCard {
+  chatId: string
+  threadId: number | undefined
+  messageId: number
+  occAtStart: number
+  capAtStart: number
+  timer: ReturnType<typeof setTimeout>
+}
+let compactNotifyState: CompactNotifyState = idleCompactNotifyState()
+let outstandingCompactCard: OutstandingCompactCard | null = null
 const activeDraftStreams = new Map<string, DraftStreamHandle>()
 const activeDraftParseModes = new Map<string, 'HTML' | 'MarkdownV2' | undefined>()
 const suppressPtyPreview = new Set<string>()
@@ -1233,14 +1277,224 @@ function purgeReactionTracking(key: string): void {
   // survives us getting killed by our own restart. Fire-and-forget;
   // response to the client was already sent when the restart was
   // scheduled, so nobody is waiting on this.
-  if (activeTurnStartedAt.size === 0 && pendingRestarts.size > 0) {
-    for (const [agentName, _timestamp] of pendingRestarts.entries()) {
-      triggerSelfRestart(agentName, 'turn-complete-pending-restart');
-      pendingRestarts.delete(agentName);
+  if (activeTurnStartedAt.size === 0) {
+    if (pendingRestarts.size > 0) {
+      for (const [agentName, _timestamp] of pendingRestarts.entries()) {
+        triggerSelfRestart(agentName, 'turn-complete-pending-restart');
+        pendingRestarts.delete(agentName);
+      }
+    } else {
+      // Strictly lower priority than a pending restart: if we just
+      // kicked a restart the process is going away and compacting is
+      // moot, so only evaluate when no restart drained this pass.
+      maybeProactiveCompact();
     }
   }
 }
 
+/**
+ * Model-idle proactive-compaction check. Called ONLY from the
+ * activeTurnStartedAt.size === 0 gate above (never mid-turn). Opt-in via
+ * the resolved agent config's session.max_context_tokens; a no-op when
+ * unset, so a fresh `switchroom setup` is unchanged.
+ *
+ * Occupancy = the latest usage-bearing assistant turn's
+ * input + cache_read + cache_creation tokens (the prefix the model
+ * actually re-read this turn ≈ current window fill). readTurnUsages(_,1)
+ * returns exactly that single turn and skips tool-only / usage-less
+ * lines, so we never under-count off a sub-line.
+ *
+ * Note (accepted, benign): there is a check-to-send race — a new inbound
+ * could set activeTurnStartedAt between this idle check and the async
+ * tmux send. A `/compact` that lands as a new turn starts is queued in
+ * claude's prompt buffer and runs at the next idle prompt (see the
+ * FUTURE-GAP note in src/agents/inject.ts); it is not a mid-generation
+ * injection. We do not claim size===0 is atomic.
+ */
+function maybeProactiveCompact(): void {
+  if (compactDispatching) return;
+
+  const agentName = process.env.SWITCHROOM_AGENT_NAME;
+  if (!agentName) return;
+
+  let cap: number | undefined;
+  try {
+    const cfg = loadSwitchroomConfig();
+    // Resolve through the cascade so a fleet-wide
+    // `defaults.session.max_context_tokens` applies even when the agent
+    // has no explicit per-agent session block (rawAgent → {}).
+    const rawAgent = cfg.agents?.[agentName] ?? {};
+    const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent);
+    cap = resolved.session?.max_context_tokens;
+  } catch {
+    // Best-effort — config may be unreadable in odd boot states; a
+    // failed read just means "no proactive compaction this pass".
+    return;
+  }
+  if (cap == null || cap <= 0) return; // opt-in: unset → native compaction only
+
+  const file = lastSessionActiveFile;
+  if (!file) return;
+
+  const turns = readTurnUsages(file, 1);
+  if (turns.length === 0) return;
+  const t = turns[0];
+  const occupancy = t.input + t.cacheRead + t.cacheCreate;
+
+  const wasArmed = compactState.armed;
+  const decision = decideProactiveCompact(compactState, occupancy, cap);
+  compactState = decision.state;
+  // Re-arm edge: the decider only flips disarmed→armed when post-
+  // /compact occupancy fell below 0.6×cap — i.e. context verifiably
+  // shrank. That edge is the honest "compaction finished" signal.
+  const rearmed = !wasArmed && decision.state.armed;
+
+  // User-facing notification transitions (pure). Resolved synchronously
+  // here — before any await and before the !fire return — so a
+  // re-entrant purge pass can't double-post (compactState was already
+  // persisted/disarmed above). All card I/O is reached only past the
+  // `cap == null` opt-in return earlier in this function, so a fleet
+  // with the feature off never posts anything (Defaults preserved).
+  const nt = nextCompactNotify(compactNotifyState, {
+    fired: decision.fire,
+    rearmed,
+    activeFile: file,
+  });
+  compactNotifyState = nt.state;
+  if (nt.action === 'finish') {
+    void resolveCompactCard('finished', occupancy);
+  } else if (nt.action === 'start' || nt.action === 'start-superseding') {
+    if (nt.action === 'start-superseding') {
+      void resolveCompactCard('superseded', occupancy);
+    }
+    void postCompactCard(occupancy, cap);
+  }
+
+  if (!decision.fire) return;
+
+  // Set the re-entrancy guard synchronously BEFORE the await so a
+  // re-entrant purge pass can't double-dispatch (the decider already
+  // disarmed + armed the cooldown in decision.state).
+  compactDispatching = true;
+  process.stderr.write(
+    `telegram gateway: proactive /compact for ${agentName} ` +
+      `(occupancy=${occupancy} >= cap=${cap})\n`,
+  );
+  void injectSlashCommandImpl(agentName, '/compact')
+    .catch((err: unknown) => {
+      process.stderr.write(
+        `telegram gateway: proactive /compact inject failed for ` +
+          `${agentName}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    })
+    .finally(() => {
+      compactDispatching = false;
+    });
+}
+
+/**
+ * Post the START card for a proactive compaction. Best-effort: a failed
+ * send just means no card (the compaction itself still happens). The
+ * outstanding record + a wall-clock timeout are armed so the card can
+ * never dangle if the re-arm edge never arrives (failed/idle case).
+ */
+async function postCompactCard(occ: number, cap: number): Promise<void> {
+  try {
+    const chatId = loadAccess().allowFrom[0];
+    if (!chatId) return;
+    const threadId = chatThreadMap.get(chatId);
+    const text =
+      `🗜️ <b>Context compaction</b>\n` +
+      `Working context hit ~${occ.toLocaleString()} tokens ` +
+      `(cap ${cap.toLocaleString()}) — running <code>/compact</code>. ` +
+      `Older detail moves to Hindsight; I'll confirm here once the ` +
+      `context has shrunk (may take a turn or two).`;
+    const sent = await swallowingApiCall(
+      () =>
+        bot.api.sendMessage(chatId, text, {
+          parse_mode: 'HTML',
+          ...(threadId != null ? { message_thread_id: threadId } : {}),
+        }),
+      { chat_id: chatId, verb: 'proactiveCompact.start' },
+    );
+    const messageId = (sent as { message_id?: number } | undefined)
+      ?.message_id;
+    if (typeof messageId !== 'number') return;
+    const timer = setTimeout(() => {
+      void resolveCompactCard('timeout', null);
+    }, COMPACT_CARD_TIMEOUT_MS);
+    timer.unref?.();
+    outstandingCompactCard = {
+      chatId,
+      threadId,
+      messageId,
+      occAtStart: occ,
+      capAtStart: cap,
+      timer,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: proactive-compact start card failed: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
+/**
+ * Resolve the outstanding START card to a terminal state by editing it
+ * in place. `finished` is driven by the decider re-arm edge (context
+ * verifiably shrank), `superseded` when a newer compaction starts first,
+ * `timeout` by the wall-clock timer (re-arm never arrived). The
+ * outstanding record + timer are cleared synchronously BEFORE the await
+ * so a stale message_id can never be edited twice and the timer can't
+ * double-fire. On `timeout` the pure notify state is also reset so a
+ * future compaction starts a clean lifecycle.
+ */
+async function resolveCompactCard(
+  kind: 'finished' | 'superseded' | 'timeout',
+  occNow: number | null,
+): Promise<void> {
+  const card = outstandingCompactCard;
+  if (!card) return;
+  outstandingCompactCard = null;
+  clearTimeout(card.timer);
+  if (kind === 'timeout') compactNotifyState = idleCompactNotifyState();
+  let text: string;
+  if (kind === 'finished') {
+    text =
+      `✅ <b>Context compacted</b>\n` +
+      `Working context reduced` +
+      (occNow != null
+        ? ` (~${card.occAtStart.toLocaleString()} → ` +
+          `~${occNow.toLocaleString()} tokens)`
+        : '') +
+      `. Hindsight retains the detail.`;
+  } else if (kind === 'superseded') {
+    text =
+      `↩️ <b>Context compaction superseded</b>\n` +
+      `A newer compaction started before this one confirmed.`;
+  } else {
+    text =
+      `⚠️ <b>Compaction issued</b>\n` +
+      `<code>/compact</code> was requested but the context isn't ` +
+      `confirmed reduced yet. Native compaction and Hindsight still apply.`;
+  }
+  try {
+    await swallowingApiCall(
+      () =>
+        bot.api.editMessageText(card.chatId, card.messageId, text, {
+          parse_mode: 'HTML',
+        }),
+      { chat_id: card.chatId, verb: `proactiveCompact.${kind}` },
+    );
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: proactive-compact ${kind} card edit failed: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
 function endStatusReaction(chatId: string, threadId: number | undefined, outcome: 'done' | 'error'): void {
   const key = statusKey(chatId, threadId)
   const ctrl = activeStatusReactions.get(key)
@@ -2997,6 +3251,9 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onSessionEvent(_client: IpcClient, msg: SessionEventForward) {
+    // Track the session-tail's attached file for the proactive-
+    // compaction occupancy read (see maybeProactiveCompact).
+    if (msg.activeFile) lastSessionActiveFile = msg.activeFile
     const ev = msg.event as unknown as SessionEvent
     // Pass the envelope's chatId so non-enqueue events can route to the
     // correct card even when the driver's currentChatId is stale.

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -121,6 +121,15 @@ export interface SessionEventForward {
   event: Record<string, unknown>;
   chatId: string;
   threadId?: number;
+  /**
+   * The session-tail's currently-attached JSONL path (its tracked
+   * `currentFile`, not an independent re-scan). Forwarded so the
+   * gateway's proactive-compaction check reads occupancy from the
+   * exact file the tailer is on — avoids the sub-agent-mtime /
+   * stale-rotation wrong-file hazard. Absent until the tailer has
+   * attached a file.
+   */
+  activeFile?: string;
 }
 
 export interface PermissionRequestForward {

package/telegram-plugin/gateway/proactive-compact.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure decision core for proactive context compaction
+ * (`session.max_context_tokens`). Kept side-effect-free so the
+ * anti-spam state machine — the part most prone to livelock /
+ * double-fire — is unit-testable in isolation. The impure shell
+ * (config load, session-file read, tmux `/compact` inject) lives in
+ * gateway.ts and calls `decideProactiveCompact` at the model-idle gate.
+ *
+ * Occupancy fed in by the caller = the latest usage-bearing assistant
+ * turn's `input + cache_read + cache_creation` tokens (the prefix the
+ * model re-read this turn ≈ live context-window fill). Not cumulative.
+ */
+
+/** Hysteresis lower band: re-arm only once occupancy < fraction × cap. */
+export const COMPACT_REARM_FRACTION = 0.6;
+
+/**
+ * Turn-count re-fire floor: after a fire, skip this many idle
+ * evaluations regardless of occupancy. Guards against a slow
+ * post-`/compact` JSONL rotation still reading the pre-compact turn and
+ * triggering an immediate second compaction.
+ */
+export const COMPACT_COOLDOWN_TURNS = 3;
+
+export interface CompactState {
+  /** False after a fire; re-armed only below the hysteresis band. */
+  armed: boolean;
+  /** Idle evaluations remaining before re-fire is even considered. */
+  cooldownTurns: number;
+}
+
+export interface CompactDecision {
+  fire: boolean;
+  /** Next state — caller must persist this verbatim. */
+  state: CompactState;
+}
+
+export function initialCompactState(): CompactState {
+  return { armed: true, cooldownTurns: 0 };
+}
+
+/**
+ * Decide whether to fire `/compact` this idle evaluation, given the
+ * current state, the measured occupancy, and the configured cap.
+ *
+ * Precedence (each returns early):
+ *  1. Cooldown floor — burn one turn, never fire.
+ *  2. Disarmed — re-arm iff occupancy < REARM_FRACTION × cap; never
+ *     fire on the arming pass (so we can't arm and fire together).
+ *  3. Below cap — hold.
+ *  4. Armed and at/above cap — fire, disarm, start the cooldown.
+ *
+ * Livelock safety: once disarmed, step 2 is the ONLY path back to
+ * armed, and it requires occupancy to actually drop below the lower
+ * band. If a compaction fails to shrink context, the cap stays
+ * exceeded, occupancy never drops below 0.6×cap, and we stay disarmed
+ * — i.e. we degrade to "don't fire" rather than firing every turn.
+ */
+export function decideProactiveCompact(
+  state: CompactState,
+  occupancy: number,
+  cap: number,
+): CompactDecision {
+  if (state.cooldownTurns > 0) {
+    return {
+      fire: false,
+      state: { armed: state.armed, cooldownTurns: state.cooldownTurns - 1 },
+    };
+  }
+
+  if (!state.armed) {
+    const armed = occupancy < cap * COMPACT_REARM_FRACTION;
+    return { fire: false, state: { armed, cooldownTurns: 0 } };
+  }
+
+  if (occupancy < cap) {
+    return { fire: false, state };
+  }
+
+  return {
+    fire: true,
+    state: { armed: false, cooldownTurns: COMPACT_COOLDOWN_TURNS },
+  };
+}

package/telegram-plugin/tests/compact-notify.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest'
+import {
+  nextCompactNotify,
+  idleCompactNotifyState,
+  type CompactNotifyState,
+} from '../gateway/compact-notify.js'
+
+const FILE_A = '/state/.../sess-a.jsonl'
+const FILE_B = '/state/.../sess-b.jsonl'
+
+describe('nextCompactNotify', () => {
+  it('idle + fired → start, awaiting with fileAtStart', () => {
+    const r = nextCompactNotify(idleCompactNotifyState(), {
+      fired: true,
+      rearmed: false,
+      activeFile: FILE_A,
+    })
+    expect(r.action).toBe('start')
+    expect(r.state).toEqual({ phase: 'awaiting', fileAtStart: FILE_A })
+  })
+
+  it('idle + nothing → none', () => {
+    const r = nextCompactNotify(idleCompactNotifyState(), {
+      fired: false,
+      rearmed: false,
+      activeFile: FILE_A,
+    })
+    expect(r.action).toBe('none')
+    expect(r.state.phase).toBe('idle')
+  })
+
+  it('idle + spurious rearm (no card outstanding) → none', () => {
+    const r = nextCompactNotify(idleCompactNotifyState(), {
+      fired: false,
+      rearmed: true,
+      activeFile: FILE_A,
+    })
+    expect(r.action).toBe('none')
+    expect(r.state.phase).toBe('idle')
+  })
+
+  it('awaiting + rearm on SAME file → finish, back to idle', () => {
+    const awaiting: CompactNotifyState = { phase: 'awaiting', fileAtStart: FILE_A }
+    const r = nextCompactNotify(awaiting, {
+      fired: false,
+      rearmed: true,
+      activeFile: FILE_A,
+    })
+    expect(r.action).toBe('finish')
+    expect(r.state).toEqual(idleCompactNotifyState())
+  })
+
+  it('awaiting + rearm on DIFFERENT file → none (sub-agent false-positive guard)', () => {
+    const awaiting: CompactNotifyState = { phase: 'awaiting', fileAtStart: FILE_A }
+    const r = nextCompactNotify(awaiting, {
+      fired: false,
+      rearmed: true,
+      activeFile: FILE_B,
+    })
+    expect(r.action).toBe('none')
+    expect(r.state).toBe(awaiting) // unchanged, still awaiting
+  })
+
+  it('awaiting + rearm but activeFile null → none', () => {
+    const awaiting: CompactNotifyState = { phase: 'awaiting', fileAtStart: FILE_A }
+    const r = nextCompactNotify(awaiting, {
+      fired: false,
+      rearmed: true,
+      activeFile: null,
+    })
+    expect(r.action).toBe('none')
+    expect(r.state.phase).toBe('awaiting')
+  })
+
+  it('awaiting + no rearm → none, stays awaiting (shell timeout owns dangling)', () => {
+    const awaiting: CompactNotifyState = { phase: 'awaiting', fileAtStart: FILE_A }
+    const r = nextCompactNotify(awaiting, {
+      fired: false,
+      rearmed: false,
+      activeFile: FILE_A,
+    })
+    expect(r.action).toBe('none')
+    expect(r.state.phase).toBe('awaiting')
+  })
+
+  it('awaiting + fired again → start-superseding, awaiting with NEW fileAtStart', () => {
+    const awaiting: CompactNotifyState = { phase: 'awaiting', fileAtStart: FILE_A }
+    const r = nextCompactNotify(awaiting, {
+      fired: true,
+      rearmed: false,
+      activeFile: FILE_B,
+    })
+    expect(r.action).toBe('start-superseding')
+    expect(r.state).toEqual({ phase: 'awaiting', fileAtStart: FILE_B })
+  })
+
+  it('full healthy cycle: fire → hold → rearm(same file) → idle', () => {
+    let s = idleCompactNotifyState()
+    const fires: string[] = []
+    const seq = [
+      { fired: true, rearmed: false, activeFile: FILE_A }, // START
+      { fired: false, rearmed: false, activeFile: FILE_A }, // cooldown/hold
+      { fired: false, rearmed: false, activeFile: FILE_A }, // hold
+      { fired: false, rearmed: true, activeFile: FILE_A }, // FINISH
+      { fired: false, rearmed: false, activeFile: FILE_A }, // idle, nothing
+    ]
+    for (const ev of seq) {
+      const r = nextCompactNotify(s, ev)
+      s = r.state
+      fires.push(r.action)
+    }
+    expect(fires).toEqual(['start', 'none', 'none', 'finish', 'none'])
+    expect(s).toEqual(idleCompactNotifyState())
+  })
+
+  it('rearm that arrives only after a file flip never finishes the wrong card', () => {
+    // START on FILE_A; a sub-agent (FILE_B) leads and "rearms" → ignored;
+    // later the real drop is observed back on FILE_A → finish.
+    let s = nextCompactNotify(idleCompactNotifyState(), {
+      fired: true,
+      rearmed: false,
+      activeFile: FILE_A,
+    }).state
+    const mid = nextCompactNotify(s, {
+      fired: false,
+      rearmed: true,
+      activeFile: FILE_B,
+    })
+    expect(mid.action).toBe('none')
+    s = mid.state
+    const fin = nextCompactNotify(s, {
+      fired: false,
+      rearmed: true,
+      activeFile: FILE_A,
+    })
+    expect(fin.action).toBe('finish')
+  })
+})