@feng0531/dsh-code-review 0.83.0 → 0.84.0

package/src/primary-input.mjs

@@ -1,5 +1,5 @@
-import {sourceSegments} from './source-segments.mjs';
-import {changeRegion} from './change-region.mjs';
+import { sourceSegments } from './source-segments.mjs';
+import { changeRegion } from './change-region.mjs';
 import { CONTEXT_SIDE_NOTICE } from './context-identity.mjs';
 import { approvedCallerBindings } from './caller-binding-input.mjs';
 import { REQUIREMENT_NOTICE } from './business-requirement.mjs';
@@ -13,45 +13,88 @@ 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重复生成发现。';
+const optional = h => h.confidence === 'namespace-member-syntax-only' || h.confidence === 'instance-method-syntax-only';
 
 // Pure preparation over already captured data. No model calls or new reads.
 export function preparePrimaryInput(input, file, { instructions, scope, grouping, maxInputBytes }) {
   let changes = changeMap(file.left.text, file.right.text);
-  if(changes.status==='limited'){const region=changeRegion(file.left.text,file.right.text);if(region.status==='changed')changes={status:'changed',precision:'envelope',reason:'Exact diff unavailable; broad region includes potentially unchanged lines, not exact edits or causal proof.',edits:[{id:'envelope1',old:region.old,new:region.new}],hunks:[{id:'envelope-h1',old:region.old,new:region.new,editIds:['envelope1']}]};}
-  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.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), snapshotId: input.id, file, changes, context: input.context ?? [], rules: input.rules ?? [] };
+  if (changes.status === 'limited') {
+    const region = changeRegion(file.left.text, file.right.text);
+    if (region.status === 'changed') {
+      changes = {
+        status: 'changed', precision: 'envelope',
+        reason: 'Exact diff unavailable; broad region includes potentially unchanged lines, not exact edits or causal proof.',
+        edits: [{ id: 'envelope1', old: region.old, new: region.new }],
+        hunks: [{ id: 'envelope-h1', old: region.old, new: region.new, editIds: ['envelope1'] }],
+      };
+    }
+  }
+
+  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),
+    snapshotId: input.id,
+    file,
+    changes,
+    context: input.context ?? [],
+    rules: input.rules ?? [],
+  };
+
   const contextRelations = inferContextRelations(input, file);
   if (contextRelations.length) {
     base.contextRelations = contextRelations;
     base.contextRelationNotice = '导入/include/命名与调用位置仅为语法线索；可能被宏、构建搜索路径或同名局部变量影响，不证明绑定、可达性或因果。context.text为批准当前/目标侧文本；仅明确oldText/oldRevision字段是历史旧侧，禁止互换。';
   }
