dsh-live-compact 1.1.4 → 1.1.6

package/index.js

@@ -16,31 +16,30 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { setImmediate as scheduleImmediate } from "node:timers";
+import { Worker } from "node:worker_threads";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { loadBase, loadCompaction, loadLlm } from "./adapter.js";
 import { DEFAULTS, engineConfig, readSettings } from "./settings.js";
-import { attachBackupHint, backgroundJobId, backupClaimOk, buildCard, collectJobs, cutLongReadRound, finishedToolRounds, indexToolCalls, jobCutDecision, keptToolRounds, messageText, planMessages, pointerOnlyText, pointerSpanAllowed, RAIL_TOKENS, readResultLabel, reservedCutEnd, resolveEngine, resolveProviderBaseURL, roundHasLongRead, selectCutIndexes, shadowSections, takeLocalCut, withoutFullBackupClaim } from "./plan.js";
-import { captureOwnedToolResult, contentHash, rawExcerptText, readRawToolResult, restoreToolText, runPruneAfterCapture, verifiedRaw } from "./raw.js";
+import { attachBackupHint, backgroundJobId, backupClaimOk, buildCard, collectJobs, cutLongReadRound, finishedToolRounds, indexToolCalls, isToolFailure, jobCutDecision, keptToolRounds, messageText, planMessages, pointerOnlyText, pointerSpanAllowed, RAIL_TOKENS, readResultLabel, reservedCutEnd, resolveEngine, resolveProviderBaseURL, roundHasLongRead, selectCutIndexes, shadowSections, takeLocalCut, withoutFullBackupClaim } from "./plan.js";
+import { captureOwnedToolResult, contentHash, rawExcerptText, rawName, readRawToolResult, restoreToolText, runPruneAfterCapture, verifiedRaw } from "./raw.js";
 import {
-  discardShadowFiles,
   ensureShadowDir,
   flushDrainStats,
   noteShadowWarning,
-  rotateShadow,
+  saveShadowTransaction,
   shadowDirectory,
-  sessionDir,
-  shadowAccessFused,
   shadowFileBody,
   shadowMaxBytes,
+  sessionDir,
+  shadowAccessFused,
+  shadowAccessFuseBuffer,
   tightenCreatedShadow,
   tightenShadow,
-  writeShadowFile,
-  writeShadowOwner,
-  withShadowRoot,
 } from "./shadow.js";
 import { buildSendLess, decideThunder } from "./thunder.js";
 import { inCooldown, skipLiveOfficialCompaction } from "./cooldown.js";
+import { activeCompactionPeers, warnCompactionStandDown } from "./gate.js";
 
 const { BasicCompactionEngine } = await loadBase();
 const { CompactionId, toolPairingBalancedAfter, toolPairingBalancedBefore } = await loadCompaction();
@@ -57,6 +56,134 @@ const CAPTURE_EVENT_BATCH = 128;
 const CAPTURE_RESULT_BATCH = 1;
 const RECOVER_RAW_BATCH = 1;
 const CAPTURE_RETRY_LIMIT = 8;
