refactor(session): drop the run.json snapshot debounce

Author: TheGreatAxios

src/exec/runner.ts

@@ -102,7 +102,6 @@ import {
   clearActiveDisposeHost,
 } from "../session/active-host.js";
 import {
-  createRunSnapshotDebouncer,
   finalizeRunState,
   loadState,
   saveState,
@@ -536,18 +535,13 @@ export async function runExec(config: Config): Promise<ExecResult> {
       : {}),
   };
   let stopHeartbeat: (() => void) | undefined;
-  // CL-10667: debounced per-turn boundary snapshots; terminal exposes flush.
-  let runSnapshotDebouncer:
-    | ReturnType<typeof createRunSnapshotDebouncer>
-    | undefined;
 
   const persist = async (
     status: "running" | "done" | "failed" | "cancelled",
     extra?: { error?: string },
   ): Promise<void> => {
     if (finalized && status === "running") return;
     if (status !== "running") {
-      await runSnapshotDebouncer?.flush();
       finalized = true;
       stopHeartbeat?.();
       stopHeartbeat = undefined;
@@ -601,9 +595,6 @@ export async function runExec(config: Config): Promise<ExecResult> {
   };
 
   await persist("running");
-  runSnapshotDebouncer = createRunSnapshotDebouncer({
-    write: () => persist("running"),
-  });
   stopHeartbeat = startRunHeartbeat({
     shouldTick: () => !finalized,
     tick: () => persist("running"),
@@ -1057,8 +1048,7 @@ export async function runExec(config: Config): Promise<ExecResult> {
             activeRunHandle.cacheWriteModel = `${event.data.source.provider}:${event.data.source.model}`;
           }
         }
-        // CL-10667: debounced — the write recomputes state when it fires.
-        runSnapshotDebouncer?.schedule();
+        void persist("running");
       },
       resolveContextDir: () => workdir,
     });

src/session/run-snapshot-debounce.test.ts

@@ -131,62 +131,6 @@ export async function saveState(
   return write;
 }
 
-/**
- * Debounce window for mid-run `running` snapshots (CL-10667): coalesces the
- * per-turn boundary write to ~0.2/turn at a ~1s/turn cadence, while the
- * run-liveness heartbeat keeps mtime freshness over longer gaps.
- */
-export const RUN_SNAPSHOT_DEBOUNCE_MS = 5_000;
-
-export interface RunSnapshotDebouncer {
-  /** Mark a pending write and arm the one-shot timer once. */
-  schedule: () => void;
-  /** Cancel the timer and run any pending write immediately. */
-  flush: () => Promise<void>;
-}
-
-/**
- * Lazy payoff: the deferred write recomputes its snapshot when it fires, not
- * at schedule time, so a front of rapid turns persists the state current at
- * fire time. One timer; `schedule` while armed only re-marks dirty. The
- * writer maps write failures to undefined so a stalled flush cannot wedge
- * the terminal path that awaits it.
- */
-export function createRunSnapshotDebouncer(args: {
-  write: () => Promise<void>;
-  intervalMs?: number;
-}): RunSnapshotDebouncer {
-  const intervalMs = args.intervalMs ?? RUN_SNAPSHOT_DEBOUNCE_MS;
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  let dirty = false;
-  let inFlight: Promise<void> = Promise.resolve();
-
-  const run = (): void => {
-    dirty = false;
-    inFlight = args.write().catch(() => undefined);
-  };
-
-  return {
-    schedule: () => {
-      dirty = true;
-      if (timer !== null) return;
-      timer = setTimeout(() => {
-        timer = null;
-        if (dirty) run();
-      }, intervalMs);
-      timer.unref?.();
-    },
-    flush: async () => {
-      if (timer !== null) {
-        clearTimeout(timer);
-        timer = null;
-      }
-      if (dirty) run();
-      await inFlight;
-    },
-  };
-}
-
 // Terminal-write path: clears the in-memory active-run handle (active-run.ts)
 // alongside the on-disk status so the two cannot drift. Non-terminal
 // ("running") snapshots use saveState directly.

src/session/state.ts

