dsh-live-compact 1.1.4 → 1.1.5

package/index.js

@@ -16,28 +16,26 @@ 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";
@@ -57,6 +55,100 @@ 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 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 } of entry.pending.values()) reject(error);
+    entry.pending.clear();
+    removeEntry();
+    worker.terminate().catch(() => {});
+  };
+  worker.on("message", (message) => {
+    const task = entry.pending.get(message?.id);
+    if (!task) return;
+    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) => {
+    entry.pending.set(id, { resolve, reject });
+    try {
+      entry.worker.postMessage({ id, payload });
+    } catch (error) {
+      entry.pending.delete(id);
+      reject(error);
+      entry.scheduleIdleExit();
+    }
+  });
+}
+
+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 eventContent(session, seq) {
   const event = session.eventAt(seq);
@@ -184,80 +276,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,9 +357,11 @@ 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;
@@ -365,7 +420,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) {
@@ -437,9 +491,11 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
   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 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);
+    ? { 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 null;
   card = attachBackupHint(card, freshShadowFile("cut", key));
   if (!card.text.includes("不是备份文件路径")) card = { ...card, text: `${card.text}\n序号是本会话日志里的事件号，不是备份文件路径。` };
@@ -473,6 +529,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) {
@@ -585,7 +642,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 +653,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 +664,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 +700,13 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     scheduleImmediate(() => {
       task.scheduled = false;
       try {
-        const latest = task.session.snapshotEvents?.();
+        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 +714,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,
@@ -739,12 +809,16 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     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);
@@ -805,7 +879,7 @@ 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.flushPendingCaptures(agent.session, this.chunkToolCallIds(agent.session, chunk));
             await this.commitSelectedSpan(agent, chunk, op);
             measurement = this.ctx.tokenMeter.measure(agent.session);
             const after = measurement.totalTokens;
@@ -914,7 +988,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"}`);
         }
@@ -1137,8 +1232,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" ||
@@ -1216,6 +1312,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     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 +1342,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,7 +1366,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       progressed,
       retryable: retry !== null,
       done: exhausted && retry === null && next > lastSeq,
-      nextIndex: index,
+      nextIndex: retryIndex ?? index,
     };
   }
 
@@ -1353,14 +1453,34 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
 
   recoverVisibleRaw(session, access = {}) {
     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));
       }
     }
   }
@@ -1368,6 +1488,14 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   recoverVisibleRawBatch(session, access = {}, startIndex = 0, limit = RECOVER_RAW_BATCH, visibleIds = null) {
     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 +1504,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 +1536,20 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
   }
 
   captureSession(session) {
-    return this.captureNew(session, session?.snapshotEvents?.() || []);
+    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 +1566,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);
       }
@@ -1479,6 +1649,7 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     warnKey = DEFAULT_KEY,
     protectPaths = [],
     access = {},
+    rotationIO = {},
   ) {
     return saveShadowImpl.call(
       this,
@@ -1488,9 +1659,68 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
       warnKey,
       protectPaths,
       access,
+      rotationIO,
     );
   }
 
+  async saveShadowAsync(
+    messages,
+    required,
+    shadowFile,
+    warnKey = DEFAULT_KEY,
+    protectPaths = [],
+    access = {},
+    rotationIO = {},
+  ) {
+    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 +1730,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 +1752,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,7 +1760,7 @@ 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) => ({
@@ -1539,9 +1769,25 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     })));
     const facts = [...new Set([...(trunk.hardLines || []), ...(trunk.missing || [])])];
     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;
+  }
 }