-  if (/\.(?:c|cc|cpp|cxx|h|hh|hpp|hxx)$/.test(file.path)) {
-    const calls = ['old','new'].flatMap(side => cppCallSites((side === 'old' ? file.left : file.right).text).map(site => ({ ...site, side })));
-    if (calls.length) { base.cppCallSites = calls; base.cppCallNotice = '最多20条零参语法位置/侧，仅导航子集；不表示全部调用覆盖，不证明宏展开、重载选择、动态分派或执行顺序。其他源码须在批准范围内读取。'; }
+
+  if (CPP_FILE.test(file.path)) {
+    const calls = ['old', 'new'].flatMap(side => cppCallSites((side === 'old' ? file.left : file.right).text).map(site => ({ ...site, side })));
+    if (calls.length) {
+      base.cppCallSites = calls;
+      base.cppCallNotice = '最多20条零参语法位置/侧，仅导航子集；不表示全部调用覆盖，不证明宏展开、重载选择、动态分派或执行顺序。其他源码须在批准范围内读取。';
+    }
   }
+
   const csharpHints = inferCsharpContext(input, file);
-  if (csharpHints.length) { base.csharpContextHints = csharpHints; base.csharpContextNotice = '仅批准context的C#静态类型/方法语法位置；历史输入按contextSide/contextVersion区分正文，无旧正文不回退目标侧。不证明语义绑定或执行可达。歧义不推定，线索不增加审查覆盖。'; }
+  if (csharpHints.length) {
+    base.csharpContextHints = csharpHints;
+    base.csharpContextNotice = '仅批准context的C#静态类型/方法语法位置；历史输入按contextSide/contextVersion区分正文，无旧正文不回退目标侧。不证明语义绑定或执行可达。歧义不推定，线索不增加审查覆盖。';
+  }
+
   if (input.callerDiscovery) {
     const callerBindings = approvedCallerBindings(input, file);
-    if (callerBindings.length) { base.callerBindings = callerBindings; base.callerBindingNotice = '调用方文件的导入行、调用行与目标声明行仅为语法位置线索，来源限于已批准上下文；历史side/revision要求调用方与目标声明同版本，缺侧不回退。仅导航，窗口中的原文须按相应版本catalog读取；不证明执行可达、动态分派、重载选择或完整调用覆盖，也不代表全部调用方。'; }
+    if (callerBindings.length) {
+      base.callerBindings = callerBindings;
+      base.callerBindingNotice = '调用方文件的导入行、调用行与目标声明行仅为语法位置线索，来源限于已批准上下文；历史side/revision要求调用方与目标声明同版本，缺侧不回退。仅导航，窗口中的原文须按相应版本catalog读取；不证明执行可达、动态分派、重载选择或完整调用覆盖，也不代表全部调用方。';
+    }
   }
+
   let payload = JSON.stringify(base);
   const measure = value => initialInputBudget({ instructions, input: value }, scope, maxInputBytes);
   const metadata = {};
-  const optional = h => h.confidence === 'namespace-member-syntax-only' || h.confidence === 'instance-method-syntax-only';
+
   // Optional member navigation must not block source review or force extra windows.
-  if (base.contextRelations?.some(e=>e.bindingHints?.some(optional)) && !measure(payload).fits) {
+  if (base.contextRelations?.some(e => e.bindingHints?.some(optional)) && !measure(payload).fits) {
     metadata.optionalBindingFallback = 'input-budget';
-    metadata.omittedOptionalBindingCount = base.contextRelations.reduce((n,e)=>n+(e.bindingHints??[]).filter(optional).length,0);
-    base.contextRelations = base.contextRelations.map(e=>({...e,bindingHints:(e.bindingHints??[]).filter(h=>!optional(h))}));
+    metadata.omittedOptionalBindingCount = base.contextRelations.reduce((n, e) => n + (e.bindingHints ?? []).filter(optional).length, 0);
+    base.contextRelations = base.contextRelations.map(e => ({ ...e, bindingHints: (e.bindingHints ?? []).filter(h => !optional(h)) }));
     payload = JSON.stringify(base);
   }
   // Optional navigation must not block source review or force extra windows.
   if (base.callerBindings?.length && !measure(payload).fits) {
     metadata.callerBindingFallback = 'input-budget';
-    metadata.omittedCallerBindingCount = base.callerBindings.reduce((count,c)=>count+c.bindings.length,0);
-    delete base.callerBindings; delete base.callerBindingNotice;
+    metadata.omittedCallerBindingCount = base.callerBindings.reduce((count, c) => count + c.bindings.length, 0);
+    delete base.callerBindings;
+    delete base.callerBindingNotice;
     payload = JSON.stringify(base);
   }
+
   let batches, synthesis;
   const group = grouping?.groups.find(g => g.fileIds.includes(file.id));
   if (group) {
@@ -59,32 +102,48 @@ export function preparePrimaryInput(input, file, { instructions, scope, grouping
     const relatedFiles = input.files.filter(f => f.id !== file.id && f.eligibility === 'reviewable' && group.fileIds.includes(f.id));
     if (relatedFiles.length) {
       const relations = grouping.links.filter(link => !link.split && group.fileIds.includes(link.from) && group.fileIds.includes(link.to));
-      const bindingRelations = inferImportRelations(input.files).filter(edge => (edge.bindingHints?.length || edge.definitionHints?.length) && (edge.from === file.id || edge.to === file.id) && group.fileIds.includes(edge.from) && group.fileIds.includes(edge.to)).map(({ from, to, side, bindingHints, definitionHints }) => ({ from, to, side, bindingHints, ...(definitionHints?.length ? { definitionHints } : {}) }));
-      const grouped = JSON.stringify({ ...base, relatedFiles, relations, bindingRelations, relationNotice: '命名和相对导入关系仅为源码线索，可能被同名局部变量遮蔽，不证明绑定、调用可达或因果；只报告主file的问题，不为relatedFiles重复生成发现。' });
-      if (measure(grouped).fits) { payload = grouped; metadata.relatedFileIds = relatedFiles.map(f => f.id); }
-      else {
+      const bindingRelations = inferImportRelations(input.files)
+        .filter(edge => (edge.bindingHints?.length || edge.definitionHints?.length) && (edge.from === file.id || edge.to === file.id) && group.fileIds.includes(edge.from) && group.fileIds.includes(edge.to))
+        .map(({ from, to, side, bindingHints, definitionHints }) => ({ from, to, side, bindingHints, ...(definitionHints?.length ? { definitionHints } : {}) }));
+      const grouped = JSON.stringify({ ...base, relatedFiles, relations, bindingRelations, relationNotice: RELATION_NOTICE });
+      if (measure(grouped).fits) {
+        payload = grouped;
+        metadata.relatedFileIds = relatedFiles.map(f => f.id);
+      } else {
         // Optional member hints must not cost the grouped related sources either.
         const groupedOmitted = bindingRelations.reduce((n, e) => n + (e.bindingHints ?? []).filter(optional).length, 0);
         const trimmedRelations = bindingRelations.map(e => ({ ...e, bindingHints: (e.bindingHints ?? []).filter(h => !optional(h)) })).filter(e => e.bindingHints.length || e.definitionHints?.length);
-        const trimmed = JSON.stringify({ ...base, relatedFiles, relations, bindingRelations: trimmedRelations, relationNotice: '命名和相对导入关系仅为源码线索，可能被同名局部变量遮蔽，不证明绑定、调用可达或因果；只报告主file的问题，不为relatedFiles重复生成发现。' });
-        if (groupedOmitted && measure(trimmed).fits) { payload = trimmed; metadata.relatedFileIds = relatedFiles.map(f => f.id); metadata.optionalBindingFallback = 'input-budget'; metadata.omittedOptionalBindingCount = (metadata.omittedOptionalBindingCount ?? 0) + groupedOmitted; }
-        else metadata.groupFallback = 'input-budget';
+        const trimmed = JSON.stringify({ ...base, relatedFiles, relations, bindingRelations: trimmedRelations, relationNotice: RELATION_NOTICE });
+        if (groupedOmitted && measure(trimmed).fits) {
+          payload = trimmed;
+          metadata.relatedFileIds = relatedFiles.map(f => f.id);
+          metadata.optionalBindingFallback = 'input-budget';
+          metadata.omittedOptionalBindingCount = (metadata.omittedOptionalBindingCount ?? 0) + groupedOmitted;
+        } else {
+          metadata.groupFallback = 'input-budget';
+        }
       }
     }
   }
+
   if (!measure(payload).fits && scope) {
-    const exactWindows=changeWindows(file,changes);
-    const windows=exactWindows?sourceSegments(exactWindows):null;
+    const exactWindows = changeWindows(file, changes);
+    const windows = exactWindows ? sourceSegments(exactWindows) : null;
     if (windows) {
       const compactFile = { ...file, left: { ...file.left, text: undefined }, right: { ...file.right, text: undefined } };
       const contextCatalog = scope.catalog().filter(source => ['context', 'context-old'].includes(source.side));
       if (contextCatalog.length) metadata.contextMode = 'approved-retrieval';
       const windowBase = { ...base };
       if (base.cppCallSites?.length) {
-        windowBase.cppCallSites = base.cppCallSites.map(({line,expression,side})=>({line,expression,side}));
+        windowBase.cppCallSites = base.cppCallSites.map(({ line, expression, side }) => ({ line, expression, side }));
         windowBase.cppCallNotice = '最多40条旧/新侧零参语法导航；统一confidence=syntax-only-unresolved，可能为宏/重载/动态分派，无绑定、可达性或顺序保证，不是证据或完整覆盖。原文仍须按批准catalog读取。';
       }
-      const compact = JSON.stringify({ ...windowBase, context: [], contextCatalog, contextMode: 'approved-retrieval', contextNotice: '上下文全文仍在同一批准快照，仅目录进入窗口初始输入；必须按sourceId和版本侧read原文，不把目录视为证据或完整覆盖。', file: compactFile, windows, sourceMode: 'change-windows', windowNotice: '窗口可能为精确hunk的分段或粗粒度包络，精度以changes.precision为准；片段两侧不保证行对齐，不以片段证明精确编辑或回归因果。start/count为原始源码行号，不得重编号。完整源码未随初始输入发送，可在catalog批准范围内检索；缺少上下文时说明限制。' });
+      const compact = JSON.stringify({
+        ...windowBase, context: [], contextCatalog, contextMode: 'approved-retrieval',
+        contextNotice: '上下文全文仍在同一批准快照，仅目录进入窗口初始输入；必须按sourceId和版本侧read原文，不把目录视为证据或完整覆盖。',
+        file: compactFile, windows, sourceMode: 'change-windows',
+        windowNotice: '窗口可能为精确hunk的分段或粗粒度包络，精度以changes.precision为准；片段两侧不保证行对齐，不以片段证明精确编辑或回归因果。start/count为原始源码行号，不得重编号。完整源码未随初始输入发送，可在catalog批准范围内检索；缺少上下文时说明限制。',
+      });
       if (!measure(compact).fits) {
         const envelope = JSON.parse(compact);
         const plan = planWindowBatches(windows, subset => JSON.stringify({ ...envelope, windows: subset, windowNotice: '本批仅审查windows包含的编辑，其他hunk另批；行号为原始行号，跨片段上下文不足说明限制。' }), measure);
@@ -105,11 +164,13 @@ export function preparePrimaryInput(input, file, { instructions, scope, grouping
       }
     }
   }
+
   if (batches?.length > 1) {
     synthesis = prepareWindowSynthesis(batches.map(batch => batch.payload), measure);
     metadata.synthesisStatus = synthesis.budget.fits ? 'ready' : 'input-blocked';
     metadata.synthesisInputBytes = synthesis.budget.bytes;
   }
+
   const budget = measure(payload);
   return { changes, payload, batches, synthesis, budget, metadata: { ...metadata, initialInputBytes: budget.bytes } };
 }

package/src/project-report.mjs

@@ -1,6 +1,23 @@
-import {markdownReport} from './review.mjs';
-export function renderProjectReport(report){
- const seen=new Set(),findings=[];for(const f of report.findings??[]){const key=JSON.stringify([f.path,f.anchor,f.title,f.evidence]);if(!seen.has(key)){seen.add(key);findings.push(f);}}
- const merged={...report,findings,interactions:(report.batches??[]).flatMap(b=>b.interactions??[]),limitations:(report.batches??[]).flatMap(b=>b.limitations??[])};
- return markdownReport(merged).replace('# Code Review 报告','# 全项目代码审查报告')+'\n\n总体范围：'+report.coverage.completed+'/'+report.coverage.total+' 个文件完成主审；排除 '+report.coverage.excluded+'，阻断 '+report.coverage.blocked+'，未完成 '+report.coverage.pending+'。综合未完成项单独列出；主审完成不等于审核通过。'+(report.outdated?'\n注意：来源已变化或无法复核，仅对应原批准快照。':'');
+import { markdownReport } from './review.mjs';
+
+function dedupeFindings(findings) {
+  const seen = new Set();
+  const result = [];
+  for (const f of findings ?? []) {
+    const key = JSON.stringify([f.path, f.anchor, f.title, f.evidence]);
+    if (!seen.has(key)) { seen.add(key); result.push(f); }
+  }
+  return result;
+}
+
+export function renderProjectReport(report) {
+  const merged = {
+    ...report,
+    findings: dedupeFindings(report.findings),
+    interactions: (report.batches ?? []).flatMap(b => b.interactions ?? []),
+    limitations: (report.batches ?? []).flatMap(b => b.limitations ?? []),
+  };
+  const scope = '总体范围：' + report.coverage.completed + '/' + report.coverage.total + ' 个文件完成主审；排除 ' + report.coverage.excluded + '，阻断 ' + report.coverage.blocked + '，未完成 ' + report.coverage.pending + '。综合未完成项单独列出；主审完成不等于审核通过。';
+  const outdated = report.outdated ? '\n注意：来源已变化或无法复核，仅对应原批准快照。' : '';
+  return markdownReport(merged).replace('# Code Review 报告', '# 全项目代码审查报告') + '\n\n' + scope + outdated;
 }

package/src/project-review-service.mjs

@@ -1,38 +1,178 @@
-import {renderProjectReport} from './project-report.mjs';
-import {realpath} from 'node:fs/promises';
-import {randomUUID} from 'node:crypto';
-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,markdownReport} from './review.mjs';
-import {createDshModel} from './dsh-model.mjs';
-const owner=exec=>{const a=exec?.agent;if(!a?.session?.header?.cwd||!a.options?.provider||!a.options?.model)throw new Error('Active Agent with cwd and model required');return {agent:a,cwd:a.session.header.cwd,route:{provider:a.options.provider,model:a.options.model,...(a.options.reasoningEffort?{reasoningEffort:a.options.reasoningEffort}:{})}};};
-export function createProjectReviewService(llm,{allowModelSending=false,authorize=async()=>false,now=Date.now,ttlMs=300000,maxPreviews=8,projectMaxCalls=Number.MAX_SAFE_INTEGER}={}){
- 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');
- const previews=new Map(),lifetime=new AbortController();let busy=false;
- async function capture(cwd,args,signal){
-  let commands=0,metadataBytes=0;const captureBudget={signal,reserve(){signal.throwIfAborted();commands++;},charge(size){metadataBytes+=size;if(metadataBytes>8*1024*1024)throw Object.assign(new Error('Project shared metadata budget exceeded'),{code:'PROJECT_CAPTURE_BUDGET'});}};
-  const captureOptions={signal,svnCaptureBudget:captureBudget};
-  const root=await realpath(await resolveWorkspaceRepository(cwd,args.repositoryPath)),vcs=await detectVcs(root),inventory=await projectInventory(root,vcs,captureOptions);
-  let paths=inventory.records.map(r=>r.path);if(args.selectedPaths!==undefined){if(!Array.isArray(args.selectedPaths)||args.selectedPaths.length>1000||new Set(args.selectedPaths).size!==args.selectedPaths.length||args.selectedPaths.some(p=>!paths.includes(p)))throw new Error('Invalid tracked project selection');paths=paths.filter(p=>args.selectedPaths.includes(p));}
-  if(paths.length>1000)throw new Error('Project exceeds 1000 tracked nodes; explicitly select a bounded file set instead of claiming full review');
-  const batches=[];let bytes=0;for(let i=0;i<paths.length;i+=12){const s=await captureProjectBatch(inventory,paths.slice(i,i+12),captureOptions);bytes+=Buffer.byteLength(JSON.stringify(s));if(bytes>16*1024*1024)throw new Error('Project capture exceeds shared 16MiB limit; select fewer files');batches.push(s);}
-  const verified=await projectInventory(root,vcs,captureOptions);if(verified.id!==inventory.id)throw new Error('Project inventory changed during capture');
-  for(const b of batches)if((await captureProjectBatch(verified,b.files.map(f=>f.path),captureOptions)).id!==b.id)throw new Error('Project source changed during capture');
-  const result={root,vcs,inventoryId:inventory.id,inventoryComplete:inventory.vcs==='git',totalTrackedNodes:inventory.records.length,selectedFiles:paths.length,selectionComplete:paths.length===inventory.records.length,notice:inventory.notice,batches};return {...result,id:hash(JSON.stringify(result))};
- }
- const signalFor=exec=>AbortSignal.any([lifetime.signal,...(exec.signal?[exec.signal]:[])]);
- return {owns:id=>previews.has(id),
-  async preview(args,exec){if(busy)throw new Error('Review service busy');if(!args||typeof args!=='object')throw new Error('Project preview parameters required');if(Object.keys(args).some(k=>!['reviewMode','repositoryPath','selectedPaths'].includes(k))||args.reviewMode!=='project')throw new Error('Project mode supports only reviewMode/repositoryPath/selectedPaths; change/history context parameters are not project parameters');const current=owner(exec);busy=true;try{const s=await capture(current.cwd,args,signalFor(exec));for(const [id,p]of previews)if(p.expires<=now())previews.delete(id);while(previews.size>=maxPreviews)previews.delete(previews.keys().next().value);const previewId=randomUUID();previews.set(previewId,{...current,args:structuredClone(args),snapshotId:s.id,expires:now()+ttlMs});return {previewId,snapshotId:s.id,reviewMode:'project',repositoryRoot:s.root,vcs:s.vcs,model:current.route,modelSendingEnabled:allowModelSending,totalTrackedNodes:s.totalTrackedNodes,selectedFiles:s.selectedFiles,selectionComplete:s.selectionComplete,inventoryComplete:s.inventoryComplete,batches:s.batches.length,files:s.batches.flatMap(b=>b.files.map(f=>({path:f.path,eligibility:f.eligibility,reason:f.reason}))),notice:s.notice+' 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.'};}finally{busy=false;}},
-  async execute(args,exec){if(busy)throw new Error('Review service busy');if(!allowModelSending)throw new Error('Model sending disabled');if(args.confirmed!==true||typeof args.previewId!=='string'||Object.keys(args).some(k=>!['previewId','confirmed'].includes(k)))throw new Error('Confirmed preview required');const p=previews.get(args.previewId),current=owner(exec);if(!p||p.expires<=now()||p.agent!==current.agent||p.cwd!==current.cwd||JSON.stringify(p.route)!==JSON.stringify(current.route))throw new Error('Preview missing expired or owner/model/directory changed');previews.delete(args.previewId);busy=true;const signal=signalFor(exec);try{const s=await capture(current.cwd,p.args,signal);if(s.id!==p.snapshotId)throw new Error('Project changed since preview');if(await authorize({snapshot:s,route:p.route,exec})!==true)throw new Error('Model sending denied');if(owner(exec).cwd!==p.cwd||JSON.stringify(owner(exec).route)!==JSON.stringify(p.route))throw new Error('Agent changed during approval');signal.throwIfAborted();
-   await exec.reviewCheckpoint?.({stage:'approved-manifest',snapshotId:s.id,files:s.batches.flatMap(b=>b.files.map(f=>({fileId:f.id,path:f.path,status:f.eligibility==='reviewable'?'pending':f.eligibility})))});
-   let calls=0;const adapter=createDshModel(llm,p.route,{correctJson:true}),model=request=>{if(calls>=projectMaxCalls)throw new Error('Shared project model call limit exceeded');calls++;return adapter({...request,onProtocolCorrection:async info=>{if(calls>=projectMaxCalls)throw new Error('Shared project model call limit exceeded');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 files=results.flatMap(r=>r.files.map(f=>({...f,batchSnapshotId:r.snapshotId}))),coverage={total:s.selectedFiles,completed:files.filter(f=>f.status==='completed').length,excluded:files.filter(f=>f.status==='excluded').length,blocked:files.filter(f=>f.status==='blocked').length,pending:files.filter(f=>!['completed','excluded','blocked'].includes(f.status)).length};const findings=results.flatMap(r=>r.findings.map(f=>({...f,batchSnapshotId:r.snapshotId})));const report={schemaVersion:1,mode:'project',snapshotId:s.id,status:signal.aborted?'cancelled':coverage.total===0||coverage.completed===0?'partial':results.every(r=>r.status==='completed')&&files.every(f=>['completed','excluded'].includes(f.status))?'completed':'partial',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,notice:s.notice+' 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.'};
-   try{report.outdated=(await capture(current.cwd,p.args,signal)).id!==s.id;}catch{report.outdated=true;}
-   return {report,markdown:renderProjectReport(report)};
-  }finally{busy=false;}},dispose(){lifetime.abort();previews.clear();}
- };
+import { renderProjectReport } from './project-report.mjs';
+import { realpath } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+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 { 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 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) {
+  const a = exec?.agent;
+  if (!a?.session?.header?.cwd || !a.options?.provider || !a.options?.model) throw new Error('Active Agent with cwd and model required');
+  return { agent: a, cwd: a.session.header.cwd, route: { provider: a.options.provider, model: a.options.model, ...(a.options.reasoningEffort ? { reasoningEffort: a.options.reasoningEffort } : {}) } };
+}
+
+function makeCaptureBudget(signal) {
+  let commands = 0, metadataBytes = 0;
+  return {
+    signal,
+    reserve() { signal.throwIfAborted(); commands++; },
+    charge(size) {
+      metadataBytes += size;
+      if (metadataBytes > 8 * 1024 * 1024) throw Object.assign(new Error('Project shared metadata budget exceeded'), { code: 'PROJECT_CAPTURE_BUDGET' });
+    },
+  };
+}
+
+async function captureProject(cwd, args, signal) {
+  const captureBudget = makeCaptureBudget(signal);
+  const captureOptions = { signal, svnCaptureBudget: captureBudget };
+  const root = await realpath(await resolveWorkspaceRepository(cwd, args.repositoryPath));
+  const vcs = await detectVcs(root);
+  const inventory = await projectInventory(root, vcs, captureOptions);
+
+  let paths = inventory.records.map(record => record.path);
+  if (args.selectedPaths !== undefined) {
+    if (!Array.isArray(args.selectedPaths) || args.selectedPaths.length > 1000 || new Set(args.selectedPaths).size !== args.selectedPaths.length || args.selectedPaths.some(p => !paths.includes(p))) throw new Error('Invalid tracked project selection');
+    paths = paths.filter(p => args.selectedPaths.includes(p));
+  }
+  if (paths.length > 1000) throw new Error('Project exceeds 1000 tracked nodes; explicitly select a bounded file set instead of claiming full review');
+
+  const batches = [];
+  let bytes = 0;
+  for (let i = 0; i < paths.length; i += 12) {
+    const batch = await captureProjectBatch(inventory, paths.slice(i, i + 12), captureOptions);
+    bytes += Buffer.byteLength(JSON.stringify(batch));
+    if (bytes > 16 * 1024 * 1024) throw new Error('Project capture exceeds shared 16MiB limit; select fewer files');
+    batches.push(batch);
+  }
+
+  const verified = await projectInventory(root, vcs, captureOptions);
+  if (verified.id !== inventory.id) throw new Error('Project inventory changed during capture');
+  for (const b of batches) {
+    if ((await captureProjectBatch(verified, b.files.map(f => f.path), captureOptions)).id !== b.id) throw new Error('Project source changed during capture');
+  }
+
+  const result = {
+    root, vcs, inventoryId: inventory.id, inventoryComplete: inventory.vcs === 'git',
+    totalTrackedNodes: inventory.records.length, selectedFiles: paths.length,
+    selectionComplete: paths.length === inventory.records.length, notice: inventory.notice, batches,
+  };
+  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 } = {}) {
+  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');
+
+  const previews = new Map();
+  const lifetime = new AbortController();
+  let busy = false;
+
+  const signalFor = exec => AbortSignal.any([lifetime.signal, ...(exec.signal ? [exec.signal] : [])]);
+
+  return {
+    owns: id => previews.has(id),
+
+    async preview(args, exec) {
+      if (busy) throw new Error('Review service busy');
+      if (!args || typeof args !== 'object') throw new Error('Project preview parameters required');
+      if (Object.keys(args).some(k => !['reviewMode', 'repositoryPath', 'selectedPaths'].includes(k)) || args.reviewMode !== 'project') throw new Error('Project mode supports only reviewMode/repositoryPath/selectedPaths; change/history context parameters are not project parameters');
+      const current = owner(exec);
+      busy = true;
+      try {
+        const s = await captureProject(current.cwd, args, signalFor(exec));
+        for (const [id, p] of previews) if (p.expires <= now()) previews.delete(id);
+        while (previews.size >= maxPreviews) previews.delete(previews.keys().next().value);
+        const previewId = randomUUID();
+        previews.set(previewId, { ...current, args: structuredClone(args), snapshotId: s.id, expires: now() + ttlMs });
+        return {
+          previewId, snapshotId: s.id, reviewMode: 'project', repositoryRoot: s.root, vcs: s.vcs,
+          model: current.route, modelSendingEnabled: allowModelSending,
+          totalTrackedNodes: s.totalTrackedNodes, selectedFiles: s.selectedFiles, selectionComplete: s.selectionComplete,
+          inventoryComplete: s.inventoryComplete, batches: s.batches.length,
+          files: s.batches.flatMap(b => b.files.map(f => ({ path: f.path, eligibility: f.eligibility, reason: f.reason }))),
+          notice: s.notice + PREVIEW_NOTICE_SUFFIX,
+        };
+      } finally { busy = false; }
+    },
+
+    async execute(args, exec) {
+      if (busy) throw new Error('Review service busy');
+      if (!allowModelSending) throw new Error('Model sending disabled');
+      if (args.confirmed !== true || typeof args.previewId !== 'string' || Object.keys(args).some(k => !['previewId', 'confirmed'].includes(k))) throw new Error('Confirmed preview required');
+      const p = previews.get(args.previewId);
+      const current = owner(exec);
+      if (!p || p.expires <= now() || p.agent !== current.agent || p.cwd !== current.cwd || JSON.stringify(p.route) !== JSON.stringify(current.route)) throw new Error('Preview missing expired or owner/model/directory changed');
+      previews.delete(args.previewId);
+      busy = true;
+      const signal = signalFor(exec);
+      try {
+        const s = await captureProject(current.cwd, p.args, signal);
+        if (s.id !== p.snapshotId) throw new Error('Project changed since preview');
+        if (await authorize({ snapshot: s, route: p.route, exec }) !== true) throw new Error('Model sending denied');
+        if (owner(exec).cwd !== p.cwd || JSON.stringify(owner(exec).route) !== JSON.stringify(p.route)) throw new Error('Agent changed during approval');
+        signal.throwIfAborted();
+
+        await exec.reviewCheckpoint?.({
+          stage: 'approved-manifest', snapshotId: s.id,
+          files: s.batches.flatMap(b => b.files.map(f => ({ fileId: f.id, path: f.path, status: f.eligibility === 'reviewable' ? 'pending' : f.eligibility }))),
+        });
+
+        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');
+          calls++;
+          return adapter({ ...request, onProtocolCorrection: async info => {
+            if (calls >= projectMaxCalls) throw new Error('Shared project model call limit exceeded');
+            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 files = results.flatMap(r => r.files.map(f => ({ ...f, batchSnapshotId: r.snapshotId })));
+        const coverage = {
+          total: s.selectedFiles,
+          completed: files.filter(f => f.status === 'completed').length,
+          excluded: files.filter(f => f.status === 'excluded').length,
+          blocked: files.filter(f => f.status === 'blocked').length,
+          pending: files.filter(f => !['completed', 'excluded', 'blocked'].includes(f.status)).length,
+        };
+        const findings = results.flatMap(r => r.findings.map(f => ({ ...f, batchSnapshotId: r.snapshotId })));
+
+        const report = {
+          schemaVersion: 1, mode: 'project', snapshotId: s.id,
+          status: signal.aborted ? 'cancelled'
+            : coverage.total === 0 || coverage.completed === 0 ? 'partial'
+            : results.every(r => r.status === 'completed') && files.every(f => ['completed', 'excluded'].includes(f.status)) ? 'completed'
+            : 'partial',
+          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,
+          notice: s.notice + REPORT_NOTICE_SUFFIX,
+        };
+
+        try { report.outdated = (await captureProject(current.cwd, p.args, signal)).id !== s.id; }
+        catch { report.outdated = true; }
+        return { report, markdown: renderProjectReport(report) };
+      } finally { busy = false; }
+    },
+
+    dispose() { lifetime.abort(); previews.clear(); },
+  };
 }

package/src/project-snapshot.mjs

@@ -1,45 +1,106 @@
-import {realpath,lstat} from 'node:fs/promises';
+import { realpath, lstat } from 'node:fs/promises';
 import path from 'node:path';
-import {checked} from './process.mjs';
-import {hash,decode,readLocal,relativePath} from './content.mjs';
-import {isSecretPath} from './secret-path.mjs';
-import {xml} from './svn.mjs';
-import {svnCallerNode} from './svn-caller-node.mjs';
+import { checked } from './process.mjs';
+import { hash, decode, readLocal, relativePath } from './content.mjs';
+import { isSecretPath } from './secret-path.mjs';
+import { xml } from './svn.mjs';
+import { svnCallerNode } from './svn-caller-node.mjs';
 
-const canonical=v=>Array.isArray(v)?v.map(canonical):v&&typeof v==='object'?Object.fromEntries(Object.keys(v).sort().map(k=>[k,canonical(v[k])])):v;
-const text=b=>new TextDecoder('utf-8',{fatal:true}).decode(b);
-export async function projectInventory(cwd,vcs,options={}){
- const root=await realpath(cwd),signal=options.signal;let records=[],identity;
- if(vcs==='git'){
-  const args=['--no-optional-locks','-c','core.fsmonitor=false','-c','core.untrackedCache=false'];
-  const actual=text(await checked('git',[...args,'rev-parse','--show-toplevel'],{...options,cwd:root,signal})).trim();if(await realpath(actual)!==root)throw new Error('Full project requires explicit repository root');
-  const index=await checked('git',[...args,'ls-files','--stage','-z'],{...options,cwd:root,signal,maxBytes:2*1024*1024});
-  for(const row of text(index).split(String.fromCharCode(0)).filter(Boolean)){const m=/^(\d{6}) ([a-f0-9]+) ([0-3])\t([\s\S]+)$/.exec(row);if(!m)throw new Error('Invalid full-project Git index');records.push({path:relativePath(m[4]),kind:m[1],stage:m[3],indexOid:m[2]});}
-  identity={indexHash:hash(index)};
- }else if(vcs==='svn'){
-  const info=xml(await checked('svn',['--non-interactive','info','--xml','--','.@'],{...options,cwd:root,signal})).info?.entry?.[0];
-  if(!info||await realpath(info['wc-info']?.['wcroot-abspath'])!==root)throw new Error('Full project requires SVN working-copy root');
-  const status=await checked('svn',['--non-interactive','status','--xml','--verbose','--ignore-externals','--','.@'],{...options,cwd:root,signal,maxBytes:2*1024*1024});
-  for(const e of xml(status).status?.target?.flatMap(t=>t.entry??[])??[]){const p=e['@_path'].replaceAll('\\','/');if(p==='.')continue;const state=e['wc-status'];if(['unversioned','ignored'].includes(state?.['@_item']))continue;records.push({path:relativePath(p),state});}
-  identity={repositoryUuid:info.repository?.uuid,url:info.url,statusHash:hash(JSON.stringify(records.map(r=>({path:r.path,state:Object.fromEntries(Object.entries(r.state??{}).sort())})).sort((a,b)=>a.path.localeCompare(b.path)))),depth:info['wc-info']?.depth??null};
- }else throw new Error('Unsupported project VCS');
- if(records.length>10000)throw new Error('Full-project inventory exceeds 10000 tracked nodes; select a smaller explicit scope');
- records.sort((a,b)=>a.path.localeCompare(b.path));const grouped=new Map();for(const r of records){if(grouped.has(r.path)){grouped.get(r.path).duplicate=true;}else grouped.set(r.path,r);}records=[...grouped.values()];
- const inventory={root,vcs,records,identity,notice:'Tracked current working files only, including unchanged files. Not a historical diff, not untracked or ignored files, not external/submodule contents. Sparse SVN inventory is observed local scope only.'};
- return {...inventory,id:hash(JSON.stringify(canonical(inventory)))};
+const canonical = v => Array.isArray(v) ? v.map(canonical) : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map(k => [k, canonical(v[k])])) : v;
+const text = b => new TextDecoder('utf-8', { fatal: true }).decode(b);
+
+const INVENTORY_NOTICE = 'Tracked current working files only, including unchanged files. Not a historical diff, not untracked or ignored files, not external/submodule contents. Sparse SVN inventory is observed local scope only.';
+
+async function inventoryGit(root, options) {
+  const args = ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false'];
+  const actual = text(await checked('git', [...args, 'rev-parse', '--show-toplevel'], { ...options, cwd: root })).trim();
+  if (await realpath(actual) !== root) throw new Error('Full project requires explicit repository root');
+  const index = await checked('git', [...args, 'ls-files', '--stage', '-z'], { ...options, cwd: root, maxBytes: 2 * 1024 * 1024 });
+  const records = [];
+  for (const row of text(index).split(String.fromCharCode(0)).filter(Boolean)) {
+    const m = /^(\d{6}) ([a-f0-9]+) ([0-3])\t([\s\S]+)$/.exec(row);
+    if (!m) throw new Error('Invalid full-project Git index');
+    records.push({ path: relativePath(m[4]), kind: m[1], stage: m[3], indexOid: m[2] });
+  }
+  return { records, identity: { indexHash: hash(index) } };
+}
+
+async function inventorySvn(root, options) {
+  const info = xml(await checked('svn', ['--non-interactive', 'info', '--xml', '--', '.@'], { ...options, cwd: root })).info?.entry?.[0];
+  if (!info || await realpath(info['wc-info']?.['wcroot-abspath']) !== root) throw new Error('Full project requires SVN working-copy root');
+  const status = await checked('svn', ['--non-interactive', 'status', '--xml', '--verbose', '--ignore-externals', '--', '.@'], { ...options, cwd: root, maxBytes: 2 * 1024 * 1024 });
+  const records = [];
+  for (const e of xml(status).status?.target?.flatMap(t => t.entry ?? []) ?? []) {
+    const p = e['@_path'].replaceAll('\\', '/');
+    if (p === '.') continue;
+    const state = e['wc-status'];
+    if (['unversioned', 'ignored'].includes(state?.['@_item'])) continue;
+    records.push({ path: relativePath(p), state });
+  }
+  const identity = {
+    repositoryUuid: info.repository?.uuid,
+    url: info.url,
+    statusHash: hash(JSON.stringify(records.map(r => ({ path: r.path, state: Object.fromEntries(Object.entries(r.state ?? {}).sort()) })).sort((a, b) => a.path.localeCompare(b.path)))),
+    depth: info['wc-info']?.depth ?? null,
+  };
+  return { records, identity };
+}
+
+export async function projectInventory(cwd, vcs, options = {}) {
+  const root = await realpath(cwd);
+  const source = vcs === 'git' ? await inventoryGit(root, options)
+    : vcs === 'svn' ? await inventorySvn(root, options)
+    : null;
+  if (!source) throw new Error('Unsupported project VCS');
+  let records = source.records;
+  if (records.length > 10000) throw new Error('Full-project inventory exceeds 10000 tracked nodes; select a smaller explicit scope');
+  records.sort((a, b) => a.path.localeCompare(b.path));
+  const grouped = new Map();
+  for (const r of records) { if (grouped.has(r.path)) { grouped.get(r.path).duplicate = true; } else grouped.set(r.path, r); }
+  records = [...grouped.values()];
+  const inventory = { root, vcs, records, identity: source.identity, notice: INVENTORY_NOTICE };
+  return { ...inventory, id: hash(JSON.stringify(canonical(inventory))) };
+}
+
+async function bindProjectSource(inventory, record, name, file, options) {
+  if (inventory.vcs === 'git') {
+    if (record.stage !== '0' || !['100644', '100755'].includes(record.kind) || record.duplicate) throw new Error('Conflicted, linked or submodule Git source excluded');
+    file.projectSource = { ...record };
+    return;
+  }
+  const state = record.state;
+  if (!['normal', 'modified', 'added'].includes(state?.['@_item']) || !['none', 'normal', 'modified'].includes(state['@_props']) || ['@_switched', '@_file-external', '@_tree-conflicted', '@_copied'].some(k => state[k] === 'true')) throw new Error('Unsafe full SVN project source state');
+  const node = await svnCallerNode(inventory.root, name, { ...options, allowProjectCurrent: true });
+  file.projectSource = { revision: node.revision, nodeFingerprint: node.fingerprint, repositoryUuid: inventory.identity.repositoryUuid };
 }
 
-export async function captureProjectBatch(inventory,paths,options={}){
- if(!Array.isArray(paths)||paths.length>200||new Set(paths).size!==paths.length)throw new Error('Invalid project batch');
- const files=[];let bytes=0;
- for(const name of paths){const record=inventory.records.find(r=>r.path===name);if(!record)throw new Error('Project file outside inventory');const f={id:hash(name),path:name,kind:'file',rawStatus:'project-current',rightExists:true,eligibility:'reviewable',properties:[],reviewMode:'project',contentNotice:'Full current-file review. Empty left side is a transport sentinel, NOT an actual empty baseline or a newly added file; review existing defects in current source, do not infer introduced regression.'};files.push(f);
-  if(isSecretPath(name)){f.eligibility='excluded';f.reason='Credential path excluded';continue;}
-  try{const stat=await lstat(path.join(inventory.root,name));if(stat.isDirectory()){f.eligibility='excluded';f.reason='Directory metadata is inventory only';continue;}if(stat.isSymbolicLink()||!stat.isFile())throw new Error('Linked or nonregular project source excluded');
-   if(inventory.vcs==='git'){if(record.stage!=='0'||!['100644','100755'].includes(record.kind)||record.duplicate)throw new Error('Conflicted, linked or submodule Git source excluded');f.projectSource={...record};}
-   else{const state=record.state;if(!['normal','modified','added'].includes(state?.['@_item'])||!['none','normal','modified'].includes(state['@_props'])||['@_switched','@_file-external','@_tree-conflicted','@_copied'].some(k=>state[k]==='true'))throw new Error('Unsafe full SVN project source state');const node=await svnCallerNode(inventory.root,name,{...options,allowProjectCurrent:true});f.projectSource={revision:node.revision,nodeFingerprint:node.fingerprint,repositoryUuid:inventory.identity.repositoryUuid};}
-   f.left=decode(Buffer.alloc(0));f.right=await readLocal(inventory.root,name,options);bytes+=f.right.bytes;if(bytes>4*1024*1024)throw new Error('Project batch exceeds shared 4MiB source limit');
-  }catch(error){options.signal?.throwIfAborted();if(error.code==='PROJECT_CAPTURE_BUDGET'||/exceeds shared/.test(error.message))throw error;f.eligibility='blocked';f.reason=error.message;delete f.left;delete f.right;}
- }
- const scope={mode:'project',inventoryId:inventory.id,totalTrackedNodes:inventory.records.length,batchPaths:paths,untrackedIncluded:false,inventoryComplete:inventory.vcs==='git',scopeCompleteness:inventory.vcs==='svn'?'observed-working-copy-only':'tracked-index-only',notice:inventory.notice};
- const snapshot={schemaVersion:1,vcs:inventory.vcs,root:inventory.root,files,context:[],projectScope:scope};return {...snapshot,id:hash(JSON.stringify(snapshot))};
+export async function captureProjectBatch(inventory, paths, options = {}) {
+  if (!Array.isArray(paths) || paths.length > 200 || new Set(paths).size !== paths.length) throw new Error('Invalid project batch');
+  const files = [];
+  let bytes = 0;
+  for (const name of paths) {
+    const record = inventory.records.find(r => r.path === name);
+    if (!record) throw new Error('Project file outside inventory');
+    const file = { id: hash(name), path: name, kind: 'file', rawStatus: 'project-current', rightExists: true, eligibility: 'reviewable', properties: [], reviewMode: 'project', contentNotice: 'Full current-file review. Empty left side is a transport sentinel, NOT an actual empty baseline or a newly added file; review existing defects in current source, do not infer introduced regression.' };
+    files.push(file);
+    if (isSecretPath(name)) { file.eligibility = 'excluded'; file.reason = 'Credential path excluded'; continue; }
+    try {
+      const stat = await lstat(path.join(inventory.root, name));
+      if (stat.isDirectory()) { file.eligibility = 'excluded'; file.reason = 'Directory metadata is inventory only'; continue; }
+      if (stat.isSymbolicLink() || !stat.isFile()) throw new Error('Linked or nonregular project source excluded');
+      await bindProjectSource(inventory, record, name, file, options);
+      file.left = decode(Buffer.alloc(0));
+      file.right = await readLocal(inventory.root, name, options);
+      bytes += file.right.bytes;
+      if (bytes > 4 * 1024 * 1024) throw new Error('Project batch exceeds shared 4MiB source limit');
+    } catch (error) {
+      options.signal?.throwIfAborted();
+      if (error.code === 'PROJECT_CAPTURE_BUDGET' || /exceeds shared/.test(error.message)) throw error;
+      file.eligibility = 'blocked'; file.reason = error.message;
+      delete file.left; delete file.right;
+    }
+  }
+  const scope = { mode: 'project', inventoryId: inventory.id, totalTrackedNodes: inventory.records.length, batchPaths: paths, untrackedIncluded: false, inventoryComplete: inventory.vcs === 'git', scopeCompleteness: inventory.vcs === 'svn' ? 'observed-working-copy-only' : 'tracked-index-only', notice: inventory.notice };
+  const snapshot = { schemaVersion: 1, vcs: inventory.vcs, root: inventory.root, files, context: [], projectScope: scope };
+  return { ...snapshot, id: hash(JSON.stringify(snapshot)) };
 }