@@ -24,7 +24,6 @@ import { setAgentSourceUnlessClosed } from "../agent-source-sync.js";
 import { billingIdentityFromSource } from "../../cost/session-cost.js";
 import { createRunSummary, type RunSummary } from "../../session/hooks.js";
 import {
-  createRunSnapshotDebouncer,
   finalizeRunState,
   saveState,
   type RunState,
@@ -262,20 +261,10 @@ export function createRunPersistence(
     await writeRunSnapshot("running");
   };
 
-  // CL-10667: per-turn boundary snapshots coalesce behind the debounce
-  // window (lazy payoff — the deferred write recomputes state at fire time,
-  // so nothing scheduled goes stale).
-  // Observable exposes flush before they observe or supersede run.json.
-  const runSnapshotDebouncer = createRunSnapshotDebouncer({
-    write: () => persistRunSnapshot("running"),
-  });
-
   return {
     writeRunSnapshot,
     persistRunSnapshot,
     heartbeatRunSnapshot,
-    scheduleRunSnapshot: runSnapshotDebouncer.schedule,
-    flushRunSnapshot: runSnapshotDebouncer.flush,
   };
 }
 
@@ -322,18 +311,11 @@ export async function createRunLifecycle(
   newSession: () => void;
   agentProxy: Agent;
 }> {
-  const {
-    persistRunSnapshot,
-    heartbeatRunSnapshot,
-    scheduleRunSnapshot,
-    flushRunSnapshot,
-  } = createRunPersistence(state, services);
+  const { persistRunSnapshot, heartbeatRunSnapshot } = createRunPersistence(
+    state,
+    services,
+  );
   state.persistRunSnapshot = persistRunSnapshot;
-  // CL-10667: per-turn boundary snapshots schedule behind the debounce
-  // window; observable exposes (interrupt rebuild, rotation, finalize) flush
-  // the pending write before they observe or supersede run.json.
-  state.scheduleRunSnapshot = scheduleRunSnapshot;
-  state.flushRunSnapshot = flushRunSnapshot;
   const activateAndCommitWire = (names: string[]): void => {
     if (!services.activatedToolNames.activate(names)) return;
     if (services.flushPromotions()) {
@@ -618,10 +600,6 @@ export async function createRunLifecycle(
       enqueue: enqueueOp,
       rebuild: async () => {
         try {
-          // CL-10667: run.json is observable the moment the rebuild starts
-          // reading store state, so the pending debounced snapshot flushes
-          // first.
-          await state.flushRunSnapshot?.();
           // close() tears down stream consumers before the aborted cycle's
           // inference.error is delivered, so the recorder never sees a
           // terminal event. Dispose before that teardown salvages the buffer
@@ -702,10 +680,6 @@ export async function createRunLifecycle(
             "stream drain during session-rotation teardown failed",
           ),
         );
-        // CL-10667: the rotation terminal write supersets the pending
-        // snapshot for the outgoing session; flush so the debounced write
-        // cannot straddle the id repoint below.
-        await state.flushRunSnapshot?.();
         await persistRunSnapshot(
           "done",
           { finishedAt: Date.now() },
@@ -789,9 +763,6 @@ export async function finalizeTUIRun(
   await hostOf(state).waitUntilExit();
   state.stopRunHeartbeat?.();
   delete state.stopRunHeartbeat;
-  // CL-10667: pending debounced snapshots flush ahead of the terminal write
-  // so a failed or dropped terminal write cannot leave run.json stale.
-  await state.flushRunSnapshot?.();
   // Stop workers before awaiting the session-op tail so a hung enqueue cannot
   // delay abort/reap; persistence, hooks, and telemetry stay after stop.
   // Toolset dispose lives inside shutdownRuntime so quit, crash, and signals

src/tui/runner/exit.ts

@@ -176,8 +176,7 @@ export async function assembleTUISession(
             start.activeRunHandle.cacheWriteModel = `${event.data.source.provider}:${event.data.source.model}`;
           }
         }
-        // CL-10667: debounced — the write recomputes state when it fires.
-        state.scheduleRunSnapshot?.();
+        void state.persistRunSnapshot?.("running");
       },
       hookEnabled: initialHookEnabled,
       onHookEvent: (event) => emitter.emit("hook", event),

src/tui/runner/session.ts

@@ -332,10 +332,6 @@ export interface RunnerState {
     extra?: SnapshotExtra,
     kind?: Exclude<SnapshotKind, "run-end">,
   ) => Promise<void>;
-  /** CL-10667: debounced per-turn boundary snapshot writer. */
-  scheduleRunSnapshot?: () => void;
-  /** CL-10667: flush any pending debounced snapshot before observing run.json. */
-  flushRunSnapshot?: () => Promise<void>;
   shutdownRuntime?: () => Promise<void>;
   stopFleetReporting?: () => void;
   stopRunHeartbeat?: () => void;