@feng0531/dsh-code-review 0.83.1 → 0.85.0

package/src/git.mjs

@@ -2,6 +2,7 @@ import { isSecretPath } from './secret-path.mjs';
 import { realpath } from 'node:fs/promises';
 import { run, checked } from './process.mjs';
 import { hash, decode, readLocal, relativePath } from './content.mjs';
+import { changeScope } from './git-change-scope.mjs';
 
 const flags = ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false'];
 const STATUS_ARGS = ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'];
@@ -38,6 +39,29 @@ function parseChanges(bytes) {
   return changes;
 }
 
+/** Keep only the entries the requested comparison actually observes. */
+function changesInScope(changes, scope) {
+  if (scope === 'worktree') return changes;
+  if (scope === 'staged') return changes.filter(change => change.rawStatus[0] !== ' ' && change.rawStatus[0] !== '?');
+  return changes.filter(change => change.rawStatus[1] !== ' ' || change.rawStatus === '??');
+}
+
+/** Report only the status column this scope observes so identity follows the compared sides. */
+function scopeStatus(rawStatus, scope) {
+  if (scope === 'worktree') return rawStatus;
+  if (scope === 'staged') return rawStatus[0] + ' ';
+  return rawStatus === '??' ? '??' : ' ' + rawStatus[1];
+}
+
+/**
+ * Serialize one change for the snapshot. An unstaged entry compares index to worktree, so a
+ * staged rename's old path is not a side of that comparison and must not reach the model.
+ */
+function scopeEntry(change, scope) {
+  const oldPath = scope === 'unstaged' ? undefined : change.oldPath;
+  return { path: change.path, ...(oldPath ? { oldPath } : {}), rawStatus: scopeStatus(change.rawStatus, scope) };
+}
+
 /** Resolve only reviewable changed baselines; never enumerate the whole HEAD tree. */
 async function resolveBaselines(root, head, changes, selectedPaths, options, signal) {
   const base = new Map();
@@ -60,22 +84,104 @@ async function resolveBaselines(root, head, changes, selectedPaths, options, sig
   return base;
 }
 
+/**
+ * Resolve index entries for the selected paths only. Stage entries above zero mean an
+ * unresolved conflict; callers block those files instead of reading a partial side.
+ */
+async function resolveIndexEntries(root, names, options) {
+  const entries = new Map();
+  for (let i = 0; i < names.length; i += 64) {
+    const chunk = names.slice(i, i + 64);
+    const records = text(await git(root, ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', ...chunk], options)).split('\0');
+    for (const record of records) {
+      if (!record) continue;
+      const m = /^(\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([\s\S]+)$/.exec(record);
+      if (!m || !chunk.includes(m[4])) throw new Error('Invalid index entry lookup');
+      if (entries.has(m[4])) entries.set(m[4], { conflict: true });
+      else entries.set(m[4], { mode: m[1], oid: m[2], stage: m[3] });
+    }
+  }
+  return entries;
+}
+
+/** Stable identity of the index entries a capture depends on; mode and content changes are caught even when status text is unchanged. */
+function indexIdentity(entries, names) {
+  return names.map(name => {
+    const entry = entries.get(name);
+    return name + '\0' + (entry ? (entry.conflict ? 'conflict' : entry.mode + ':' + entry.oid) : '');
+  }).join('\n');
+}
+
+function assertReviewableIndexEntry(entry) {
+  if (!entry) throw new Error('Missing index baseline');
+  if (entry.conflict || entry.stage !== '0') throw new Error('Unresolved conflict');
+  if (entry.mode === '120000' || entry.mode === '160000') throw new Error('Submodule or symbolic link baseline');
+}
+
+async function readIndexBlob(root, entry, options, maxFileBytes) {
+  let bytes;
+  try {
+    bytes = await git(root, ['cat-file', 'blob', entry.oid], { ...options, maxBytes: maxFileBytes });
+  } catch (error) {
+    if (/output limit exceeded/i.test(error.message)) throw new Error('File size limit exceeded');
+    throw error;
+  }
+  return decode(bytes);
+}
+
+/** A staged deletion has no index entry; every other staged path reads its index blob. */
+async function readStagedRight(root, entry, options, maxFileBytes) {
+  if (!entry) return { right: decode(Buffer.alloc(0)), rightExists: false };
+  assertReviewableIndexEntry(entry);
+  return { right: await readIndexBlob(root, entry, options, maxFileBytes), rightExists: true };
+}
+
+/** Unstaged left side is the index entry; untracked files have no index baseline. */
+async function readUnstagedLeft(root, change, entries, options, maxFileBytes) {
+  if (change.rawStatus === '??') return decode(Buffer.alloc(0));
+  const entry = entries.get(change.path);
+  assertReviewableIndexEntry(entry);
+  return readIndexBlob(root, entry, options, maxFileBytes);
+}
+
+/** Worktree and staged captures read the same HEAD baseline; unstaged uses the index instead. */
+async function readHeadLeft(root, change, baselines, options, maxFileBytes) {
+  const previous = baselines.get(change.oldPath ?? change.path);
+  if (previous && (previous.type !== 'blob' || previous.mode === '120000')) throw new Error('Submodule or symbolic link baseline');
+  return previous ? decode(await git(root, ['cat-file', 'blob', previous.oid], { ...options, maxBytes: maxFileBytes })) : decode(Buffer.alloc(0));
+}
+
+async function readWorktreeRight(root, change, options) {
+  try {
+    return { right: await readLocal(root, change.path, options), rightExists: true };
+  } catch (error) {
+    if (error.code === 'ENOENT' && change.rawStatus.includes('D')) return { right: decode(Buffer.alloc(0)), rightExists: false };
+    throw error;
+  }
+}
+
 export async function captureGit(cwd, options = {}) {
   const { signal, selectedPaths, maxFiles = 200, maxFileBytes = 256 * 1024 } = options;
+  const scope = changeScope(options.changeScope);
   if (selectedPaths) for (const name of selectedPaths) relativePath(name);
   const root = await resolveRoot(cwd, options);
   const before = await git(root, STATUS_ARGS, options);
   const head = await resolveHead(root, options);
-  const changes = parseChanges(before);
-  if (changes.length > maxFiles) throw new Error('Change count limit exceeded; narrow repository scope');
+  const changes = changesInScope(parseChanges(before), scope);
+  const counted = changes.filter(change => change.rawStatus !== '??' || selectedPaths?.includes(change.path));
+  if (counted.length > maxFiles) throw new Error('Change count limit exceeded; narrow repository scope');
   const known = new Set(changes.map(c => c.path));
-  if (selectedPaths?.some(p => !known.has(p))) throw new Error('Selected path is not a current change');
-  const base = head ? await resolveBaselines(root, head, changes, selectedPaths, options, signal) : new Map();
+  if (selectedPaths?.some(p => !known.has(p))) throw new Error('Selected path is not a current change in the selected scope');
+  const projectedBefore = scope === 'worktree' ? null : JSON.stringify(changes.map(change => scopeEntry(change, scope)));
+  const baselines = scope !== 'unstaged' && head ? await resolveBaselines(root, head, changes, selectedPaths, options, signal) : new Map();
+  const indexNames = scope === 'worktree' ? [] : [...new Set(changes.filter(change => change.rawStatus !== '??').map(change => change.path))];
+  const indexEntries = scope === 'worktree' ? new Map() : await resolveIndexEntries(root, indexNames, options);
+  const indexBefore = indexIdentity(indexEntries, indexNames);
 
   const files = [];
   for (const change of changes) {
     signal?.throwIfAborted();
-    const item = { ...change, id: hash(change.path), eligibility: 'reviewable', properties: [] };
+    const item = { ...scopeEntry(change, scope), id: hash(change.path), eligibility: 'reviewable', properties: [] };
     files.push(item);
     if (isSecretPath(change.path) || isSecretPath(change.oldPath)) { item.eligibility = 'excluded'; item.reason = 'Credential path excluded'; continue; }
     if ((selectedPaths && !selectedPaths.includes(change.path)) || (change.rawStatus === '??' && !selectedPaths?.includes(change.path))) {
@@ -85,18 +191,14 @@ export async function captureGit(cwd, options = {}) {
       relativePath(change.path);
       if (change.oldPath) relativePath(change.oldPath);
       if (/U/.test(change.rawStatus) || ['AA', 'DD'].includes(change.rawStatus)) throw new Error('Unresolved conflict');
-      const previous = base.get(change.oldPath ?? change.path);
-      if (previous && (previous.type !== 'blob' || previous.mode === '120000')) throw new Error('Submodule or symbolic link baseline');
-      const left = previous ? await git(root, ['cat-file', 'blob', previous.oid], { ...options, maxBytes: maxFileBytes }) : Buffer.alloc(0);
-      item.left = decode(left);
-      try {
-        item.right = await readLocal(root, change.path, options);
-        item.rightExists = true;
-      } catch (error) {
-        if (error.code === 'ENOENT' && change.rawStatus.includes('D')) { item.right = decode(Buffer.alloc(0)); item.rightExists = false; }
-        else throw error;
-      }
-      if (previous && item.rightExists && item.left.hash === item.right.hash && !change.oldPath) {
+      const baselineExists = scope === 'unstaged' ? change.rawStatus !== '??' : baselines.has(change.oldPath ?? change.path);
+      item.left = scope === 'unstaged' ? await readUnstagedLeft(root, change, indexEntries, options, maxFileBytes) : await readHeadLeft(root, change, baselines, options, maxFileBytes);
+      const right = scope === 'staged'
+        ? await readStagedRight(root, change.rawStatus[0] === 'D' ? undefined : indexEntries.get(change.path), options, maxFileBytes)
+        : await readWorktreeRight(root, change, options);
+      item.right = right.right;
+      item.rightExists = right.rightExists;
+      if (baselineExists && item.rightExists && item.left.hash === item.right.hash && !item.oldPath) {
         item.eligibility = 'excluded'; item.reason = 'No net content change (mode-only changes not analyzed)';
       }
     } catch (error) {
@@ -106,18 +208,28 @@ export async function captureGit(cwd, options = {}) {
     }
   }
 
-  if (!(await git(root, STATUS_ARGS, options)).equals(before)) throw new Error('Repository changed during capture');
+  const after = await git(root, STATUS_ARGS, options);
+  const scopeUnchanged = scope === 'worktree'
+    ? after.equals(before)
+    : JSON.stringify(changesInScope(parseChanges(after), scope).map(change => scopeEntry(change, scope))) === projectedBefore;
+  if (!scopeUnchanged) throw new Error('Repository changed during capture');
   const finalHead = await run('git', [...flags, 'rev-parse', '--verify', 'HEAD'], { ...options, cwd: root });
   if ((finalHead.code === 0 ? text(finalHead.stdout).trim() : null) !== head) throw new Error('HEAD changed during capture');
-  for (const file of files.filter(f => f.right)) {
-    if (file.rightExists) {
-      if ((await readLocal(root, file.path, options)).hash !== file.right.hash) throw new Error('Content changed during capture');
-    } else {
-      try { await readLocal(root, file.path, options); }
-      catch (error) { if (error.code === 'ENOENT') continue; throw error; }
-      throw new Error('Deleted path reappeared during capture');
+  if (scope !== 'worktree') {
+    const entriesAfter = await resolveIndexEntries(root, indexNames, options);
+    if (indexIdentity(entriesAfter, indexNames) !== indexBefore) throw new Error('Index changed during capture');
+  }
+  if (scope !== 'staged') {
+    for (const file of files.filter(f => f.right)) {
+      if (file.rightExists) {
+        if ((await readLocal(root, file.path, options)).hash !== file.right.hash) throw new Error('Content changed during capture');
+      } else {
+        try { await readLocal(root, file.path, options); }
+        catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+        throw new Error('Deleted path reappeared during capture');
+      }
     }
   }
-  const snapshot = { schemaVersion: 1, vcs: 'git', root, baseline: head, files };
+  const snapshot = { schemaVersion: 1, vcs: 'git', root, baseline: head, ...(scope === 'worktree' ? {} : { changeScope: scope }), files };
   return { ...snapshot, id: hash(JSON.stringify(snapshot)) };
 }

package/src/model-contract.mjs

@@ -3,12 +3,9 @@ const VERDICT_CONTRACT = '本阶段必须返回 {"verdicts":[{"candidateId":"c1"
 const GROUPS_CONTRACT = '本阶段返回groups数组，每项含fileIds和reason，文件身份必须来自输入，不是findings响应。';
 const RISK_CONTRACT = '本阶段返回 {"risks":[]} 或原指令要求的风险条目，不是findings。';
 const INTERACTION_CONTRACT = '本阶段返回 {"findings":[],"limitations":[]}；发现必须包含原指令全部字段和跨文件interaction.editRefs。无足够跨文件证据时说明limitations，不编造。';
-const FINDINGS_CONTRACT = '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。anchor.line用side/start/end/snippet且精确匹配原行；需要更多证据可按检索协议先返回requests。';
+const FINDINGS_CONTRACT = '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。行定位写成 anchor:{kind:"line",side:"new",start:1,end:1,snippet:"逐行原文"}（仅为形状示例，不是证据）；start/end用原来源一基行号而非窗口内序号，精确匹配原行；old/new按当前阶段允许侧选择，示例不改变授权；仅当没有retrievalFinalization且仍有检索余量时，需要更多证据可按检索协议先返回requests。';
 
-export function modelContract(input, instructions = '') {
-  let p;
-  try { p = JSON.parse(input); } catch { return ''; }
-  if (!p || typeof p !== 'object' || Array.isArray(p)) return '';
+function stageContract(p, instructions) {
   if (Array.isArray(p.candidates)) return VERDICT_CONTRACT;
   if (/返回\{groups:/.test(instructions)) return GROUPS_CONTRACT;
   if (/仅制定审查计划/.test(instructions)) return RISK_CONTRACT;
@@ -16,3 +13,11 @@ export function modelContract(input, instructions = '') {
   if (p.file) return FINDINGS_CONTRACT;
   return '';
 }
+
+export function modelContract(input, instructions = '') {
+  let p;
+  try { p = JSON.parse(input); } catch { return ''; }
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return '';
+  const contract = stageContract(p, instructions);
+  return contract + (p.retrievalFinalization ? ' 本次检索已受限：只返回当前阶段最终schema，禁止requests；不能将缺证据声称为无问题或完整覆盖。' : '');
+}

package/src/model-json.mjs

@@ -1,13 +1,19 @@
 // Accept one complete JSON value, optionally inside one exact Markdown fence.
+// This parser never repairs bytes or invokes a model; orchestration owns corrections.
 export function modelJson(text) {
- const bytes=Buffer.byteLength(text);
- const trimmed=text.trim();
- const fence=/^```(?:json)?\r?\n([\s\S]*)\r?\n```$/.exec(trimmed);
- const body=fence?fence[1]:trimmed;
- try { JSON.parse(body); } catch {
-  const shape = !trimmed ? 'empty' : trimmed.startsWith('```') && !fence ? 'non-exact-fence' : /^[{\[]/.test(body) ? 'json-like-invalid' : 'non-json-leading';
-  const error=new Error('Model response is not complete JSON (bytes='+bytes+', envelope='+(fence?'json-fence':'plain')+', shape='+shape+'); no repair or retry performed');
-  error.code='MODEL_INVALID_JSON';throw error;
- }
- return body;
+  const bytes = Buffer.byteLength(text);
+  const trimmed = text.trim();
+  const fence = /^```(?:json)?\r?\n([\s\S]*)\r?\n```$/.exec(trimmed);
+  const body = fence ? fence[1] : trimmed;
+  try {
+    JSON.parse(body);
+  } catch {
+    const envelope = fence ? 'json-fence' : 'plain';
+    const shape = !trimmed ? 'empty' : trimmed.startsWith('```') && !fence ? 'non-exact-fence' : /^[{\[]/.test(body) ? 'json-like-invalid' : 'non-json-leading';
+    const error = new Error('Model response is not complete JSON (bytes=' + bytes + ', envelope=' + envelope + ', shape=' + shape + '); no repair or retry performed by JSON parser');
+    error.code = 'MODEL_INVALID_JSON';
+    error.diagnostic = { jsonBytes: bytes, envelope, shape };
+    throw error;
+  }
+  return body;
 }

package/src/primary-input.mjs

@@ -13,6 +13,7 @@ import { planWindowBatches } from './window-batches.mjs';
 import { changeWindows } from './change-windows.mjs';
 import { changeMap } from './change-map.mjs';
 import { initialInputBudget } from './input-budget.mjs';
+import { changeScopeNotice } from './git-change-scope.mjs';
 
 const CPP_FILE = /\.(?:c|cc|cpp|cxx|h|hh|hpp|hxx)$/;
 const RELATION_NOTICE = '命名和相对导入关系仅为源码线索，可能被同名局部变量遮蔽，不证明绑定、调用可达或因果；只报告主file的问题，不为relatedFiles重复生成发现。';
@@ -35,6 +36,7 @@ export function preparePrimaryInput(input, file, { instructions, scope, grouping
 
   const base = {
     ...(input.projectScope ? { projectScope: input.projectScope, reviewNotice: 'Full current-file review; empty left is a sentinel, not a historical baseline. changes are transport coordinates only, do not infer introduced regression.' } : {}),
+    ...(input.changeScope ? { changeScope: input.changeScope, changeScopeNotice: changeScopeNotice(input.changeScope) } : {}),
     ...(input.history ? { contextSideNotice: CONTEXT_SIDE_NOTICE } : {}),
     ...(input.businessRequirement !== undefined ? { businessRequirement: input.businessRequirement, requirementNotice: REQUIREMENT_NOTICE } : {}),
     defectGuidance: defectGuidance(file.path, file.rightExists === false ? file.left.text : file.right.text),

package/src/project-execution.mjs

@@ -0,0 +1,40 @@
+import { reviewSnapshot } from './review.mjs';
+
+export const DEFAULT_PROJECT_CONCURRENCY = 3;
+export function projectConcurrency(value = DEFAULT_PROJECT_CONCURRENCY) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 8) throw new Error('Project concurrency must be an integer from 1 to 8');
+  return value;
+}
+
+// Parallelize independent approved snapshots, never dependent stages within a batch.
+// Admission and the shared call reservation are synchronous; completion order is not report order.
+export async function reviewProjectBatches(batches, model, { concurrency = DEFAULT_PROJECT_CONCURRENCY, remainingCalls, signal, onProgress } = {}) {
+  projectConcurrency(concurrency);
+  if (!Array.isArray(batches) || typeof remainingCalls !== 'function') throw new Error('Invalid project execution');
+  const controller = new AbortController();
+  const batchSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  const results = new Array(batches.length);
+  let next = 0, failed = false, failure;
+  const unstarted = batch => ({ snapshotId: batch.id, status: 'partial', files: batch.files.map(f => ({ fileId: f.id, path: f.path, status: f.eligibility === 'reviewable' ? 'pending' : f.eligibility, reason: 'Session project budget exhausted or cancelled' })), findings: [], limitations: [] });
+  const worker = async () => {
+    while (!failed) {
+      const index = next++;
+      if (index >= batches.length) return;
+      const batch = batches[index];
+      try {
+        if (batchSignal.aborted || remainingCalls() <= 0) { results[index] = unstarted(batch); continue; }
+        results[index] = await reviewSnapshot(batch, model, {
+          signal: batchSignal, maxCalls: remainingCalls(), remainingCalls, enableRetrieval: true, enableVerification: true,
+          enableAnchorCorrection: true, correctProtocol: true,
+          onProgress: onProgress ? event => onProgress({ ...event, snapshotId: batch.id, batchIndex: index }) : undefined,
+        });
+      } catch (error) {
+        if (!failed) { failed = true; failure = error; controller.abort(error); }
+      }
+    }
+  };
+  // Never release service ownership while a sibling model/cleanup is still running.
+  await Promise.all(Array.from({ length: Math.min(concurrency, batches.length) }, worker));
+  if (failed) throw failure;
+  return results;
+}

package/src/project-review-service.mjs

@@ -5,10 +5,10 @@ import { hash } from './content.mjs';
 import { resolveWorkspaceRepository } from './workspace-repository.mjs';
 import { detectVcs } from './snapshot.mjs';
 import { projectInventory, captureProjectBatch } from './project-snapshot.mjs';
-import { reviewSnapshot } from './review.mjs';
+import { reviewProjectBatches, projectConcurrency as validateProjectConcurrency } from './project-execution.mjs';
 import { createDshModel } from './dsh-model.mjs';
 
-const PREVIEW_NOTICE_SUFFIX = ' Full current source audit, not regression-only diff. Shared session execution budget: no internal elapsed-time or model-call cutoff, 16MiB capture memory protection. Blocked/excluded/pending files are not reviewed successfully. No untracked/ignored/external bodies; no complete semantic call graph. Show scope and model before confirmed execute.';
+const PREVIEW_NOTICE_SUFFIX = ' Full current source audit, not regression-only diff. Shared session execution budget: no internal elapsed-time or model-call cutoff, 16MiB capture memory protection. Blocked/excluded/pending files are not reviewed successfully. No untracked/ignored/external bodies; no complete semantic call graph. Independent approved batches run with bounded concurrency; per-batch evidence and global model-call budgets remain enforced. Show scope and model before confirmed execute.';
 const REPORT_NOTICE_SUFFIX = ' Coverage counts processing of selected tracked files only, not proof of correctness. Excluded and blocked are never completed. No cross-batch whole-program semantic coverage is claimed.';
 
 function owner(exec) {
@@ -66,10 +66,11 @@ async function captureProject(cwd, args, signal) {
   return { ...result, id: hash(JSON.stringify(result)) };
 }
 
-export function createProjectReviewService(llm, { allowModelSending = false, authorize = async () => false, now = Date.now, ttlMs = 300000, maxPreviews = 8, projectMaxCalls = Number.MAX_SAFE_INTEGER } = {}) {
+export function createProjectReviewService(llm, { allowModelSending = false, authorize = async () => false, now = Date.now, ttlMs = 300000, maxPreviews = 8, projectMaxCalls = Number.MAX_SAFE_INTEGER, projectConcurrency = 3 } = {}) {
   for (const n of [ttlMs, maxPreviews]) if (!Number.isSafeInteger(n) || n < 1) throw new Error('Invalid project preview limit');
   if (!Number.isSafeInteger(projectMaxCalls) || projectMaxCalls < 1) throw new Error('Invalid project model call limit');
 
+  validateProjectConcurrency(projectConcurrency);
   const previews = new Map();
   const lifetime = new AbortController();
   let busy = false;
@@ -96,6 +97,7 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
           model: current.route, modelSendingEnabled: allowModelSending,
           totalTrackedNodes: s.totalTrackedNodes, selectedFiles: s.selectedFiles, selectionComplete: s.selectionComplete,
           inventoryComplete: s.inventoryComplete, batches: s.batches.length,
+          execution: { batchConcurrency: projectConcurrency },
           files: s.batches.flatMap(b => b.files.map(f => ({ path: f.path, eligibility: f.eligibility, reason: f.reason }))),
           notice: s.notice + PREVIEW_NOTICE_SUFFIX,
         };
@@ -127,23 +129,19 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
         let calls = 0;
         const adapter = createDshModel(llm, p.route, { correctJson: true });
         const model = request => {
-          if (calls >= projectMaxCalls) throw new Error('Shared project model call limit exceeded');
+          if (calls >= projectMaxCalls) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
           calls++;
           return adapter({ ...request, onProtocolCorrection: async info => {
-            if (calls >= projectMaxCalls) throw new Error('Shared project model call limit exceeded');
+            if (calls >= projectMaxCalls) throw Object.assign(new Error('Shared project model call limit exceeded'), { code: 'PROJECT_MODEL_CALL_LIMIT' });
             calls++;
             await request.onProtocolCorrection?.(info);
           }});
         };
 
-        const results = [];
-        for (const b of s.batches) {
-          if (signal.aborted || calls >= projectMaxCalls) {
-            results.push({ snapshotId: b.id, status: 'partial', files: b.files.map(f => ({ fileId: f.id, path: f.path, status: f.eligibility === 'reviewable' ? 'pending' : f.eligibility, reason: 'Session project budget exhausted or cancelled' })), findings: [], limitations: [] });
-            continue;
-          }
-          results.push(await reviewSnapshot(b, model, { signal, maxCalls: projectMaxCalls - calls, enableRetrieval: true, enableVerification: true, correctProtocol: true, onProgress: exec.reviewCheckpoint }));
-        }
+        const results = await reviewProjectBatches(s.batches, model, {
+          concurrency: projectConcurrency, signal, remainingCalls: () => projectMaxCalls - calls,
+          onProgress: exec.reviewCheckpoint,
+        });
 
         const files = results.flatMap(r => r.files.map(f => ({ ...f, batchSnapshotId: r.snapshotId })));
         const coverage = {
@@ -164,6 +162,7 @@ export function createProjectReviewService(llm, { allowModelSending = false, aut
           repositoryRoot: s.root, vcs: s.vcs, model: p.route, modelCalls: calls, maxModelCalls: projectMaxCalls,
           totalTrackedNodes: s.totalTrackedNodes, selectionComplete: s.selectionComplete, inventoryComplete: s.inventoryComplete,
           coverage, files, findings, batches: results,
+          execution: { batchConcurrency: projectConcurrency },
           notice: s.notice + REPORT_NOTICE_SUFFIX,
         };
 

package/src/response-correction.mjs

@@ -0,0 +1,28 @@
+// Ask for one new response; never normalize identities, severities or evidence locally.
+const GUIDANCE = {
+  MODEL_INVALID_REVIEW_RESPONSE: '返回含 findings 和 limitations 数组的当前阶段完整对象。',
+  MODEL_INVALID_FINDING_IDENTITY: 'fileId 必须原样复制本次主 file.id，不使用路径、候选编号或其他文件身份。',
+  MODEL_INVALID_FINDING_SEVERITY: 'severity 仅允许 critical、high、medium、low，不使用 P1/P2、数字或翻译标签。',
+  MODEL_MISSING_FINDING_FIELD: '每个发现必须包含非空 title/evidence/trigger/impact/suggestion。',
+  MODEL_INVALID_ANCHOR: 'anchor 必须使用当前阶段允许的 kind、side、整数 start/end 及精确 snippet。',
+  MODEL_ANCHOR_MISMATCH: 'snippet 必须逐行精确复制批准来源，start/end 是该来源的原始一基行号，不能使用展示窗口的相对行号。不得模糊匹配、改写源码或用 file anchor 隐藏定位失败。',
+};
+
+export async function correctedResponse(generate, validate, request, { enabled = false, canCorrect = () => true, onCorrection = async () => {} } = {}) {
+  const approved = { ...request };
+  const original = await generate({ ...approved });
+  try { return validate(original); } catch (error) {
+    approved.signal?.throwIfAborted();
+    if (!enabled || !Object.hasOwn(GUIDANCE, error?.code) || !canCorrect()) throw error;
+    await onCorrection({ action: 'review-response-correction', code: error.code, notice: 'Original response rejected; requesting one new response under the same approved scope and shared budgets.' });
+    approved.signal?.throwIfAborted();
+    const instructions = approved.instructions + '\n本次是一次明确的主审响应协议纠正：' + GUIDANCE[error.code] + ' 重新核对原批准源码并返回完整当前阶段 schema；不得把格式错误当成无缺陷，不得为通过校验编造证据或静默删除有证据的候选。原响应未被接受，纠正后仍需全部严格校验。';
+    // generate enforces the same input/call/reader limits and enclosing signal.
+    const response = await generate({ ...approved, instructions });
+    approved.signal?.throwIfAborted();
+    try { return validate(response); } catch (second) {
+      second.responseAttempts = [{ code: error.code }, { code: second.code ?? 'REVIEW_EXECUTION_FAILED' }];
+      throw second;
+    }
+  }
+}

package/src/retrieval-loop.mjs

@@ -1,5 +1,5 @@
 import { RETRIEVAL_INSTRUCTIONS } from './prompts.mjs';
-import { executeRetrievalBatch } from './retrieval-protocol.mjs';
+import { executeRetrievalBatch, parseRetrievalResponse } from './retrieval-protocol.mjs';
 
 export { RETRIEVAL_INSTRUCTIONS };
 
@@ -18,7 +18,7 @@ function compactFollowup(input) {
 }
 
 export function retrievalRequest(request, scope, retrieved = []) {
-  return { ...request, instructions: request.instructions + '\n' + RETRIEVAL_INSTRUCTIONS, input: JSON.stringify({ ...JSON.parse(request.input), catalog: scope.catalog(), retrieved }) };
+  return { ...request, instructions: request.instructions + '\n' + RETRIEVAL_INSTRUCTIONS + BUDGET_SUFFIX, input: JSON.stringify({ ...JSON.parse(request.input), catalog: scope.catalog(), retrieved, ...(scope.budget ? { retrievalBudget: scope.budget() } : {}) }) };
 }
 
 function recordRetrieval(operation, result, onTruncated, onRetrieved) {
@@ -34,50 +34,95 @@ function recordRetrieval(operation, result, onTruncated, onRetrieved) {
 
 const CORRECTION_SUFFIX = ' 本次是检索协议纠正：上次请求整批未执行。只返回requests数组，不带findings/limitations；read使用catalog的id和整数start/count，不用path/end。或直接返回当前阶段最终schema。不得扩大批准来源。';
 
-export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {} } = {}) {
+const BUDGET_SUFFIX = ' retrievalBudget为宿主共享检索预算的当前余量，不是新授权。每项操作消耗一次call及实际序列化输出字节；不要请求超过余量的整批操作。预算将尽请及时按本阶段schema最终答复，只引用已提供证据，证据不足须保留限制或uncertain。';
+const FINAL_SUFFIX = ' 检索预算最终答复：本次仅有一次最终schema答复机会，不得再返回requests。不得把缺证据变成无问题/已核查；只保留已提供且可严格验证的证据，其余说明限制或uncertain。不增加reader、模型调用、输入或超时预算。';
+const budgetFailure = error => ['READER_CALL_BUDGET_EXCEEDED', 'READER_OUTPUT_BUDGET_EXCEEDED', 'RETRIEVAL_ROUND_BUDGET_EXCEEDED'].includes(error?.code);
+
+function roundBudgetError() {
+  const error = new Error('Retrieval round budget exceeded');
+  error.code = 'RETRIEVAL_ROUND_BUDGET_EXCEEDED';
+  return error;
+}
+
+export async function retrievalLoop(model, request, scope, { correctProtocol = false, maxRounds = Number.MAX_SAFE_INTEGER, maxInputBytes = 96 * 1024, beforeCall = () => {}, onTruncated = () => {}, onRetrieved = () => {}, onBudgetLimited = () => {} } = {}) {
   if (!Number.isSafeInteger(maxRounds) || maxRounds < 0 || !Number.isSafeInteger(maxInputBytes) || maxInputBytes < 1) throw new Error('Invalid retrieval loop budget');
   const retrieved = [];
-  let protocolCorrection;
+  let protocolCorrection, finalization;
+  const finalize = async error => {
+    finalization = { code: error.code, reason: error.message, ...(scope.budget ? { budget: scope.budget() } : {}) };
+    await onBudgetLimited(finalization);
+    await request.onProtocolEvent?.({ action: 'retrieval-budget-finalization', ...finalization });
+  };
+  const checkExhausted = async round => {
+    const budget = scope.budget?.();
+    if (!finalization && budget && (budget.remainingCalls === 0 || budget.remainingOutputBytes === 0)) {
+      const error = new Error(budget.remainingCalls === 0 ? 'Reader call budget exceeded' : 'Reader output budget exceeded');
+      error.code = budget.remainingCalls === 0 ? 'READER_CALL_BUDGET_EXCEEDED' : 'READER_OUTPUT_BUDGET_EXCEEDED';
+      await finalize(error);
+    } else if (!finalization && round >= maxRounds) await finalize(roundBudgetError());
+  };
+  const nextRequest = records => {
+    const next = retrievalRequest(request, scope, records);
+    if (finalization) next.input = JSON.stringify({ ...JSON.parse(next.input), retrievalFinalization: finalization });
+    next.instructions += (protocolCorrection ? CORRECTION_SUFFIX : '') + (finalization ? FINAL_SUFFIX : '');
+    return next;
+  };
   for (let round = 0; ; round++) {
     request.signal?.throwIfAborted();
-    let { input, instructions: baseInstructions } = retrievalRequest(request, scope, retrieved);
-    const instructions = baseInstructions + (protocolCorrection ? CORRECTION_SUFFIX : '');
+    await checkExhausted(round);
+    let { input, instructions } = nextRequest(retrieved);
     if (correctProtocol && retrieved.length && Buffer.byteLength(input) + Buffer.byteLength(instructions) > maxInputBytes) input = compactFollowup(input);
     if (Buffer.byteLength(input) + Buffer.byteLength(instructions) > maxInputBytes) throw new Error('Retrieval input budget exceeded');
+    request.signal?.throwIfAborted();
     beforeCall();
+    request.signal?.throwIfAborted();
     const response = await model({ ...request, instructions, input });
     request.signal?.throwIfAborted();
     const serialized = typeof response === 'string' ? response : JSON.stringify(response);
     if (typeof serialized !== 'string' || Buffer.byteLength(serialized) > 128 * 1024) throw new Error('Retrieval response too large');
     const parsed = JSON.parse(serialized);
     if (!parsed || !Object.hasOwn(parsed, 'requests')) return parsed;
-    if (round >= maxRounds) throw new Error('Retrieval round budget exceeded');
+    // Schema and authorization remain hard failures, including on the final turn.
+    // Preflight all dynamic ranges and aggregate budgets before any capability.
     let batch;
     try {
-      batch = executeRetrievalBatch(parsed, scope, request.signal, ({ request: operation, result }) => recordRetrieval(operation, result, onTruncated, onRetrieved));
+      const operations = parseRetrievalResponse(parsed);
+      const allowed = new Set(scope.catalog().map(item => item.id));
+      if (operations.some(r => r.kind === 'read' ? !allowed.has(r.id) : r.sourceIds?.some(id => !allowed.has(id)))) throw new Error('Source not authorized');
+      if (finalization) {
+        const error = new Error(finalization.reason + '; final response required, no further retrieval permitted');
+        error.code = 'RETRIEVAL_FINAL_RESPONSE_REQUIRED';
+        throw error;
+      }
+      scope.preflight?.(operations);
+      const execute = () => executeRetrievalBatch(parsed, scope, request.signal);
+      batch = scope.transaction ? scope.transaction(execute) : execute();
     } catch (error) {
       request.signal?.throwIfAborted();
-      if (!correctProtocol || protocolCorrection || !(/Invalid retrieval batch|Invalid read request|Invalid search request|Invalid find request/.test(error.message))) throw error;
+      if (!finalization && budgetFailure(error)) { await finalize(error); continue; }
+      if (finalization || !correctProtocol || protocolCorrection || !(/Invalid retrieval batch|Invalid read request|Invalid search request|Invalid find request|Invalid line range|Line range outside source/.test(error.message))) throw error;
       protocolCorrection = { code: error.code ?? 'MODEL_INVALID_RETRIEVAL' };
       await request.onProtocolEvent?.({ action: 'retrieval-protocol-correction', code: protocolCorrection.code });
       continue;
     }
+    for (const item of batch) recordRetrieval(item.request, item.result, onTruncated, onRetrieved);
+    await checkExhausted(round + 1);
     for (const item of batch) {
       let candidate = [...retrieved, item];
-      let next = retrievalRequest(request, scope, candidate);
+      let next = nextRequest(candidate);
       if (correctProtocol) {
         while (retrieved.length && Buffer.byteLength(compactFollowup(next.input)) + Buffer.byteLength(next.instructions) > maxInputBytes) {
           retrieved.shift();
           await request.onProtocolEvent?.({ action: 'prior-retrieval-deferred', notice: 'Prior returned fragment no longer in current prompt; reread approved source for evidence.' });
           candidate = [...retrieved, item];
-          next = retrievalRequest(request, scope, candidate);
+          next = nextRequest(candidate);
         }
       }
       let fits = Buffer.byteLength(next.input) + Buffer.byteLength(next.instructions) <= maxInputBytes;
       if (correctProtocol && !fits) fits = Buffer.byteLength(compactFollowup(next.input)) + Buffer.byteLength(next.instructions) <= maxInputBytes;
       if (correctProtocol && !fits) {
         const omitted = { request: item.request, result: { omitted: true, reason: 'Result omitted: request fewer lines/matches; no body or receipt provided.' } };
-        const minimal = retrievalRequest(request, scope, [...retrieved, omitted]);
+        const minimal = nextRequest([...retrieved, omitted]);
         if (Buffer.byteLength(compactFollowup(minimal.input)) + Buffer.byteLength(minimal.instructions) > maxInputBytes) throw new Error('Retrieval input metadata exceeds model capacity');
         retrieved.push(omitted);
         await request.onProtocolEvent?.({ action: 'oversized-retrieval-omitted', kind: item.request.kind });