CL-9006: fix automatic compaction governor so post-compact above-threshold sessions latch (#1175)

* test(compaction): red latch tests for post-compact above-threshold re-arm

* fix(compaction): latch post-compact re-arm on a wide resume gap

* docs(context-window): correct hasWideResumeGap comment (proactive path only)

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -189,12 +189,12 @@ The agent maintains an optional **`manage_tasks`** list (create/update via the h
 
 When a cycle's input tokens cross a threshold, the director compacts the inference-facing history (the full run is always retained in the context store). The threshold is **model-aware** — roughly 60% of the active model's real context window — so small-window models compact early enough to avoid provider context-overflow while large-window models do not compact prematurely. The compacted prefix is **append-only across passes**: the existing compacted user turn stays byte-identical; new folds become later summary turns with a harness-inserted assistant spacer (identified by reserved `model: "harness"`, plus a visible sentinel; persisted `[compaction]` tokens without a producer still freeze) between them so the prompt head can remain in the provider KV cache. Model-emitted copies of the spacer are not frozen. Spacer-only model replies are incomplete: ChatDirector nudges, then falls through loop-protection, workflow-idle, and open-task rails rather than empty-settling with work still open. The governor covers five cases:
 
-- **Threshold at a tool pause** — Once over threshold, the follow-up `infer` after a tool batch is swapped for a `compact` cycle, and inference resumes via a host continuation message. After a compact that remains over the high watermark, the governor uses **growth hysteresis** (wait for usage to grow by ~10% of the window) instead of re-arming on every cycle; dropping under 60% is not required.
+- **Threshold at a tool pause** — Once over threshold, the follow-up `infer` after a tool batch is swapped for a `compact` cycle, and inference resumes via a host continuation message. After a compact that remains over the high watermark, the governor latches: it does not re-arm on growth alone until usage climbs a wide resume gap (~20% of the window, a full warning band) past the post-compact measurement, or until a summarizing fold gets usage back at or under the threshold. A consecutive-compact cap holds across tool-call occupancy as a second rail.
 - **Idle (end-of-turn)** — An interactive turn can end with a reply and then sit idle with no tool batch to intercept; the governor requests a continuation at that pause and compacts when it arrives. An operator message that races the continuation still compacts first, then re-enters inference to answer it.
 - **Idle recompress past the provider TTL** — Cache expiry does not compact. Stored turns stay. When settings set `anthropicCachePrompt`, and the saved Anthropic-protocol cache write is at least 5 minutes old, the pre-inference context transform stubs old tool-result bodies on the outgoing prompt only. `turns.jsonl` is not rewritten. The setting defaults off.
 
 - **Operator `/compact`** — A first-class slash command folds now without waiting for the occupancy governor. Optional trailing instructions go to the summarizer (empty uses the default structured fold) and are stored on the compact record so later auto-folds still see them. Director rebuild (`/model`, interrupt, resume) restores those instructions from the latest compact record's parameters. An in-flight turn uses the same pair-safe compact-then-continue hop as threshold compact; an idle compact shows the fold and does not start a new turn.
-- **Overflow recovery** — A `context_overflow` inference error would otherwise become a terminal error reply; the governor compacts and retries instead, bounded so a history the compactor cannot shrink does not loop forever. Overflow ignores hysteresis for the compact itself.
+- **Overflow recovery** — A `context_overflow` inference error would otherwise become a terminal error reply; the governor compacts and retries instead, bounded so a history the compactor cannot shrink does not loop forever. The overflow compact itself always fires, but the recovery counts against the same latch: only an under-threshold fold restores the budget, and the proactive path stays subject to the latched re-arm rule.
 
 The compaction control flow is shaped by a reactor invariant: a `compact` action runs in its own cycle (it cannot be paired with `infer`), and **the reactor delivers no event after a compact cycle**. A director that simply emitted `compact` in place of the follow-up `infer` would leave the loop idle forever — the cause of an earlier stall. Instead the governor pairs `compact` with an emit action (`custom.compaction.continue`), and the host answers that emission by delivering a content-less inbound message (`buildCompactionContinuationMessage()`) through the serial operation queue, generation-guarded like every other deliver. A hop superseded because interrupt already bumped generation and enqueued a rebuild is re-queued onto the replacement agent rather than consumed on the outgoing liveAgent. That message adds no turn (`createInboundTurn` returns `null` for empty content) but re-enters the loop, where the director issues the follow-up `infer` against the freshly truncated history. Each emission is answered at most once (a replayed duplicate of an already-answered emission is ignored), and an unsolicited continuation with neither resume flag set answers `wait` rather than burning a billable inference. The legacy `requestContinuation` closure survives only on the sub-agent path, which delivers directly with no host emit hop; idle arming keeps the two channels exclusive (closure fires and the arming flag stays false, or no closure and the flag reports the arming) so a caller honoring both cannot double-deliver.
 

src/agent/compaction.test.ts

@@ -14,7 +14,7 @@ import {
   stickyExtraInstructionsFromRecords,
 } from "./compaction.js";
 import {
-  compactionResumeDeltaFor,
+  compactionWideResumeDeltaFor,
   compactionThresholdFor,
 } from "../provider/context-window.js";
 import {
@@ -147,7 +147,7 @@ function overflowError(): ReactorInboundEvent {
 }
 
 const overThreshold = compactionThresholdFor("m") + 1;
-const resumeDelta = compactionResumeDeltaFor("m");
+const wideDelta = compactionWideResumeDeltaFor("m");
 const inferAction: ReactorAction[] = [{ type: "infer" }];
 const tenTurns = turnsOfLength(10, 1);
 const threeTurns = turnsOfLength(3, 1);
@@ -634,15 +634,15 @@ describe("compaction governor", () => {
       governor.interceptActions(toolDone(), inferAction, capabilities),
     ).not.toBeNull();
 
-    // Post-compact snapshot is still over high; growth hysteresis must hold
-    // the next arm until usage grows by resumeDelta.
+    // Post-compact snapshot is still over high; the latch must hold the next
+    // arm until usage climbs a wide resume gap past the snapshot.
     governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
     expect(
       governor.interceptActions(toolDone(), inferAction, capabilities),
     ).toBeNull();
   });
 
-  test("re-arms after usage grows by the resume delta past the last compact", () => {
+  test("re-arms after usage grows by the wide resume gap past the last compact", () => {
     const governor = createCompactionGovernor(() => undefined);
     governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
     expect(
@@ -655,7 +655,7 @@ describe("compaction governor", () => {
     ).toBeNull();
 
     governor.noteInferenceDone(
-      inferenceDone(overThreshold + resumeDelta),
+      inferenceDone(overThreshold + wideDelta),
       tenTurns,
     );
     const actions = governor.interceptActions(
@@ -667,7 +667,7 @@ describe("compaction governor", () => {
     expect(actions?.some((a) => a.type === "compact")).toBe(true);
   });
 
-  test("clears hysteresis once usage drops under the high watermark", () => {
+  test("clears the latch once usage drops under the high watermark", () => {
     const governor = createCompactionGovernor(() => undefined);
     governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
     expect(
@@ -695,7 +695,7 @@ describe("compaction governor", () => {
     expect(actions?.some((a) => a.type === "compact")).toBe(true);
   });
 
-  test("overflow still compact while hysteresis blocks the proactive path", () => {
+  test("overflow still compacts while the latch blocks the proactive path", () => {
     const governor = createCompactionGovernor(() => undefined);
     governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
     expect(
@@ -712,7 +712,7 @@ describe("compaction governor", () => {
     expect(actions?.some((a) => a.type === "compact")).toBe(true);
   });
 
-  test("consecutive threshold and idle compacts are bounded until occupancy", () => {
+  test("consecutive threshold and idle compacts stay bounded across tool-call occupancy", () => {
     const governor = createCompactionGovernor(() => undefined);
     const echo = LEGACY_COMPACT_SPACER_TEXT;
     governor.noteInferenceDone(inferenceDone(overThreshold, echo), tenTurns);
@@ -722,42 +722,47 @@ describe("compaction governor", () => {
 
     governor.noteInferenceDone(inferenceDone(overThreshold, echo), tenTurns);
     governor.noteInferenceDone(
-      inferenceDone(overThreshold + resumeDelta, echo),
+      inferenceDone(overThreshold + wideDelta, echo),
       tenTurns,
     );
     expect(
       governor.interceptActions(toolDone(), inferAction, capabilities),
     ).not.toBeNull();
 
+    // Still over after two folds: the cap holds on both rails even as usage
+    // keeps climbing past wide gaps ...
     governor.noteInferenceDone(
-      inferenceDone(overThreshold + resumeDelta, echo),
+      inferenceDone(overThreshold + wideDelta, echo),
       tenTurns,
     );
     governor.noteInferenceDone(
-      inferenceDone(overThreshold + 2 * resumeDelta, echo),
+      inferenceDone(overThreshold + 2 * wideDelta, echo),
       tenTurns,
     );
     expect(
       governor.interceptActions(toolDone(), inferAction, capabilities),
     ).toBeNull();
-    governor.noteIdleTurn(
-      inferenceDone(overThreshold + 2 * resumeDelta, echo),
-      [{ type: "reply", content: "done" }],
-    );
+    governor.noteIdleTurn(inferenceDone(overThreshold + 2 * wideDelta, echo), [
+      { type: "reply", content: "done" },
+    ]);
     expect(
       governor.interceptIdleContinuation(emptyMessage(), capabilities),
     ).toBeNull();
 
+    // ... and tool-call occupancy does not reopen either rail.
     governor.noteInferenceDone(
-      inferenceDone(overThreshold + 3 * resumeDelta, "real work"),
+      inferenceDoneWithTools(overThreshold + 3 * wideDelta),
       tenTurns,
     );
     expect(
       governor.interceptActions(toolDone(), inferAction, capabilities),
     ).toBeNull();
 
+    // Fold evidence restores the rails: under the watermark, then a fresh
+    // crossing arms immediately with no gap required.
+    governor.noteInferenceDone(inferenceDone(1000, "real work"), tenTurns);
     governor.noteInferenceDone(
-      inferenceDoneWithTools(overThreshold + 4 * resumeDelta),
+      inferenceDone(overThreshold, "real work"),
       tenTurns,
     );
     expect(
@@ -936,6 +941,167 @@ describe("compaction governor", () => {
   });
 });
 
+describe("post-compact above-threshold latch (CL-9006)", () => {
+  // Half the wide gap: growth that used to re-arm under the old resume delta
+  // must no longer re-arm on its own.
+  const smallGrowth = Math.floor(wideDelta / 2);
+
+  test("resume-delta-scale growth while still over threshold does not re-arm", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).not.toBeNull();
+
+    // Post-compact measurement stays over the high watermark: the latch sets.
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    // Growth by half the wide gap must NOT re-arm on its own.
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + smallGrowth),
+      tenTurns,
+    );
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).toBeNull();
+    // The idle path shares the same latch.
+    governor.noteIdleTurn(inferenceDone(overThreshold + smallGrowth), [
+      { type: "reply", content: "done" },
+    ]);
+    expect(
+      governor.interceptIdleContinuation(emptyMessage(), capabilities),
+    ).toBeNull();
+  });
+
+  test("a wide resume gap while still over threshold re-arms", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).not.toBeNull();
+
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + wideDelta),
+      tenTurns,
+    );
+    const actions = governor.interceptActions(
+      toolDone(),
+      inferAction,
+      capabilities,
+    );
+    expect(actions).not.toBeNull();
+    expect(actions?.some((a) => a.type === "compact")).toBe(true);
+  });
+
+  test("the consecutive-compact cap holds across tool-call occupancy", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).not.toBeNull();
+
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + wideDelta),
+      tenTurns,
+    );
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).not.toBeNull();
+
+    // Post-compact measurement still over: tool-call occupancy must not reset
+    // the cap, even past a wide gap.
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + wideDelta),
+      tenTurns,
+    );
+    governor.noteInferenceDone(
+      inferenceDoneWithTools(overThreshold + 2 * wideDelta),
+      tenTurns,
+    );
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).toBeNull();
+    // The idle path shares the same cap.
+    governor.noteIdleTurn(
+      inferenceDoneWithTools(overThreshold + 2 * wideDelta),
+      [{ type: "reply", content: "done" }],
+    );
+    expect(
+      governor.interceptIdleContinuation(emptyMessage(), capabilities),
+    ).toBeNull();
+  });
+
+  test("overflow recoveries are bounded across still-over measurements", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).not.toBeNull();
+    expect(governor.resumeAfterCompact(emptyMessage())).toBe("infer");
+
+    // Still-over post-compact measurement: no relief, budget stays spent.
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).not.toBeNull();
+    expect(governor.resumeAfterCompact(emptyMessage())).toBe("infer");
+
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).toBeNull();
+  });
+
+  test("an under-threshold fold restores the overflow budget", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).not.toBeNull();
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).not.toBeNull();
+    // Fold evidence: usage back under the watermark restores the budget.
+    governor.noteInferenceDone(inferenceDone(1000), tenTurns);
+    expect(
+      governor.interceptOverflow(overflowError(), capabilities),
+    ).not.toBeNull();
+  });
+
+  test("auto re-arm after an operator compact uses the identical latch", () => {
+    const governor = createCompactionGovernor(() => undefined);
+    governor.noteInferenceDone(inferenceDone(1000), tenTurns);
+    expect(governor.requestManual("", { inFlight: true })).toBe("armed");
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).not.toBeNull();
+
+    // Post-operator-compact measurement stays over: small growth must not
+    // re-arm the automatic path.
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + smallGrowth),
+      tenTurns,
+    );
+    expect(
+      governor.interceptActions(toolDone(), inferAction, capabilities),
+    ).toBeNull();
+
+    // Wide gap re-arms identically to the automatic path.
+    governor.noteInferenceDone(
+      inferenceDone(overThreshold + wideDelta),
+      tenTurns,
+    );
+    const actions = governor.interceptActions(
+      toolDone(),
+      inferAction,
+      capabilities,
+    );
+    expect(actions).not.toBeNull();
+    expect(actions?.some((a) => a.type === "compact")).toBe(true);
+  });
+});
+
 describe("cache expiry never folds (CL-8914)", () => {
   const MINUTE_MS = 60_000;
 
@@ -1045,10 +1211,10 @@ describe("cache expiry never folds (CL-8914)", () => {
     ).toBeNull();
   });
 
-  test("the hysteresis gap does not fold on cache expiry", () => {
+  test("the latched gap does not fold on cache expiry", () => {
     // After a threshold compact, a post-compact infer at the same usage
-    // clears `pending` via growth hysteresis — the exact re-entry where the
-    // removed TTL path used to fire.
+    // clears `pending` via the above-threshold latch — the exact re-entry
+    // where the removed TTL path used to fire.
     let nowMs = 70_000_000;
     const governor = createCompactionGovernor(
       () => undefined,