dsh-log-contract 0.3.6 → 0.3.7

package/bin/dsh-log-contract.mjs

@@ -13,17 +13,19 @@
  *   contracts                     列出内置契约规则目录
  */
 import fs from 'node:fs';
-import { loadSessionLog, validateSessionLog, createPreWriter, repairSession, CONTRACT_RULES, ruleById, extractToolOutputs, auditToolCalls } from '../lib/index.js';
+import { loadSessionLog, validateSessionLog, resumeVerdict, createPreWriter, repairSession, CONTRACT_RULES, ruleById, extractToolOutputs, auditToolCalls } from '../lib/index.js';
 
 const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log contract guard）
 
 用法：
-  dsh-log-contract check <session-log> [--json] [--max-details N]
+  dsh-log-contract check <session-log> [--json] [--max-details N] [--resume]
       离线体检。session-log 支持 .jsonl 与 .jsonl.zstd。
       --json          输出机器可读 JSON 报告
       --max-details N 每条违规最多列 N 个缺失 seq（默认 8，--json 忽略）
+      --resume        输出三档结论（L3）：可加载 / 可继续 / 可压缩——
+                      回答「这个会话还能不能用」；--json 时附带 verdict 字段
 
-  dsh-log-contract fix <session-log> [--remove-markers] [--neutralize] [--clip-crossstep] [--apply] [--backup-dir DIR] [--json]
+  dsh-log-contract fix <session-log> [--remove-markers] [--neutralize] [--clip-crossstep] [--drop-failed-turns] [--trim-last N] [--compact-last N] [--tail-renumber D] [--neutralize-orphan] [--extract-turn N] [--keep-ranges a-b,c-d] [--apply] [--backup-dir DIR] [--json]
       诊断 + 修复（2026-08 事故固化方案）。先做严格 seq 连续扫描 + 契约体检
       （含 W1/W2 wire 级悬空 tool 检查），再按需修复：
       --remove-markers 移除 retrace/message-editor marker 并全量重编号
@@ -32,6 +34,21 @@ const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log cont
       --neutralize     原地中和 turn-null marker（type→retrace/marker +
                        ignorable:true，删 surfaceOp/sourceEventSeqs，seq/行数不变）
                        —— token-meter 不再刷屏，会话驻留也安全（2026-08-30 事故）
+      --drop-failed-turns 删除"本轮运行失败"的轮次（清失败报错气泡）
+      --trim-last N    裁剪到最近 N 条 append 消息（保留所在 turn 结构）
+      --trim-budget N  按 token 预算裁剪（L5）：自动选保留消息数使估算 ≤ N
+                       （中文 ≈ 字符数×0.94，不是 ÷4；下限至少保留 5 条消息）
+      --compact-last N 官方压缩：遮蔽旧 surface 节点，日志零删除（/compact 语义）
+      --tail-renumber D 尾部 seq 统一平移（delta 是减数：要加 N 传 −N）
+                       （修复多写入者/旧光标造成的尾部 seq 回归/间隙；从首个
+                       可平移 seq 起）
+      --neutralize-orphan 原地归零 fork 边界孤儿 inbox spliced（removedCount→0，
+                       seq/行数不变 → 不再重复排队）
+      --extract-turn N 双流交织恢复：只保留轮次 N + 无 turn 系统事件，其余
+                       删除并全量重编号（--extract-turn-to M 把第二个同名
+                       轮次改号为 M）
+      --keep-ranges a-b,c-d 只保留 1-based 行区间（含端点），其余删除 +
+                       全量重编号（header 行永远保留）
       --apply          备份后落盘（.zstd 走官方帧格式重建：帧1=header、
                        帧2=其余、带 checksum、单个结尾换行）
       不传 --apply 为干跑（只报告）。