+const RECOVERY_ACL_REAUTH_LIMIT = 32;
+const SHADOW_WORKER_TIMEOUT_MS = 30000;
+
+const shadowWorkers = new Map();
+
+function shadowWorkerFor(root) {
+  const key = String(root);
+  let entry = shadowWorkers.get(key);
+  if (entry) return entry;
+  const worker = new Worker(new URL("./shadow-save-worker.mjs", import.meta.url), {
+    workerData: { spineWorker: 1, accessFuse: shadowAccessFuseBuffer() },
+  });
+  entry = { worker, nextId: 1, pending: new Map(), idleTimer: null, retired: false };
+  const removeEntry = () => {
+    if (shadowWorkers.get(key) === entry) shadowWorkers.delete(key);
+  };
+  const scheduleIdleExit = () => {
+    if (entry.retired || entry.pending.size || entry.idleTimer) return;
+    entry.idleTimer = setTimeout(() => {
+      entry.idleTimer = null;
+      if (entry.pending.size) return;
+      entry.retired = true;
+      removeEntry();
+      worker.terminate().catch(() => {});
+    }, 500);
+    entry.idleTimer.unref?.();
+  };
+  entry.scheduleIdleExit = scheduleIdleExit;
+  const fail = (error) => {
+    entry.retired = true;
+    if (entry.idleTimer) {
+      clearTimeout(entry.idleTimer);
+      entry.idleTimer = null;
+    }
+    for (const { reject, timer } of entry.pending.values()) {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    }
+    entry.pending.clear();
+    removeEntry();
+    worker.terminate().catch(() => {});
+  };
+  worker.on("message", (message) => {
+    const task = entry.pending.get(message?.id);
+    if (!task) return;
+    if (task.timer) clearTimeout(task.timer);
+    entry.pending.delete(message.id);
+    if (message?.ok) {
+      task.resolve(message.result);
+      scheduleIdleExit();
+      return;
+    }
+    const error = new Error(message?.error?.message || "spine: shadow worker failed");
+    if (message?.error?.code) error.code = message.error.code;
+    task.reject(error);
+    scheduleIdleExit();
+  });
+  worker.on("error", (error) => fail(error));
+  worker.on("exit", (code) => {
+    if (entry.pending.size || (!entry.retired && code !== 0)) {
+      fail(Object.assign(new Error(`spine: shadow worker exited ${code}`), { code: "ESHADOWWORKER" }));
+    } else {
+      entry.retired = true;
+      if (entry.idleTimer) clearTimeout(entry.idleTimer);
+      entry.idleTimer = null;
+      removeEntry();
+    }
+  });
+  shadowWorkers.set(key, entry);
+  return entry;
+}
+
+function runShadowWorker(payload) {
+  const entry = shadowWorkerFor(payload.shadow);
+  if (entry.idleTimer) {
+    clearTimeout(entry.idleTimer);
+    entry.idleTimer = null;
+  }
+  const id = entry.nextId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const error = Object.assign(new Error("spine: shadow worker timed out"), { code: "ESHADOWWORKER" });
+      failShadowWorker(entry, error);
+    }, SHADOW_WORKER_TIMEOUT_MS);
+    timer.unref?.();
+    entry.pending.set(id, { resolve, reject, timer });
+    try {
+      entry.worker.postMessage({ id, payload });
+    } catch (error) {
+      clearTimeout(timer);
+      entry.pending.delete(id);
+      reject(error);
+      entry.scheduleIdleExit();
+    }
+  });
+}
+
+function failShadowWorker(entry, error) {
+  if (!entry || entry.retired) return;
+  entry.retired = true;
+  if (entry.idleTimer) {
+    clearTimeout(entry.idleTimer);
+    entry.idleTimer = null;
+  }
+  for (const { reject, timer } of entry.pending.values()) {
+    if (timer) clearTimeout(timer);
+    reject(error);
+  }
+  entry.pending.clear();
+  for (const [key, value] of shadowWorkers) {
+    if (value === entry) shadowWorkers.delete(key);
+  }
+  entry.worker.terminate().catch(() => {});
+}
+
+function recoveryRetryable(record, dir, toolCallId) {
+  if (record?.retryable === true || record?.reason === "unwritable") return true;
+  // A completely absent backup has never been captured and can be retried.
+  // If its metadata is still present, the body was damaged after capture and
+  // must remain fail-closed rather than being silently overwritten.
+  if (record?.reason === "missing-file") return !existsSync(join(dir, `${rawName(toolCallId)}.meta.json`));
+  return false;
+}
+
+function captureErrorRetryable(error) {
+  const code = error?.code;
+  return code === "ESHADOWBUSY" || ["EAGAIN", "EBUSY", "EINTR", "EIO"].includes(code);
+}
 
 function eventContent(session, seq) {
   const event = session.eventAt(seq);
@@ -78,7 +205,27 @@ function isCheckpoint(session, seq) {
   // 自己的卡片，以及已经写过的官方标记，都要停住。新卡片不再用官方标记。
   // Stop on our own cards and on older official markers. New cards do not use the official marker.
   if (kind === SPINE_SOURCE_KIND || kind === "compact-checkpoint") return true;
-  return eventText(session, seq).includes(MARK);
+  // The legacy text marker is only meaningful on a user/message card and only
+  // at the beginning of its text. A tool result or an ordinary sentence that
+  // merely mentions the marker must not create a permanent cut boundary.
+  if (event?.type !== "user/message") return false;
+  const text = eventText(session, seq).trimStart();
+  return text === MARK || text.startsWith(`${MARK}\n`) || text.startsWith(`${MARK}\r\n`);
+}
+
+function latestTurnCompleted(events) {
+  let lastStart = -1;
+  let lastEnd = -1;
+  let reason;
+  for (let index = 0; index < (events || []).length; index += 1) {
+    const event = events[index];
+    if (event?.type === "turn/start") lastStart = index;
+    if (event?.type === "turn/end") {
+      lastEnd = index;
+      reason = event.data?.reason?.kind;
+    }
+  }
+  return lastEnd > lastStart && reason === "completed";
 }
 
 function spineCheckpointSource(compactionId) {
@@ -184,80 +331,41 @@ export function saveShadowImpl(
   rotationIO = {},
 ) {
   const shadow = shadowDirectory();
-  ensureShadowDir(shadow, access);
-
   const file = shadowFilePath(shadowFile, warnKey);
-  const dir = sessionDir(shadow, warnKey);
-  ensureShadowDir(dir, access);
-
-  return withShadowRoot(shadow, () => {
-    const owner = join(dir, "owner");
-    const ownerExisted = existsSync(owner);
-    let ownerWritten = false;
-
-    try {
-      writeShadowOwner(dir, access, shadow);
-      ownerWritten = true;
-
-      const body = shadowFileBody(warnKey, shadowBody(messages));
-      const incoming = Buffer.byteLength(body);
-      const cap = shadowMaxBytes();
-
-      const rotation = rotateShadow({
-        ...rotationIO,
-        dir: shadow,
-        incomingBytes: incoming,
-        protectPath: file,
-        protectPaths,
-        sessionKey: warnKey,
-        cap,
-      });
-
-      if (!rotation.ok) {
-        if (rotation.reason) {
-          const incomplete = rotation.reason === "scan-incomplete";
-          const error = Object.assign(new Error(incomplete
-            ? "spine: shadow capacity scan is incomplete; backup refused; leaving the span"
-            : "spine: shadow capacity measurement is invalid; backup refused; leaving the span"), {
-            code: incomplete ? "ESHADOWSCAN" : "ESHADOWMETER",
-          });
-          if (required) throw error;
-          this.ctx.logger?.warn?.(error.message);
-          return;
-        }
-        this.warnShadowFull(warnKey, shadow, rotation.used, cap);
-        if (required) {
-          throw new Error(
-            "spine: shadow backup is full; leaving the span",
-          );
-        }
-        return;
-      }
-
-      if (rotation.deleted > 0) {
-        this.ctx.logger?.info?.(
-          `spine: shadow 轮换 删除 ${rotation.deleted} 个文件，` +
-          `腾出 ${rotation.freed} 字节，` +
-          `用量 ${rotation.used + incoming}/${cap}`,
-        );
-      }
-
-      if (rotation.oversize) {
-        this.warnShadowOversize(warnKey, cap);
-      }
-
-      writeShadowFile(file, body, access, { root: shadow });
-
-      if (!existsSync(file)) {
-        throw new Error("spine: shadow backup was not written");
-      }
-    } catch (error) {
-      if (ownerWritten && !ownerExisted) {
-        discardShadowFiles([owner], error);
-      }
-      throw error;
-    }
+  const body = shadowFileBody(warnKey, shadowBody(messages));
+  const cap = shadowMaxBytes();
+  const result = saveShadowTransaction({
+    shadow,
+    file,
+    body,
+    required,
+    protectPaths,
+    sessionKey: warnKey,
+    cap,
+    access,
+    rotationIO,
   });
+  if (!result?.ok) {
+    if (result?.reason === "scan-incomplete" || result?.reason === "invalid-measurement") {
+      const error = result.reason === "scan-incomplete"
+        ? "spine: shadow capacity scan is incomplete; backup refused; leaving the span"
+        : "spine: shadow capacity measurement is invalid; backup refused; leaving the span";
+      this.ctx.logger?.warn?.(error);
+    } else if (result?.rotation) {
+      this.warnShadowFull(warnKey, shadow, result.rotation.used, cap);
+    }
+    return result;
+  }
+  const rotation = result.rotation;
+  if (rotation.deleted > 0) {
+    this.ctx.logger?.info?.(
+      `spine: shadow 轮换 删除 ${rotation.deleted} 个文件，` +
+      `腾出 ${rotation.freed} 字节，` +
+      `用量 ${rotation.used + Buffer.byteLength(body)}/${cap}`,
+    );
+  }
+  if (rotation.oversize) this.warnShadowOversize(warnKey, cap);
+  return result;
 }
 
 export { saveShadowImpl as saveShadow };
@@ -304,16 +412,16 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
       type: event?.type === "tool/result" ? "tool" : "other",
       toolCalls,
       longRead: event?.type === "tool/result" && call?.name === "read" && (priced[index].tokens || 0) >= settings.chunkMin,
+      checkpoint: isCheckpoint(session, nodes[index]),
     });
   }
-  const rounds = keptToolRounds(visible, settings.keepRounds);
+  const floorVisible = visible.reduce((found, item, index) => item.checkpoint ? index : found, -1);
+  const rounds = keptToolRounds(visible, settings.keepRounds, floorVisible);
   const newestLong = [...finishedToolRounds(visible)].reverse().find((round) => roundHasLongRead(visible, round));
   const span = rounds.length ? { start: rounds[0].start, end: rounds.at(-1).end } : null;
   const cutEnd = span ? reservedCutEnd(visible[span.start].index, first) : null;
   if (span && cutEnd === null) return null;
   if (cutEnd !== null) {
-    const keptEnd = visible[span.end].index;
-    for (let index = visible[span.start].index; index <= keptEnd; index += 1) keptTokens += priced[index].tokens;
     end = cutEnd;
     while (end >= first && classifications[end].isGenuineUserBoundary && !(floorCard >= 0 && end - 1 <= floorCard)) end -= 1;
     if (floorCard >= 0 && end <= floorCard) return null;
@@ -365,7 +473,6 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
     }
     return pieces;
   };
