chainlesschain 0.162.155 → 0.162.156

package/src/commands/batch.js

@@ -0,0 +1,345 @@
+/**
+ * `cc batch` — dynamic worktree batch (gap-analysis 第四阶段 #4). Split a big
+ * change into independent UNITS, run each in its own git worktree in parallel,
+ * test each, and aggregate diff/test/merge-conflict results.
+ *
+ *   cc batch --units units.json                 # run declared units
+ *   cc batch --units units.json --test "npm test" --concurrency 4 --merge
+ *   cc batch --decompose "migrate all foo() calls to bar()" --parts 8
+ *       # ask an agent to split the goal into a units.json, then run it
+ *   cc batch --decompose "…" --parts 8 --plan-only   # emit units, don't run
+ *
+ * units.json: { "units": [ { "key": "u1", "prompt": "…", "test": "npm test -w a" } ] }
+ *
+ * Real isolation comes from worktree-isolator (the same primitive `cc team
+ * --worktree` uses); the fan-out + aggregation core lives in lib/agent-batch.js
+ * (fully injectable). Branches persist for inspection unless merged.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+import { execFileSync } from "child_process";
+import chalk from "chalk";
+import { logger } from "../lib/logger.js";
+import { runBatch } from "../lib/agent-batch.js";
+import {
+  createWorktree,
+  removeWorktree,
+  previewWorktreeMerge,
+  mergeWorktree,
+} from "../harness/worktree-isolator.js";
+import { findProjectRoot } from "../lib/project-detector.js";
+
+const BIN = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "bin",
+  "chainlesschain.js",
+);
+
+const DECOMPOSE_SCHEMA = {
+  type: "object",
+  properties: {
+    units: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          prompt: { type: "string" },
+          test: { type: "string" },
+        },
+        required: ["key", "prompt"],
+      },
+    },
+  },
+  required: ["units"],
+};
+
+export function registerBatchCommand(program) {
+  program
+    .command("batch")
+    .description(
+      "Split a large change into independent units, run each in its own git worktree in parallel, and aggregate results",
+    )
+    .option(
+      "--units <file>",
+      "Units JSON file ({ units: [{key, prompt, test?}] })",
+    )
+    .option(
+      "--decompose <goal>",
+      "Ask an agent to split this goal into units first (structured output)",
+    )
+    .option("--parts <n>", "Target number of units for --decompose", "6")
+    .option(
+      "--plan-only",
+      "With --decompose: print the units and exit (no run)",
+    )
+    .option("--concurrency <n>", "Max worktrees running at once", "4")
+    .option("--test <cmd>", "Default test command run in each worktree")
+    .option("--merge", "Merge clean, passing branches back to base")
+    .option("--model <model>", "Model for agent runs")
+    .option("--json", "Machine-readable JSON output")
+    .action(async (options) => {
+      process.exitCode = await runBatchCommand(options);
+    });
+}
+
+export async function runBatchCommand(options = {}, _deps = {}) {
+  const log = _deps.log || ((m) => console.log(m));
+  const errLog = _deps.err || ((m) => logger.error(m));
+  const repoDir =
+    _deps.repoDir || findProjectRoot(process.cwd()) || process.cwd();
+
+  // 1. Resolve the unit list — from a file, or by decomposing a goal.
+  let units;
+  try {
+    if (options.units) {
+      const doc = JSON.parse(fs.readFileSync(options.units, "utf8"));
+      units = Array.isArray(doc) ? doc : doc.units;
+    } else if (options.decompose) {
+      units = await (_deps.decompose || decomposeGoal)(
+        options.decompose,
+        Number(options.parts) || 6,
+        { model: options.model, repoDir },
+      );
+      if (options.planOnly) {
+        log(JSON.stringify({ units }, null, 2));
+        return 0;
+      }
+    } else {
+      errLog("Provide --units <file> or --decompose <goal>.");
+      return 4;
+    }
+  } catch (err) {
+    errLog(`Failed to resolve units: ${err.message}`);
+    return 4;
+  }
+
+  // 2. Run the batch with real worktree + agent + git deps.
+  const deps = _deps.batchDeps || {
+    createWorktree: (key, branch) => createWorktree(repoDir, branch).path,
+    removeWorktree: (worktreePath, opts) =>
+      removeWorktree(repoDir, worktreePath, opts),
+    runAgent:
+      _deps.runAgent ||
+      ((prompt, cwd) => spawnAgent(prompt, cwd, { model: options.model })),
+    runTest: _deps.runTest || runTestCommand,
+    diffStat: _deps.diffStat || gitDiffStat,
+    commit: _deps.commit || gitCommitAll,
+    previewMerge: (branch) => previewWorktreeMerge(repoDir, branch),
+    mergeBranch: (branch, message) =>
+      mergeWorktree(repoDir, branch, { message }),
+    branchFor: (key) => `batch/${sanitize(key)}`,
+  };
+
+  const onEvent = options.json ? () => {} : (ev) => log(formatEvent(ev));
+
+  let outcome;
+  try {
+    outcome = await runBatch(
+      {
+        units,
+        concurrency: options.concurrency,
+        test: options.test || null,
+        merge: options.merge === true,
+        onEvent,
+      },
+      deps,
+    );
+  } catch (err) {
+    errLog(`Batch failed: ${err.message}`);
+    return 1;
+  }
+
+  if (options.json) {
+    log(JSON.stringify(outcome, null, 2));
+  } else {
+    log("");
+    log(chalk.bold("  Batch summary:"));
+    const s = outcome.summary;
+    log(
+      `  ${s.total} units — ${chalk.green(s.done + " done")}, ` +
+        `${chalk.red(s.testFailed + " test-failed")}, ` +
+        `${chalk.yellow(s.errored + " errored")}, ${s.noChanges} no-change`,
+    );
+    if (options.merge) {
+      log(
+        `  merged ${chalk.green(s.merged)}, conflicts ${chalk.yellow(s.conflicted)}`,
+      );
+    }
+    log("");
+  }
+  // Non-zero when anything failed so CI can gate on it.
+  return outcome.summary.testFailed + outcome.summary.errored > 0 ? 1 : 0;
+}
+
+// ─── real effectful deps ───────────────────────────────────────────────────
+
+function sanitize(key) {
+  return String(key).replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+
+function spawnAgent(prompt, cwd, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      BIN,
+      "agent",
+      "-p",
+      prompt,
+      "--permission-mode",
+      "acceptEdits",
+      "--output-format",
+      "text",
+    ];
+    if (opts.model) args.push("--model", opts.model);
+    const child = spawn(process.execPath, args, {
+      cwd,
+      env: { ...process.env, CLAUDECODE: "1" },
+      windowsHide: true,
+    });
+    let err = "";
+    child.stderr?.on("data", (d) => (err += d.toString("utf8")));
+    child.on("error", (e) => reject(new Error(e.message)));
+    child.on("close", (code) =>
+      code === 0
+        ? resolve({ code })
+        : reject(new Error(err.trim() || `agent exited ${code}`)),
+    );
+  });
+}
+
+function runTestCommand(command, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      env: process.env,
+      windowsHide: true,
+    });
+    let err = "";
+    child.stderr?.on("data", (d) => (err += d.toString("utf8")));
+    child.on("error", (e) => reject(new Error(e.message)));
+    child.on("close", (code) =>
+      code === 0
+        ? resolve({ code })
+        : reject(new Error(err.trim() || `test exited ${code}`)),
+    );
+  });
+}
+
+/** `git add -A` staged numstat totals for a worktree. */
+function gitDiffStat(cwd) {
+  try {
+    execFileSync("git", ["add", "-A"], { cwd, stdio: "ignore" });
+    const out = execFileSync("git", ["diff", "--cached", "--numstat"], {
+      cwd,
+      encoding: "utf8",
+    });
+    let insertions = 0;
+    let deletions = 0;
+    let filesChanged = 0;
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [add, del] = trimmed.split("\t");
+      filesChanged += 1;
+      insertions += add === "-" ? 0 : parseInt(add, 10) || 0;
+      deletions += del === "-" ? 0 : parseInt(del, 10) || 0;
+    }
+    return { filesChanged, insertions, deletions };
+  } catch {
+    return { filesChanged: 0, insertions: 0, deletions: 0 };
+  }
+}
+
+function gitCommitAll(cwd, message) {
+  try {
+    execFileSync("git", ["add", "-A"], { cwd, stdio: "ignore" });
+    execFileSync("git", ["commit", "-m", message, "--no-verify"], {
+      cwd,
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false; // nothing to commit / commit failed
+  }
+}
+
+/** Spawn a headless agent that emits a units JSON via --json-schema. */
+async function decomposeGoal(goal, parts, opts = {}) {
+  const prompt =
+    `Split this task into ${parts} INDEPENDENT units that can each be done in a ` +
+    `separate git worktree WITHOUT depending on each other's changes. For each ` +
+    `unit give a short kebab-case "key", a self-contained "prompt" (the full ` +
+    `instruction for an agent working only on that unit), and optionally a "test" ` +
+    `shell command to verify it.\n\nTask: ${goal}`;
+  return new Promise((resolve, reject) => {
+    const args = [
+      BIN,
+      "agent",
+      "-p",
+      prompt,
+      "--json-schema",
+      JSON.stringify(DECOMPOSE_SCHEMA),
+      "--permission-mode",
+      "plan",
+    ];
+    if (opts.model) args.push("--model", opts.model);
+    const child = spawn(process.execPath, args, {
+      cwd: opts.repoDir || process.cwd(),
+      env: { ...process.env, CLAUDECODE: "1" },
+      windowsHide: true,
+    });
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => (out += d.toString("utf8")));
+    child.stderr?.on("data", (d) => (err += d.toString("utf8")));
+    child.on("error", (e) => reject(new Error(e.message)));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(err.trim() || `decompose agent exited ${code}`));
+        return;
+      }
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed.units);
+      } catch (e) {
+        reject(new Error(`could not parse decomposition output: ${e.message}`));
+      }
+    });
+  });
+}
+
+function formatEvent(ev) {
+  switch (ev.type) {
+    case "batch:start":
+      return chalk.dim(
+        `  batch: ${ev.units} units, concurrency ${ev.concurrency}`,
+      );
+    case "unit:start":
+      return chalk.dim(`  ▶ ${ev.key} (${ev.branch})`);
+    case "unit:done": {
+      const badge =
+        ev.status === "done"
+          ? chalk.green("✓")
+          : ev.status === "test-failed"
+            ? chalk.red("✗ test")
+            : ev.status === "error"
+              ? chalk.red("✗ error")
+              : chalk.gray("·");
+      return `  ${badge} ${ev.key} (${ev.filesChanged} files)`;
+    }
+    case "unit:integrated":
+      return ev.conflicts
+        ? chalk.yellow(`  ⚠ ${ev.key}: ${ev.conflicts} conflict(s)`)
+        : chalk.green(`  ↳ ${ev.key}: ${ev.merged ? "merged" : "clean"}`);
+    default:
+      return "";
+  }
+}
+
+export const _internal = { decomposeGoal, gitDiffStat, DECOMPOSE_SCHEMA };

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.155",
+      "cliVersion": "0.162.156",
       "cliVersions": [
         "0.4.46",
         "0.37.4",
@@ -12,11 +12,16 @@
         "0.162.152",
         "0.162.153",
         "0.162.154",
-        "0.162.155"
+        "0.162.155",
+        "0.162.156"
       ],
       "date": null,
       "title": "",
       "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.156：agenda/batch 双命令（第四阶段收口）+ @chainlesschain/agent-sdk 0.1.0 npm 首发（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.155 → **0.162.156** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）；**`@chainlesschain/agent-sdk` 0.1.0 同 run 首发 npm**（平台化第三阶段产物，npm-publish.yml / release.yml 均已加发布 step，防 trap #127 漏发）。纯 `packages/cli/src`（+web-panel dist 随包）+ 新独立包，未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令数 **170 → 172**（新增顶层 `agenda`/`batch`，清单已重生，13 文档面已扫）。\n\n- **`cc agenda` + notify/schedule 双 agent 工具（第四阶段批19）**：Monitor/Cron/Push 暴露为 agent 可调工具（AGENT_TOOLS 21→23）——`notify` 推送到用户已配置的多通道通知器（Telegram/企业微信/钉钉/飞书）；`schedule` 一工具五动作（wakeup/cron/monitor/list/cancel），单轮进程持不住定时器 → 意图持久化到 `~/.chainlesschain/agent-schedule/*.jsonl`（0600），由 `cc agenda list|run|cancel` 消费触发（wakeup/cron 到期 spawn `cc agent -p`，monitor 跑命令匹配 stop_when 即通知）。两工具 LOW 风险、plan 模式禁用；29 单测 + 真进程 smoke。\n- **`cc batch` 动态 worktree 批处理（第四阶段批20，第四阶段全收口）**：把大改动拆成独立单元并行跑——`--units <file>` 或 `--decompose <goal> --parts N`（agent 经 `--json-schema` 产单元 JSON，`--plan-only` 只打印）；每单元独立 git worktree（复用 `cc team --worktree` 的 worktree-isolator），`--test` 门控、`--merge` 顺序集成（后合分支与已合冲突时报告不强合、测试失败单元永不合并）；15 单测 + 2 真 git/worktree 集成测试。\n- **`@chainlesschain/agent-sdk` 0.1.0 首发**：`cc agent` stream-json 双工协议的 TypeScript 正式契约（Agent Protocol v1）——流式事件全词汇 + 审批回调（fail-closed）+ 检查点 + 会话恢复；`AgentSession` spawn 客户端（Windows `cmd.exe /c` shim + `NoDefaultCurrentDirectoryInExePath` 反劫持 + `taskkill /T` 进程树回收内置）、`attachBackgroundSession` 后台管道接管、`/browser` 浏览器安全入口（web-panel bg-\\* 帧）、`/protocol` 纯类型入口；双构建 ESM+CJS，零运行时依赖，36 测试（单元+真管道集成+真 CLI e2e）。VS Code 扩展（vendored）与 web-panel（vite alias）已消费；JetBrains 对齐语言中立 `docs/PROTOCOL.md`。用户文档 `docs-site/docs/chainlesschain/agent-sdk.md`。\n- 修复（随本版仓内，不在 cli 包面）：SDK 真 CLI e2e 抓出的两 IDE 首会话不落盘洞（IDE 重载后 resume 静默空会话）已在两插件修复，随各自下次插件发版出货。"
