@feng0531/dsh-code-review 0.85.11 → 0.86.0

package/src/review-artifacts.mjs

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, open, lstat, realpath, rename, unlink, chmod } from 'node:fs/promises';
+import path from 'node:path';
+
+const queues = new Map();
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const STATUSES = new Set(['completed', 'failed', 'cancelled', 'incomplete', 'validated-draft', 'rejected']);
+const fail = code => Object.assign(new Error(code), { code });
+const within = (base, name) => { const r = path.relative(base, name); return r === '' || (!path.isAbsolute(r) && r !== '..' && !r.startsWith('..' + path.sep)); };
+function ownerIdentity(owner) {
+  if (!owner || !['sessionId', 'cwd', 'provider', 'model'].every(key => typeof owner[key] === 'string' && owner[key].length > 0 && owner[key].length <= 4096) || !path.isAbsolute(owner.cwd) || !(owner.reasoningEffort == null || typeof owner.reasoningEffort === 'string' && owner.reasoningEffort.length <= 256)) throw fail('INVALID_REVIEW_ARTIFACT_OWNER');
+  return { sessionId: owner.sessionId, cwd: owner.cwd, provider: owner.provider, model: owner.model, reasoningEffort: owner.reasoningEffort ?? null };
+}
+function snapshot(value, depth = 0) {
+  if (depth > 64) throw fail('INVALID_REVIEW_ARTIFACT');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'object' || ![Object.prototype, Array.prototype, null].includes(Object.getPrototypeOf(value))) throw fail('INVALID_REVIEW_ARTIFACT');
+  const result = Array.isArray(value) ? [] : Object.create(null);
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (Array.isArray(value) && key === 'length') continue;
+    if (!descriptor.enumerable) continue;
+    if (!('value' in descriptor) || descriptor.value === undefined) throw fail('INVALID_REVIEW_ARTIFACT');
+    Object.defineProperty(result, key, { value: snapshot(descriptor.value, depth + 1), enumerable: true, configurable: true, writable: true });
+  }
+  return result;
+}
+async function projectedRealpath(name) {
+  let current = path.resolve(name); const suffix = [];
+  for (;;) {
+    try { return path.join(await realpath(current), ...suffix); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try { if ((await lstat(current)).isSymbolicLink()) throw fail('UNSAFE_REVIEW_ARTIFACT'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+      const parent = path.dirname(current); if (parent === current) throw error;
+      suffix.unshift(path.basename(current)); current = parent;
+    }
+  }
+}
+
+// Artifacts are untrusted private evidence, never approved source or confirmed findings.
+export function createReviewArtifacts({ directory, maxArtifactBytes = 1048576, maxJobBytes = 8388608, maxArtifacts = 64 } = {}) {
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw fail('INVALID_REVIEW_ARTIFACT_DIRECTORY');
+  if (![maxArtifactBytes, maxJobBytes, maxArtifacts].every(n => Number.isSafeInteger(n) && n > 0) || maxArtifactBytes > 16777216 || maxJobBytes > 268435456 || maxArtifacts > 10000) throw fail('INVALID_REVIEW_ARTIFACT_LIMIT');
+  let canonical;
+  async function safeDirectory(owner) {
+    const [workspace, resolved] = await Promise.all([projectedRealpath(owner.cwd), projectedRealpath(directory)]);
+    if (within(workspace, resolved) || canonical !== undefined && canonical !== resolved) throw fail('UNSAFE_REVIEW_ARTIFACT');
+    await mkdir(resolved, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(directory) !== resolved) throw fail('UNSAFE_REVIEW_ARTIFACT');
+    await chmod(resolved, 0o700); canonical ??= resolved;
+    return resolved;
+  }
+  async function load(filename, jobId, owner) {
+    let handle;
+    try {
+      const stat = await lstat(filename);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > maxJobBytes + maxArtifacts * 1024 + 65536) throw fail('UNSAFE_REVIEW_ARTIFACT');
+      handle = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      const actual = await handle.stat();
+      if (!actual.isFile() || stat.ino !== actual.ino || stat.dev !== actual.dev) throw fail('UNSAFE_REVIEW_ARTIFACT');
+      const record = JSON.parse(await handle.readFile('utf8'));
+      if (record.jobId !== jobId || JSON.stringify(record.owner) !== JSON.stringify(owner)) throw fail('FOREIGN_REVIEW_ARTIFACT');
+      if (!Array.isArray(record.artifacts) || record.artifacts.length > maxArtifacts || !Number.isSafeInteger(record.retainedBytes) || record.retainedBytes < 0 || record.retainedBytes > maxJobBytes) throw fail('UNSAFE_REVIEW_ARTIFACT');
+      return record;
+    } catch (error) { if (error.code === 'ENOENT') return { jobId, owner, retainedBytes: 0, artifacts: [] }; throw error; }
+    finally { await handle?.close(); }
+  }
+  async function transaction(jobId, owner, work) {
+    if (typeof jobId !== 'string' || !UUID.test(jobId)) throw fail('INVALID_REVIEW_ARTIFACT_JOB');
+    try {
+      const root = await safeDirectory(owner), filename = path.join(root, jobId + '.json');
+      const previous = queues.get(filename) ?? Promise.resolve();
+      const next = previous.catch(() => {}).then(async () => {
+        await safeDirectory(owner);
+        const record = await load(filename, jobId, owner);
+        return work(record, filename);
+      });
+      queues.set(filename, next);
+      try { return await next; } finally { if (queues.get(filename) === next) queues.delete(filename); }
+    } catch (error) {
+      if (['INVALID_REVIEW_ARTIFACT_JOB', 'UNSAFE_REVIEW_ARTIFACT', 'FOREIGN_REVIEW_ARTIFACT'].includes(error.code)) throw fail(error.code);
+      throw fail('ARTIFACT_STORE_FAILED');
+    }
+  }
+  return {
+    async record(jobId, owner, artifact) {
+      const who = ownerIdentity(owner), value = snapshot(artifact);
+      if (!value || Array.isArray(value) || typeof value !== 'object') throw fail('INVALID_REVIEW_ARTIFACT');
+      const serialized = JSON.stringify(value), bytes = Buffer.byteLength(serialized);
+      const summary = { artifactId: randomUUID(), hash: createHash('sha256').update(serialized).digest('hex'), bytes, status: STATUSES.has(value.status) ? value.status : 'unclassified', omitted: false, recorded: true };
+      return transaction(jobId, who, async (record, filename) => {
+        if (bytes > maxArtifactBytes || record.retainedBytes + bytes > maxJobBytes || record.artifacts.length >= maxArtifacts) {
+          summary.omitted = true; summary.diagnostic = 'REVIEW_ARTIFACT_LIMIT_EXCEEDED';
+          if (record.artifacts.length >= maxArtifacts) return { ...summary, recorded: false };
+        }
+        record.artifacts.push({ ...summary, ...(summary.omitted ? {} : { artifact: value }) });
+        if (!summary.omitted) record.retainedBytes += bytes;
+        const tmp = path.join(canonical, jobId + '.' + randomUUID() + '.tmp'); let handle;
+        try {
+          handle = await open(tmp, 'wx', 0o600); await handle.writeFile(JSON.stringify(record)); await handle.sync(); await handle.close(); handle = undefined;
+          await safeDirectory(who);
+          try { const stat = await lstat(filename); if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) throw fail('UNSAFE_REVIEW_ARTIFACT'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+          await rename(tmp, filename);
+        } finally { await handle?.close(); await unlink(tmp).catch(() => {}); }
+        return { ...summary };
+      });
+    },
+    async read(jobId, owner, { offset = 0, limit = 20 } = {}) {
+      const who = ownerIdentity(owner);
+      if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw fail('INVALID_REVIEW_ARTIFACT_PAGE');
+      return transaction(jobId, who, async record => ({ jobId, totalArtifacts: record.artifacts.length, offset, limit, artifacts: record.artifacts.slice(offset, offset + limit) }));
+    },
+  };
+}

package/src/review-diagnostics.mjs

@@ -1,13 +1,20 @@
 import { REVIEW_RUNTIME } from './runtime-identity.mjs';
-const PHASES = ['business-grouping', 'risk-planning', 'primary', 'file-interaction', 'window-synthesis', 'verification'];
-const PURPOSES = ['primary-initial', 'retrieval-followup', 'budget-finalization', 'json-correction', 'business-grouping', 'risk-planning', 'window-synthesis', 'file-interaction', 'verification'];
+const PHASES = ['business-grouping', 'risk-planning', 'primary', 'group-primary', 'file-interaction', 'window-synthesis', 'verification'];
+const PURPOSES = ['primary-initial', 'retrieval-followup', 'budget-finalization', 'json-correction', 'business-grouping', 'risk-planning', 'group-primary', 'window-synthesis', 'file-interaction', 'verification'];
 const READER_FIELDS = ['calls', 'outputBytes', 'maxCalls', 'maxOutputBytes', 'remainingCalls', 'remainingOutputBytes', 'maxResultBytes'];
+const JSON_ISSUES = ['property-name', 'colon', 'separator', 'invalid-escape', 'control-character', 'unterminated-string', 'unexpected-end', 'trailing-content', 'syntax'];
+const CORRECTION_CODES = ['MODEL_INVALID_JSON', 'MODEL_INVALID_REVIEW_RESPONSE', 'MODEL_INVALID_FINDING_IDENTITY', 'MODEL_INVALID_FINDING_SEVERITY', 'MODEL_MISSING_FINDING_FIELD', 'MODEL_INVALID_ANCHOR', 'MODEL_ANCHOR_MISMATCH', 'RETRIEVAL_PROTOCOL_ERROR'];
+const LIMIT_CODES = ['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED', 'RETRIEVAL_ROUND_BUDGET_EXCEEDED'];
+const RECOVERY_KINDS = ['native-tool', 'text-compatible', 'trailing-prose'];
+const FALLBACK_REASONS = ['mode-notauto', 'smallchange', 'disabled', 'project', 'laterround', 'multi-batch', 'incomplete-edit-scope', 'input-budget'];
 const number = n => Number.isFinite(n) && n >= 0 ? Math.round(n) : null;
 // Source-free counters only; call walls overlap and include lifecycle observation.
 export function reviewDiagnostics(report, { reviewWallMs = null, executionWallMs = null } = {}) {
+  // Shared orchestration is one aggregator, not copied into each file's work.
+  const sources = [...(report.files ?? []), ...(report.orchestration ? [report.orchestration] : [])];
   const phases = [];
   for (const phase of PHASES) {
-    const rows = (report.files ?? []).map(f => f.modelMetrics?.[phase]).filter(Boolean);
+    const rows = sources.map(f => f.modelMetrics?.[phase]).filter(Boolean);
     if (!rows.length) continue;
     const sum = field => rows.every(r => number(r[field]) !== null) ? number(rows.reduce((n, r) => n + r[field], 0)) : null;
     phases.push({ phase, calls: sum('calls'), observedCallWallSumMs: sum('durationMs'), inputBytes: sum('inputBytes'), totalOutputBytes: sum('totalOutputBytes') });
@@ -15,14 +22,32 @@ export function reviewDiagnostics(report, { reviewWallMs = null, executionWallMs
   const plans = (report.files ?? []).flatMap(f => f.riskPlans ?? []);
   const observedModelCalls = phases.length && phases.every(p => p.calls !== null) ? phases.reduce((n, p) => n + p.calls, 0) : null;
   const modelCallPurposes = PURPOSES.flatMap(purpose => {
-    const values = (report.files ?? []).map(f => f.modelCallPurposes?.[purpose]).filter(value => value !== undefined);
+    const values = sources.map(f => f.modelCallPurposes?.[purpose]).filter(value => value !== undefined);
     if (!values.length) return [];
     return [{ purpose, calls: values.every(value => number(value) !== null) ? number(values.reduce((sum, value) => sum + value, 0)) : null }];
   });
   const readerBudget = Object.fromEntries(READER_FIELDS.map(field => [field, number(report.readerBudget?.[field])]));
-  return { schemaVersion: 2, pluginVersion: REVIEW_RUNTIME.version, reviewWallMs: number(reviewWallMs), executionWallMs: number(executionWallMs),
-    modelCalls: number(report.modelCalls), observedModelCalls, phases, modelCallPurposes, readerBudget,
+  const correctionCounts = new Map();
+  for (const event of sources.flatMap(f => f.modelCorrections ?? [])) {
+    if (!['explicit-json-correction', 'retrieval-protocol-correction', 'review-format-correction'].includes(event?.action) || !CORRECTION_CODES.includes(event.code)) continue;
+    const jsonIssue = JSON_ISSUES.includes(event.jsonIssue) ? event.jsonIssue : null;
+    const key = JSON.stringify([event.code, jsonIssue]);
+    correctionCounts.set(key, (correctionCounts.get(key) ?? 0) + 1);
+  }
+  const correctionReasons = [...correctionCounts].map(([key, calls]) => { const [code, jsonIssue] = JSON.parse(key); return { code, jsonIssue, calls }; }).sort((a, b) => a.code.localeCompare(b.code) || String(a.jsonIssue).localeCompare(String(b.jsonIssue)));
+  const limits = sources.flatMap(f => f.retrievalLimits ?? []);
+  const readerLimitReasons = LIMIT_CODES.flatMap(code => { const calls = limits.filter(row => row?.code === code).length; return calls ? [{ code, calls }] : []; });
+  const readerLimits = { maxRounds: number(report.readerLimits?.maxRounds ?? report.maxRetrievalRounds) };
+  const riskPlanningFallbackReasons = FALLBACK_REASONS.flatMap(reason => { const calls = (report.files ?? []).filter(f => f.riskPlanningFallbackReason === reason).length; return calls ? [{ reason, calls }] : []; });
+  const recoveryEvents = sources.flatMap(source => source.modelRecoveries ?? []);
+  const transportRecoveries = RECOVERY_KINDS.flatMap(kind => { const calls = recoveryEvents.filter(event => event?.action === 'json-transport-recovery' && event.kind === kind).length; return calls ? [{ kind, calls }] : []; });
+  const resume = { reusedFiles: number(report.resume?.reusedFiles) };
+  const artifactRecords = Array.isArray(report.artifacts) ? report.artifacts : null;
+  const artifacts = { retained: artifactRecords ? artifactRecords.filter(record => record?.omitted === false && record.recorded === true).length : null, omitted: artifactRecords ? artifactRecords.filter(record => record?.omitted === true).length : null };
+  return { schemaVersion: 2, resume, artifacts, transportRecoveries, pluginVersion: REVIEW_RUNTIME.version, reviewWallMs: number(reviewWallMs), executionWallMs: number(executionWallMs),
+    modelCalls: number(report.modelCalls), observedModelCalls, phases, modelCallPurposes, readerBudget, correctionReasons, readerLimitReasons, readerLimits, riskPlanningFallbackReasons,
     planning: { completed: plans.filter(p => p.status === 'completed' && p.method !== 'inline').length, inline: plans.filter(p => p.method === 'inline' && p.status === 'completed').length, inlineAbsent: plans.filter(p => p.method === 'inline' && p.status === 'absent').length, inlineInvalid: plans.filter(p => p.method === 'inline' && p.status === 'invalid').length, fallback: plans.filter(p => p.status === 'fallback').length, skipped: plans.filter(p => p.status === 'skipped').length },
+    callPurposeNotice: 'primary-initial is the first call of a retrieval-enabled stage, not only primary review; phase identifies the stage. Correction reason counts include actual correction invocation records only, not both failures and completion notices.',
     timingNotice: 'Observed call wall sums overlap under concurrency and include lifecycle observation; not pure provider latency. Missing values are unavailable, not zero.' };
 }
 export function diagnosticsMarkdown(d) {
@@ -35,13 +60,21 @@ export function diagnosticsMarkdown(d) {
     output.push('', '累计调用墙钟可能并发重叠，且包含生命周期观察／初始检查点等待，不是纯提供方耗时，也不能从总耗时中相减当作本地开销。');
   } else output.push('- 逐阶段模型观测不可用（未产生或旧报告未记录），不按零耗时解释。');
   if (d.modelCallPurposes?.length) {
-    const labels = { 'primary-initial': '阶段初始', 'retrieval-followup': '检索后续', 'budget-finalization': '预算受限最终答复', 'json-correction': 'JSON纠正', 'business-grouping': '业务分组', 'risk-planning': '风险计划', 'window-synthesis': '窗口综合', 'file-interaction': '跨文件综合', verification: '复核' };
+    const labels = { 'primary-initial': '阶段初始', 'retrieval-followup': '检索后续', 'budget-finalization': '预算受限最终答复', 'json-correction': 'JSON纠正', 'business-grouping': '业务分组', 'risk-planning': '风险计划', 'group-primary': '分组主审', 'window-synthesis': '窗口综合', 'file-interaction': '跨文件综合', verification: '复核' };
     output.push('- 调用目的：' + d.modelCallPurposes.filter(row => PURPOSES.includes(row.purpose)).map(row => labels[row.purpose] + ' ' + (number(row.calls) ?? '不可用')).join('；') + '。');
   }
   if (d.readerBudget && READER_FIELDS.some(field => number(d.readerBudget[field]) !== null)) {
     const n = field => number(d.readerBudget[field]) ?? '不可用';
     output.push('- 共享读取预算：调用 ' + n('calls') + '/' + n('maxCalls') + '，序列化输出字节 ' + n('outputBytes') + '/' + n('maxOutputBytes') + '；剩余调用 ' + n('remainingCalls') + '，剩余输出字节 ' + n('remainingOutputBytes') + '。');
   }
+  if (d.correctionReasons?.length) output.push('- 纠正原因（仅实际纠正调用，不重复计失败／完成通知）：' + d.correctionReasons.filter(r => CORRECTION_CODES.includes(r.code)).map(r => r.code + (JSON_ISSUES.includes(r.jsonIssue) ? '/' + r.jsonIssue : '') + ' ' + (number(r.calls) ?? '不可用')).join('；') + '。');
+  if (d.readerLimitReasons?.length) output.push('- 读取限制原因：' + d.readerLimitReasons.filter(r => LIMIT_CODES.includes(r.code)).map(r => r.code + ' ' + (number(r.calls) ?? '不可用')).join('；') + '。');
+  if (number(d.readerLimits?.maxRounds) !== null) output.push('- 每阶段最大检索轮次：' + number(d.readerLimits.maxRounds) + '；调用数／输出字节耗尽与轮次耗尽分别记录，不能混同。');
+  if (d.riskPlanningFallbackReasons?.length) output.push('- 风险策略回退原因：' + d.riskPlanningFallbackReasons.filter(r => FALLBACK_REASONS.includes(r.reason)).map(r => r.reason + ' ' + (number(r.calls) ?? '不可用')).join('；') + '。');
+  if (d.transportRecoveries?.length) output.push('- 本地结果传输：' + d.transportRecoveries.filter(row => RECOVERY_KINDS.includes(row.kind)).map(row => row.kind + ' ' + (number(row.calls) ?? '不可用')).join('；') + '；仅计成功解析的传输事件，不表示额外模型调用或缺陷确认。');
+  if (number(d.resume?.reusedFiles) !== null) output.push('- 续审复用已完成文件：' + number(d.resume.reusedFiles) + '；复用成果不计为本次模型调用或新读取证据。');
+  if (number(d.artifacts?.retained) !== null || number(d.artifacts?.omitted) !== null) output.push('- 私有模型工件：已留存 ' + (number(d.artifacts.retained) ?? '不可用') + '，未留存 ' + (number(d.artifacts.omitted) ?? '不可用') + '；诊断仅含计数，不包含正文或访问标识。');
+  output.push('- primary-initial 表示启用检索的某阶段初始调用，不仅是主审；具体阶段以阶段统计为准。');
   output.push('- 风险计划：完成 ' + d.planning.completed + '，回退 ' + d.planning.fallback + '，跳过 ' + d.planning.skipped + '；合并主审问题 ' + (d.planning.inline ?? 0) + '，缺失 ' + (d.planning.inlineAbsent ?? 0) + '，无效 ' + (d.planning.inlineInvalid ?? 0) + '（非独立规划）。');
   return output;
 }

package/src/review-jobs.mjs

@@ -1,3 +1,4 @@
+import {createReviewArtifacts} from './review-artifacts.mjs';
 import {jobProgress} from './job-progress.mjs';
 import {recoveryCoverage} from './recovery-coverage.mjs';
 import {randomUUID} from 'node:crypto';
@@ -7,6 +8,7 @@ import path from 'node:path';
 // Report storage is host-owned, never inside a reviewed working copy.
 export function createReviewJobs({directory}={}){
  if(typeof directory!=='string'||!path.isAbsolute(directory))throw new Error('Absolute host report directory required');
+ const artifacts=createReviewArtifacts({directory:path.join(directory,'artifacts')});
  const jobs=new Map(),listeners=new Map();const changed=id=>{for(const fn of [...(listeners.get(id)??[])])fn();};let disposed=false,canonicalDirectory;
  const identity=exec=>{const a=exec?.agent,s=a?.session;if(!s||!a.options?.provider||!a.options?.model||!s.header?.cwd)throw new Error('Review job requires session identity');const id=s.header.id??s.id;if(typeof id!=='string'||!id)throw new Error('Durable session id required');return {sessionId:id,cwd:s.header.cwd,provider:a.options.provider,model:a.options.model,reasoningEffort:a.options.reasoningEffort??null};};
  const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
@@ -59,7 +61,7 @@ export function createReviewJobs({directory}={}){
      controller.signal.throwIfAborted();
      job.record.status='running';await enqueue(()=>save(job));
      controller.signal.throwIfAborted();
-     const result=await work({signal:controller.signal,checkpoint:async value=>enqueue(async()=>{job.record.stage=value.stage??'reviewing';job.record.checkpoints.push(structuredClone(value));await save(job);})});
+     const result=await work({signal:controller.signal,artifact:async value=>{const ref=await artifacts.record(id,job.record.owner,value);await enqueue(async()=>{(job.record.artifacts??=[]).push(ref);await save(job);});return ref;},saveResumeState:async value=>enqueue(async()=>{job.record.resumeState=structuredClone(value);await save(job);}),checkpoint:async value=>enqueue(async()=>{job.record.stage=value.stage??'reviewing';job.record.checkpoints.push(structuredClone(value));await save(job);})});
      job.record.result=result;job.record.status=controller.signal.aborted?'cancelled':'completed';
     }catch(error){job.record.status=controller.signal.aborted?'cancelled':'failed';job.record.error=error?.message??String(error);}
     finally{
@@ -74,7 +76,9 @@ export function createReviewJobs({directory}={}){
    await startup;
    return {jobId:id,status:job.record.status,waitRevision:job.savedRevision,progress:jobProgress(job.record),nextAction:'Call code_review_wait with waitFor=terminal until terminal status; reuse the returned waitRevision as after without guessing increments. No code_review_status call is needed after each event. Do not finish the user request at start.',notice:'Background job accepted; start is not a completed review. Explicit cancel or plugin disposal stops it.'};
   },
-  async status(id,exec,page){const r=structuredClone(await owned(id,exec)),active=jobs.get(id);if(active&&!active.settled&&!['queued','running'].includes(r.status)){r.status='running';r.stage='finalizing';delete r.result;delete r.finishedAt;}r.recovery=recoveryCoverage(r);r.progress=jobProgress(r);r.waitRevision=jobs.get(id)?.savedRevision??r.checkpoints.length;r.nextAction=['queued','running'].includes(r.status)?'Call code_review_wait with waitFor=terminal; reuse the exact returned waitRevision as after, never guess increments. No code_review_status call is needed after each event. Do not end the user request while task runs.':r.result?.previewId?'Show preview and request user confirmation before execute.':'Collect final report and unfinished scope, then provide one final answer.';if(!page)return r;const {offset=0,limit=20,checkpointIndex}=page;if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(limit)||limit<1||limit>100)throw new Error('Invalid result page');if(checkpointIndex!==undefined){if(!Number.isSafeInteger(checkpointIndex)||checkpointIndex<0||checkpointIndex>=r.checkpoints.length)throw new Error('Invalid checkpoint index');return {jobId:r.jobId,status:r.status,waitRevision:r.waitRevision,progress:r.progress,nextAction:r.nextAction,checkpointIndex,checkpoint:pageCheckpoint(r.checkpoints[checkpointIndex],offset,limit),page:{offset,limit}};}const result=r.result;const report=result?.report;return {...r,result:undefined,recovery:{...r.recovery,unfinishedStages:r.recovery.unfinishedStages.slice(offset,offset+limit),files:r.recovery.files.slice(offset,offset+limit),windows:r.recovery.windows.slice(offset,offset+limit),suggestedPaths:r.recovery.suggestedPaths.slice(offset,offset+limit),totalObservedFiles:r.recovery.files.length},checkpoints:r.checkpoints.slice(offset,offset+limit).map(c=>pageCheckpoint(c,0,limit)),checkpointPage:{offset,limit,total:r.checkpoints.length},...(result?{resultSummary:report?{status:report.status,coverage:report.coverage,model:report.model,snapshotId:report.snapshotId,diagnostics:report.diagnostics,execution:report.execution,modelCalls:report.modelCalls}:({...result,files:result.files?.slice(offset,offset+limit),filePage:result.files?{offset,limit,total:result.files.length}:undefined}),resultPage:report?{files:report.files?.slice(offset,offset+limit),findings:report.findings?.slice(offset,offset+limit),totalFiles:report.files?.length,totalFindings:report.findings?.length}:undefined}: {})};},
+  async resume(id,exec){const r=await owned(id,exec);if(jobs.get(id)&&!jobs.get(id).settled||['queued','running'].includes(r.status)||!r.resumeState)throw new Error('No terminal completed-chain resume state available');return structuredClone(r.resumeState);},
+  async artifacts(id,exec,page){const r=await owned(id,exec);return artifacts.read(id,r.owner,page);},
+  async status(id,exec,page){const r=structuredClone(await owned(id,exec));delete r.resumeState;const active=jobs.get(id);if(active&&!active.settled&&!['queued','running'].includes(r.status)){r.status='running';r.stage='finalizing';delete r.result;delete r.finishedAt;}r.recovery=recoveryCoverage(r);r.progress=jobProgress(r);r.waitRevision=jobs.get(id)?.savedRevision??r.checkpoints.length;r.nextAction=['queued','running'].includes(r.status)?'Call code_review_wait with waitFor=terminal; reuse the exact returned waitRevision as after, never guess increments. No code_review_status call is needed after each event. Do not end the user request while task runs.':r.result?.previewId?'Show preview and request user confirmation before execute.':'Collect final report and unfinished scope, then provide one final answer.';if(!page)return r;const {offset=0,limit=20,checkpointIndex}=page;if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(limit)||limit<1||limit>100)throw new Error('Invalid result page');if(checkpointIndex!==undefined){if(!Number.isSafeInteger(checkpointIndex)||checkpointIndex<0||checkpointIndex>=r.checkpoints.length)throw new Error('Invalid checkpoint index');return {jobId:r.jobId,status:r.status,waitRevision:r.waitRevision,progress:r.progress,nextAction:r.nextAction,checkpointIndex,checkpoint:pageCheckpoint(r.checkpoints[checkpointIndex],offset,limit),page:{offset,limit}};}const result=r.result;const report=result?.report;return {...r,result:undefined,recovery:{...r.recovery,unfinishedStages:r.recovery.unfinishedStages.slice(offset,offset+limit),files:r.recovery.files.slice(offset,offset+limit),windows:r.recovery.windows.slice(offset,offset+limit),suggestedPaths:r.recovery.suggestedPaths.slice(offset,offset+limit),totalObservedFiles:r.recovery.files.length},checkpoints:r.checkpoints.slice(offset,offset+limit).map(c=>pageCheckpoint(c,0,limit)),checkpointPage:{offset,limit,total:r.checkpoints.length},...(result?{resultSummary:report?{status:report.status,coverage:report.coverage,model:report.model,snapshotId:report.snapshotId,diagnostics:report.diagnostics,execution:report.execution,modelCalls:report.modelCalls}:({...result,files:result.files?.slice(offset,offset+limit),filePage:result.files?{offset,limit,total:result.files.length}:undefined}),resultPage:report?{files:report.files?.slice(offset,offset+limit),findings:report.findings?.slice(offset,offset+limit),totalFiles:report.files?.length,totalFindings:report.findings?.length}:undefined}: {})};},
   async wait(id,exec,{after,waitFor='progress',timeoutMs=60000,signal}={}){
    const r=await owned(id,exec);
    if(!Number.isSafeInteger(timeoutMs)||timeoutMs<1||timeoutMs>60000)throw new Error('Invalid wait duration');

package/src/review-resume.mjs

@@ -0,0 +1,53 @@
+import { hash } from './content.mjs';
+import { validateBusinessGroups } from './business-groups.mjs';
+
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().filter(key => value[key] !== undefined).map(key => [key, canonical(value[key])])) : value;
+const digest = value => hash(JSON.stringify(canonical(value)));
+const safeFile = file => !file?.stageFailures?.length && !file?.reviewPasses?.some(pass => pass.status !== 'completed') && !file?.windowCoverage?.pending?.length && file?.status === 'completed' && file.resumeEligible === true && !file.retrievalLimited && (!file.synthesisStatus || file.synthesisStatus === 'completed') && (!file.verificationStatus || !['pending', 'failed'].includes(file.verificationStatus));
+
+// Host-private, schema-versioned completed-chain state. A previous result grants
+// neither source authority nor model approval. Exact whole-snapshot binding is
+// deliberately conservative: any changed context/rule/source invalidates reuse.
+export function buildResumeState(snapshot, options, report) {
+  if (typeof snapshot?.id !== 'string' || !Array.isArray(snapshot.files) || !report || !Array.isArray(report.files) || !Array.isArray(report.findings)) throw new Error('Invalid resume checkpoint');
+  const approved = new Map(snapshot.files.filter(file => file.eligibility === 'reviewable').map(file => [file.id, file]));
+  const completed = [];
+  for (const state of report.files) {
+    const file = approved.get(state.fileId);
+    if (!file || file.path !== state.path || !safeFile(state)) continue;
+    if (completed.some(item => item.fileId === file.id)) throw new Error('Duplicate resume file');
+    const findings = report.findings.filter(finding => finding.fileId === file.id);
+    if (findings.some(finding => finding.verification?.status !== 'completed') || (report.interactions ?? []).some(item => item.fileIds?.includes(file.id) && item.status !== 'completed')) continue;
+    completed.push({ fileId: file.id, path: file.path, state: structuredClone(state), findings: structuredClone(findings), limitations: structuredClone((report.limitations ?? []).filter(item => item.fileId === file.id)) });
+  }
+  let businessGrouping;
+  if (report.businessGrouping?.groups) {
+    validateBusinessGroups({ groups: report.businessGrouping.groups.map(group => ({ fileIds: group.fileIds, reason: group.reason })) }, snapshot.files);
+    businessGrouping = structuredClone(report.businessGrouping);
+  }
+  const interactions = structuredClone((report.interactions ?? []).filter(item => Array.isArray(item.fileIds) && item.fileIds.length && item.status === 'completed' && item.fileIds.every(id => completed.some(row => row.fileId === id))));
+  const identity = digest({ snapshot, options });
+  const result = { schemaVersion: 1, snapshotId: snapshot.id, identityHash: identity, completed, ...(businessGrouping ? { businessGrouping } : {}), interactions };
+  if (Buffer.byteLength(JSON.stringify(result)) > 8 * 1024 * 1024) throw new Error('Resume checkpoint exceeds storage limit');
+  return result;
+}
+
+export function validateResumeState(value, snapshot, options) {
+  if (!value || value.schemaVersion !== 1 || value.snapshotId !== snapshot?.id || value.identityHash !== digest({ snapshot, options }) || !Array.isArray(value.completed) || value.completed.length > snapshot.files.length) throw new Error('Resume identity mismatch; capture a fresh independent review');
+  const seen = new Set();
+  for (const item of value.completed) {
+    const source = snapshot.files.find(file => file.id === item?.fileId && file.path === item.path && file.eligibility === 'reviewable');
+    if (!source || seen.has(item.fileId) || !safeFile(item.state) || item.state.fileId !== item.fileId || item.state.path !== item.path || !Array.isArray(item.findings) || item.findings.some(finding => finding?.fileId !== item.fileId || finding.verification?.status !== 'completed') || !Array.isArray(item.limitations) || item.limitations.some(item => item?.fileId !== source.id)) throw new Error('Invalid completed resume chain');
+    seen.add(item.fileId);
+  }
+  if (value.businessGrouping !== undefined) {
+    if (!Array.isArray(value.businessGrouping?.groups)) throw new Error('Invalid resume business partition');
+    validateBusinessGroups({ groups: value.businessGrouping.groups.map(group => ({ fileIds: group.fileIds, reason: group.reason })) }, snapshot.files);
+  }
+  if (!Array.isArray(value.interactions) || value.interactions.some(item => !Array.isArray(item?.fileIds) || !item.fileIds.length || item.status !== 'completed' || item.fileIds.some(id => !seen.has(id)))) throw new Error('Invalid resume interactions');
+  return structuredClone(value);
+}
+
+export function resumePreview(state, sourceJobId) {
+  return { sourceJobId, reusableFiles: state.completed.length, fileIds: state.completed.map(item => item.fileId), notice: 'Only exact-identity completed file chains are reusable. Pending/interrupted stages run again; old findings retain prior-run provenance, not fresh model evidence. Fresh preview confirmation and model authorization are still required.' };
+}