-  const spanText = (spanStart, spanEnd) => spanPieces(spanStart, spanEnd).map((piece) => piece.text).join("\n");
   const liveText = (spanStart, spanEnd) => {
     const bits = [];
     for (let index = 0; index < nodes.length; index += 1) {
@@ -402,6 +509,9 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
   };
   let usedLongCut = false;
   let picked = null;
+  const fallbackWithoutLongRead = () => context.disableLongRead
+    ? null
+    : selectNewestChunk(session, measurement, key, { ...context, disableLongRead: true });
   if (longSpan) {
     const longPicked = cutLongReadRound(items, longSpan.start, longSpan.end, cutOptions);
     if (longPicked && longPicked.start >= longSpan.start && longPicked.end <= longSpan.end) {
@@ -427,25 +537,39 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
         }
       }
     }
-    if (pairStart < 0) return null;
-    if (usedLongCut && pairStart < longSpan.start) return null;
-    if (!pointerSpanAllowed(items, pairStart, picked.end, context.engine || "cloud")) return null;
-    if (!cutOk(toolPairingBalancedBefore, session, nodes[pairStart])) return null;
+    if (pairStart < 0) return usedLongCut ? fallbackWithoutLongRead() : null;
+    if (usedLongCut && pairStart < longSpan.start) return fallbackWithoutLongRead();
+    if (!pointerSpanAllowed(items, pairStart, picked.end, context.engine || "cloud")) return usedLongCut ? fallbackWithoutLongRead() : null;
+    if (!cutOk(toolPairingBalancedBefore, session, nodes[pairStart])) return usedLongCut ? fallbackWithoutLongRead() : null;
     picked.start = pairStart;
   }
-  if (usedLongCut && (picked.start < longSpan.start || picked.end > longSpan.end)) return null;
+  if (usedLongCut && (picked.start < longSpan.start || picked.end > longSpan.end)) return fallbackWithoutLongRead();
   const start = picked.start;
   end = picked.end;
   const tokens = items.slice(start, end + 1).reduce((sum, item) => sum + item.tokens, 0);
+  const pieces = spanPieces(start, end);
+  if (picked.pointerOnly && pieces.some((piece) => piece.role === "tool" && isToolFailure(piece.text, piece.isError))) {
+    return usedLongCut ? fallbackWithoutLongRead() : null;
+  }
   let card = picked.pointerOnly
-    ? { ok: true, text: pointerOnlyText(spanPieces(start, end)), hardLines: [], missing: [], needsBackup: false, rawPaths: [] }
-    : buildCard(spanText(start, end), liveText(start, end), spanPieces(start, end), extras);
-  if (card.ok !== true) return null;
+    ? { ok: true, text: pointerOnlyText(pieces), hardLines: [], missing: [], needsBackup: false, rawPaths: [] }
+    : buildCard(pieces.map((piece) => piece.text).join("\n"), liveText(start, end), pieces, extras);
+  if (card.ok !== true) return usedLongCut ? fallbackWithoutLongRead() : null;
   card = attachBackupHint(card, freshShadowFile("cut", key));
   if (!card.text.includes("不是备份文件路径")) card = { ...card, text: `${card.text}\n序号是本会话日志里的事件号，不是备份文件路径。` };
   if (!cutOk(toolPairingBalancedAfter, session, nodes[end])) return null;
   let after = 0;
   for (let index = end + 1; index < priced.length; index += 1) after += priced[index].tokens;
+  // `keptTokens` must describe retained rounds to the right of the actual
+  // cut. A long-read cut can be newer than the ordinary rounds selected above;
+  // counting those older rounds made `tailBeyondKept` negative and disabled
+  // the tail guard.
+  for (const round of rounds) {
+    const roundStart = visible[round.start]?.index;
+    const roundEnd = visible[round.end]?.index;
+    if (!Number.isInteger(roundStart) || !Number.isInteger(roundEnd) || roundStart <= end) continue;
+    for (let index = roundStart; index <= roundEnd; index += 1) keptTokens += priced[index].tokens;
+  }
   let prefix = 0;
   for (let index = 0; index < start; index += 1) prefix += priced[index].tokens;
   return { start: nodes[start], end: nodes[end], tokens, after, keptTokens, card, prefix };
@@ -473,6 +597,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   captureRetryStats = new Map();
   retryableCaptureSeqs = new Map();
   retryableCaptureSeeded = new Set();
