@aexol/spectral 0.9.182 → 0.9.183

package/dist/memory/hooks/observer-trigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observer-trigger.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/observer-trigger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAWpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAO7C,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA0KjF"}
+{"version":3,"file":"observer-trigger.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/observer-trigger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAWpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAY7C,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA8KjF"}

package/dist/memory/hooks/observer-trigger.js

@@ -7,23 +7,28 @@ import { estimateEntryTokens, estimateStringTokens } from "../tokens.js";
 import { OBSERVATION_CUSTOM_TYPE, reflectionToPromptLine } from "../types.js";
 import { getProjectObsStore } from "../project-observations-store.js";
 import { relayProjectObservations } from "../inter-agent-relay.js";
+/** Write diagnostic lines only when structured debug logging is enabled. */
+function debugStderr(runtime, message) {
+    if (runtime.config.debugLog === true)
+        process.stderr.write(message);
+}
 export function registerObserverTrigger(ext, runtime) {
     ext.on("turn_end", (_event, ctx) => {
-        process.stderr.write("[obs-mem] turn_end fired\n");
+        debugStderr(runtime, "[obs-mem] turn_end fired\n");
         runtime.ensureConfig(ctx.cwd);
         if (runtime.config.passive === true) {
-            process.stderr.write("[obs-mem] passive=true → skipping\n");
+            debugStderr(runtime, "[obs-mem] passive=true → skipping\n");
             return;
         }
         if (runtime.observerInFlight) {
-            process.stderr.write("[obs-mem] observer already in flight → skipping\n");
+            debugStderr(runtime, "[obs-mem] observer already in flight → skipping\n");
             return;
         }
         const entries = ctx.sessionManager.getBranch();
         const tokens = rawTokensSinceLastBound(entries);
-        process.stderr.write(`[obs-mem] tokens since last bound: ${tokens} (threshold: ${runtime.config.observationThresholdTokens})\n`);
+        debugStderr(runtime, `[obs-mem] tokens since last bound: ${tokens} (threshold: ${runtime.config.observationThresholdTokens})\n`);
         if (tokens < runtime.config.observationThresholdTokens) {
-            process.stderr.write("[obs-mem] below threshold → skipping observer\n");
+            debugStderr(runtime, "[obs-mem] below threshold → skipping observer\n");
             return;
         }
         const lastBoundIdx = lastObservationCoverEndIdx(entries);
@@ -60,7 +65,7 @@ export function registerObserverTrigger(ext, runtime) {
             if (capIdx < chunkEntries.length) {
                 chunkEntries = chunkEntries.slice(0, capIdx);
                 effectiveCoversUpToId = chunkEntries[capIdx - 1]?.id ?? coversUpToId;
-                process.stderr.write(`[obs-mem] chunk capped at ~${accumulated.toLocaleString()} tokens ` +
+                debugStderr(runtime, `[obs-mem] chunk capped at ~${accumulated.toLocaleString()} tokens ` +
                     `(${chunkEntries.length} source entries); remaining unobserved entries deferred\n`);
                 debugLog("observer.chunk_capped", {
                     originalCount: rawTailEntriesBetween(entries, coversFromId, coversUpToId).length,

package/dist/relay/client.d.ts

@@ -7,12 +7,16 @@
  *    machine JWT via `Authorization: Bearer <jwt>`.
  *  - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
  *    `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
- *    rely on the backend pings rather than emitting our own (single source
- *    of liveness, no jitter on our side).
+ *    keep this app-level reply in addition to the protocol-level heartbeat
+ *    below.
+ *  - **Client heartbeat:** additionally emits a protocol-level `ws` ping
+ *    every `HEARTBEAT_INTERVAL_MS` and requires a `pong` within
+ *    `HEARTBEAT_TIMEOUT_MS`. This detects a half-open send path (e.g. after
+ *    laptop sleep/wake) where `readyState` still reports `OPEN`.
  *  - **Watchdog timer:** tracks `lastActivityMs` on every received frame /
  *    ping. Every 15 s, if no activity within `WATCHDOG_MS` (120 s = 2×
- *    backend timeout), force-closes the socket (4001 "watchdog-timeout")
- *    and triggers a reconnect. Detects silent backend death (Docker OOM
+ *    backend timeout), terminates the socket and triggers a reconnect.
+ *    Detects silent backend death (Docker OOM
  *    kill, network partition without TCP RST) where the socket stays open
  *    but no data flows.
  *  - **Pre-reconnect health check:** before opening a new WS, does a quick
@@ -104,11 +108,19 @@ export declare class RelayClient extends EventEmitter {
     private tightLoopWindowStart;
     private reconnectTimer;
     private sendQueue;
+    /** Wire currently waiting on a `ws.send` callback. Only one in flight to preserve FIFO. */
+    private sendInFlight;
+    private sendTimer;
     /** Set true when the WS error handler sees an HTTP 401/403 upgrade rejection. */
     private authFailed;
     /** Timestamp of last received frame / ping — drives the watchdog. */
     private lastActivityMs;
     private watchdogTimer;
+    private heartbeatTimer;
+    private heartbeatPongTimer;
+    private heartbeatPending;
+    /** Guards the async window of `scheduleReconnect` (health check). */
+    private reconnectInFlight;
     constructor(opts: RelayClientOptions);
     /** Open the connection. Idempotent — calling twice is a no-op. */
     connect(): void;
@@ -129,6 +141,30 @@ export declare class RelayClient extends EventEmitter {
     private openSocket;
     private startWatchdog;
     private stopWatchdog;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private enqueueWire;
+    private clearSendInFlight;
+    /**
+     * Drain the FIFO send queue over the current socket. Exactly one frame is
+     * in flight at a time so ordering is preserved. If `ws.send` never calls
+     * its callback (half-open socket), the frame stays at the front of the
+     * queue and the connection is force-reconnected; the next `open` flushes
+     * it again.
+     */
+    private flushSendQueue;
+    private setTcpKeepAlive;
+    /**
+     * Tear down a suspected-dead socket and schedule a reconnect immediately.
+     * Unlike the `close` path, this does not wait for a (possibly never
+     * arriving) `close` event — `terminate()` destroys the socket directly.
+     */
+    private forceReconnect;
+    /**
+     * Single disconnect entry point for both real `close` events and forced
+     * reconnects. Ignored for sockets that have already been replaced.
+     */
+    private handleDisconnect;
     /**
      * Pre-reconnect health check: quick HTTP GET to `<backendUrl>/health`.
      * Returns true when the backend is reachable (or when no backendUrl is

package/dist/relay/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,SAAS,MAAM,IAAI,CAAC;AA4B3B,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD,2DAA2D;IAC3D,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+C;IAE3E,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,mEAAmE;IACnE,OAAO,CAAC,UAAU,CAAK;IACvB,qEAAqE;IACrE,OAAO,CAAC,sBAAsB,CAAK;IACnC,mEAAmE;IACnE,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,SAAS,CAAgB;IACjC,iFAAiF;IACjF,OAAO,CAAC,UAAU,CAAS;IAE3B,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAA+B;gBAExC,IAAI,EAAE,kBAAkB;IAYpC,kEAAkE;IAClE,OAAO,IAAI,IAAI;IAMf;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO;IAqBzC;;;OAGG;IACH,OAAO,IAAI,IAAI;IA2Bf,OAAO,CAAC,UAAU;IA4LlB,OAAO,CAAC,aAAa;IAsBrB,OAAO,CAAC,YAAY;IAOpB;;;;;OAKG;YACW,WAAW;YA8BX,iBAAiB;CAmDhC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/relay/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,SAAS,MAAM,IAAI,CAAC;AAoC3B,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACjD,2DAA2D;IAC3D,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AASD,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAmB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+C;IAE3E,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,mEAAmE;IACnE,OAAO,CAAC,UAAU,CAAK;IACvB,qEAAqE;IACrE,OAAO,CAAC,sBAAsB,CAAK;IACnC,mEAAmE;IACnE,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,SAAS,CAAgB;IACjC,2FAA2F;IAC3F,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAA+B;IAChD,iFAAiF;IACjF,OAAO,CAAC,UAAU,CAAS;IAE3B,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,kBAAkB,CAA+B;IACzD,OAAO,CAAC,gBAAgB,CAAS;IACjC,qEAAqE;IACrE,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,IAAI,EAAE,kBAAkB;IAYpC,kEAAkE;IAClE,OAAO,IAAI,IAAI;IAMf;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO;IAQzC;;;OAGG;IACH,OAAO,IAAI,IAAI;IA6Bf,OAAO,CAAC,UAAU;IAwFlB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,iBAAiB;IAQzB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAqDtB,OAAO,CAAC,eAAe;IAOvB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+GxB;;;;;OAKG;YACW,WAAW;YA8BX,iBAAiB;CAyDhC"}

package/dist/relay/client.js

@@ -7,12 +7,16 @@
  *    machine JWT via `Authorization: Bearer <jwt>`.
  *  - Reply `{kind:"pong"}` to backend `{kind:"ping"}`. Backend closes
  *    `4408 heartbeat-timeout` if it doesn't hear from us within 90s; we
- *    rely on the backend pings rather than emitting our own (single source
- *    of liveness, no jitter on our side).
+ *    keep this app-level reply in addition to the protocol-level heartbeat
+ *    below.
+ *  - **Client heartbeat:** additionally emits a protocol-level `ws` ping
+ *    every `HEARTBEAT_INTERVAL_MS` and requires a `pong` within
+ *    `HEARTBEAT_TIMEOUT_MS`. This detects a half-open send path (e.g. after
+ *    laptop sleep/wake) where `readyState` still reports `OPEN`.
  *  - **Watchdog timer:** tracks `lastActivityMs` on every received frame /
  *    ping. Every 15 s, if no activity within `WATCHDOG_MS` (120 s = 2×
- *    backend timeout), force-closes the socket (4001 "watchdog-timeout")
- *    and triggers a reconnect. Detects silent backend death (Docker OOM
+ *    backend timeout), terminates the socket and triggers a reconnect.
+ *    Detects silent backend death (Docker OOM
  *    kill, network partition without TCP RST) where the socket stays open
  *    but no data flows.
  *  - **Pre-reconnect health check:** before opening a new WS, does a quick
@@ -66,6 +70,14 @@ const WATCHDOG_INTERVAL_MS = 15_000;
 const WATCHDOG_SILENCE_MS = 120_000;
 /** HTTP timeout for the pre-reconnect health check. */
 const HEALTH_CHECK_TIMEOUT_MS = 5_000;
+/** TCP keepalive initial delay (ms). Lets the OS detect a dead path after sleep. */
+const TCP_KEEPALIVE_MS = 30_000;
+/** Client-originated protocol-level ping interval (ms). */
+const HEARTBEAT_INTERVAL_MS = 30_000;
+/** Client pong timeout before forcing a reconnect (ms). */
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+/** Outbound write acknowledgement timeout (ms). */
+const SEND_TIMEOUT_MS = 10_000;
 export class RelayClient extends EventEmitter {
     relayUrl;
     machineJwt;
@@ -86,11 +98,19 @@ export class RelayClient extends EventEmitter {
     tightLoopWindowStart = 0;
     reconnectTimer = null;
     sendQueue = [];
+    /** Wire currently waiting on a `ws.send` callback. Only one in flight to preserve FIFO. */
+    sendInFlight = null;
+    sendTimer = null;
     /** Set true when the WS error handler sees an HTTP 401/403 upgrade rejection. */
     authFailed = false;
     /** Timestamp of last received frame / ping — drives the watchdog. */
     lastActivityMs = 0;
     watchdogTimer = null;
+    heartbeatTimer = null;
+    heartbeatPongTimer = null;
+    heartbeatPending = false;
+    /** Guards the async window of `scheduleReconnect` (health check). */
+    reconnectInFlight = false;
     constructor(opts) {
         super();
         this.relayUrl = opts.relayUrl;
@@ -106,7 +126,7 @@ export class RelayClient extends EventEmitter {
     connect() {
         if (this.disposed)
             return;
-        if (this.ws)
+        if (this.ws || this.reconnectTimer || this.reconnectInFlight)
             return;
         this.openSocket();
     }
@@ -122,22 +142,8 @@ export class RelayClient extends EventEmitter {
         if (this.disposed)
             return false;
         const wire = typeof frame === "string" ? frame : JSON.stringify(frame);
-        const ws = this.ws;
-        if (ws && ws.readyState === WebSocket.OPEN) {
-            try {
-                ws.send(wire);
-                return true;
-            }
-            catch (err) {
-                this.emit("error", err);
-                return false;
-            }
-        }
-        // Queue it.
-        if (this.sendQueue.length >= SEND_QUEUE_CAP) {
-            this.sendQueue.shift();
-        }
-        this.sendQueue.push(wire);
+        this.enqueueWire(wire);
+        this.flushSendQueue();
         return true;
     }
     /**
@@ -156,6 +162,8 @@ export class RelayClient extends EventEmitter {
             clearInterval(this.watchdogTimer);
             this.watchdogTimer = null;
         }
+        this.stopHeartbeat();
+        this.clearSendInFlight();
         const ws = this.ws;
         this.ws = null;
         if (ws) {
@@ -183,25 +191,20 @@ export class RelayClient extends EventEmitter {
         this.lastActivityMs = Date.now();
         this.startWatchdog();
         ws.on("open", () => {
+            if (this.ws !== ws)
+                return;
             this.lastActivityMs = Date.now();
             this.openedAtMs = Date.now();
-            // Flush any queued frames.
-            const queued = this.sendQueue;
-            this.sendQueue = [];
-            for (const wire of queued) {
-                try {
-                    ws.send(wire);
-                }
-                catch (err) {
-                    // Re-queue on failure and stop draining; the next open will retry.
-                    this.sendQueue = queued.slice(queued.indexOf(wire));
-                    this.emit("error", err);
-                    return;
-                }
-            }
+            this.setTcpKeepAlive(ws);
+            this.startHeartbeat();
+            // Flush any queued frames with write acknowledgements and timeouts.
+            this.clearSendInFlight();
+            this.flushSendQueue();
             this.emit("open");
         });
         ws.on("message", (data) => {
+            if (this.ws !== ws)
+                return;
             this.lastActivityMs = Date.now();
             let parsed;
             try {
@@ -213,12 +216,7 @@ export class RelayClient extends EventEmitter {
             }
             // Heartbeat: reply pong inline, do NOT propagate.
             if (parsed && parsed.kind === "ping") {
-                try {
-                    ws.send(JSON.stringify({ kind: "pong" }));
-                }
-                catch (err) {
-                    this.emit("error", err);
-                }
+                this.send({ kind: "pong" });
                 return;
             }
             if (parsed && parsed.kind === "welcome") {
@@ -230,7 +228,21 @@ export class RelayClient extends EventEmitter {
             }
             this.emit("frame", parsed);
         });
+        ws.on("pong", () => {
+            if (this.ws !== ws)
+                return;
+            this.lastActivityMs = Date.now();
+            if (this.heartbeatPending) {
+                this.heartbeatPending = false;
+                if (this.heartbeatPongTimer) {
+                    clearTimeout(this.heartbeatPongTimer);
+                    this.heartbeatPongTimer = null;
+                }
+            }
+        });
         ws.on("error", (err) => {
+            if (this.ws !== ws)
+                return;
             // Detect HTTP auth failures during the WS upgrade handshake.
             // The `ws` library surfaces these as `Error: Unexpected server
             // response: 401` (or 403). Mark `authFailed` so the close handler
@@ -240,97 +252,13 @@ export class RelayClient extends EventEmitter {
                 msg.includes("Unexpected server response: 403")) {
                 this.authFailed = true;
             }
-            // `ws` emits 'error' before 'close'; we don't reconnect here — the
-            // 'close' handler is the single reconnect entry point so we don't
-            // double-schedule.
+            // `ws` emits 'error' before 'close'. Reconnect is driven from the
+            // `close` handler (or `forceReconnect` for suspected-dead sockets);
+            // scheduling it here would double-schedule.
             this.emit("error", err);
         });
         ws.on("close", (code, reason) => {
-            this.ws = null;
-            this.stopWatchdog();
-            // Stable-open gate: only reset backoff if the socket was open long
-            // enough to be considered healthy. A connect→immediate-die loop (1006,
-            // proxy kill, duplicate instance) must escalate through the full
-            // schedule instead of pinning at RECONNECT_SCHEDULE[0] = 1s forever.
-            const openDuration = this.openedAtMs > 0 ? Date.now() - this.openedAtMs : 0;
-            this.openedAtMs = 0;
-            if (openDuration >= STABLE_OPEN_MS) {
-                this.reconnectAttempt = 0;
-                this.consecutiveRapidCloses = 0;
-            }
-            else {
-                // Tight-loop detection: if the socket dies repeatedly right after
-                // open, bail out with an actionable message instead of reconnecting
-                // forever.
-                const now = Date.now();
-                if (now - this.tightLoopWindowStart > TIGHT_LOOP_WINDOW_MS) {
-                    this.tightLoopWindowStart = now;
-                    this.consecutiveRapidCloses = 1;
-                }
-                else {
-                    this.consecutiveRapidCloses++;
-                }
-                if (this.consecutiveRapidCloses >= TIGHT_LOOP_MAX_CLOSES) {
-                    this.logger.error("\n✗ Relay connection dropped repeatedly right after opening.");
-                    this.logger.error("  This usually means another `spectral serve` process is running for the same machine,");
-                    this.logger.error("  or a reverse proxy / firewall is closing the WebSocket immediately.");
-                    this.logger.error('  Check: `ps aux | grep "spectral serve"` and your proxy WS timeout settings.\n');
-                    this.dispose();
-                    this.exit(1);
-                    return;
-                }
-            }
-            const reasonStr = reason?.toString() ?? "";
-            this.emit("close", { code, reason: reasonStr });
-            if (this.disposed)
-                return;
-            // Backend evicts older WS sessions when a newer registration arrives
-            // for the same machineId (see backend `registry.ts: register()`).
-            // If we reconnect here we'll just kick out the new instance, which
-            // will then reconnect and kick us out — an infinite ping-pong.
-            // Exit instead so the operator (or process supervisor) notices.
-            if (code === 1000 && reasonStr === "replaced-by-newer-registration") {
-                this.logger.error("\n✗ Another `spectral serve` instance has registered for this machine.");
-                this.logger.error("  This instance is exiting to avoid a reconnect loop.");
-                this.logger.error("  If you want to run multiple instances, use distinct `--machine-name` values.\n");
-                this.dispose();
-                this.exit(1);
-                return;
-            }
-            // Machine was revoked by the team admin from the Aexol Studio panel
-            // (backend sets `KnownMachine.revokedAt` and closes the socket with
-            // 4001 "machine-revoked"). Exit immediately — the machine JWT is now
-            // invalid and re-registration requires a fresh `spectral serve`.
-            if (code === 4001 && reasonStr === "machine-revoked") {
-                this.logger.error("\n✗ This machine has been disconnected from the Aexol Studio panel.");
-                // Delete the machine identity file so the next `spectral serve`
-                // forces a fresh registration rather than reusing the revoked JWT.
-                unlink(getMachineFile()).catch(() => { });
-                this.logger.error("  Run `spectral login` then `spectral serve` to re-register.\n");
-                this.dispose();
-                this.exit(1);
-                return;
-            }
-            if (reasonStr === "team-changed") {
-                // Team was changed via Studio — the machine_team_changed frame handler
-                // in serve.ts already saved the new JWT. Just reconnect normally.
-                if (this.authFailed) {
-                    this.emit("auth-failed");
-                    return;
-                }
-                this.scheduleReconnect();
-                return;
-            }
-            // Auth failure at the transport layer (HTTP 401/403 on WS upgrade).
-            // The machine JWT is invalid (expired, malformed, or revoked by key
-            // rotation) but the backend didn't send a structured close reason.
-            // Signal the caller so it can attempt re-registration instead of
-            // entering an infinite reconnect loop with a dead token.
-            if (this.authFailed) {
-                this.emit("auth-failed");
-                return;
-            }
-            this.scheduleReconnect();
+            this.handleDisconnect(ws, code, reason?.toString() ?? "");
         });
     }
     // --- watchdog -------------------------------------------------------------
@@ -343,16 +271,7 @@ export class RelayClient extends EventEmitter {
             const elapsed = Date.now() - this.lastActivityMs;
             if (elapsed > WATCHDOG_SILENCE_MS) {
                 this.logger.warn(`Watchdog: no relay activity for ${Math.round(elapsed / 1000)}s, forcing reconnect`);
-                const ws = this.ws;
-                this.ws = null;
-                if (ws) {
-                    try {
-                        ws.close(4001, "watchdog-timeout");
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
+                this.forceReconnect("watchdog-timeout");
             }
         }, WATCHDOG_INTERVAL_MS);
     }
@@ -362,6 +281,250 @@ export class RelayClient extends EventEmitter {
             this.watchdogTimer = null;
         }
     }
+    // --- heartbeat -------------------------------------------------------------
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            if (this.disposed)
+                return;
+            const ws = this.ws;
+            if (!ws || ws.readyState !== WebSocket.OPEN || this.heartbeatPending) {
+                return;
+            }
+            this.heartbeatPending = true;
+            this.heartbeatPongTimer = setTimeout(() => {
+                this.heartbeatPongTimer = null;
+                if (!this.heartbeatPending)
+                    return;
+                this.heartbeatPending = false;
+                this.logger.warn("Heartbeat: no pong from relay, forcing reconnect");
+                this.forceReconnect("heartbeat-timeout");
+            }, HEARTBEAT_TIMEOUT_MS);
+            try {
+                ws.ping();
+            }
+            catch (err) {
+                this.heartbeatPending = false;
+                if (this.heartbeatPongTimer) {
+                    clearTimeout(this.heartbeatPongTimer);
+                    this.heartbeatPongTimer = null;
+                }
+                this.emit("error", err);
+                this.forceReconnect("heartbeat-error");
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.heartbeatPongTimer) {
+            clearTimeout(this.heartbeatPongTimer);
+            this.heartbeatPongTimer = null;
+        }
+        this.heartbeatPending = false;
+    }
+    // --- outbound send safety ---------------------------------------------------
+    enqueueWire(wire) {
+        if (this.sendQueue.length >= SEND_QUEUE_CAP) {
+            // Never evict the frame currently awaiting a write callback — it is
+            // still at the front of the queue and must survive a reconnect.
+            const dropIndex = this.sendInFlight !== null ? 1 : 0;
+            if (this.sendQueue.length > dropIndex) {
+                this.sendQueue.splice(dropIndex, 1);
+            }
+        }
+        this.sendQueue.push(wire);
+    }
+    clearSendInFlight() {
+        this.sendInFlight = null;
+        if (this.sendTimer) {
+            clearTimeout(this.sendTimer);
+            this.sendTimer = null;
+        }
+    }
+    /**
+     * Drain the FIFO send queue over the current socket. Exactly one frame is
+     * in flight at a time so ordering is preserved. If `ws.send` never calls
+     * its callback (half-open socket), the frame stays at the front of the
+     * queue and the connection is force-reconnected; the next `open` flushes
+     * it again.
+     */
+    flushSendQueue() {
+        if (this.disposed)
+            return;
+        const ws = this.ws;
+        if (!ws ||
+            ws.readyState !== WebSocket.OPEN ||
+            this.sendInFlight !== null ||
+            this.sendQueue.length === 0) {
+            return;
+        }
+        const wire = this.sendQueue[0];
+        this.sendInFlight = wire;
+        this.sendTimer = setTimeout(() => {
+            this.sendTimer = null;
+            if (this.sendInFlight !== wire || this.ws !== ws)
+                return;
+            this.sendInFlight = null;
+            this.logger.warn("Relay send timed out; forcing reconnect");
+            this.forceReconnect("send-timeout");
+        }, SEND_TIMEOUT_MS);
+        try {
+            ws.send(wire, (err) => {
+                if (this.sendInFlight !== wire)
+                    return;
+                this.sendInFlight = null;
+                if (this.sendTimer) {
+                    clearTimeout(this.sendTimer);
+                    this.sendTimer = null;
+                }
+                if (err) {
+                    this.logger.warn(`Relay send failed: ${err.message}`);
+                    this.forceReconnect("send-error");
+                    return;
+                }
+                if (this.sendQueue[0] === wire) {
+                    this.sendQueue.shift();
+                }
+                this.flushSendQueue();
+            });
+        }
+        catch (err) {
+            if (this.sendInFlight === wire) {
+                this.sendInFlight = null;
+                if (this.sendTimer) {
+                    clearTimeout(this.sendTimer);
+                    this.sendTimer = null;
+                }
+                this.emit("error", err);
+                this.forceReconnect("send-error");
+            }
+        }
+    }
+    setTcpKeepAlive(ws) {
+        const socket = ws._socket;
+        if (socket && typeof socket.setKeepAlive === "function") {
+            socket.setKeepAlive(true, TCP_KEEPALIVE_MS);
+        }
+    }
+    /**
+     * Tear down a suspected-dead socket and schedule a reconnect immediately.
+     * Unlike the `close` path, this does not wait for a (possibly never
+     * arriving) `close` event — `terminate()` destroys the socket directly.
+     */
+    forceReconnect(reason) {
+        if (this.disposed)
+            return;
+        const ws = this.ws;
+        if (!ws) {
+            void this.scheduleReconnect();
+            return;
+        }
+        try {
+            ws.terminate();
+        }
+        catch (err) {
+            this.emit("error", err);
+        }
+        this.handleDisconnect(ws, 1006, reason);
+    }
+    /**
+     * Single disconnect entry point for both real `close` events and forced
+     * reconnects. Ignored for sockets that have already been replaced.
+     */
+    handleDisconnect(ws, code, reason) {
+        if (this.ws !== ws)
+            return;
+        this.ws = null;
+        this.stopWatchdog();
+        this.stopHeartbeat();
+        this.clearSendInFlight();
+        // Stable-open gate: only reset backoff if the socket was open long
+        // enough to be considered healthy. A connect→immediate-die loop (1006,
+        // proxy kill, duplicate instance) must escalate through the full
+        // schedule instead of pinning at RECONNECT_SCHEDULE[0] = 1s forever.
+        const openDuration = this.openedAtMs > 0 ? Date.now() - this.openedAtMs : 0;
+        this.openedAtMs = 0;
+        if (openDuration >= STABLE_OPEN_MS) {
+            this.reconnectAttempt = 0;
+            this.consecutiveRapidCloses = 0;
+        }
+        else {
+            // Tight-loop detection: if the socket dies repeatedly right after
+            // open, bail out with an actionable message instead of reconnecting
+            // forever.
+            const now = Date.now();
+            if (now - this.tightLoopWindowStart > TIGHT_LOOP_WINDOW_MS) {
+                this.tightLoopWindowStart = now;
+                this.consecutiveRapidCloses = 1;
+            }
+            else {
+                this.consecutiveRapidCloses++;
+            }
+            if (this.consecutiveRapidCloses >= TIGHT_LOOP_MAX_CLOSES) {
+                this.logger.error("\n✗ Relay connection dropped repeatedly right after opening.");
+                this.logger.error("  This usually means another `spectral serve` process is running for the same machine,");
+                this.logger.error("  or a reverse proxy / firewall is closing the WebSocket immediately.");
+                this.logger.error('  Check: `ps aux | grep "spectral serve"` and your proxy WS timeout settings.\n');
+                this.dispose();
+                this.exit(1);
+                return;
+            }
+        }
+        this.emit("close", { code, reason });
+        if (this.disposed)
+            return;
+        // Backend evicts older WS sessions when a newer registration arrives
+        // for the same machineId (see backend `registry.ts: register()`).
+        // If we reconnect here we'll just kick out the new instance, which
+        // will then reconnect and kick us out — an infinite ping-pong.
+        // Exit instead so the operator (or process supervisor) notices.
+        if (code === 1000 && reason === "replaced-by-newer-registration") {
+            this.logger.error("\n✗ Another `spectral serve` instance has registered for this machine.");
+            this.logger.error("  This instance is exiting to avoid a reconnect loop.");
+            this.logger.error("  If you want to run multiple instances, use distinct `--machine-name` values.\n");
+            this.dispose();
+            this.exit(1);
+            return;
+        }
+        // Machine was revoked by the team admin from the Aexol Studio panel
+        // (backend sets `KnownMachine.revokedAt` and closes the socket with
+        // 4001 "machine-revoked"). Exit immediately — the machine JWT is now
+        // invalid and re-registration requires a fresh `spectral serve`.
+        if (code === 4001 && reason === "machine-revoked") {
+            this.logger.error("\n✗ This machine has been disconnected from the Aexol Studio panel.");
+            // Delete the machine identity file so the next `spectral serve`
+            // forces a fresh registration rather than reusing the revoked JWT.
+            unlink(getMachineFile()).catch(() => { });
+            this.logger.error("  Run `spectral login` then `spectral serve` to re-register.\n");
+            this.dispose();
+            this.exit(1);
+            return;
+        }
+        if (reason === "team-changed") {
+            // Team was changed via Studio — the machine_team_changed frame handler
+            // in serve.ts already saved the new JWT. Just reconnect normally.
+            if (this.authFailed) {
+                this.emit("auth-failed");
+                return;
+            }
+            void this.scheduleReconnect();
+            return;
+        }
+        // Auth failure at the transport layer (HTTP 401/403 on WS upgrade).
+        // The machine JWT is invalid (expired, malformed, or revoked by key
+        // rotation) but the backend didn't send a structured close reason.
+        // Signal the caller so it can attempt re-registration instead of
+        // entering an infinite reconnect loop with a dead token.
+        if (this.authFailed) {
+            this.emit("auth-failed");
+            return;
+        }
+        void this.scheduleReconnect();
+    }
     /**
      * Pre-reconnect health check: quick HTTP GET to `<backendUrl>/health`.
      * Returns true when the backend is reachable (or when no backendUrl is
@@ -400,54 +563,62 @@ export class RelayClient extends EventEmitter {
     async scheduleReconnect() {
         if (this.disposed)
             return;
-        if (this.reconnectTimer)
+        if (this.reconnectTimer || this.reconnectInFlight)
             return;
-        // Pre-reconnect health check — avoids wasting time on a slow TCP
-        // connect when the backend is down. The health endpoint is a cheap
-        // HTTP GET; if even that fails, skip the WS attempt entirely.
-        const healthy = await this.healthCheck();
-        if (!healthy) {
-            // Backend unreachable — use a fixed 5 s retry instead of advancing
-            // the backoff schedule (this is an environment problem, not a WS
-            // handshake problem).
+        this.reconnectInFlight = true;
+        try {
+            // Pre-reconnect health check — avoids wasting time on a slow TCP
+            // connect when the backend is down. The health endpoint is a cheap
+            // HTTP GET; if even that fails, skip the WS attempt entirely.
+            const healthy = await this.healthCheck();
+            if (this.disposed)
+                return;
+            if (!healthy) {
+                // Backend unreachable — use a fixed 5 s retry instead of advancing
+                // the backoff schedule (this is an environment problem, not a WS
+                // handshake problem).
+                const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
+                const delay = RECONNECT_SCHEDULE[idx];
+                this.reconnectAttempt++;
+                this.emit("reconnect-scheduled", { delayMs: delay, attempt: this.reconnectAttempt });
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = null;
+                    void this.scheduleReconnect().catch(() => { });
+                }, delay);
+                return;
+            }
             const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
-            const delay = RECONNECT_SCHEDULE[idx];
+            const base = RECONNECT_SCHEDULE[idx];
+            const jitter = base * JITTER_RATIO * (Math.random() * 2 - 1);
+            const delay = Math.max(0, Math.round(base + jitter));
             this.reconnectAttempt++;
             this.emit("reconnect-scheduled", { delayMs: delay, attempt: this.reconnectAttempt });
+            // IMPORTANT: do NOT `unref()` this timer. `spectral serve` is a long-
+            // lived daemon and the reconnect timer is frequently the ONLY thing
+            // keeping the event loop alive between a WS close and the next open
+            // (the SessionStreamManager holds nothing while idle). An unref'd
+            // timer lets Node decide the loop is empty and exit the process,
+            // which manifests as the daemon silently dying after a network blip.
+            // Tests dispose the client explicitly via `dispose()`, which clears
+            // this timer, so they still terminate cleanly.
             this.reconnectTimer = setTimeout(() => {
                 this.reconnectTimer = null;
-                void this.scheduleReconnect().catch(() => { });
+                if (this.disposed)
+                    return;
+                try {
+                    this.openSocket();
+                }
+                catch (err) {
+                    // A synchronous throw from the WebSocket constructor (DNS, bad
+                    // URL, etc.) must not kill the daemon — log it and re-schedule
+                    // so the backoff continues forever.
+                    this.emit("error", err);
+                    void this.scheduleReconnect().catch(() => { });
+                }
             }, delay);
-            return;
         }
-        const idx = Math.min(this.reconnectAttempt, RECONNECT_SCHEDULE.length - 1);
-        const base = RECONNECT_SCHEDULE[idx];
-        const jitter = base * JITTER_RATIO * (Math.random() * 2 - 1);
-        const delay = Math.max(0, Math.round(base + jitter));
-        this.reconnectAttempt++;
-        this.emit("reconnect-scheduled", { delayMs: delay, attempt: this.reconnectAttempt });
-        // IMPORTANT: do NOT `unref()` this timer. `spectral serve` is a long-
-        // lived daemon and the reconnect timer is frequently the ONLY thing
-        // keeping the event loop alive between a WS close and the next open
-        // (the SessionStreamManager holds nothing while idle). An unref'd
-        // timer lets Node decide the loop is empty and exit the process,
-        // which manifests as the daemon silently dying after a network blip.
-        // Tests dispose the client explicitly via `dispose()`, which clears
-        // this timer, so they still terminate cleanly.
-        this.reconnectTimer = setTimeout(() => {
-            this.reconnectTimer = null;
-            if (this.disposed)
-                return;
-            try {
-                this.openSocket();
-            }
-            catch (err) {
-                // A synchronous throw from the WebSocket constructor (DNS, bad
-                // URL, etc.) must not kill the daemon — log it and re-schedule
-                // so the backoff continues forever.
-                this.emit("error", err);
-                void this.scheduleReconnect().catch(() => { });
-            }
-        }, delay);
+        finally {
+            this.reconnectInFlight = false;
+        }
     }
 }

package/dist/sdk/ai/cache-benchmark/benchmark.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/benchmark.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAgB,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,CAiE9F;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,EAAE,CASzG;AASD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAmBxE"}
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/benchmark.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAgB,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,CA0F9F;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,EAAE,CASzG;AASD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAuBxE"}

package/dist/sdk/ai/cache-benchmark/benchmark.js

@@ -8,6 +8,7 @@ function resolvePricing(config) {
 export function runBenchmark(strategy, config) {
     const pricing = resolvePricing(config);
     const minCacheTokens = config.minCacheTokens ?? 1024;
+    const reReadFraction = config.reReadFraction ?? 0;
     const systemText = fillerText(Math.max(0, config.systemPromptTokens * 4), 0);
     const toolsText = fillerText(Math.max(0, config.toolsTokens * 4), 1);
     const simulator = new PrefixCacheSimulator({
@@ -23,6 +24,10 @@ export function runBenchmark(strategy, config) {
     let totalCacheWriteTokens = 0;
     let maxPromptTokens = 0;
     let finalPromptTokens = 0;
+    let totalTurnPromptTokens = 0;
+    let totalDroppedTokens = 0;
+    let totalSummaryTokens = 0;
+    let totalReReadTokens = 0;
     for (let turn = 0; turn < config.turns; turn++) {
         const promptTokens = resolvePerTurn(config.turnPromptTokens, turn);
         const outputTokens = resolvePerTurn(config.turnOutputTokens, turn);
@@ -31,6 +36,13 @@ export function runBenchmark(strategy, config) {
         state = { entries: step.entries };
         if (step.cut)
             cutCount++;
+        if (step.lost) {
+            totalDroppedTokens += step.lost.droppedTokens;
+            totalSummaryTokens += step.lost.summaryTokens;
+            const hardLost = Math.max(0, step.lost.droppedTokens - step.lost.summaryTokens);
+            totalReReadTokens += hardLost * reReadFraction;
+        }
+        totalTurnPromptTokens += promptTokens;
         const promptText = serializePrompt(systemText, toolsText, step.entries);
         const result = simulator.account(promptText, outputTokens);
         totalPromptTokens += result.promptTokens;
@@ -41,7 +53,13 @@ export function runBenchmark(strategy, config) {
         maxPromptTokens = Math.max(maxPromptTokens, result.promptTokens);
         finalPromptTokens = result.promptTokens;
     }
-    const totalCost = (totalInputTokens * pricing.input +
+    const contextLossRate = totalDroppedTokens > 0
+        ? Math.min(1, Math.max(0, 1 - totalSummaryTokens / totalDroppedTokens))
+        : 0;
+    const avgTurnPromptTokens = totalTurnPromptTokens / config.turns;
+    const reReadTurns = avgTurnPromptTokens > 0 ? totalReReadTokens / avgTurnPromptTokens : 0;
+    const reReadCost = (totalReReadTokens * pricing.input) / 1_000_000;
+    const totalCost = ((totalInputTokens + totalReReadTokens) * pricing.input +
         totalOutputTokens * pricing.output +
         totalCacheReadTokens * pricing.cacheRead) /
         1_000_000;
@@ -59,6 +77,12 @@ export function runBenchmark(strategy, config) {
         avgPromptTokens: Math.round(totalPromptTokens / config.turns),
         maxPromptTokens,
         finalPromptTokens,
+        totalDroppedTokens,
+        totalSummaryTokens,
+        contextLossRate,
+        totalReReadTokens,
+        reReadTurns,
+        reReadCost,
         totalCost,
         costPerTurn: totalCost / config.turns,
         costVsKeepAllPct: 0,
@@ -85,14 +109,14 @@ export function formatBenchmarkReport(results) {
     const lines = [];
     lines.push("## Cache benchmark (OpenAI-style prefix cache)");
     lines.push("");
-    lines.push("cacheHitRate = cacheRead / prompt tokens; input == cacheWrite == uncached prompt tokens.");
+    lines.push("cacheHitRate = cacheRead / prompt tokens.");
+    lines.push("ctx loss % = 1 - summaryTokens/droppedTokens (100% == hard truncation destroyed everything).");
+    lines.push("re-read tokens = hard-lost context re-injected as new uncached input; re-read turns = re-read tokens / avg turn prompt. cost $ includes the re-read penalty.");
     lines.push("");
-    lines.push("| strategy | cuts | avg prompt | avg cacheRead | avg cacheWrite | cache hit % | cost $ | cost/turn $ | vs keep-all % |");
-    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
+    lines.push("| strategy | cuts | avg prompt | cache hit % | ctx loss % | dropped ctx | re-read tok | re-read turns | cost $ | vs keep-all % |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
     for (const result of results) {
-        const avgCacheRead = result.totalCacheReadTokens / result.turns;
-        const avgCacheWrite = result.totalCacheWriteTokens / result.turns;
-        lines.push(`| ${result.name} | ${result.cutCount} | ${fmt(result.avgPromptTokens, 0)} | ${fmt(avgCacheRead, 0)} | ${fmt(avgCacheWrite, 0)} | ${fmt(result.cacheHitRate * 100, 1)} | ${fmt(result.totalCost, 4)} | ${fmt(result.costPerTurn, 5)} | ${fmt(result.costVsKeepAllPct, 1)} |`);
+        lines.push(`| ${result.name} | ${result.cutCount} | ${fmt(result.avgPromptTokens, 0)} | ${fmt(result.cacheHitRate * 100, 1)} | ${fmt(result.contextLossRate * 100, 1)} | ${fmt(result.totalDroppedTokens, 0)} | ${fmt(result.totalReReadTokens, 0)} | ${fmt(result.reReadTurns, 1)} | ${fmt(result.totalCost, 4)} | ${fmt(result.costVsKeepAllPct, 1)} |`);
     }
     lines.push("");
     return lines.join("\n");

package/dist/sdk/ai/cache-benchmark/strategies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/strategies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAM5E,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAUtF;AAED,wFAAwF;AACxF,wBAAgB,OAAO,IAAI,aAAa,CAMvC;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAUlE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,CAc3F;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC/B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACnB,aAAa,CAiBf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACnB,aAAa,CA8Bf"}
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/strategies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAU5E,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAUtF;AAED,wFAAwF;AACxF,wBAAgB,OAAO,IAAI,aAAa,CAMvC;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAgBlE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,CAoB3F;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC/B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACnB,aAAa,CAsBf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACnB,aAAa,CAmCf"}

package/dist/sdk/ai/cache-benchmark/strategies.js

@@ -2,6 +2,9 @@ import { fillerText } from "./tokens.js";
 function append(state, entry) {
     return [...state.entries, entry];
 }
+function droppedTokens(entries) {
+    return entries.reduce((sum, entry) => sum + entry.tokens, 0);
+}
 /** Create a deterministic compaction summary that is byte-stable after creation. */
 export function createSummaryEntry(cutTurn, summaryTokens) {
     const header = `summary(cut=${cutTurn}):`;
@@ -30,7 +33,13 @@ export function truncateSliding(windowTurns) {
         step: (state, _turn, entry) => {
             const appended = append(state, entry);
             const entries = appended.slice(-windowTurns);
-            return { entries, cut: appended.length > entries.length };
+            const dropped = appended.slice(0, Math.max(0, appended.length - entries.length));
+            const cut = dropped.length > 0;
+            return {
+                entries,
+                cut,
+                lost: cut ? { droppedTokens: droppedTokens(dropped), summaryTokens: 0 } : undefined,
+            };
         },
     };
 }
@@ -44,7 +53,13 @@ export function truncateBatched(cutEveryTurns, keepLastTurns) {
             // turn is 0-based; cut once a full batch has accumulated.
             if ((turn + 1) % cutEveryTurns === 0) {
                 const entries = appended.slice(-keepLastTurns);
-                return { entries, cut: appended.length > entries.length };
+                const dropped = appended.slice(0, Math.max(0, appended.length - entries.length));
+                const cut = dropped.length > 0;
+                return {
+                    entries,
+                    cut,
+                    lost: cut ? { droppedTokens: droppedTokens(dropped), summaryTokens: 0 } : undefined,
+                };
             }
             return { entries: appended, cut: false };
         },
@@ -65,7 +80,12 @@ export function summarizeBatched(cutEveryTurns, keepRecentTurns, summaryTokens)
                 return { entries: appended, cut: false };
             }
             const summary = createSummaryEntry(turn + 1, summaryTokens);
-            return { entries: [summary, ...recent], cut: true };
+            const dropped = appended.slice(0, appended.length - recent.length);
+            return {
+                entries: [summary, ...recent],
+                cut: true,
+                lost: { droppedTokens: droppedTokens(dropped), summaryTokens: summary.tokens },
+            };
         },
     };
 }