+        },
         {
           "heading": "Added — cc CLI 0.162.155：权限模式/auto 分类器 + 后台会话可交互接管全家桶（第一阶段收口，CLI-only npm 发版）",
           "body": "> `chainlesschain` 0.162.154 → **0.162.155** 已发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src`（+web-panel dist 随包）增量，未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。gap-analysis「第一阶段：安全与可运营性」4 项全部落地（批 1-15，9 commit `e3ab46c73f..1618a3ca83`）。命令数 **165 → 170**（新增顶层 `attach`/`auto-mode`/`daemon`/`logs`/`remote-control`，清单已重生）。发版前本机三层全绿（unit 21808 / integration 除 1 已知 real-spawn flake 隔离 3 连绿 / e2e 628）。\n\n- **权限模式补齐 `manual`/`auto`/`dontAsk`**（headless + 交互 REPL 双面）：`manual`=default 别名；`auto`=可配置分类器——settings `autoMode.decisions` 按 riskLevel（对象/数组形）与 tool/commandPattern 细粒度规则（`*` glob，声明序优先）映射 allow/ask/deny，未配置时字节不变映射 trusted；`dontAsk`=需确认动作直接 deny 不弹审批（REPL 两处 confirmer 全覆盖）。REPL `/permissions auto|dontask` 中途切换，Shift+Tab 循环兼容；`cc agent --permission-mode` 对交互式会话生效（顺带修 `resolveAgentPolicy` 白名单静默丢弃 `--vim/--think/--fallback-model/--pdh` 等交互 flag 的预存 bug）。\n- **`cc auto-mode defaults|config [--json]`**：内置分类默认值文档 + user/project/local/managed 分层合并后的有效配置（含细粒度规则展示）；修 `mergeSandboxSettings` 数组分支把数组形 decisions 毁成 `\"[object Object]\"` 的潜伏 bug（新 `mergeAutoModeSettings`，decisions=有序规则集 closer 层整体替换）。\n- **`cc permissions recent|denials [--json|--clear]` + 决策逐层解释链**：跨会话持久 denial ring buffer（headless + REPL 双源）；被拒 run_shell 附带 `permissionChain`（settings-rules→shell-policy→approval-gate 各层判定+理由），`/permissions denials` 与 `cc permissions recent` 渲染紧凑链——一眼看清「allow 规则为何没生效」。\n- **后台会话可运营全家桶**：顶层 `cc logs <id>` / `cc attach <id>` / `cc daemon status|view|stop|rename|resume`。worker heartbeat + workerPid/agentPid 分离 + stale-heartbeat/PID-reuse 防误杀（可靠标 `lost`）；`cc daemon resume <id> <prompt>` 把崩溃/终态会话按 sessionId 续接为新后台运行（原 argv 有意不持久化防 secrets 落盘）。\n- **`cc attach` 可交互接管（session transport）**：worker 每会话托管本地 NDJSON 控制通道（Win named pipe / POSIX socket，随机 token 存 0600 state 文件）；attach 后键入即发 follow-up prompt（同 `--session` 自动续接对话史，多轮 turn 循环），`/stop` 截断当前轮，turn 运行中断开任务照跑、idle 断开会话收尾；transport 不可用自动回退日志流，`--no-input` 强制纯日志。\n- **web-panel「后台 Agent」面板**：新 `bg-*` WS 协议（list/view/attach/prompt/stop-turn/detach/stop/rename/resume，attach 期间推送 worker 事件与日志增量）；takeover token 永不过 WS 边界。面板含列表/接管卡片/日志流/重命名/续跑。\n- 修复：后台 rename 与 worker read-modify-write 竞态（写后校验+有界重试）；`settingsVerdict` 未传入 executeToolInner 的解释链断点；launcher/worker 状态竞写（先写 state 后 spawn + heartbeat 重申 transport）。\n- **`cc remote-control`（第四阶段批17，随本版一同发布）**：统一远控入口（别名 `rc`）——start/status/stop 组合既有 remote-session 栈（WS server + E2EE relay + registry + ledger + push + audit），配对 URI 双模式（relay E2EE / 直连 LAN），跨进程 0600 state 发现；顺带修 `cc serve --remote-session-relay-url` 白名单丢参从未生效的预存 bug。\n- **MCP tool search（第二阶段批16，随本版一同发布）**：大规模 MCP 面下工具定义超上下文阈值（默认窗口 10%，`mcp.toolSearch` settings / `CC_TOOL_SEARCH` env 可配）时自动换成 `[deferred]` stub + 内部 `tool_search` 检索工具；完整 schema 经 tool result 返回（append-only，保 prompt cache 稳定）；REPL `/context` 新增 MCP tool schemas 占用与优化建议一节。未超阈值/关闭时行为字节不变。"

package/src/index.js

@@ -156,6 +156,12 @@ import { registerServeCommand } from "./commands/serve.js";
 // Remote Control unified entry (第四阶段 #1)
 import { registerRemoteControlCommand } from "./commands/remote-control.js";
 
+// Agenda: consumer for agent-scheduled wakeups/crons/monitors (第四阶段 #3)
+import { registerAgendaCommand } from "./commands/agenda.js";
+
+// Batch: dynamic worktree batch — split a change into parallel units (第四阶段 #4)
+import { registerBatchCommand } from "./commands/batch.js";
+
 // Web UI
 import { registerUiCommand } from "./commands/ui.js";
 import { registerPackCommand } from "./commands/pack.js";
@@ -586,6 +592,12 @@ export function createProgram(opts = {}) {
   // Remote Control unified entry
   registerRemoteControlCommand(program);
 
+  // Agenda: fire agent-scheduled wakeups/crons/monitors
+  registerAgendaCommand(program);
+
+  // Batch: dynamic worktree batch
+  registerBatchCommand(program);
+
   // Web UI
   registerUiCommand(program);
 

package/src/lib/agent-batch.js

@@ -0,0 +1,235 @@
+/**
+ * agent-batch — dynamic worktree batch core (gap-analysis 第四阶段 #4).
+ *
+ * Takes a large task already decomposed into independent UNITS and runs each in
+ * its OWN git worktree, in parallel (bounded concurrency), then aggregates the
+ * outcome: per-unit agent status, test result, diff stat, and — on integration
+ * — a merge-conflict preview against base. This is the `/batch` shape from
+ * Claude Code, built on the same worktree isolation `cc team --worktree` uses.
+ *
+ * Pure over injected deps (worktree lifecycle, agent/test spawns, git) so the
+ * whole fan-out + aggregation is unit-testable without a real repo or LLM.
+ *
+ * A `unit` is `{ key, prompt, test? }`. Concurrency is a simple worker pool.
+ * Integration is SEQUENTIAL (like TeamWorktreeCoordinator.integrate) so a later
+ * branch that conflicts with an already-merged one is reported, not clobbered.
+ */
+
+/** Run `items` through `worker` with at most `limit` in flight; preserves order. */
+async function mapPool(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  const runners = new Array(Math.max(1, Math.min(limit, items.length)))
+    .fill(0)
+    .map(async () => {
+      while (true) {
+        const i = next++;
+        if (i >= items.length) return;
+        results[i] = await worker(items[i], i);
+      }
+    });
+  await Promise.all(runners);
+  return results;
+}
+
+function normalizeUnits(units) {
+  if (!Array.isArray(units) || units.length === 0) {
+    throw new Error("batch requires a non-empty `units` array");
+  }
+  const seen = new Set();
+  return units.map((u, i) => {
+    const key = String(u.key || `unit-${i + 1}`);
+    if (seen.has(key)) throw new Error(`duplicate unit key "${key}"`);
+    seen.add(key);
+    if (!u.prompt || typeof u.prompt !== "string") {
+      throw new Error(`unit "${key}" has no prompt`);
+    }
+    return { key, prompt: u.prompt, test: u.test || null };
+  });
+}
+
+/**
+ * @param {object} opts
+ * @param {Array<{key,prompt,test?}>} opts.units
+ * @param {number} [opts.concurrency=4]
+ * @param {string} [opts.test]         default test command for units without one
+ * @param {boolean} [opts.merge]       merge clean branches back to base
+ * @param {(msg:object)=>void} [opts.onEvent]  progress callback
+ * @param {object} deps  injected effectful ops (see command wiring)
+ * @returns {Promise<{units:Array, summary:object}>}
+ */
+export async function runBatch(opts, deps) {
+  const units = normalizeUnits(opts.units);
+  const concurrency = Math.max(1, Number(opts.concurrency) || 4);
+  const onEvent = opts.onEvent || (() => {});
+  const {
+    createWorktree,
+    removeWorktree,
+    runAgent,
+    runTest,
+    diffStat,
+    commit,
+    previewMerge,
+    mergeBranch,
+    branchFor = (key) => `batch/${key}`,
+  } = deps;
+
+  onEvent({ type: "batch:start", units: units.length, concurrency });
+
+  const results = await mapPool(units, concurrency, async (unit) => {
+    const branch = branchFor(unit.key);
+    const record = {
+      key: unit.key,
+      branch,
+      status: "pending",
+      filesChanged: 0,
+      insertions: 0,
+      deletions: 0,
+      testCommand: unit.test || opts.test || null,
+      testPassed: null,
+      committed: false,
+      error: null,
+    };
+    let worktreePath = null;
+    try {
+      worktreePath = createWorktree(unit.key, branch);
+      onEvent({ type: "unit:start", key: unit.key, branch });
+      await runAgent(unit.prompt, worktreePath);
+
+      const stat = diffStat(worktreePath);
+      record.filesChanged = stat.filesChanged;
+      record.insertions = stat.insertions;
+      record.deletions = stat.deletions;
+
+      const testCmd = unit.test || opts.test || null;
+      if (testCmd) {
+        try {
+          await runTest(testCmd, worktreePath);
+          record.testPassed = true;
+        } catch (err) {
+          record.testPassed = false;
+          record.testError = err.message;
+        }
+      }
+
+      if (stat.filesChanged > 0) {
+        record.committed = commit(worktreePath, `batch: ${unit.key}`);
+      }
+      // A unit whose tests FAILED is reported failed even though its worktree
+      // committed — integration below skips non-passing units so a red unit
+      // never merges into base.
+      record.status =
+        record.testPassed === false
+          ? "test-failed"
+          : record.filesChanged === 0
+            ? "no-changes"
+            : "done";
+    } catch (err) {
+      record.status = "error";
+      record.error = err.message;
+    }
+    onEvent({
+      type: "unit:done",
+      key: unit.key,
+      status: record.status,
+      testPassed: record.testPassed,
+      filesChanged: record.filesChanged,
+    });
+    return { record, worktreePath };
+  });
+
+  // Sequential integration: only units that DID change, committed, and did not
+  // fail tests are eligible. Preview each; merge clean ones when --merge.
+  for (const { record } of results) {
+    if (!record.committed || record.status === "test-failed") {
+      record.integration = { eligible: false, reason: record.status };
+      continue;
+    }
+    let preview;
+    try {
+      preview = previewMerge(record.branch);
+    } catch (err) {
+      record.integration = {
+        eligible: true,
+        clean: false,
+        merged: false,
+        conflicts: [],
+        error: err.message,
+      };
+      continue;
+    }
+    const clean = preview?.success === true;
+    const conflicts = preview?.conflicts || [];
+    let merged = false;
+    if (clean && opts.merge) {
+      let mergeResult;
+      try {
+        mergeResult = mergeBranch(record.branch, `Merge batch ${record.key}`);
+      } catch (err) {
+        mergeResult = { success: false, message: err.message };
+      }
+      merged = mergeResult?.success === true;
+      if (!merged && (!conflicts || conflicts.length === 0)) {
+        record.integration = {
+          eligible: true,
+          clean,
+          merged,
+          conflicts: mergeResult?.conflicts || [],
+          error: mergeResult?.message || null,
+        };
+        continue;
+      }
+    }
+    record.integration = { eligible: true, clean, merged, conflicts };
+    onEvent({
+      type: "unit:integrated",
+      key: record.key,
+      clean,
+      merged,
+      conflicts: conflicts.length,
+    });
+  }
+
+  // Best-effort teardown of every worktree we created (branches persist for the
+  // user to inspect/merge later unless already merged).
+  if (typeof removeWorktree === "function") {
+    for (const { record, worktreePath } of results) {
+      if (!worktreePath) continue;
+      try {
+        removeWorktree(worktreePath, {
+          deleteBranch: record.integration?.merged === true,
+        });
+      } catch {
+        // best-effort — a leftover worktree is recoverable via `git worktree`
+      }
+    }
+  }
+
+  const records = results.map((r) => r.record);
+  const summary = summarize(records);
+  onEvent({ type: "batch:done", ...summary });
+  return { units: records, summary };
+}
+
+function summarize(records) {
+  const summary = {
+    total: records.length,
+    done: 0,
+    testFailed: 0,
+    noChanges: 0,
+    errored: 0,
+    merged: 0,
+    conflicted: 0,
+  };
+  for (const r of records) {
+    if (r.status === "done") summary.done += 1;
+    else if (r.status === "test-failed") summary.testFailed += 1;
+    else if (r.status === "no-changes") summary.noChanges += 1;
+    else if (r.status === "error") summary.errored += 1;
+    if (r.integration?.merged) summary.merged += 1;
+    if (r.integration?.conflicts?.length) summary.conflicted += 1;
+  }
+  return summary;
+}
+
+export const _internal = { mapPool, normalizeUnits, summarize };