+  captureRecoveryHolds = new Map();
   pruneGuarded = false;
 
   constructor(ctx, config, resolvedConfig) {
@@ -487,6 +612,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       });
       ctx.on("session/event", (session, event) => {
         try {
+          if (this.standDown?.()) return;
           this.noteEvent(session, event);
           if (event?.type !== "tool/result") return;
           const id = event.data?.message?.toolCallId;
@@ -500,6 +626,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
           job = new Promise((resolve) => {
             scheduleImmediate(() => {
               try {
+                if (this.standDown?.()) return;
                 const current = this.rawSeen.get(key);
                 if (!current || current.retryable) {
                   const record = this.captureOne(session, event);
@@ -523,10 +650,11 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       });
       ctx.on("agent/status", ({ agent, status }) => {
         if (status !== "idle") return;
+        if (this.standDown?.()) return;
         const state = this.stateFor(agent);
         if (state.warming) return;
         const events = agent.session.snapshotEvents();
-        const done = events.some((event) => event.type === "turn/end" && event.data?.reason?.kind === "completed");
+        const done = latestTurnCompleted(events);
         if (!done) return;
         state.warming = true;
         const job = this.finishTurn(agent, events, { deferCapture: true })
@@ -543,6 +671,24 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     }
   }
 
+  standDown() {
+    const peers = activeCompactionPeers(this.ctx);
+    if (peers.length) warnCompactionStandDown(this.ctx);
+    return peers.length > 0;
+  }
+
+  ownedSignal(signal) {
+    const controller = new AbortController();
+    const dispose = this.ctx.on("internal/status", () => {
+      if (this.standDown?.()) controller.abort();
+    }, { global: true });
+    if (this.standDown?.()) controller.abort();
+    return {
+      signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
+      dispose,
+    };
+  }
+
   stateFor(agent) {
     const key = sessionKey(agent);
     let state = this.sessionState.get(key);
@@ -585,7 +731,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     return planMessages(messages);
   }
 
-  scheduleCaptureCatchup(agent, events, settings) {
+  scheduleCaptureCatchup(agent, events, settings, options = {}) {
     this.pendingCatchups ||= new Map();
     this.pendingCatchupJobs ||= new Set();
     this.pendingCuts ||= new Set();
@@ -596,6 +742,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       task.session = agent.session;
       task.events = events;
       task.settings = settings;
+      task.freezeSnapshot ||= options.freezeSnapshot === true;
       return task;
     }
     let resolve;
@@ -606,16 +753,17 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       session: agent.session,
       events,
       settings,
-      phase: "events",
+      phase: "previsible",
       eventIndex: 0,
       recoverIndex: 0,
-      visibleIds: null,
+      visibleIds: [...new Set(this.surfaceToolIds(agent.session))],
       scheduled: false,
       retryRequested: false,
       captureRetryAttempts: 0,
       progressed: false,
       eventTail: Number.isInteger(events?.at?.(-1)?.seq) ? events.at(-1).seq : -1,
       surfaceTail: agent.session.surface?.nodes?.at?.(-1) ?? -1,
+      freezeSnapshot: options.freezeSnapshot === true,
       resolve,
       promise,
     };
@@ -641,13 +789,17 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     scheduleImmediate(() => {
       task.scheduled = false;
       try {
-        const latest = task.session.snapshotEvents?.();
+        if (this.standDown?.()) {
+          this.finishCaptureCatchup(task);
+          return;
+        }
+        const latest = task.freezeSnapshot ? null : task.session.snapshotEvents?.();
         const latestTail = Number.isInteger(latest?.at?.(-1)?.seq) ? latest.at(-1).seq : -1;
         const latestSurfaceTail = task.session.surface?.nodes?.at?.(-1) ?? -1;
         if (Array.isArray(latest) && (latestTail !== task.eventTail || latest.length !== task.events.length)) {
           task.events = latest;
           task.eventTail = latestTail;
-          if (task.phase === "visible") {
+          if (task.phase === "previsible" || task.phase === "visible") {
             task.phase = "events";
             task.visibleIds = null;
             task.recoverIndex = 0;
@@ -655,11 +807,22 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
         }
         if (latestSurfaceTail !== task.surfaceTail) {
           task.surfaceTail = latestSurfaceTail;
-          if (task.phase === "visible") {
+          if (task.phase === "previsible" || task.phase === "visible") {
             task.visibleIds = [...new Set(this.surfaceToolIds(task.session))];
             task.recoverIndex = 0;
           }
         }
+        if (task.phase === "previsible") {
+          const recovered = this.recoverVisibleRawBatch(task.session, {}, task.recoverIndex, RECOVER_RAW_BATCH, task.visibleIds);
+          task.progressed ||= recovered.progressed;
+          task.recoverIndex = recovered.nextIndex;
+          if (!recovered.done) {
+            this.queueCaptureCatchup(task);
+            return;
+          }
+          task.phase = "events";
+          task.eventIndex = 0;
+        }
         if (task.phase === "events") {
           const result = this.captureNewBatch(task.session, task.events, task.settings, {
             eventLimit: CAPTURE_EVENT_BATCH,
@@ -709,18 +872,20 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     this.pendingCatchups.delete(task.key);
     this.pendingCatchupJobs.delete(task.promise);
     task.resolve();
-    if (task.retryRequested && task.progressed) this.scheduleMaintenanceRetry(task.agent);
+    if (!this.standDown?.() && task.retryRequested && task.progressed) this.scheduleMaintenanceRetry(task.agent);
   }
 
   scheduleMaintenanceRetry(agent) {
+    if (this.standDown?.()) return;
     const state = this.stateFor(agent);
     if (state.retryScheduled) return;
     state.retryScheduled = true;
     scheduleImmediate(() => {
       state.retryScheduled = false;
+      if (this.standDown?.()) return;
       if (state.warming) return;
       const events = agent.session.snapshotEvents();
-      const done = events.some((event) => event.type === "turn/end" && event.data?.reason?.kind === "completed");
+      const done = latestTurnCompleted(events);
       if (!done) return;
       state.warming = true;
       const job = this.finishTurn(agent, events, { deferCapture: true })
@@ -734,32 +899,49 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   async finishTurn(agent, events, options = {}) {
+    if (this.standDown?.()) return null;
     const settings = readSettings(this.liveConfig);
     const state = this.stateFor(agent);
     const signal = AbortSignal.timeout(30000);
     const ev = events || agent.session.snapshotEvents();
     const deferCapture = options.deferCapture === true;
-    const catchup = deferCapture
-      ? this.scheduleCaptureCatchup(agent, ev, settings)
-      : { finished: true, progressed: false, retryRequested: false };
-    if (!deferCapture) {
-      await this.flushPendingCaptures();
-      this.captureNew(agent.session, ev, settings);
+    let catchup = { finished: true, progressed: false, retryRequested: false };
+    if (deferCapture) {
+      catchup = this.scheduleCaptureCatchup(agent, ev, settings);
+    } else {
+      if (ev.length > CAPTURE_EVENT_BATCH) {
+        catchup = this.scheduleCaptureCatchup(agent, ev, settings, { freezeSnapshot: true });
+      } else {
+        await this.flushPendingCaptures();
+        this.captureNew(agent.session, ev, settings);
+      }
     }
     const jobs = collectJobs(ev);
     const calls = indexToolCalls(ev);
     try {
       await agent.runMaintenance(async (agentSignal) => {
+        if (this.standDown?.()) return;
         const op = AbortSignal.any([agentSignal, signal]);
         let measurement = this.ctx.tokenMeter.measure(agent.session);
-        if (measurement.totalTokens < settings.minTokens || measurement.totalTokens >= settings.bigGate) return;
+        const settleTurnBaseline = () => {
+          state.turnBase = measurement.totalTokens;
+          state.maxTurnGrowth = 0;
+        };
+        if (measurement.totalTokens < settings.minTokens || measurement.totalTokens >= settings.bigGate) {
+          settleTurnBaseline();
+          return;
+        }
         // Restored cards establish a baseline; a live card still skips once,
         // even when maintenance or engine construction is delayed.
         if (skipLiveOfficialCompaction(agent.session)) {
           this.ctx.logger?.info?.("spine cooldown: live official compaction seen, skip this pass");
+          settleTurnBaseline();
+          return;
+        }
+        if (inCooldown(agent.session, { windowMs: settings.cooldownMs })) {
+          settleTurnBaseline();
           return;
         }
-        if (inCooldown(agent.session, { windowMs: settings.cooldownMs })) return;
         this.ensurePruneGuard();
         const resolved = this.engineFor(agent);
         if (state.engine !== resolved.engine || state.engineSource !== resolved.source) {
@@ -805,8 +987,9 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
           try {
             state.localOnly = true;
             state.approvedCard = chunk.card;
-            if (deferCapture) await this.flushPendingCaptures(agent.session, this.chunkToolCallIds(agent.session, chunk));
-            await this.commitSelectedSpan(agent, chunk, op);
+            await this.flushPendingCaptures(agent.session, this.chunkToolCallIds(agent.session, chunk));
+            const committed = await this.commitSelectedSpan(agent, chunk, op);
+            if (committed === false) break;
             measurement = this.ctx.tokenMeter.measure(agent.session);
             const after = measurement.totalTokens;
             reduced = after < before;
@@ -841,6 +1024,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
         }
         if (drainNotes.length) flushDrainStats(shadowDirectory(), drainNotes, { sid: state.key, drain });
         state.turnBase = measurement.totalTokens;
+        state.maxTurnGrowth = 0;
         await this.ctx.sessions?.flush?.(agent.session);
         this.rememberPrefix(agent);
       });
@@ -882,6 +1066,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   async commitSelectedSpan(agent, chunk, signal) {
+    if (this.standDown?.()) return false;
     signal?.throwIfAborted();
     const session = agent.session;
     if (chunk.card?.ok !== true || !chunk.card.text) throw new Error("spine: approved card missing; leaving the span");
@@ -914,7 +1099,28 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       const event = session.eventAt(seq);
       if (event?.type === "tool/result") {
         const id = event.data?.message?.toolCallId;
-        const raw = id ? this.rawSeen.get(this.rawKey(session, id)) : null;
+        let raw = id ? this.rawSeen.get(this.rawKey(session, id)) : null;
+        if (id && raw?.ok && raw.recovered && raw.aclVerified !== true) {
+          try {
+            const verified = readRawToolResult({
+              dir: sessionDir(shadowDirectory(), session.id || DEFAULT_KEY),
+              toolCallId: id,
+              tighten: true,
+            });
+            // ACL success cannot establish a new content identity. Keep the
+            // first verified hash even if an external writer replaces both files.
+            const sameBackup = verified?.ok && verified.path === raw.path &&
+              verified.sha256 === raw.sha256 && verified.bytes === raw.bytes;
+            raw = sameBackup
+              ? { ...verified, recovered: false, aclVerified: true }
+              : { ...raw, ok: false, reason: verified?.reason || "hash-mismatch", aclVerified: false };
+            this.rawSeen.set(this.rawKey(session, id), raw);
+          } catch (error) {
+            noteShadowWarning(this.ctx?.logger, error);
+            raw = { ...raw, ok: false, reason: "unwritable", toolCallId: id, aclVerified: false };
+            this.rawSeen.set(this.rawKey(session, id), raw);
+          }
+        }
         if (!id || !verifiedRaw(raw).ok) {
           throw new Error(`spine: raw backup missing before cut: ${id || "unknown"}`);
         }
@@ -927,6 +1133,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     }
     const summarized = await this.summarize({ messages, liveCompact: { card: chunk.card } }, agent, signal);
     signal?.throwIfAborted();
+    if (this.standDown?.()) return false;
     assertCurrentSpan(shadowedSeqs);
     const compactionId = CompactionId(randomUUID());
     const checkpointMessage = createUserMessage({
@@ -986,11 +1193,27 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   async compactIfNeeded(agent, trigger, signal) {
+    if (this.standDown?.()) return null;
     const state = this.stateFor(agent);
     state.liveAgent = agent;
     state.localOnly = false;
     this.ensurePruneGuard();
-    return super.compactIfNeeded(agent, trigger, signal);
+    const owned = this.ownedSignal(signal);
+    try {
+      return await super.compactIfNeeded(agent, trigger, owned.signal);
+    } finally {
+      owned.dispose?.();
+    }
+  }
+
+  async compactNow(agent, signal, sourceCommandId) {
+    if (this.standDown?.()) return null;
+    const owned = this.ownedSignal(signal);
+    try {
+      return await super.compactNow(agent, owned.signal, sourceCommandId);
+    } finally {
+      owned.dispose?.();
+    }
   }
 
   // Preserve explicit URL precedence. Only the exact account provider gets
@@ -999,9 +1222,11 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     const header = agent?.session?.requestHeader?.()?.config || {};
     const context = agent?.session?.requestContext?.() || {};
     const provider = header.provider || context.provider || "";
+    const model = header.model || context.model || "";
     const listed = this.listedProviders();
     const baseURL = resolveProviderBaseURL({
       provider,
+      model,
       headerURL: header.baseURL || context.baseURL || "",
       listed,
       layers: this.providerLayers(),
@@ -1073,10 +1298,21 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       try {
         const loaded = createRequire(anchor)("@earendil-works/pi-ai/providers/all");
         const list = typeof loaded.builtinProviders === "function" ? loaded.builtinProviders() : [];
-        return list.map((entry) => ({
-          id: entry?.id || "",
-          baseURL: entry?.baseUrl || entry?.baseURL || "",
-        })).filter((entry) => entry.id && entry.baseURL);
+        return list.map((entry) => {
+          let models = [];
+          try {
+            const declared = typeof entry?.getModels === "function" ? entry.getModels() : entry?.models || [];
+            models = (Array.isArray(declared) ? declared : []).map((model) => ({
+              id: model?.id || "",
+              baseURL: model?.baseUrl || model?.baseURL || "",
+            })).filter((model) => model.id && model.baseURL);
+          } catch {}
+          return {
+            id: entry?.id || "",
+            baseURL: entry?.baseUrl || entry?.baseURL || "",
+            models,
+          };
+        }).filter((entry) => entry.id && (entry.baseURL || entry.models.length));
       } catch {}
     }
     return [];
@@ -1106,6 +1342,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   captureOne(session, event, access = {}) {
+    if (this.standDown?.()) return null;
     const id = event?.data?.message?.toolCallId;
     if (!id) return null;
     const key = session?.id || DEFAULT_KEY;
@@ -1137,8 +1374,9 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
         ),
         access,
       });
-      this.rawSeen.set(mapKey, record);
-      return record;
+      const cached = record?.ok ? { ...record, aclVerified: true } : record;
+      this.rawSeen.set(mapKey, cached);
+      return cached;
     } catch (error) {
       if (
         error?.code === "ESHADOWACCESS" ||
@@ -1151,7 +1389,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       }
       const message = error instanceof Error ? error.message : String(error);
       this.ctx?.logger?.warn?.(`spine: raw backup failed: ${message}`);
-      const record = { ok: false, reason: "unwritable", toolCallId: id, retryable: error?.code === "ESHADOWBUSY" };
+      const record = { ok: false, reason: "unwritable", toolCallId: id, retryable: captureErrorRetryable(error) };
       this.rawSeen.set(mapKey, record);
       return record;
     }
@@ -1211,11 +1449,21 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   captureNewBatch(session, events, settings = readSettings(this.liveConfig), limits = {}) {
+    if (this.standDown?.()) {
+      return {
+        seen: new Set(),
+        progressed: false,
+        retryable: false,
+        done: true,
+        nextIndex: Number.isInteger(limits.startIndex) ? limits.startIndex : 0,
+      };
+    }
     if (!Array.isArray(events)) events = [];
     const key = session?.id || DEFAULT_KEY;
     const cursor = this.captureCursorStart(session, events, settings);
     let next = cursor;
     let retry = null;
+    let retryIndex = null;
     let processed = 0;
     let captures = 0;
     let progressed = false;
@@ -1245,7 +1493,10 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
             captures += 1;
           }
           this.noteCaptureResult(session, event, record);
-          if (record?.retryable && retry === null) retry = seq;
+          if (record?.retryable && retry === null) {
+            retry = seq;
+            retryIndex = index;
+          }
         }
       }
       next = seq + 1;
@@ -1266,11 +1517,12 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       progressed,
       retryable: retry !== null,
       done: exhausted && retry === null && next > lastSeq,
-      nextIndex: index,
+      nextIndex: retryIndex ?? index,
     };
   }
 
   captureNew(session, events, settings = readSettings(this.liveConfig)) {
+    if (this.standDown?.()) return new Set();
     if (!Array.isArray(events)) events = [];
     const key = session?.id || DEFAULT_KEY;
     const cursor = this.captureCursorStart(session, events, settings);
@@ -1326,6 +1578,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   writeCaptureCursor(key, cursor, access = {}) {
+    if (this.standDown?.()) return;
     if (this.persistCapture !== true || !Number.isSafeInteger(cursor) || cursor < 0) return;
     let tmp;
     let fd;
@@ -1352,22 +1605,52 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   recoverVisibleRaw(session, access = {}) {
+    if (this.standDown?.()) return;
     const dir = sessionDir(shadowDirectory(), session?.id || DEFAULT_KEY);
-    for (const id of new Set(this.surfaceToolIds(session))) {
+    const ids = [...new Set(this.surfaceToolIds(session))];
+    if (ids.length && existsSync(dir)) ensureShadowDir(dir, access);
+    for (const id of ids) {
       const mapKey = this.rawKey(session, id);
       if (this.rawSeen.has(mapKey)) continue;
       try {
-        this.rawSeen.set(mapKey, readRawToolResult({ dir, toolCallId: id, access }));
+        const record = readRawToolResult({ dir, toolCallId: id, access, tighten: false });
+        const retryable = recoveryRetryable(record, dir, id);
+        const cached = record?.ok
+          ? { ...record, recovered: true, aclVerified: false }
+          : { ...record, ...(retryable ? { retryable: true } : {}), recovered: true, aclVerified: false };
+        this.rawSeen.set(mapKey, cached);
+        if (!cached.ok) {
+          const event = (session?.surface?.nodes || [])
+            .map((seq) => session.eventAt?.(seq))
+            .find((candidate) => candidate?.type === "tool/result" && candidate.data?.message?.toolCallId === id);
+          if (event) this.noteCaptureResult(session, event, cached);
+          if (retryable) this.captureRecoveryHolds.set(session?.id || DEFAULT_KEY, this.captureRecoveryFingerprint(session));
+        }
       } catch (error) {
         noteShadowWarning(this.ctx?.logger, error);
-        this.rawSeen.set(mapKey, { ok: false, reason: "unwritable", toolCallId: id });
+        const failed = { ok: false, reason: "unwritable", toolCallId: id, retryable: true, recovered: true, aclVerified: false };
+        this.rawSeen.set(mapKey, failed);
+        const event = (session?.surface?.nodes || [])
+          .map((seq) => session.eventAt?.(seq))
+          .find((candidate) => candidate?.type === "tool/result" && candidate.data?.message?.toolCallId === id);
+        if (event) this.noteCaptureResult(session, event, failed);
+        this.captureRecoveryHolds.set(session?.id || DEFAULT_KEY, this.captureRecoveryFingerprint(session));
       }
     }
   }
 
   recoverVisibleRawBatch(session, access = {}, startIndex = 0, limit = RECOVER_RAW_BATCH, visibleIds = null) {
+    if (this.standDown?.()) return { nextIndex: startIndex, done: true, progressed: false };
     const ids = visibleIds || [...new Set(this.surfaceToolIds(session))];
     const dir = sessionDir(shadowDirectory(), session?.id || DEFAULT_KEY);
+    if (ids.length && startIndex === 0 && existsSync(dir)) {
+      try {
+        ensureShadowDir(dir, access);
+      } catch (error) {
+        noteShadowWarning(this.ctx?.logger, error);
+        return { nextIndex: ids.length, done: true, progressed: false };
+      }
+    }
     let index = Math.max(0, startIndex);
     let processed = 0;
     let progressed = false;
@@ -1376,12 +1659,31 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       const mapKey = this.rawKey(session, id);
       if (this.rawSeen.has(mapKey)) continue;
       try {
-        const record = readRawToolResult({ dir, toolCallId: id, access });
-        this.rawSeen.set(mapKey, record);
+        const record = readRawToolResult({ dir, toolCallId: id, access, tighten: false });
+        const retryable = recoveryRetryable(record, dir, id);
+        const cached = record?.ok
+          ? { ...record, recovered: true, aclVerified: false }
+          : { ...record, ...(retryable ? { retryable: true } : {}), recovered: true, aclVerified: false };
+        this.rawSeen.set(mapKey, cached);
+        if (!cached.ok) {
+          const event = session?.eventAt?.(session?.surface?.nodes?.find?.((seq) => {
+            const candidate = session.eventAt?.(seq);
+            return candidate?.type === "tool/result" && candidate.data?.message?.toolCallId === id;
+          }));
+          if (event) this.noteCaptureResult(session, event, cached);
+          if (retryable) this.captureRecoveryHolds.set(session?.id || DEFAULT_KEY, this.captureRecoveryFingerprint(session));
+        }
         progressed ||= Boolean(record?.ok);
       } catch (error) {
         noteShadowWarning(this.ctx?.logger, error);
-        this.rawSeen.set(mapKey, { ok: false, reason: "unwritable", toolCallId: id });
+        const failed = { ok: false, reason: "unwritable", toolCallId: id, retryable: true, recovered: true, aclVerified: false };
+        this.rawSeen.set(mapKey, failed);
+        const event = session?.eventAt?.(session?.surface?.nodes?.find?.((seq) => {
+          const candidate = session.eventAt?.(seq);
+          return candidate?.type === "tool/result" && candidate.data?.message?.toolCallId === id;
+        }));
+        if (event) this.noteCaptureResult(session, event, failed);
+        this.captureRecoveryHolds.set(session?.id || DEFAULT_KEY, this.captureRecoveryFingerprint(session));
       }
       processed += 1;
     }
@@ -1389,7 +1691,21 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   captureSession(session) {
-    return this.captureNew(session, session?.snapshotEvents?.() || []);
+    if (this.standDown?.()) return new Set();
+    const key = session?.id || DEFAULT_KEY;
+    const events = session?.snapshotEvents?.() || [];
+    const fingerprint = this.captureRecoveryFingerprint(session, events);
+    if (this.captureRecoveryHolds.get(key) === fingerprint) {
+      this.captureRecoveryHolds.delete(key);
+      return new Set();
+    }
+    return this.captureNew(session, events);
+  }
+
+  captureRecoveryFingerprint(session, events = null) {
+    const snapshot = events || session?.snapshotEvents?.() || [];
+    const nodes = session?.surface?.nodes || [];
+    return `${snapshot.length}:${snapshot.at(-1)?.seq ?? -1}|${nodes.length}:${nodes.at(-1) ?? -1}`;
   }
 
   surfaceToolIds(session) {
@@ -1406,14 +1722,24 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   rawVerifiedSet(session) {
     const ids = new Set();
     const dir = sessionDir(shadowDirectory(), session?.id || DEFAULT_KEY);
-    for (const id of this.surfaceToolIds(session)) {
+    const visibleIds = this.surfaceToolIds(session);
+    const recoveredNeedsAcl = visibleIds.filter((id) => {
       const cached = this.rawSeen.get(this.rawKey(session, id));
-      if (!cached?.ok) continue;
+      return cached?.ok && cached.recovered === true && cached.aclVerified !== true;
+    });
+    if (recoveredNeedsAcl.length > RECOVERY_ACL_REAUTH_LIMIT) return ids;
+    for (const id of visibleIds) {
+      const cached = this.rawSeen.get(this.rawKey(session, id));
+      if (!cached?.ok || cached.aclVerified !== true && cached.recovered !== true) continue;
       try {
         // Recheck both files immediately before prune, retaining the first
         // trusted hash rather than blessing a replacement raw/meta pair.
-        const stored = readRawToolResult({ dir, toolCallId: id });
-        if (stored.ok && stored.path === cached.path && stored.sha256 === cached.sha256 && stored.bytes === cached.bytes) ids.add(id);
+        const needsAcl = cached.recovered === true && cached.aclVerified !== true;
+        const stored = readRawToolResult({ dir, toolCallId: id, tighten: needsAcl });
+        if (stored.ok && stored.path === cached.path && stored.sha256 === cached.sha256 && stored.bytes === cached.bytes) {
+          ids.add(id);
+          if (needsAcl) this.rawSeen.set(this.rawKey(session, id), { ...stored, recovered: false, aclVerified: true });
+        }
       } catch (error) {
         noteShadowWarning(this.ctx?.logger, error);
       }
@@ -1422,6 +1748,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   ensurePruneGuard() {
+    if (this.standDown?.()) return;
     if (this.pruneGuarded) return;
     let pruner;
     try {
@@ -1439,6 +1766,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     function guarded(session) {
       const engine = pruner.__spineEngine;
       try {
+        if (engine.standDown?.()) return;
         engine.captureSession(session);
         return runPruneAfterCapture(engine.surfaceToolIds(session), engine.rawVerifiedSet(session), () => original(session));
       } catch (error) {
@@ -1479,7 +1807,9 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     warnKey = DEFAULT_KEY,
     protectPaths = [],
     access = {},
+    rotationIO = {},
   ) {
+    if (this.standDown?.()) return { ok: false, reason: "stand-down" };
     return saveShadowImpl.call(
       this,
       messages,
@@ -1488,9 +1818,69 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       warnKey,
       protectPaths,
       access,
+      rotationIO,
     );
   }
 
+  async saveShadowAsync(
+    messages,
+    required,
+    shadowFile,
+    warnKey = DEFAULT_KEY,
+    protectPaths = [],
+    access = {},
+    rotationIO = {},
+  ) {
+    if (this.standDown?.()) return { ok: false, reason: "stand-down" };
+    if (!access.runner && (access.platform ?? process.platform) === "win32" && shadowAccessFused()) {
+      const error = new Error("spine: shadow permission already failed; backup refused");
+      error.code = "ESHADOWACCESS";
+      throw error;
+    }
+    const injected = Object.values(access || {}).some((value) => typeof value === "function") ||
+      Object.values(rotationIO || {}).some((value) => typeof value === "function");
+    // Node's test runner can monkey-patch fs bindings in the parent isolate;
+    // a worker cannot observe those injected failures. Keep test/fault-injection
+    // paths synchronous while production uses the complete off-thread txn.
+    if (injected || process.env.NODE_TEST_CONTEXT) {
+      return this.saveShadow(messages, required, shadowFile, warnKey, protectPaths, access, rotationIO);
+    }
+    const shadow = shadowDirectory();
+    const file = shadowFilePath(shadowFile, warnKey);
+    const body = shadowFileBody(warnKey, shadowBody(messages));
+    const cap = shadowMaxBytes();
+    const result = await runShadowWorker({
+      shadow,
+      file,
+      body,
+      required,
+      protectPaths,
+      sessionKey: warnKey,
+      cap,
+      access,
+      rotationIO,
+    });
+    if (!result?.ok) {
+      if (result?.reason === "scan-incomplete" || result?.reason === "invalid-measurement") {
+        this.ctx.logger?.warn?.(result.reason === "scan-incomplete"
+          ? "spine: shadow capacity scan is incomplete; backup refused; leaving the span"
+          : "spine: shadow capacity measurement is invalid; backup refused; leaving the span");
+      } else if (result?.rotation) {
+        this.warnShadowFull(warnKey, shadow, result.rotation.used, cap);
+      }
+      return result;
+    }
+    if (result.rotation?.deleted > 0) {
+      this.ctx.logger?.info?.(
+        `spine: shadow 轮换 删除 ${result.rotation.deleted} 个文件，` +
+        `腾出 ${result.rotation.freed} 字节，` +
+        `用量 ${result.rotation.used + Buffer.byteLength(body)}/${cap}`,
+      );
+    }
+    if (result.rotation?.oversize) this.warnShadowOversize(warnKey, cap);
+    return result;
+  }
+
   async summarize(input, agent, signal) {
     const decision = takeLocalCut(input?.liveCompact);
     const state = this.stateFor(agent);
@@ -1500,14 +1890,14 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       const card = input?.liveCompact?.card;
       if (card?.needsBackup && !card.shadowFile) throw new Error("spine: omit refused; backup path missing");
       const restored = this.restoreRawMessages(input.messages, state.key);
-      this.saveShadow(restored, true, card?.shadowFile, state.key, card?.rawPaths || []);
+      await this.saveShadowAsync(restored, true, card?.shadowFile, state.key, card?.rawPaths || []);
       if (card?.needsBackup && !existsSync(card.shadowFile)) throw new Error("spine: shadow backup was not written");
       const text = backupClaimOk(restored) ? decision.text : withoutFullBackupClaim(decision.text, card?.shadowFile);
       const block = { type: "text", text };
       return { summary: [block], provider: "local", model: "spine-extract", rawOutput: [block] };
     }
     try {
-      this.saveShadow(
+      await this.saveShadowAsync(
         this.restoreRawMessages(input.messages, state.key),
         false,
         freshShadowFile("official", state.key),
@@ -1522,7 +1912,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       }
     }
     const joined = input.messages.map(messageText).join("\n\n");
-    if (process.env.SPINE_THUNDER !== "1") return super.summarize(input, agent, signal);
+    if (process.env.SPINE_THUNDER !== "1") return this.summarizeOfficial(input, agent, signal);
     const next = joined;
     const mode = decideThunder({
       previous: state.lastPrefix || "",
@@ -1530,18 +1920,34 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       modelKind: process.env.SPINE_THUNDER_MODEL === "27b" ? "27b" : "flash",
       prefixTokens: state.lastPrefixTokens || 0,
     });
-    if (mode === "attach") return super.summarize(input, agent, signal);
+    if (mode === "attach") return this.summarizeOfficial(input, agent, signal);
     const users = input.messages.filter((message) => (message?.role ?? message?.message?.role) === "user");
     const taskLine = messageText(users.at(-1) || input.messages.at(-1)).slice(0, 500);
     const trunk = buildCard(joined, "", input.messages.map((message) => ({
       role: message?.role ?? message?.message?.role,
       text: messageText(message),
     })));
-    const facts = [...new Set([...(trunk.hardLines || []), ...(trunk.missing || [])])];
+    const facts = [...(trunk.hardFacts || []), ...(trunk.missingFacts || [])];
     const slim = buildSendLess({ taskLine, uncovered: trunk.uncovered, facts });
-    return super.summarize({
+    return this.summarizeOfficial({
       ...input,
       messages: [{ role: "user", content: [{ type: "text", text: slim }] }],
     }, agent, signal);
   }
+
+  async summarizeOfficial(input, agent, signal) {
+    const result = await super.summarize(input, agent, signal);
+    const blocks = Array.isArray(result?.summary) ? result.summary : [];
+    const usable = blocks.some((block) => {
+      if (typeof block === "string") return block.trim().length > 0;
+      if (!block || typeof block !== "object") return false;
+      if (typeof block.text === "string" && block.text.trim()) return true;
+      return Array.isArray(block.content) && block.content.some((part) => typeof part?.text === "string" && part.text.trim());
+    });
+    if (!usable) {
+      this.ctx.logger?.warn?.("spine: official summarizer returned no usable summary; leaving the span untouched");
+      throw new Error("spine: official summarizer returned no usable summary");
+    }
+    return result;
+  }
 }