@@ -79,6 +96,7 @@ function printViolations(violations, maxDetails = 8) {
 
 function cmdCheck(args) {
   const json = args.includes('--json');
+  const resume = args.includes('--resume');
   const maxDetailsIdx = args.indexOf('--max-details');
   const maxDetails = maxDetailsIdx >= 0 && args[maxDetailsIdx + 1] ? Number(args[maxDetailsIdx + 1]) : 8;
   const file = args.find((a) => !a.startsWith('-'));
@@ -94,7 +112,32 @@ function cmdCheck(args) {
   const { summary, violations, ok } = result;
 
   if (json) {
-    process.stdout.write(JSON.stringify({ file, ok, summary, violations }, null, 2) + '\n');
+    const payload = { file, ok, summary, violations };
+    if (resume) payload.resume = resumeVerdict(result);
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    process.exit(ok ? 0 : 1);
+  }
+
+  if (resume) {
+    const v = resumeVerdict(result);
+    const tier = v.verdict;
+    const icons = { loadable: '✅ 可加载', resumable: '✅ 可继续', compactable: '✅ 可压缩', broken: '❌ 不可用' };
+    process.stdout.write(`\n📋 dsh-log-contract check --resume —— ${file}\n`);
+    process.stdout.write(`   事件 ${summary.events} ｜ surface 节点 ${summary.surfaceNodes} ｜ replace 代数 ${summary.replaceGeneration} ｜ 帧 ${summary.frames}（${(summary.compressedBytes / 1024).toFixed(1)}KiB → ${(summary.plaintextBytes / 1024).toFixed(1)}KiB）\n`);
+    process.stdout.write(`   违规 ${summary.total}（error ${summary.bySeverity.error} / warning ${summary.bySeverity.warning}）\n\n`);
+    process.stdout.write(`   三档结论：\n`);
+    const tiers = [
+      ['可加载 loadable', v.loadable, '会话能被 DSH 读入（结构规则 S1-S9/E/W 全绿）', v.blocking.loadable],
+      ['可继续 resumable', v.resumable, 'resume/followup 可用（结构 + I1 inbox 重放绿）', v.blocking.resumable],
+      ['可压缩 compactable', v.compactable, '/compact 与压力测量可用（前两档 + T1/T2 token-meter 配对绿）', v.blocking.compactable],
+    ];
+    for (const [name, pass, desc, blockers] of tiers) {
+      const mark = pass ? '✅' : '❌';
+      process.stdout.write(`     ${mark} ${name} — ${desc}\n`);
+      if (blockers.length > 0) process.stdout.write(`        阻断: ${[...new Set(blockers)].join(', ')}\n`);
+    }
+    process.stdout.write(`\n   结论: ${icons[tier]}${v.verdict === 'compactable' ? ' —— 可安全继续使用' : v.verdict === 'broken' ? ' —— 见上方违规明细（error 级 = 会话不可读/不可写）' : ' —— 部分能力受限'}\n\n`);
+    printViolations(violations, maxDetails);
     process.exit(ok ? 0 : 1);
   }
 
@@ -177,15 +220,27 @@ function cmdFix(args) {
   const dropFailedTurns = args.includes('--drop-failed-turns');
   const trimIdx = args.indexOf('--trim-last');
   const trimLast = trimIdx >= 0 && args[trimIdx + 1] ? Number(args[trimIdx + 1]) : undefined;
+  const budgetIdx = args.indexOf('--trim-budget');
+  const trimBudget = budgetIdx >= 0 && args[budgetIdx + 1] ? Number(args[budgetIdx + 1]) : undefined;
   const compactIdx = args.indexOf('--compact-last');
   const compactLast = compactIdx >= 0 && args[compactIdx + 1] ? Number(args[compactIdx + 1]) : undefined;
+  // L4 新原语（2026-08-30 任务书 §L4 收编 tools/）
+  const tailIdx = args.indexOf('--tail-renumber');
+  const tailRenumberDelta = tailIdx >= 0 && args[tailIdx + 1] ? Number(args[tailIdx + 1]) : undefined;
+  const neutralizeOrphan = args.includes('--neutralize-orphan');
+  const extractIdx = args.indexOf('--extract-turn');
+  const extractTurn = extractIdx >= 0 && args[extractIdx + 1] ? Number(args[extractIdx + 1]) : undefined;
+  const extractToIdx = args.indexOf('--extract-turn-to');
+  const extractTurnTo = extractToIdx >= 0 && args[extractToIdx + 1] ? Number(args[extractToIdx + 1]) : undefined;
+  const keepRangesIdx = args.indexOf('--keep-ranges');
+  const keepRanges = keepRangesIdx >= 0 && args[keepRangesIdx + 1] ? args[keepRangesIdx + 1] : undefined;
   const apply = args.includes('--apply');
   const backupDirIdx = args.indexOf('--backup-dir');
   const backupDir = backupDirIdx >= 0 && args[backupDirIdx + 1] ? args[backupDirIdx + 1] : undefined;
   const file = args.find((a) => !a.startsWith('-'));
   if (!file) fail(USAGE);
 
-  const result = repairSession(file, { removeMarkers, neutralize, clipCrossStep, dropFailedTurns, trimLast, compactLast, apply, backupDir });
+  const result = repairSession(file, { removeMarkers, neutralize, clipCrossStep, dropFailedTurns, trimLast, trimBudget, compactLast, tailRenumberDelta, neutralizeOrphan, extractTurn, extractTurnTo, keepRanges, apply, backupDir });
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     process.exit(result.ok ? 0 : 1);
@@ -202,7 +257,7 @@ function cmdFix(args) {
   } else if (apply) {
     process.stdout.write('   （--apply 且无问题——无内容可修）\n');
   } else {
-    process.stdout.write(`   （干跑模式：${result.removed} 项可移除、${result.renumbered} 行待重编号、${result.neutralized} 个 turn-null marker 可中和、${result.clipped} 个跨 step 引用可裁剪；加 --apply 落盘，--remove-markers / --neutralize / --clip-crossstep / --drop-failed-turns / --trim-last N 启用于对应修复）\n`);
+    process.stdout.write(`   （干跑模式：${result.removed} 项可移除、${result.renumbered} 行待重编号、${result.neutralized} 个 turn-null marker 可中和、${result.clipped} 个跨 step 引用可裁剪；加 --apply 落盘，--remove-markers / --neutralize / --clip-crossstep / --drop-failed-turns / --trim-last N / --trim-budget N / --tail-renumber D / --neutralize-orphan / --extract-turn N / --keep-ranges a-b,c-d 启用于对应修复）\n`);
   }
   process.stdout.write('\n');
   process.exit(result.ok ? 0 : 1);

package/lib/index.js

@@ -5,9 +5,9 @@
  * 公开 API：离线体检 + 写前校验 + 修复 + 契约目录。
  */
 export { loadSessionLog, tailSeq } from './log-reader.js';
-export { validateSessionLog } from './validate.js';
+export { validateSessionLog, resumeVerdict } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
-export { repairSession, strictScanText, removeMarkersText, neutralizeMarkersText, clipCrossStepSourcesText, dropFailedTurnsText, trimLastMessagesText, compactLastMessagesText, rebuildZstdText } from './repair.js';
+export { repairSession, strictScanText, removeMarkersText, neutralizeMarkersText, clipCrossStepSourcesText, dropFailedTurnsText, trimLastMessagesText, trimLastMessagesByBudget, estimateTokensText, compactLastMessagesText, rebuildZstdText, tailRenumberText, neutralizeOrphanText, extractTurnText, keepRangesText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';
 export { tokenMeterViolations, tokenMeterSourceViolations, physicalOrderViolations, inboxReplayViolations } from './checks.js';
 export { auditToolCalls, extractText, extractToolOutputs, indexToolCalls, toolCommandOf } from './archaeology.js';

package/lib/repair.js

@@ -317,10 +317,19 @@ export function removeMarkersText(text) {
  * @param {(event: object) => boolean} dropPredicate - 命中即删除该事件行。
  * @returns {{ text: string, removed: number, renumbered: number }}
  */
-function renumberWithDrops(parts, dropPredicate) {
+function renumberWithDrops(parts, dropPredicate, dropLinePredicate = null) {
+  // 行身份删除（dropLinePredicate）：双流交织时保留行与删除行可能共享 seq
+  // 值，按 seq 值判删会误删保留行——extractTurn 等场景必须按行身份删除。
+  // 两种判据任一命中即删；dropLinePredicate 用行索引（parts 下标）。
   const dropped = new Set();
-  for (const raw of parts) {
+  const droppedLines = new Set();
+  for (let i = 0; i < parts.length; i++) {
+    const raw = parts[i];
     if (!raw.trim()) continue;
+    if (dropLinePredicate && dropLinePredicate(i)) {
+      droppedLines.add(i);
+      continue;
+    }
     let v;
     try {
       v = JSON.parse(raw);
@@ -344,11 +353,16 @@ function renumberWithDrops(parts, dropPredicate) {
   const out = [];
   let removed = 0;
   let renumbered = 0;
-  for (const raw of parts) {
+  for (let i = 0; i < parts.length; i++) {
+    const raw = parts[i];
     if (!raw.trim()) {
       out.push(raw);
       continue;
     }
+    if (dropLinePredicate && dropLinePredicate(i)) {
+      removed++;
+      continue;
+    }
     let v;
     try {
       v = JSON.parse(raw);
@@ -399,6 +413,101 @@ function renumberWithDrops(parts, dropPredicate) {
   return { text: fixed, removed, renumbered };
 }
 
+/**
+ * 按行身份保留 + 全量重编号（extract-turn / keep-ranges 用）。
+ *
+ * ⚠️ 与 renumberWithDrops 不同：本函数按「行是否保留」决定删除（双流交织时
+ * 保留行与删除行可能共享 seq 值，按 seq 值判删会误删保留行——2026-08-31
+ * 独立审查实测复现），且保留行**全量重映射** seq 从 0 连续（参考原工具
+ * keep-ranges.mjs 的 seqMap 逻辑），同步 seq / seq0 / sourceEventSeqs /
+ * surfaceOp 范围。header 行（首行）恒保留且不改。
+ * @param {string[]} parts - 按 \n 切分的行数组。
+ * @param {(lineIdx: number) => boolean} keepLinePredicate - 行身份保留判定。
+ * @returns {{ text: string, removed: number, renumbered: number }}
+ */
+function renumberKeptLines(parts, keepLinePredicate) {
+  // 第一遍：按物理序收集保留行的事件 seq（chunk 行展开，参考 keep-ranges 原工具）
+  const keptLineIdx = [];
+  for (let i = 0; i < parts.length; i++) {
+    const raw = parts[i];
+    if (!raw.trim()) continue;
+    if (i === 0) { keptLineIdx.push(i); continue; } // header
+    if (keepLinePredicate(i)) keptLineIdx.push(i);
+  }
+  // 建立 old→new 映射：保留行的展开事件按物理序分配 0,1,2,…
+  const seqMap = new Map();
+  let counter = 0;
+  for (const li of keptLineIdx) {
+    if (li === 0) continue; // header 无 seq
+    const decoded = decodeLine(parts[li]);
+    if (!decoded) continue;
+    for (const ev of decoded) {
+      if (typeof ev.seq === 'number' && !seqMap.has(ev.seq)) seqMap.set(ev.seq, counter++);
+    }
+  }
+  const remap = (s) => (typeof s === 'number' && seqMap.has(s) ? seqMap.get(s) : null);
+  // 第二遍：重写保留行
+  const out = [];
+  let removed = 0;
+  let renumbered = 0;
+  const keptSet = new Set(keptLineIdx);
+  for (let i = 0; i < parts.length; i++) {
+    const raw = parts[i];
+    if (!raw.trim()) {
+      out.push(raw);
+      continue;
+    }
+    if (!keptSet.has(i)) {
+      removed++;
+      continue;
+    }
+    if (i === 0) { out.push(raw); continue; } // header 原样
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      out.push(raw);
+      continue;
+    }
+    let touched = false;
+    if (typeof v.seq === 'number') {
+      const ns = remap(v.seq);
+      if (ns !== null && ns !== v.seq) {
+        v.seq = ns;
+        touched = true;
+      }
+    }
+    if (CHUNK_ROW_TYPES.has(v.type) && typeof v.seq0 === 'number') {
+      const ns = remap(v.seq0);
+      if (ns !== null && ns !== v.seq0) {
+        v.seq0 = ns;
+        touched = true;
+      }
+    }
+    if (Array.isArray(v.sourceEventSeqs)) {
+      const next = v.sourceEventSeqs.map((s) => remap(s) ?? s);
+      if (next.some((x, k) => x !== v.sourceEventSeqs[k])) {
+        v.sourceEventSeqs = next;
+        touched = true;
+      }
+    }
+    if (v.surfaceOp && v.surfaceOp.op === 'replace') {
+      const ns = remap(v.surfaceOp.start);
+      const ne = remap(v.surfaceOp.end);
+      if (ns !== null && ne !== null && (ns !== v.surfaceOp.start || ne !== v.surfaceOp.end)) {
+        v.surfaceOp.start = ns;
+        v.surfaceOp.end = ne;
+        touched = true;
+      }
+    }
+    out.push(touched ? JSON.stringify(v) : raw);
+    if (touched) renumbered++;
+  }
+  let fixed = out.join('\n');
+  if (!fixed.endsWith('\n')) fixed += '\n';
+  return { text: fixed, removed, renumbered };
+}
+
 /**
  * 删除"本轮运行失败"的轮次（turn/end 带 reason.kind==='error' 的完整轮次：
  * [turnStart..turnEnd]，含其中的 user 消息与失败产出），并全量重编号。
@@ -430,6 +539,338 @@ export function dropFailedTurnsText(text) {
   return { ...r, failedTurns: spans.length };
 }
 
+/**
+ * 尾部 seq 统一平移（fix-tail 收编，源：tools/trim-session.mjs fix-tail 模式）。
+ *
+ * 修复多写入者/旧光标造成的尾部 seq 回归/间隙：从 startSeq 起（含）的所有
+ * 事件的 seq / seq0 / sourceEventSeqs 统一加减 delta。
+ * @param {string} text - JSONL 全文。
+ * @param {number} startSeq - 平移起点（该 seq 及之后的事件全部平移）。
+ * @param {number} delta - 偏移量（减数语义：要加 N 传 −N；要减 N 传 +N）。
+ * @returns {{ text: string, changed: number, startSeq: number, delta: number }}
+ */
+export function tailRenumberText(text, startSeq, delta) {
+  if (!Number.isInteger(delta) || delta === 0) return { text, changed: 0, startSeq, delta };
+  const parts = text.split('\n');
+  const out = [];
+  let changed = 0;
+  for (const raw of parts) {
+    if (!raw.trim()) {
+      out.push(raw);
+      continue;
+    }
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      out.push(raw);
+      continue;
+    }
+    let modified = false;
+    const seq = v.seq;
+    if (typeof seq === 'number' && seq >= startSeq) {
+      const ns = seq - delta;
+      if (ns < 0) return { text, changed: 0, startSeq, delta, error: `seq ${seq} 平移后为负（delta 过大或起点有误）` };
+      v.seq = ns;
+      modified = true;
+    }
+    if (typeof v.seq0 === 'number' && v.seq0 >= startSeq) {
+      const ns = v.seq0 - delta;
+      if (ns < 0) return { text, changed: 0, startSeq, delta, error: `seq0 ${v.seq0} 平移后为负（delta 过大或起点有误）` };
+      v.seq0 = ns;
+      modified = true;
+    }
+    if (Array.isArray(v.sourceEventSeqs)) {
+      let mapped;
+      try {
+        mapped = v.sourceEventSeqs.map((s) => {
+          if (s < startSeq) return s;
+          const ns = s - delta;
+          if (ns < 0) throw new Error(`sourceEventSeqs ${s} 平移后为负`);
+          return ns;
+        });
+      } catch (err) {
+        // 与 seq/seq0 的优雅返回一致：错误走 error 字段而非未捕获异常
+        return { text, changed: 0, startSeq, delta, error: err.message };
+      }
+      if (mapped.some((s, i) => s !== v.sourceEventSeqs[i])) {
+        v.sourceEventSeqs = mapped;
+        modified = true;
+      }
+    }
+    if (modified) changed++;
+    out.push(JSON.stringify(v));
+  }
+  return { text: out.join('\n'), changed, startSeq, delta };
+}
+
+/**
+ * fork 边界孤儿 spliced 原地归零（--neutralize-orphan）。
+ *
+ * 2026-08-28 fork 边界事故：裁剪后历史 inbox spliced 残留（已消费消息被
+ * 重新排队 → UI 显示"待排队消息"）。与 neutralize 同类：原地改
+ * `removedCount → 0`（start/inserted 不变，seq/行数不变 → 附着力安全）。
+ *
+ * ⚠️ 判定（2026-08-31 独立审查修正）：不能对"所有 removedCount>0 的
+ * next-turn spliced"下手——DSH 每个轮次消费消息都会写这种 spliced
+ * （archive 实测 3069 处 removedCount>0，但真 I1 违规只 2 处）。只归零
+ * **实际触发 I1 违规**的那条：按官方 inbox 重放（checks.js
+ * inboxReplayViolations 同款状态机），`start + removedCount > 队列长`
+ * 即孤儿——归零后队列重放不再越界、已消费消息不再重复投递。
+ *
+ * @param {string} text - JSONL 全文。
+ * @returns {{ text: string, neutralized: number, seqs: number[] }}
+ */
+export function neutralizeOrphanText(text) {
+  const parts = text.split('\n');
+  // 解析 header.seedLength（与 checks.js inboxReplayViolations 同口径）
+  let seedLength = 0;
+  try {
+    const hdr = JSON.parse(parts[0] || '');
+    if (typeof hdr?.seedLength === 'number' && Number.isSafeInteger(hdr.seedLength)) seedLength = hdr.seedLength;
+  } catch { /* header 缺失时从 0 重放 */ }
+  const state = { 'next-turn': [], 'next-step': [] };
+  const seqs = [];
+  let neutralized = 0;
+  for (let i = 1; i < parts.length; i++) {
+    const raw = parts[i];
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!v || typeof v !== 'object' || v.type !== 'agent/inbox/spliced') continue;
+    if (v.seq < seedLength) continue; // seed 区域不重放（与官方一致）
+    const splice = v.data;
+    if (!splice || typeof splice.target !== 'string' || !['next-turn', 'next-step'].includes(splice.target)) continue;
+    const inbox = state[splice.target];
+    const removedCount = splice.removedCount ?? 0;
+    const start = splice.start ?? 0;
+    const inserted = Array.isArray(splice.inserted) ? splice.inserted : [];
+    // 只有越界（start+removedCount > 队列长）才判为孤儿——与 I1 规则同判定
+    if (start + removedCount > inbox.length && removedCount > 0) {
+      v.data.removedCount = 0;
+      parts[i] = JSON.stringify(v);
+      seqs.push(v.seq);
+      neutralized++;
+      // 归零后照常推进重放状态（removedCount=0 → 插入 inserted，不删除）
+      inbox.splice(start, 0, ...inserted);
+    } else {
+      // 合法 spliced：正常推进重放状态
+      inbox.splice(start, removedCount, ...inserted);
+    }
+  }
+  return { text: parts.join('\n'), neutralized, seqs };
+}
+
+/**
+ * 双流交织恢复：保留指定轮次（extract-turn 收编，源：tools/recover-interleaved.mjs）。
+ *
+ * 并发写入把两条事件流交织进同一文件（旧光标重放流 + 真实新轮次）。本原语：
+ * 保留 keepTurn 轮次的全部事件 + 其间的无 turn 系统事件（spliced/user/request
+ * 等），丢弃其余（重放流、turn-null marker、非目标轮次），全量重编号；
+ * 可选把该轮次的第二个 turn/start 起改号为 secondTurnTo（避免未闭合 turn 冲突）。
+ * @param {string} text - JSONL 全文（含 header 行）。
+ * @param {number} keepTurn - 要保留的轮次号。
+ * @param {number|null} secondTurnTo - 第二个同名 turn/start 起改号（默认 null 不改）。
+ * @returns {{ text: string, removed: number, renumbered: number, kept: number, secondRenamed: boolean }}
+ */
+export function extractTurnText(text, keepTurn, secondTurnTo = null) {
+  const parts = text.split('\n');
+  const KEEP_NULL_TYPES = new Set(['agent/inbox/spliced', 'user/message', 'request/header', 'session/end-seed', 'command/run', 'command/done']);
+  // 第一轮：按行身份决定去留（保留 turn===keepTurn 的行 + 无 turn 系统事件
+  // 白名单），并就地改第二个同名轮次的 turn 号。
+  // ⚠️ 用行索引而非 seq 值：双流交织时保留行与删除行可能共享 seq（独立审查
+  // 实测复现内容静默丢失）——按行身份删除才安全。
+  const dropLines = new Set();
+  let sawFirstTurnStart = false;
+  let inRenumberTurn = false;
+  let kept = 0;
+  for (let i = 0; i < parts.length; i++) {
+    const raw = parts[i];
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (i === 0 || v.type === 'session') { kept++; continue; } // header 永远保留
+    const d = v.data || {};
+    const turn = d.turn;
+    const t = v.type;
+    let keep = false;
+    if (turn === keepTurn) keep = true;
+    else if (turn == null && KEEP_NULL_TYPES.has(t)) keep = true;
+    if (t === 'turn/start' && d.turn === keepTurn) {
+      if (sawFirstTurnStart) inRenumberTurn = true;
+      else sawFirstTurnStart = true;
+    }
+    if (keep) {
+      kept++;
+      if (inRenumberTurn && turn === keepTurn && secondTurnTo !== null) {
+        v.data.turn = secondTurnTo;
+        parts[i] = JSON.stringify(v);
+      }
+    } else {
+      dropLines.add(i);
+    }
+  }
+  if (kept === 0) return { text, removed: 0, renumbered: 0, kept: 0, secondRenamed: false };
+  // 重编号：按行身份保留 + 全量重映射 seq（从 0 连续），同步所有引用
+  const r = renumberKeptLines(parts, (i) => !dropLines.has(i));
+  return { ...r, kept, secondRenamed: secondTurnTo !== null && inRenumberTurn };
+}
+
+/**
+ * 只保留指定 seq 区间，其余删除 + 全量重编号（keep-ranges 收编，
+ * 源：tools/keep-ranges.mjs）。
+ *
+ * 从交织/污染文件中提取干净区段。区间为 1-based 行号（含端点），
+ * 如 "10-20,40-50"；区段外的行丢弃。header 行（首行）永远保留。
+ * @param {string} text - JSONL 全文（含 header 行）。
+ * @param {string} rangesSpec - 区间串，如 "10-20,40-50"。
+ * @returns {{ text: string, removed: number, renumbered: number, keptLines: number }}
+ */
+export function keepRangesText(text, rangesSpec) {
+  const ranges = String(rangesSpec).split(',').map((part) => {
+    const m = /^(\d+)-(\d+)$/.exec(part.trim());
+    if (!m) throw new Error(`区间格式错误: "${part}"（应为 a-b，如 10-20）`);
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    if (a > b) throw new Error(`区间起点大于终点: "${part}"`);
+    return [a, b];
+  });
+  const parts = text.split('\n');
+  // 按行身份删除（双流交织时保留行与删除行可能共享 seq——独立审查发现）
+  const dropLines = new Set();
+  let keptLines = 0;
+  for (let i = 0; i < parts.length; i++) {
+    if (i === 0) { keptLines++; continue; } // header 永远保留
+    const one = i + 1; // 1-based 行号
+    const inRange = ranges.some(([a, b]) => one >= a && one <= b);
+    if (inRange) keptLines++;
+    else dropLines.add(i);
+  }
+  if (keptLines === 1) return { text, removed: 0, renumbered: 0, keptLines, error: '区间未命中任何数据行（仅 header 保留）——请检查 1-based 行号' };
+  const r = renumberKeptLines(parts, (i) => !dropLines.has(i));
+  return { ...r, keptLines };
+}
+
+/**
+ * 消息文本 token 估算（L5：中文密度校准）。
+ *
+ * 2026-08 事故教训：chars/4 对中文密集内容低估 ~3.7×（实际 ≈ 字符数×0.94）。
+ * 本函数按消息类型取文本并加权：
+ *   - 中文/全角字符：×0.94（实测密度，不是 /4）；
+ *   - 其余字符（ASCII/空格/标点）：×0.25（近似词元密度）；
+ *   - JSON 结构开销（每消息 envelope）：+12 tokens 固定。
+ * @param {string} text - JSONL 全文（含 header）。
+ * @returns {{ tokens: number, cjk: number, other: number }}
+ */
+export function estimateTokensText(text) {
+  const parts = text.split('\n');
+  let cjk = 0;
+  let other = 0;
+  let messages = 0;
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    let body = '';
+    if (v.type === 'user/message') {
+      body = (v.data?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+      messages++;
+    } else if (v.type === 'assistant/message' && v.surfaceOp === 'append') {
+      body = (v.data?.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+      messages++;
+    }
+    // 按码点分类：CJK 统一表意文字 + 全角符号按中文字符计
+    for (const ch of body) {
+      const cp = ch.codePointAt(0);
+      if (
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK 统一表意
+        (cp >= 0x3400 && cp <= 0x4dbf) || // CJK 扩展 A
+        (cp >= 0xff00 && cp <= 0xffef) || // 全角
+        (cp >= 0x3000 && cp <= 0x303f)    // CJK 标点
+      ) cjk++;
+      else if (cp > 0x20) other++;
+    }
+  }
+  const tokens = Math.ceil(cjk * 0.94 + other * 0.25 + messages * 12);
+  return { tokens, cjk, other, messages };
+}
+
+/**
+ * 按 token 预算裁剪（L5）：自动选保留消息数，使「估算 token ≤ 预算」。
+ * 保留 --trim-last N 按消息数语义；--trim-budget 走本函数。
+ * 下限保护：至少保留 5 条消息（防空会话）。
+ *
+ * 精确做法：按消息类型逐条累计 token 估算（复用 estimateTokensText 的
+ * 单条消息算法），从最近消息往回累加，直到超过预算——避免比例估算误差。
+ * @param {string} text - JSONL 全文。
+ * @param {number} budget - token 预算（如 450000）。
+ * @returns {{ text: string, removed: number, renumbered: number, kept: number, cutoff: number, estimatedTokens: number }}
+ */
+export function trimLastMessagesByBudget(text, budget) {
+  const parts = text.split('\n');
+  // 逐条消息的 { seq, tokens }：从最近往回累计
+  const msgs = [];
+  for (const raw of parts) {
+    if (!raw.trim()) continue;
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    let body = '';
+    if (v.type === 'user/message') {
+      body = (v.data?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    } else if (v.type === 'assistant/message' && v.surfaceOp === 'append') {
+      body = (v.data?.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    } else {
+      continue;
+    }
+    let cjk = 0;
+    let other = 0;
+    for (const ch of body) {
+      const cp = ch.codePointAt(0);
+      if (
+        (cp >= 0x4e00 && cp <= 0x9fff) ||
+        (cp >= 0x3400 && cp <= 0x4dbf) ||
+        (cp >= 0xff00 && cp <= 0xffef) ||
+        (cp >= 0x3000 && cp <= 0x303f)
+      ) cjk++;
+      else if (cp > 0x20) other++;
+    }
+    msgs.push({ seq: v.seq, tokens: Math.ceil(cjk * 0.94 + other * 0.25 + 12) });
+  }
+  const total = msgs.length;
+  const MIN_KEEP = 5;
+  // 从最近往回累计，找到「估算 ≤ 预算」的最大保留数
+  let acc = 0;
+  let kept = 0;
+  for (let i = total - 1; i >= 0; i--) {
+    if (acc + msgs[i].tokens > budget) break;
+    acc += msgs[i].tokens;
+    kept++;
+  }
+  if (kept < MIN_KEEP) kept = MIN_KEEP;
+  if (kept >= total) {
+    const all = estimateTokensText(text);
+    return { text, removed: 0, renumbered: 0, kept: total, cutoff: 0, estimatedTokens: all.tokens };
+  }
+  const r = trimLastMessagesText(text, kept);
+  return { ...r, estimatedTokens: acc };
+}
+
 /**
  * 裁剪到最近 keepMessages 条 append 消息（保留其所在 turn 的结构），
  * 同时移除全部 retrace/message-editor marker，并全量重编号。
@@ -739,6 +1180,61 @@ export function repairSession(file, opts = {}) {
     const r = trimLastMessagesText(plain, opts.trimLast);
     applyFix('trim', r, `裁剪到最近 ${r.kept} 条消息（丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）`);
   }
+  if (typeof opts.trimBudget === 'number') {
+    const r = trimLastMessagesByBudget(plain, opts.trimBudget);
+    if (r.removed > 0) {
+      issues.push({ kind: 'trim-budget', detail: `按 token 预算 ${opts.trimBudget} 裁剪：保留 ${r.kept} 条消息（估算 ≈${r.estimatedTokens} tokens，丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）` });
+      plain = r.text;
+    } else {
+      issues.push({ kind: 'trim-budget', detail: `估算 ${r.estimatedTokens} tokens ≤ 预算 ${opts.trimBudget}——无需裁剪（${r.kept} 条消息全保留）` });
+    }
+  }
+  // L4 新原语（2026-08-30 任务书 §L4 收编 tools/ 验证工具）
+  if (typeof opts.tailRenumberDelta === 'number') {
+    // 起点自动推导：从首个可平移的 seq 起（即所有事件都平移）。
+    // fix-tail 原工具是 <startLine> <delta> 双参；任务书 §L4 简化为单参 delta
+    // （尾部全部平移）。若需部分平移，传 --tail-renumber 前先 --keep-ranges。
+    const r = tailRenumberText(plain, 0, opts.tailRenumberDelta);
+    if (r.error) {
+      issues.push({ kind: 'tail-renumber', detail: r.error });
+    } else if (r.changed > 0) {
+      issues.push({ kind: 'tail-renumber', detail: `尾部 ${r.changed} 行 seq 平移 delta=${r.delta}` });
+      plain = r.text;
+    }
+  }
+  if (opts.neutralizeOrphan) {
+    const r = neutralizeOrphanText(plain);
+    if (r.neutralized > 0) {
+      issues.push({ kind: 'neutralize-orphan', detail: `原地归零 ${r.neutralized} 个孤儿 inbox spliced（removedCount→0，seq/行数不变）→ 不再重复排队` });
+      plain = r.text;
+    }
+  }
+  if (typeof opts.extractTurn === 'number') {
+    const r = extractTurnText(plain, opts.extractTurn, opts.extractTurnTo ?? null);
+    if (r.kept === 0) {
+      issues.push({ kind: 'extract-turn', detail: `轮次 ${opts.extractTurn} 不存在（无保留行）` });
+    } else {
+      issues.push({ kind: 'extract-turn', detail: `保留轮次 ${opts.extractTurn}（${r.kept} 行，丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）${r.secondRenamed ? `，第二同名轮次改号 ${opts.extractTurnTo}` : ''}` });
+      removed += r.removed;
+      renumbered += r.renumbered;
+      plain = r.text;
+    }
+  }
+  if (typeof opts.keepRanges === 'string') {
+    try {
+      const r = keepRangesText(plain, opts.keepRanges);
+      if (r.error) {
+        issues.push({ kind: 'keep-ranges', detail: r.error });
+      } else {
+        issues.push({ kind: 'keep-ranges', detail: `保留区间 ${opts.keepRanges}（${r.keptLines} 行，丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）` });
+        removed += r.removed;
+        renumbered += r.renumbered;
+        plain = r.text;
+      }
+    } catch (err) {
+      issues.push({ kind: 'keep-ranges', detail: String(err.message ?? err) });
+    }
+  }
   if (typeof opts.compactLast === 'number') {
     const r = compactLastMessagesText(plain, opts.compactLast);
     if (r.compacted) {
@@ -746,6 +1242,13 @@ export function repairSession(file, opts = {}) {
       plain = r.text;
     }
   }
+  // 请求的修复是否"自身失败"（独立于终检）：tail-renumber 报 error、
+  // keep-ranges 报 error、extract-turn 无保留行、keep-ranges 未命中——
+  // 任一发生 → ok=false（修复没做成，不能报成功）。
+  const requestedFailed = issues.some((i) =>
+    i.kind === 'tail-renumber' && /负|错误/.test(i.detail) ||
+    i.kind === 'keep-ranges' && i.detail.includes('未命中') ||
+    i.kind === 'extract-turn' && i.detail.includes('不存在'));
   // 全部修复完成后做一次终检（中间态的临时违规不阻塞——后续修复可能已消除）
   const scanFinal = strictScanText(plain);
   const checkFinal = validateSessionLog(loadSessionLogFromText(plain));
@@ -757,7 +1260,7 @@ export function repairSession(file, opts = {}) {
     const errs = checkFinal.violations.filter((v) => v.severity === 'error');
     issues.push({ kind: 'final-contract', detail: `修复后仍有 ${errs.length} 个 error 级违规（首条：${errs[0]?.id ?? '-'} ${errs[0]?.message?.slice(0, 90) ?? ''}）` });
   }
-  const ok = scanFinal.failures.length === 0 && checkFinal.ok;
+  const ok = !requestedFailed && scanFinal.failures.length === 0 && checkFinal.ok;
   let backupPath = null;
   let applied = false;
   if (opts.apply && ok) {

package/lib/validate.js

@@ -168,4 +168,73 @@ export function validateSessionLog(log, opts = {}) {
   };
 }
 
+/**
+ * resumeVerdict —— `check --resume` 三档结论（L3）。
+ *
+ * 回答用户「这个会话还能不能用」，三档蕴含（可压缩 ⊂ 可继续 ⊂ 可加载）：
+ *   ✅ 可加载  loadable    —— 结构规则全绿（S1-S9/E 系列/W1/W2 等 error 级全清）
+ *   ✅ 可继续  resumable   —— 结构绿 + I1（inbox 重放）绿
+ *   ✅ 可压缩  compactable —— 前两档绿 + T1/T2（token-meter 配对）绿
+ *
+ * 纯聚合输出，不新增校验逻辑：直接复用 validateSessionLog 的 violations
+ * 按规则 id 分组判定（2026-08-30 事故：离线 check 全绿但实机 token-meter 崩
+ * 的教训——T1/T2 必须单独看，不能只看 error 总数）。
+ *
+ * @param {{ok: boolean, violations: Array, summary: object}} result validateSessionLog 的返回值
+ * @returns {{
+ *   verdict: 'loadable' | 'resumable' | 'compactable' | 'broken',
+ *   loadable: boolean, resumable: boolean, compactable: boolean,
+ *   blocking: { loadable: Array, resumable: Array, compactable: Array },
+ * }}
+ */
+export function resumeVerdict(result) {
+  const { ok, violations = [] } = result;
+  // 三档各自的「阻断规则集」——按任务书 §L3 档位定义：
+  //   可加载：结构层（PERSISTENCE/FRAMING）+ 引擎层非 I1/T1/T2 的 error；
+  //   可继续：+ I1（inbox 重放）；
+  //   可压缩：+ T1/T2（token-meter 配对）。
+  const byId = {};
+  for (const v of violations) {
+    if (v.severity !== 'error') continue;
+    (byId[v.id] ??= []).push(v);
+  }
+  const has = (id) => (byId[id]?.length ?? 0) > 0;
+
+  // 可加载阻断 = 除 I1/T1/T2 外的所有 error 违规（结构/信封/物理序/工具配对等）。
+  // 注意：不能用 result.ok（它把 T1/T2/I1 也计为 error）——三档判定按任务书定义，
+  // T1/T2 只影响「可压缩」档、I1 只影响「可继续」档。
+  const loadableBlockers = violations.filter(
+    (v) => v.severity === 'error' && !['I1', 'T1', 'T2'].includes(v.id),
+  ).map((v) => v.id);
+  const loadable = loadableBlockers.length === 0;
+
+  const resumableBlockers = loadable ? (has('I1') ? ['I1'] : []) : [];
+  const resumable = loadable && !has('I1');
+
+  const compactableBlockers = resumable
+    ? (has('T1') || has('T2') ? ['T1', 'T2'].filter((id) => has(id)) : [])
+    : [];
+  const compactable = resumable && !has('T1') && !has('T2');
+
+  // 最差档位
+  const verdict = !loadable ? 'broken' : !resumable ? 'loadable' : !compactable ? 'resumable' : 'compactable';
+
+  return {
+    verdict,
+    loadable,
+    resumable,
+    compactable,
+    blocking: {
+      loadable: [...new Set(loadableBlockers)],
+      resumable: resumableBlockers,
+      compactable: compactableBlockers,
+    },
+    violationsByTier: {
+      structural: [...new Set(loadableBlockers)],
+      inbox: has('I1') ? ['I1'] : [],
+      tokenMeter: has('T1') || has('T2') ? ['T1', 'T2'].filter((id) => has(id)) : [],
+    },
+  };
+}
+
 export { ruleById };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.3.6",
+  "version": "0.3.7",
+  "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",
   "bin": {
@@ -27,6 +28,11 @@
     "LICENSE",
     "README.zh.md"
   ],
+  "scripts": {
+    "check": "node scripts/check-syntax.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm check && pnpm test"
+  },
   "keywords": [
     "dsh",
     "deepseek-harness",
@@ -59,9 +65,5 @@
     "@deepseek-ai/dsh-session": "0.1.0-rc.7",
     "esbuild": "0.28.2",
     "vitest": "4.1.11"
-  },
-  "scripts": {
-    "check": "node scripts/check-syntax.mjs",
-    "test": "vitest run"
   }
-}
+}