@hifullmoon/aicommit 2.6.2 → 2.6.3

package/CHANGELOG.md

@@ -4,6 +4,16 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 
 ## [Unreleased]
 
+## [2.6.3] - 2026-09-15
+
+### Changed
+
+- Very large `auto` split inventories now bundle adjacent local candidates by module, file kind, and Git status before hierarchical model planning, substantially reducing repeated input tokens while retaining every file in the final plan.
+
+### Fixed
+
+- Split execution now batches large path inventories instead of overflowing Node's Git output/argument buffers, and large plan/checkpoint files remain readable for recovery.
+
 ## [2.6.2] - 2026-09-14
 
 ### Fixed
@@ -245,7 +255,8 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 - Added file-level split planning and execution with Git-state concurrency checks.
 - Added provider presets and user/project configuration boundaries.
 
-[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.6.2...HEAD
+[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.6.3...HEAD
+[2.6.3]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.6.3
 [2.6.2]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.6.2
 [2.6.1]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.6.1
 [2.6.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.6.0

package/README.md

@@ -492,7 +492,7 @@ The default `largeChange.strategy: "auto"` inventories every file locally, group
 
 A normal commit typically needs one model request, with no per-file AI calls or recursive model reduction. The inventory contains at most 16 representative groups under a UTF-8 byte budget, prioritizing coverage across code, configuration, tests, and other categories. It explicitly describes sampling limits. Both terminal and JSON output distinguish fully analyzed files, representative excerpts, and metadata-only files. Provider retries, response recovery, policy correction, and user-requested regeneration can still add requests.
 
-Split mode builds local candidates and sends them in bounded batches of at most `splitMaxPlanFiles`, then merges the batch plans hierarchically. Every file remains represented even when the complete candidate inventory cannot fit one request. If `deep` analysis exhausts its aggregate budget or the hierarchy cannot converge, interactive and dry-run flows produce one conservative all-files plan with an explicit warning instead of using incomplete model output. Non-interactive committing stops unless `--allow-single-fallback` explicitly authorizes that degradation. Small changes keep the existing request path.
+Split mode builds local candidates and sends them in bounded batches of at most `splitMaxPlanFiles`, then merges the batch plans hierarchically. When an `auto` inventory exceeds four times that candidate limit, adjacent candidates are first bundled locally by top-level module, file kind, and Git status; the model receives compact counts, examples, and selected excerpts while the complete file mapping stays local. Every file remains represented even when the complete candidate inventory cannot fit one request. If `deep` analysis exhausts its aggregate budget or the hierarchy cannot converge, interactive and dry-run flows produce one conservative all-files plan with an explicit warning instead of using incomplete model output. Non-interactive committing stops unless `--allow-single-fallback` explicitly authorizes that degradation. Small changes keep the existing request path.
 
 For exhaustive chunk-by-chunk model analysis, opt in through personal configuration:
 

package/README.zh-CN.md

@@ -494,7 +494,7 @@ exec zsh
 
 普通提交通常只需要一次模型请求，不会为每个文件调用 AI，也不会递归调用模型汇总。摘要最多包含 16 个代表组，并受 UTF-8 字节预算约束；优先覆盖代码、配置和测试等不同类别。摘要明确说明抽样范围，界面和 JSON 分别报告全文分析、代表片段和仅元数据的文件数，不把抽样视为完整理解。提供方重试、响应恢复、格式修正和用户重新生成仍可能增加请求。
 
-批次提交先在本地建立候选组，再按每批最多 `splitMaxPlanFiles` 个候选发送，并分层合并各批计划；完整候选清单放不进一次请求时，仍会保留每个文件。如果 `deep` 分析耗尽总预算，或分层规划无法收敛，交互和 dry-run 流程会明确警告并生成一个覆盖全部文件的保守计划，而不会采用不完整的模型结果；非交互提交默认停止，只有显式传入 `--allow-single-fallback` 才允许该降级。小变更保持原有请求路径。
+批次提交先在本地建立候选组，再按每批最多 `splitMaxPlanFiles` 个候选发送，并分层合并各批计划。当 `auto` 清单规模超过该候选上限的四倍时，会先按顶层模块、文件类型和 Git 状态在本地归并相邻候选；模型只接收紧凑计数、少量路径示例和代表片段，完整文件映射始终留在本地。完整候选清单放不进一次请求时，仍会保留每个文件。如果 `deep` 分析耗尽总预算，或分层规划无法收敛，交互和 dry-run 流程会明确警告并生成一个覆盖全部文件的保守计划，而不会采用不完整的模型结果；非交互提交默认停止，只有显式传入 `--allow-single-fallback` 才允许该降级。小变更保持原有请求路径。
 
 确实需要逐块 AI 分析时，在个人配置中设置：
 

package/docs/distribution.md

@@ -33,7 +33,7 @@ The release workflow uses npm Trusted Publishing without a long-lived `NPM_TOKEN
 ```bash
 workdir=$(mktemp -d)
 cd "$workdir"
-npm install --package-lock-only @hifullmoon/aicommit@2.6.2
+npm install --package-lock-only @hifullmoon/aicommit@2.6.3
 npm audit signatures
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hifullmoon/aicommit",
-  "version": "2.6.2",
+  "version": "2.6.3",
   "description": "Safe, local-first AI commit message generator for Git workflows",
   "type": "module",
   "bin": {

package/schemas/aicommit-output.schema.json

@@ -195,6 +195,16 @@
               "type": "number",
               "minimum": 0
             },
+            "planningCandidatesOriginal": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Local candidates before token-saving planning compaction."
+            },
+            "planningCandidates": {
+              "type": "number",
+              "minimum": 0,
+              "description": "Candidate bundles sent through hierarchical split planning."
+            },
             "requests": {
               "type": "number",
               "minimum": 0

package/src/change-analysis.js

@@ -12,6 +12,7 @@ import {
   isDeepAnalysis,
   isGeneratedFile,
   localOverview,
+  compactLocalPlanFacts,
   localPlanBatches,
 } from './local-analysis.js';
 
@@ -714,8 +715,15 @@ export async function summarizeChanges(config, facts) {
 }
 
 export async function planAnalyzedChanges(config, facts, coverage = null, stream = null) {
-  let candidates = facts;
   const deep = isDeepAnalysis(config) && coverage?.strategy !== 'auto';
+  const compacted = deep
+    ? { facts, originalCandidates: facts.length, planningCandidates: facts.length }
+    : compactLocalPlanFacts(config, facts);
+  let candidates = compacted.facts;
+  if (coverage) {
+    coverage.planningCandidatesOriginal = compacted.originalCandidates;
+    coverage.planningCandidates = compacted.planningCandidates;
+  }
   const policy = normalizeCommitPolicy(config.commitPolicy, config.language);
   const cap = Math.min(
     config.splitMaxDiffChars || 16000,
@@ -761,7 +769,7 @@ export async function planAnalyzedChanges(config, facts, coverage = null, stream
       };
       const groups = await jsonCall(
         config,
-        `Each commit message must follow this policy: ${JSON.stringify(policy)}.\nGroup related changes into logical commits, including related implementation and tests across directories. Return [{"ids":[input IDs],"summary":"factual combined change summary","subject":"commit subject","body":"optional commit body"}]. Assign every input ID exactly once. Do not merge unrelated changes just to reduce group count.`,
+        `Each commit message must follow this policy: ${JSON.stringify(policy)}.\nGroup related changes into logical commits, including related implementation and tests across directories. Return [{"ids":[input IDs],"summary":"factual combined change summary","subject":"commit subject","body":"optional commit body"}]. Assign every input ID exactly once. Do not merge unrelated changes just to reduce group count.${!deep && level === 0 ? ' Inputs are a compact local inventory, not full semantic summaries. One ID may represent multiple files and must remain atomic; use kind, module, status, fileCount, examples, and any representativeExcerpt conservatively.' : ''}`,
         batch,
         (candidate) => {
           validatePartition(candidate, ids);

package/src/git-spool.js

@@ -11,7 +11,7 @@ process.once('exit', cleanupGitSpools);
 
 // Git writes directly to a private temporary file, never to a Node stdout
 // buffer. Consumers scan the captured bytes without reopening the worktree.
-export function spoolGit(commands, cwd) {
+export function spoolGit(commands, cwd, { env = undefined } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'aicommit-diff-'));
   const path = join(dir, 'patch');
   let fd;
@@ -20,6 +20,7 @@ export function spoolGit(commands, cwd) {
     for (const args of commands) {
       execFileSync('git', ['--no-pager', ...args], {
         cwd,
+        ...(env ? { env } : {}),
         stdio: ['ignore', fd, 'pipe'],
         timeout: 120000,
         maxBuffer: 1024 * 1024,
@@ -79,6 +80,23 @@ export function spoolGit(commands, cwd) {
         }
         if (pending.length) yield pending.toString('utf8');
       },
+      *nulFields(maxFieldBytes = 16 * 1024) {
+        let pending = Buffer.alloc(0);
+        for (const buffer of this.buffers()) {
+          const data = pending.length ? Buffer.concat([pending, buffer]) : buffer;
+          let start = 0;
+          for (let end = data.indexOf(0); end !== -1; end = data.indexOf(0, start)) {
+            if (end - start > maxFieldBytes)
+              throw new Error(`NUL-delimited Git field exceeds ${maxFieldBytes} bytes.`);
+            yield data.subarray(start, end).toString('utf8');
+            start = end + 1;
+          }
+          pending = Buffer.from(data.subarray(start));
+          if (pending.length > maxFieldBytes)
+            throw new Error(`NUL-delimited Git field exceeds ${maxFieldBytes} bytes.`);
+        }
+        if (pending.length) throw new Error('NUL-delimited Git output was truncated.');
+      },
       text(limit) {
         if (size > limit) return null;
         return [...this.lines()].join('').trim();

package/src/local-analysis.js

@@ -251,6 +251,86 @@ export function analyzeLocally(config, capture, protect, previews) {
   };
 }
 
+function planningBucketKey(fact) {
+  const topLevel = fact.module === '.' ? '.' : fact.module.split('/')[0];
+  return JSON.stringify([
+    topLevel,
+    fact.kind,
+    fact.status,
+    fact.modeChange || '',
+    Boolean(fact.binary),
+  ]);
+}
+
+function moduleSpan(facts) {
+  const modules = [...new Set(facts.map((fact) => fact.module))];
+  if (modules.length === 1) return modules[0];
+  const parts = modules.map((module) => module.split('/'));
+  const common = [];
+  for (let index = 0; index < parts[0].length; index++) {
+    const value = parts[0][index];
+    if (!parts.every((item) => item[index] === value)) break;
+    common.push(value);
+  }
+  return common.length ? `${common.join('/')}/*` : 'multiple modules';
+}
+
+// Extremely large auto-mode inventories cannot represent every independent
+// file candidate to the model without hundreds of repeated requests. Bundle
+// adjacent candidates locally while retaining their complete file mapping;
+// the model groups bundle IDs, and execution still covers every original path.
+export function compactLocalPlanFacts(config, facts) {
+  const maxItems = config.splitMaxPlanFiles || 100;
+  const threshold = maxItems * 4;
+  if (facts.length <= threshold) {
+    return { facts, originalCandidates: facts.length, planningCandidates: facts.length };
+  }
+
+  const target = Math.max(1, maxItems * 2);
+  const bundleSize = Math.ceil(facts.length / target);
+  const ordered = [...facts].sort(
+    (left, right) =>
+      planningBucketKey(left).localeCompare(planningBucketKey(right)) ||
+      left.module.localeCompare(right.module) ||
+      left.id.localeCompare(right.id),
+  );
+  const bundles = [];
+  let bucket = [];
+  let key = null;
+  const flush = () => {
+    if (!bucket.length) return;
+    const first = bucket[0];
+    const evidence = bucket.find((fact) => fact.evidence)?.evidence || '';
+    const modeChanges = new Set(bucket.map((fact) => fact.modeChange).filter(Boolean));
+    bundles.push({
+      id: `C${bundles.length + 1}`,
+      kind: first.kind,
+      module: moduleSpan(bucket),
+      status: first.status,
+      files: bucket.flatMap((fact) => fact.files),
+      additions: bucket.reduce((total, fact) => total + fact.additions, 0),
+      deletions: bucket.reduce((total, fact) => total + fact.deletions, 0),
+      modeChange: modeChanges.size === 1 ? [...modeChanges][0] : null,
+      binary: bucket.some((fact) => fact.binary),
+      evidence,
+    });
+    bucket = [];
+  };
+
+  for (const fact of ordered) {
+    const nextKey = planningBucketKey(fact);
+    if (bucket.length && (nextKey !== key || bucket.length >= bundleSize)) flush();
+    key = nextKey;
+    bucket.push(fact);
+  }
+  flush();
+  return {
+    facts: bundles,
+    originalCandidates: facts.length,
+    planningCandidates: bundles.length,
+  };
+}
+
 export function localPlanBatches(config, facts, cap) {
   const error = () =>
     fail(ERROR_CATEGORIES.CONFIG, 'A split candidate is too large for one planning request.', {
@@ -260,10 +340,7 @@ export function localPlanBatches(config, facts, cap) {
   const batches = [];
   let batch = [];
   for (const fact of facts) {
-    const item = {
-      ...summaryOf(fact, false),
-      summary: 'Local candidate only; verify grouping. Content not fully analyzed.',
-    };
+    const item = summaryOf(fact, false);
     if (Buffer.byteLength(JSON.stringify([item])) > cap) throw error();
     const candidate = [...batch, item];
     if (
@@ -278,12 +355,15 @@ export function localPlanBatches(config, facts, cap) {
   if (batch.length) batches.push(batch);
 
   const factsById = new Map(facts.map((fact) => [fact.id, fact]));
+  let evidenceCount = 0;
   for (const items of batches) {
     for (const item of items) {
+      if (evidenceCount >= 16) break;
       const evidence = factsById.get(item.id)?.evidence;
       if (!evidence) continue;
       item.representativeExcerpt = evidence;
       if (Buffer.byteLength(JSON.stringify(items)) > cap) delete item.representativeExcerpt;
+      else evidenceCount++;
     }
   }
   return batches;

package/src/split-checkpoint.js

@@ -15,7 +15,10 @@ import { validateSplitPlanArtifact } from './split-plan.js';
 
 export const SPLIT_CHECKPOINT_KIND = 'aicommit-split-checkpoint';
 export const SPLIT_CHECKPOINT_VERSION = 1;
-const MAX_CHECKPOINT_BYTES = 2 * 1024 * 1024;
+// Checkpoints contain both the validated plan and one object snapshot per real
+// path, so their bound must be larger than the plan artifact bound. This still
+// caps parsing of local metadata while allowing the supported 10,000 changes.
+const MAX_CHECKPOINT_BYTES = 128 * 1024 * 1024;
 const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 
 function object(value) {
@@ -197,7 +200,7 @@ export function readSplitCheckpoint(projectRoot) {
   if (!stat.isFile() || stat.isSymbolicLink()) {
     throw new Error('Split checkpoint must be a regular, non-symbolic-link file.');
   }
-  if (stat.size > MAX_CHECKPOINT_BYTES) throw new Error('Split checkpoint exceeds 2 MiB.');
+  if (stat.size > MAX_CHECKPOINT_BYTES) throw new Error('Split checkpoint exceeds 128 MiB.');
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(path, 'utf8'));
@@ -213,10 +216,14 @@ export function writeSplitCheckpoint(projectRoot, input) {
     ...input,
     updatedAt: new Date().toISOString(),
   });
+  const serialized = JSON.stringify(checkpoint, null, 2) + '\n';
+  if (Buffer.byteLength(serialized) > MAX_CHECKPOINT_BYTES) {
+    throw new Error('Split checkpoint exceeds the 128 MiB limit.');
+  }
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync(temporary, JSON.stringify(checkpoint, null, 2) + '\n', {
+    writeFileSync(temporary, serialized, {
       encoding: 'utf8',
       mode: 0o600,
     });

package/src/split-hunks.js

@@ -4,6 +4,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { pathBatches } from './git.js';
+
 const HUNK_HEADER_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 
 function git(projectRoot, args, { indexPath = null, input = undefined } = {}) {
@@ -215,9 +217,13 @@ export function validateHunkTransaction(projectRoot, plan, snapshots) {
     }
 
     const finalEntries = parseIndexEntries(
-      git(projectRoot, ['ls-files', '--stage', '-z', '--', ...snapshots.map((item) => item.path)], {
-        indexPath,
-      }),
+      pathBatches(snapshots.map((item) => item.path))
+        .map((batch) =>
+          git(projectRoot, ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', ...batch], {
+            indexPath,
+          }),
+        )
+        .join(''),
     );
     for (const entry of snapshots) {
       if (!entriesEqual(finalEntries.get(entry.path) || null, entry.target)) {

package/src/split-plan.js

@@ -5,7 +5,10 @@ import { normalizeCommitPolicy, validateCommitCandidate } from './policy.js';
 
 export const SPLIT_PLAN_KIND = 'aicommit-split-plan';
 export const SPLIT_PLAN_VERSION = 1;
-const MAX_PLAN_BYTES = 1024 * 1024;
+// A file-level split can legitimately contain thousands of long paths. Keep
+// reads bounded, but size the artifact limit for the validated 10,000-change
+// ceiling instead of rejecting plans that this module can create itself.
+const MAX_PLAN_BYTES = 64 * 1024 * 1024;
 const HASH_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const FINGERPRINT_RE = /^[0-9a-f]{64}$/;
 const HUNK_HASH_RE = /^[0-9a-f]{64}$/;
@@ -241,13 +244,14 @@ export function validateSplitPlanArtifact(input) {
     normalizeGroup(group, index, allowedPaths, hunkCatalog, commitPolicy, input.language),
   );
   const assignedFiles = groups.flatMap((group) => group.files);
-  if (new Set(assignedFiles).size !== assignedFiles.length) {
+  const assignedFileSet = new Set(assignedFiles);
+  if (assignedFileSet.size !== assignedFiles.length) {
     throw new Error('Split plan assigns a path to more than one group.');
   }
   const assignedHunks = new Set();
   for (const group of groups) {
     for (const assignment of group.hunks || []) {
-      if (assignedFiles.includes(assignment.path)) {
+      if (assignedFileSet.has(assignment.path)) {
         throw new Error(`Split plan assigns both a whole file and hunks: ${assignment.path}`);
       }
       for (const id of assignment.ids) {
@@ -260,7 +264,7 @@ export function validateSplitPlanArtifact(input) {
     }
   }
   const missing = displayPaths.filter((path) => {
-    if (assignedFiles.includes(path)) return false;
+    if (assignedFileSet.has(path)) return false;
     const ids = hunkCatalog.get(path);
     return !ids || [...ids].some((id) => !assignedHunks.has(`${path}\0${id}`));
   });
@@ -310,10 +314,14 @@ export function createSplitPlanArtifact({
 export async function writeSplitPlanArtifact(path, artifact) {
   const absolute = resolve(path);
   const validated = validateSplitPlanArtifact(artifact);
+  const serialized = JSON.stringify(validated, null, 2) + '\n';
+  if (Buffer.byteLength(serialized) > MAX_PLAN_BYTES) {
+    throw new Error('Split plan exceeds the 64 MiB limit.');
+  }
   await mkdir(dirname(absolute), { recursive: true, mode: 0o700 });
   const temporary = `${absolute}.${process.pid}.${Date.now()}.tmp`;
   try {
-    await writeFile(temporary, JSON.stringify(validated, null, 2) + '\n', {
+    await writeFile(temporary, serialized, {
       encoding: 'utf8',
       mode: 0o600,
       flag: 'wx',
@@ -341,7 +349,7 @@ export async function readSplitPlanArtifact(path) {
   if (!stat.isFile() || stat.isSymbolicLink()) {
     throw new Error('Split plan must be a regular, non-symbolic-link file.');
   }
-  if (stat.size > MAX_PLAN_BYTES) throw new Error('Split plan exceeds the 1 MiB limit.');
+  if (stat.size > MAX_PLAN_BYTES) throw new Error('Split plan exceeds the 64 MiB limit.');
   let parsed;
   try {
     parsed = JSON.parse(await readFile(absolute, 'utf8'));

package/src/split.js

@@ -236,20 +236,33 @@ export function getSplitChangedFiles(cwd, scope = 'all') {
 // the planner must see the same latest content executeSplit will git add -A.
 function getWorkingTreeDiff(projectRoot, head, contextLines, paths = []) {
   const u = unifiedArg(contextLines);
-  const pathArgs = paths.length ? ['--', ...paths] : [];
-  if (head) {
-    return readGit(['diff', u, 'HEAD', ...pathArgs], projectRoot).trim();
+  const batches = paths.length ? pathBatches(paths) : [[]];
+  const parts = [];
+  for (const batch of batches) {
+    const pathArgs = batch.length ? ['--', ...batch] : [];
+    if (head) {
+      parts.push(readGit(['diff', u, 'HEAD', ...pathArgs], projectRoot).trim());
+      continue;
+    }
+    parts.push(readGit(['diff', u, '--cached', ...pathArgs], projectRoot).trim());
+    parts.push(readGit(['diff', u, ...pathArgs], projectRoot).trim());
   }
-
-  const cached = readGit(['diff', u, '--cached', ...pathArgs], projectRoot).trim();
-  const unstaged = readGit(['diff', u, ...pathArgs], projectRoot).trim();
-  return [cached, unstaged].filter(Boolean).join('\n');
+  return parts.filter(Boolean).join('\n');
 }
 
 export function getSplitDiff(projectRoot, head, contextLines, scope = 'all', paths = []) {
   if (scope === 'staged') {
-    const pathArgs = paths.length ? ['--', ...paths] : [];
-    return readGit(['diff', unifiedArg(contextLines), '--cached', ...pathArgs], projectRoot).trim();
+    const batches = paths.length ? pathBatches(paths) : [[]];
+    return batches
+      .map((batch) => {
+        const pathArgs = batch.length ? ['--', ...batch] : [];
+        return readGit(
+          ['diff', unifiedArg(contextLines), '--cached', ...pathArgs],
+          projectRoot,
+        ).trim();
+      })
+      .filter(Boolean)
+      .join('\n');
   }
   return getWorkingTreeDiff(projectRoot, head, contextLines, paths);
 }
@@ -261,7 +274,7 @@ export function getSplitStateFingerprint(projectRoot, head, files, scope = 'all'
   const hash = createHash('sha256');
   if (scope === 'staged') {
     hash.update(head ? readGit(['rev-parse', 'HEAD'], projectRoot).trim() : '<unborn>');
-    hash.update(readGit(['ls-files', '--stage', '-z'], projectRoot));
+    updateGitHash(hash, ['ls-files', '--stage', '-z'], projectRoot);
     return hash.digest('hex');
   }
   files ||= getAllChangedFiles(projectRoot);
@@ -909,9 +922,9 @@ function getGroupDiff(
   return 'Changed files (new files, no diff available):\n' + parts.join('\n');
 }
 
-function parseStageZeroEntries(text) {
+function parseStageZeroEntries(fields) {
   const entries = new Map();
-  for (const field of text.split('\0')) {
+  for (const field of fields) {
     if (!field) continue;
     const match = field.match(/^(\d+) ([0-9a-f]+) (\d)\t([\s\S]+)$/);
     if (!match || match[3] !== '0') continue;
@@ -920,8 +933,37 @@ function parseStageZeroEntries(text) {
   return entries;
 }
 
-function readStageZeroEntries(projectRoot) {
-  return parseStageZeroEntries(readGit(['ls-files', '--stage', '-z'], projectRoot));
+function* filterGitFields(fields, wanted) {
+  for (const field of fields) {
+    const tab = field.indexOf('\t');
+    if (tab !== -1 && wanted.has(field.slice(tab + 1))) yield field;
+  }
+}
+
+function readStageZeroEntries(projectRoot, paths = null, indexPath = null) {
+  if (paths !== null && !paths.length) return new Map();
+  const wanted = paths === null ? null : new Set(paths);
+  const batches = paths === null ? null : pathBatches(paths);
+  if (batches && batches.length <= 8) {
+    const output = batches
+      .map((batch) => {
+        const args = ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', ...batch];
+        return indexPath
+          ? runGitWithIndex(args, projectRoot, indexPath)
+          : readGit(args, projectRoot);
+      })
+      .join('');
+    return parseStageZeroEntries(output.split('\0'));
+  }
+  const source = spoolGit([['--literal-pathspecs', 'ls-files', '--stage', '-z']], projectRoot, {
+    ...(indexPath ? { env: { ...process.env, GIT_INDEX_FILE: indexPath } } : {}),
+  });
+  try {
+    const fields = wanted ? filterGitFields(source.nulFields(), wanted) : source.nulFields();
+    return parseStageZeroEntries(fields);
+  } finally {
+    source.dispose();
+  }
 }
 
 function runGitWithIndex(args, projectRoot, indexPath, inherit = false, input = undefined) {
@@ -977,25 +1019,11 @@ function activeCommitHooks(projectRoot) {
 
 function submodulePaths(projectRoot, paths) {
   const found = new Set();
-  const index = pathBatches(paths)
-    .map((batch) =>
-      readGit(['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', ...batch], projectRoot),
-    )
-    .join('');
-  for (const entry of index.split('\0')) {
-    const match = entry.match(/^160000 [0-9a-f]+ \d\t([\s\S]+)$/);
-    if (match) found.add(match[1]);
-  }
+  for (const [path, entry] of readStageZeroEntries(projectRoot, paths))
+    if (entry.mode === '160000') found.add(path);
   if (hasHead(projectRoot)) {
-    const tree = pathBatches(paths)
-      .map((batch) =>
-        readGit(['--literal-pathspecs', 'ls-tree', '-rz', 'HEAD', '--', ...batch], projectRoot),
-      )
-      .join('');
-    for (const entry of tree.split('\0')) {
-      const match = entry.match(/^160000 commit [0-9a-f]+\t([\s\S]+)$/);
-      if (match) found.add(match[1]);
-    }
+    for (const [path, entry] of readHeadEntries(projectRoot, paths))
+      if (entry.mode === '160000') found.add(path);
   }
   return [...found];
 }
@@ -1112,7 +1140,7 @@ function resetCommittedPaths(projectRoot, groups, allFiles) {
 }
 
 function captureTargetEntries(projectRoot, scope, paths) {
-  if (scope === 'staged') return readStageZeroEntries(projectRoot);
+  if (scope === 'staged') return readStageZeroEntries(projectRoot, paths);
   const tempDir = mkdtempSync(join(tmpdir(), 'aicommit-split-snapshot-'));
   const indexPath = join(tempDir, 'index');
   try {
@@ -1128,9 +1156,7 @@ function captureTargetEntries(projectRoot, scope, paths) {
       false,
       paths.join('\0') + '\0',
     );
-    return parseStageZeroEntries(
-      runGitWithIndex(['ls-files', '--stage', '-z'], projectRoot, indexPath),
-    );
+    return readStageZeroEntries(projectRoot, paths, indexPath);
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
   }
@@ -1139,7 +1165,7 @@ function captureTargetEntries(projectRoot, scope, paths) {
 function captureCheckpointSnapshots(projectRoot, scope, allFiles) {
   const paths = [...new Set(allFiles.flatMap((change) => change.addPaths))].sort();
   const target = captureTargetEntries(projectRoot, scope, paths);
-  const index = readStageZeroEntries(projectRoot);
+  const index = readStageZeroEntries(projectRoot, paths);
   return paths.map((path) => ({
     path,
     target: target.get(path) || null,
@@ -1243,15 +1269,35 @@ function splitCommitFailure(projectRoot, message) {
 function readHeadEntries(projectRoot, paths) {
   const entries = new Map();
   if (!hasHead(projectRoot) || !paths.length) return entries;
-  const text = pathBatches(paths)
-    .map((batch) =>
-      readGit(['--literal-pathspecs', 'ls-tree', '-rz', 'HEAD', '--', ...batch], projectRoot),
-    )
-    .join('');
-  for (const field of text.split('\0')) {
-    if (!field) continue;
-    const match = field.match(/^(\d+) \S+ ([0-9a-f]+)\t([\s\S]+)$/);
-    if (match) entries.set(match[3], { mode: match[1], oid: match[2] });
+  const wanted = new Set(paths);
+  const batches = pathBatches(paths);
+  let source = null;
+  try {
+    const fields =
+      batches.length <= 8
+        ? batches
+            .map((batch) =>
+              readGit(
+                ['--literal-pathspecs', 'ls-tree', '-rz', 'HEAD', '--', ...batch],
+                projectRoot,
+              ),
+            )
+            .join('')
+            .split('\0')
+        : filterGitFields(
+            (source = spoolGit(
+              [['--literal-pathspecs', 'ls-tree', '-rz', 'HEAD']],
+              projectRoot,
+            )).nulFields(),
+            wanted,
+          );
+    for (const field of fields) {
+      if (!field) continue;
+      const match = field.match(/^(\d+) \S+ ([0-9a-f]+)\t([\s\S]+)$/);
+      if (match) entries.set(match[3], { mode: match[1], oid: match[2] });
+    }
+  } finally {
+    source?.dispose();
   }
   return entries;
 }
@@ -1289,7 +1335,7 @@ function reconcileCompletedIndex(projectRoot, checkpoint) {
   const paths = [
     ...new Set(groups.flatMap((group) => expandGroupPaths(group, checkpoint.plan.changes))),
   ];
-  const current = readStageZeroEntries(projectRoot);
+  const current = readStageZeroEntries(projectRoot, paths);
   const head = readHeadEntries(projectRoot, paths);
   const snapshots = new Map(checkpoint.snapshots.map((snapshot) => [snapshot.path, snapshot]));
   for (const path of paths) {
@@ -1826,6 +1872,13 @@ export async function splitFlow(
               analysis.coverage,
               planningStream,
             );
+            if (
+              analysis.coverage.planningCandidates < analysis.coverage.planningCandidatesOriginal
+            ) {
+              console.error(
+                `  Planning input: bundled ${analysis.coverage.planningCandidatesOriginal} local candidates into ${analysis.coverage.planningCandidates} token-efficient groups.`,
+              );
+            }
           } catch (err) {
             const exhausted =
               err.data?.analysis?.exhausted ||