@@ -100,7 +120,12 @@ export function summarizeOnTokenRatio(contextWindow, ratio, keepRecentTokens, su
                 return { entries: appended, cut: false };
             }
             const summary = createSummaryEntry(turn + 1, summaryTokens);
-            return { entries: [summary, ...recent], cut: true };
+            const dropped = appended.slice(0, keepFrom);
+            return {
+                entries: [summary, ...recent],
+                cut: true,
+                lost: { droppedTokens: droppedTokens(dropped), summaryTokens: summary.tokens },
+            };
         },
     };
 }

package/dist/sdk/ai/cache-benchmark/types.d.ts

@@ -32,12 +32,21 @@ export interface StrategyState {
     /** Ordered prompt entries currently in the active prefix (oldest first). */
     entries: PromptEntry[];
 }
+/** Accounting for the context a cut destroyed (feeds quality/duration metrics). */
+export interface LostContext {
+    /** Raw prompt tokens removed from the live prefix by this cut. */
+    droppedTokens: number;
+    /** Tokens of the replacement summary (0 for hard truncation). */
+    summaryTokens: number;
+}
 /** Result of one strategy step. */
 export interface StrategyStep {
     /** Ordered entries to send this turn (oldest first). */
     entries: PromptEntry[];
     /** True when this turn dropped or summarized part of the history (a cache breakpoint). */
     cut: boolean;
+    /** Present when this turn dropped part of the history. */
+    lost?: LostContext;
 }
 export interface CacheStrategy {
     name: string;
@@ -84,6 +93,21 @@ export interface BenchmarkResult {
     avgPromptTokens: number;
     maxPromptTokens: number;
     finalPromptTokens: number;
+    /** Raw context tokens dropped by cuts (oldest-first history removed). */
+    totalDroppedTokens: number;
+    /** Replacement summary tokens injected by cuts. */
+    totalSummaryTokens: number;
+    /**
+     * Fraction of dropped context NOT carried forward by a summary, in [0, 1].
+     * 0 == nothing lost, 1 == hard truncation destroyed everything.
+     */
+    contextLossRate: number;
+    /** Extra uncached input tokens from forced re-reads of hard-lost context. */
+    totalReReadTokens: number;
+    /** First-order duration proxy: how many extra turns those re-reads add. */
+    reReadTurns: number;
+    /** Dollar cost of the re-read recovery tokens. */
+    reReadCost: number;
     totalCost: number;
     costPerTurn: number;
     /** Percent cost delta vs the keep-all baseline (0 == same cost). */
@@ -102,5 +126,12 @@ export interface BenchmarkConfig {
     /** OpenAI only caches prefixes of at least this many tokens. */
     minCacheTokens?: number;
     sessionId?: string;
+    /**
+     * When a cut hard-loses context (dropped without a summary), the agent must
+     * re-read it. This is the fraction of hard-lost tokens re-injected as new
+     * uncached input. 0 disables recovery modeling (default); 1 means the agent
+     * fully re-reads everything it destroyed.
+     */
+    reReadFraction?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/sdk/ai/cache-benchmark/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.182",
+  "version": "0.9.183",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,