@ai-dossier/sched 0.15.0 → 0.17.0

package/README.md

@@ -172,6 +172,17 @@ containing a `blocked` batch with "unknown batch status", bricking that project'
 `SchedStore.load()`. Resume or abandon any blocked batch before downgrading past this
 version.
 
+Config schema moves to 1.7.0 (#563): a new top-level `dissolve_policy` key —
+`{ fraction, min_evictions_before_dissolve }`, both required when the key is present —
+overrides the batch dissolve threshold (default `{ fraction: 1/3,
+min_evictions_before_dissolve: 1 }`, RFC-0001 §F.8's ⅓ with no additional floor). An
+absent key falls back wholesale to the default; an invalid one degrades the WHOLE config
+file to built-in defaults, same as every other config field (`loadConfig`'s
+degrade-to-defaults contract). This release also adds the `partial` `dissolveBatch`
+strategy and the `batch-preserved` journal event (see Batch failure recovery above) — both
+are behavioral, not persisted-shape changes, so they carry no schema-version bump of their
+own.
+
 Two engine-safety policies were explicit product decisions on #464:
 
 - **Pid identity is hybrid-verified (decision 1, option C).** Every spawn records the
@@ -248,7 +259,11 @@ against real scratch repos.
 ```
 validating → attributing → fixing (ONE bounded attempt) → validating
                          → evicting (revert the member's commits) → validating
-  > ⅓ of members evicted, or a revert conflict → dissolving → members requeued
+  evictions > max(ceil(N × fraction), min_evictions_before_dissolve), or a
+  revert conflict → dissolving → members requeued (`dissolve_policy`, #563)
+  same threshold crossed, but the survivors' re-run suite came back green
+                         → reviewing (batch preserved; only the evicted
+                           members requeue — strategy=partial, #563)
   suite report unreadable, after the fallback retry when one applied
                          → blocked → validating (nothing requeued/reverted; #562)
 awaiting-merge (CONFLICTING | auto-merge-blocked)
@@ -280,13 +295,24 @@ awaiting-merge (CONFLICTING | auto-merge-blocked)
    aborted so the worktree is clean and the batch dissolves — the reverts that already
    landed ride along on the abandoned branch, which is why it is abandoned rather than
    reused. An eviction group that reaches an already-shipped member dissolves instead of
-   reverting merged work.
+   reverting merged work. Crossing the dissolve trigger no longer always dissolves (#563):
+   if the re-run suite came back green for the survivors — and every evicted member's
+   commits were actually found and reverted — the batch is PRESERVED instead: trimmed to
+   its survivors and carried straight to `reviewing`, only the evicted members requeue. A
+   red or unreadable re-run, or an evicted member whose commits were never found on the
+   branch, still dissolves in full.
 4. **Dissolve (AC3)** — `dissolveBatch` marks the batch `dissolved` and requeues every
-   UNSHIPPED member: `full` (each as its own full-cycle run) or `halved` (one or two fresh
+   UNSHIPPED member: `full` (each as its own full-cycle run), `halved` (one or two fresh
    `forming` half-batches — a single remaining member yields one — entries retagged,
-   eviction groups inherited where they survive the split). Shipped and terminal members
-   keep their outcome; nothing green is discarded, and no git runs — the batch branch is
-   simply left behind unmerged, since sched deletes nothing.
+   eviction groups inherited where they survive the split), or `partial` (#563 — never
+   marks the batch `dissolved` at all: drops the evicted members from `batch.members` and
+   its `eviction_groups`/`ranges`, transitions `validating → reviewing`, and requeues
+   nothing itself, since the caller's eviction loop already did; falls through to `full`
+   if that would leave zero survivors, so an empty batch never ships). Shipped and
+   terminal members keep their outcome; nothing green is discarded, and no git runs — the
+   batch branch is simply left behind unmerged, since sched deletes nothing. Every dissolve
+   decision — all three strategies — journals its policy inputs (`N=`, `evictions=`,
+   `threshold=`), so it is explainable without re-deriving the formula.
 5. **PR conflict (AC4)** — `handlePrConflict` rebases the batch branch, re-runs the suite
    and re-ships ONCE. A second occurrence, a conflicting rebase, a failed fetch, an
    unusable `base_branch`, a checkout that is not on the batch branch, or a red suite
@@ -299,12 +325,13 @@ awaiting-merge (CONFLICTING | auto-merge-blocked)
    with no `anchor` or no `run_id` cannot post — the CLI requires both — so the milestone
    it could not post is journaled in full instead of vanishing.
 
-Eleven journal events carry the detail: `suite-failed`, `attributed`, `fix-dispatched`,
+Twelve journal events carry the detail: `suite-failed`, `attributed`, `fix-dispatched`,
 `fix-resolved`, `member-evicted`, `revert-conflict`, `batch-rebased`, `batch-dissolved`,
-`batch-blocked` (#562 — the suite report was unreadable), `batch-split` and
-`milestone-post-failed`, plus `git-failed` for any git command that returned non-zero (the
-injected `ExecFn` collapses every git failure into `null`, so the command that produced one
-is always recorded).
+`batch-preserved` (#563 — the dissolve threshold was crossed but the survivors' re-run
+suite came back green, so the batch ships them instead of dissolving), `batch-blocked`
+(#562 — the suite report was unreadable), `batch-split` and `milestone-post-failed`, plus
+`git-failed` for any git command that returned non-zero (the injected `ExecFn` collapses
+every git failure into `null`, so the command that produced one is always recorded).
 
 Schema 1.3.0 carries the new state: `BatchEntry` gains `anchor`, `branch`, `run_id`,
 `eviction_groups`, `evictions`, `fix_attempts` and `rebase_attempts`; `QueueEntry` gains
@@ -365,8 +392,14 @@ failure rails: executing → dissolving (a member self-reports blocked)
 ```
 
 - **One shared worktree/branch per batch**, claimed once by a deterministic (no LLM)
-  `batch-setup` step: `git branch`/`push`/`worktree add` off `base_branch`, named
-  `batch/<id>-<date>`, plus a fresh `ai-dossier runstate mint` against the anchor issue.
+  `batch-setup` step, named `batch/<id>-<date>`, plus a fresh `ai-dossier runstate mint`
+  against the anchor issue. Tries a pool claim first (`npx worktree-pool claim` —
+  already warm by construction, `BatchEntry.pool_claimed`); on the cold `git branch`/
+  `push`/`worktree add` path, batch-setup warms the worktree itself before returning
+  (#561) — `cap run worktree.prepare` when the repo's manifest declares it, else
+  package-manager-detected install/build (`@ai-dossier/worktree-pool`'s command
+  resolution — respects the repo's `.worktree-pool.json` `project_subdir`/
+  `warm_commands` even in repos that never use the pool for anything else).
 - **Members run serially, one fresh `slot-cycle` agent at a time**, in the shared
   worktree. A member's completion signal is `phase=review status=done mode=slot` on its
   OWN issue (`slot-cycle` posts no phase of its own past `review` — ship is batch-owned);
@@ -391,23 +424,26 @@ failure rails: executing → dissolving (a member self-reports blocked)
   `report-issue`'s batch variant.
 - **Scope cuts, recorded rather than discovered later:** no `git bisect` stage for an
   ambiguous aggregate failure (an unattributable red suite dissolves instead); no
-  worktree-pool integration for batch-setup (cold `git worktree add` only); no per-phase
-  stall/escalation ladder for batch sub-agents (a dead-without-verification agent is
-  treated as blocked, not redispatched stronger).
+  per-phase stall/escalation ladder for batch sub-agents (a dead-without-verification
+  agent is treated as blocked, not redispatched stronger).
 
 Schema 1.7.0: `BatchEntry` gains `worktree` (absolute path of the shared batch worktree,
 null until batch-setup lands), `ranges` (`MemberRange[]` — each member's commit range,
 recomputed after every member completes) and `pr` (the batch PR parked on auto-merge,
 persisted so a restart mid-watch still knows what to poll). 1.6.0 states migrate on load:
 no batch was ever dispatched under them, so `null`/`[]`/`null` is the exact backfill, not
-a guess. Config schema moves to 1.3.0: `dispatch` gains `member_prompt`,
-`batch_tail_prompt` and `batch_report_prompt` (the three new agent prompt templates).
-
-New journal events: `batch-setup-done`, `batch-setup-failed`, `member-advanced`. Member/
-tail/report/fix-agent spawn, progress, completion and park events reuse the existing
-unit-generic names (`assigned`/`spawned`/`unit-failed`/`external-advance`/`pr-parked`/
-`merge-accepted`/`report-dispatched`/`teardown-done`/`teardown-failed`) with
-`unit = batch:<id>`.
+a guess. `BatchEntry` also gains `pool_claimed` (#561) — pre-#561 states carry no such
+key at all, and backfill it to `false` on load (no batch was ever pool-claimed before
+batch-setup had pool integration). Config schema moves to 1.3.0: `dispatch` gains
+`member_prompt`, `batch_tail_prompt` and `batch_report_prompt` (the three new agent
+prompt templates).
+
+New journal events: `batch-setup-done`, `batch-setup-failed`, `member-advanced`,
+`batch-warmup-done`, `batch-warmup-failed` (#561 — the cold-path warm step only; a pool
+claim emits neither). Member/tail/report/fix-agent spawn, progress, completion and park
+events reuse the existing unit-generic names (`assigned`/`spawned`/`unit-failed`/
+`external-advance`/`pr-parked`/`merge-accepted`/`report-dispatched`/`teardown-done`/
+`teardown-failed`) with `unit = batch:<id>`.
 
 ## API surface
 
@@ -474,8 +510,8 @@ import {
   beginFixAttempt,       // the ONE bounded mid-tier fix dispatch instruction
   resolveFixAttempt,     // record its outcome, back to validating
   evictMembers,          // revert + requeue with evidence + suite re-run + dissolve check
-  checkDissolveTrigger,  // pure: > ⅓ of members evicted
-  dissolveBatch,         // full or halved dissolve; preserves everything green
+  checkDissolveTrigger,  // pure: evicted > max(ceil(N × fraction), min floor) — dissolve_policy, #563
+  dissolveBatch,         // full | halved | partial (#563); preserves everything green
   blockBatch,            // #562: unreadable suite report → blocked; no requeue, no revert
   type BlockOptions,     // { reason, milestonePhase? } for blockBatch
   handlePrConflict,      // rebase + re-ship once, then dissolve into halves
@@ -542,7 +578,8 @@ telemetry" below.
 ├── config.json    # durable intent: max_slots, stall_timeout_ms, reconcile_interval_ms,
 │                  # pr_poll_interval_ms, dispatch (incl. report_prompt,
 │                  # phase_stall_timeout_ms, fence_takeover_timeout_ms, tiers — #527,
-│                  # suite_command — #562), auto_upgrade — #537
+│                  # suite_command — #562), auto_upgrade — #537,
+│                  # dissolve_policy — #563
 ├── events.jsonl   # append-only event journal (the operator's flight recorder)
 ├── runs/          # per-unit agent output logs (issue-<n>.log)
 └── .sched-lock/   # cross-process directory mutex (pid; stolen from dead holders)

package/dist/batch-dispatch.d.ts

@@ -47,12 +47,18 @@
  * an ambiguous aggregate failure (bisect needs a per-project "run only these
  * tests" command this module has no generic way to construct) — an
  * unattributable red aggregate suite dissolves the batch rather than
- * bisecting, which `attributing → dissolving` already models. No worktree-pool
- * integration for batch-setup — cold `git worktree add` only, mirroring
- * `teardown.ts`'s cold path. No per-phase stall/escalation ladder for batch
- * sub-agents — a dead-without-verification agent is treated as blocked and
- * evicted/reported rather than redispatched stronger. Both are documented
- * follow-ups, not gaps discovered later.
+ * bisecting, which `attributing → dissolving` already models. No per-phase
+ * stall/escalation ladder for batch sub-agents — a dead-without-verification
+ * agent is treated as blocked and evicted/reported rather than redispatched
+ * stronger. Both are documented follow-ups, not gaps discovered later.
+ *
+ * `runBatchSetup` (#561) tries a pool claim first (already warm, mirroring
+ * `teardown.ts`'s `poolReturn` — same `npx`-through-`deps.exec` pattern, never
+ * a direct in-process `claim()` import, which resolves its git root from
+ * `process.cwd()` and would break this module's `deps.repoDir` testability
+ * contract); on the cold `git worktree add` path it warms the worktree itself
+ * before returning, so a member's first command is never the one that
+ * discovers `node_modules` is missing (`env-cold`, `docs/agent-traps.md`).
  */
 import { type ResolvedDispatch, type SpawnDeps } from './dispatch';
 import { type GroundTruth } from './groundtruth';
@@ -81,17 +87,30 @@ export interface BatchDispatchDeps {
     repoDir: string;
     /** Exec for batch git/milestone-CLI operations (never throws — the `ExecFn` contract). */
     exec: ExecFn;
+    /**
+     * Exec for the cold-path warm-up install/build (#561), on its own budget —
+     * a real `npm ci` + build routinely exceeds the git-op timeout `exec` is
+     * tuned for. Falls back to `exec` when not supplied (existing callers/tests
+     * are unaffected; production wiring should still give this its own longer
+     * timeout, e.g. `@ai-dossier/worktree-pool`'s `WARM_COMMAND_TIMEOUT_MS`).
+     */
+    warmExec?: ExecFn;
     /** Runs the aggregate suite inside a batch worktree; batches never leave `validating` without one. */
     runSuite: (worktree: string) => SuiteResult;
     /**
-     * Runs one `ai-dossier cap run <capabilityId>` in a batch worktree for the
-     * per-member incremental gate (#523 AC2 — "typecheck + focused tests via
-     * `cap run test.focused` when available"). Optional and degrade-not-crash,
-     * like `batchExec`/`runBatchSuite`: without it, or on `automation-broken`/
-     * `capability-unavailable`, the gate is skipped — the member's own
-     * `slot-cycle` run already attempted this fast path (with its own reasoning
-     * fallback) before ever posting `review done`, so a repo with no manifest
-     * loses nothing but the engine's independent re-check.
+     * Runs one `ai-dossier cap run <capabilityId>` in a batch worktree. Two call
+     * sites, different degrade contracts:
+     * - the per-member incremental gate (#523 AC2 — "typecheck + focused tests
+     *   via `cap run test.focused` when available"): degrade-not-crash — without
+     *   this hook, or on `automation-broken`/`capability-unavailable`, the gate
+     *   is skipped (the member's own `slot-cycle` run already attempted this
+     *   fast path before ever posting `review done`, so a repo with no manifest
+     *   loses nothing but the engine's independent re-check).
+     * - batch-setup's `worktree.prepare` warm step (#561, `warmColdBatchWorktree`):
+     *   `undefined`/`capability-unavailable`/`automation-broken` fall through to
+     *   package-manager detection, but a declared-and-`task-failed` capability
+     *   hard-fails the whole batch setup — a repo that owns its warm-up should
+     *   never be silently second-guessed by a fallback underneath it.
      */
     runCapability?: (worktree: string, capabilityId: string) => CapOutcome;
     fsExists?: FsExists;

package/dist/batch-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-dispatch.d.ts","sourceRoot":"","sources":["../src/batch-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAWH,OAAO,EAKL,KAAK,gBAAgB,EAErB,KAAK,SAAS,EAEf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,WAAW,EAOjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAUL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAWpB,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAKV,WAAW,EAIZ,MAAM,SAAS,CAAC;AAEjB;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,aAAa,GAAG,mBAAmB,GAAG,wBAAwB,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,sGAAsG;IACtG,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,WAAW,CAAC;IAC5C;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,UAAU,CAAC;IACvE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA4xCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,gBAAgB,GACzB,eAAe,CAsEjB"}
+{"version":3,"file":"batch-dispatch.d.ts","sourceRoot":"","sources":["../src/batch-dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAiBH,OAAO,EAKL,KAAK,gBAAgB,EAErB,KAAK,SAAS,EAEf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,WAAW,EAOjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,OAAO,EAAa,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAUL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAWpB,OAAO,EAAE,KAAK,QAAQ,EAA2D,MAAM,YAAY,CAAC;AACpG,OAAO,KAAK,EAKV,WAAW,EAIZ,MAAM,SAAS,CAAC;AAGjB;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,aAAa,GAAG,mBAAmB,GAAG,wBAAwB,CAAC;AAE/F,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,WAAW,CAAC;IAC5C;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,UAAU,CAAC;IACvE,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAw8CD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,gBAAgB,GACzB,eAAe,CAsEjB"}

package/dist/batch-dispatch.js

@@ -48,12 +48,18 @@
  * an ambiguous aggregate failure (bisect needs a per-project "run only these
  * tests" command this module has no generic way to construct) — an
  * unattributable red aggregate suite dissolves the batch rather than
- * bisecting, which `attributing → dissolving` already models. No worktree-pool
- * integration for batch-setup — cold `git worktree add` only, mirroring
- * `teardown.ts`'s cold path. No per-phase stall/escalation ladder for batch
- * sub-agents — a dead-without-verification agent is treated as blocked and
- * evicted/reported rather than redispatched stronger. Both are documented
- * follow-ups, not gaps discovered later.
+ * bisecting, which `attributing → dissolving` already models. No per-phase
+ * stall/escalation ladder for batch sub-agents — a dead-without-verification
+ * agent is treated as blocked and evicted/reported rather than redispatched
+ * stronger. Both are documented follow-ups, not gaps discovered later.
+ *
+ * `runBatchSetup` (#561) tries a pool claim first (already warm, mirroring
+ * `teardown.ts`'s `poolReturn` — same `npx`-through-`deps.exec` pattern, never
+ * a direct in-process `claim()` import, which resolves its git root from
+ * `process.cwd()` and would break this module's `deps.repoDir` testability
+ * contract); on the cold `git worktree add` path it warms the worktree itself
+ * before returning, so a member's first command is never the one that
+ * discovers `node_modules` is missing (`env-cold`, `docs/agent-traps.md`).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -90,7 +96,9 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runBatchTick = runBatchTick;
+const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const worktree_pool_1 = require("@ai-dossier/worktree-pool");
 const attribution_1 = require("./attribution");
 const dispatch_1 = require("./dispatch");
 const groundtruth_1 = require("./groundtruth");
@@ -99,6 +107,7 @@ const recovery_1 = require("./recovery");
 const scheduler_1 = require("./scheduler");
 const state_1 = require("./state");
 const teardown_1 = require("./teardown");
+const types_1 = require("./types");
 function emptyResult() {
     return { spawned: [], completed: [], parked: [], mergeAccepted: [], failed: [], blocked: [] };
 }
@@ -182,13 +191,14 @@ function safeSuite(deps, batchId, worktree) {
         return { ok: false, failing: [], readable: false, detail };
     }
 }
-function recoveryDeps(deps, batch, now) {
+function recoveryDeps(deps, config, batch, now) {
     return {
         exec: deps.exec,
         repoDir: batch.worktree ?? deps.repoDir,
         journal: deps.journal,
         postMilestone: (0, recovery_1.createExecMilestonePoster)(deps.exec, { repoDir: deps.repoDir }),
         runSuite: batch.worktree !== null ? () => deps.runSuite(batch.worktree) : undefined,
+        dissolvePolicy: (0, types_1.resolveDissolvePolicy)(config.dissolve_policy),
         now: () => now,
     };
 }
@@ -230,11 +240,93 @@ function releaseSlot(state, batchId, now) {
 }
 // --- Batch setup (ready → executing, member 1) ---
 /**
- * `batch/<id>-<YYYYMMDD>` off `base_branch`, a worktree at
- * `<repoDir>/worktrees/batch-<id>-<YYYYMMDD>` (cold git only — no pool
- * integration in this version, see the module doc), and a fresh runstate run
- * id minted against the anchor. All-or-nothing: any failed step reports the
- * step name and nothing is partially recorded on the batch.
+ * A pool claim already returns a warm worktree (deps installed, built), so
+ * only the cold `git worktree add` path needs its own warm step (#561).
+ *
+ * Tries `worktree.prepare` via the optional `runCapability` hook first (a
+ * repo that declares it in its manifest knows its own warm-up best) — a
+ * declared-and-`task-failed` capability hard-fails the whole batch setup
+ * (deliberately NOT degrade-not-crash, unlike every other `runCapability`
+ * call site in this file: a repo that owns `worktree.prepare` should never
+ * be silently second-guessed by falling back underneath it). `undefined`,
+ * `capability-unavailable` (no such id declared) AND `automation-broken`
+ * (broken manifest, missing tool, timeout — "do not trust the machinery",
+ * not "the task failed") all fall through to the generic path below.
+ *
+ * The generic path reuses `@ai-dossier/worktree-pool`'s package-manager
+ * detection, guarded on `package.json` actually being present — `npm
+ * install` (and the pnpm/yarn/bun equivalents) hard-fail with no
+ * `package.json` at all, so an unguarded call would turn "nothing to warm"
+ * into a false failure for every non-Node repo. The guard is bypassed when
+ * `.worktree-pool.json` declares explicit `warm_commands` — the escape hatch
+ * for a repo whose warm-up isn't `npm install`-shaped at all.
+ *
+ * Warm commands run on `deps.warmExec ?? deps.exec` — a separate, longer
+ * budget than the git/milestone calls `deps.exec` is tuned for (a cold
+ * install+build routinely exceeds a git-op timeout; see `BatchDispatchDeps`).
+ *
+ * Journals `batch-warmup-done`/`batch-warmup-failed` with the elapsed time
+ * appended to `detail` either way (satisfying AC1 even on the no-op branch —
+ * `JournalEvent` has no dedicated `duration_ms` field).
+ */
+function warmColdBatchWorktree(deps, batch, worktree, now, 
+/** Prefixed onto the journaled detail — e.g. `pool-claim-invalid:` when the cold path was taken because a pool claim returned unusable output, rather than the ordinary "no warm spares" case. */
+poolNote = '') {
+    const warmStart = deps.now();
+    const elapsedMs = () => deps.now().getTime() - warmStart.getTime();
+    const fail = (tag) => {
+        deps.journal.append((0, journal_1.unitEvent)('batch-warmup-failed', unit(batch.id), {
+            detail: `${poolNote}${tag} ${elapsedMs()}ms`,
+        }), now);
+        return { ok: false, reason: `warmup-failed:${tag}` };
+    };
+    const done = (tag) => {
+        deps.journal.append((0, journal_1.unitEvent)('batch-warmup-done', unit(batch.id), {
+            detail: `${poolNote}${tag} ${elapsedMs()}ms`,
+        }), now);
+        return { ok: true };
+    };
+    const capOutcome = deps.runCapability?.(worktree, 'worktree.prepare');
+    if (capOutcome === 'ok')
+        return done('cap:worktree.prepare');
+    if (capOutcome === 'task-failed')
+        return fail('cap:worktree.prepare:task-failed');
+    // `undefined` (no hook injected) / `capability-unavailable` (not declared)
+    // / `automation-broken` (declared but the machinery itself is untrustworthy)
+    // all fall through to the generic package-manager path below.
+    const fsExists = deps.fsExists ?? ((p) => fs.existsSync(p));
+    const cfg = (0, worktree_pool_1.readPoolFileConfig)(deps.repoDir);
+    const projectDir = (0, worktree_pool_1.resolveProjectDir)(worktree, cfg.project_subdir);
+    // `.worktree-pool.json`'s `project_subdir` is repo config, not attacker
+    // input, but a `../`-shaped value would otherwise run install/build
+    // OUTSIDE the batch worktree entirely — skip rather than warm the wrong
+    // directory (or fail the whole batch over a misconfigured pool file).
+    if (projectDir !== worktree && !projectDir.startsWith(worktree + path.sep)) {
+        return done('skipped:project-dir-outside-worktree');
+    }
+    const hasExplicitWarmCommands = (cfg.warm_commands?.length ?? 0) > 0;
+    if (!hasExplicitWarmCommands && !fsExists(path.join(projectDir, 'package.json'))) {
+        return done('skipped:no-package-json');
+    }
+    const commands = (0, worktree_pool_1.resolveWarmCommands)(projectDir, cfg);
+    for (const [i, cmd] of commands.entries()) {
+        const [bin, ...args] = cmd;
+        if (bin === undefined)
+            return fail(`pm:${i + 1}/${commands.length}:empty-command`);
+        if ((deps.warmExec ?? deps.exec)(bin, args, projectDir) === null) {
+            return fail(`pm:${i + 1}/${commands.length}:${bin}`);
+        }
+    }
+    const pm = commands[0]?.[0] ?? 'none';
+    return done(`pm:${pm}:${commands.length}cmds`);
+}
+/**
+ * `batch/<id>-<YYYYMMDD>` off `base_branch`, and a fresh runstate run id
+ * minted against the anchor. The worktree is either a pool claim (already
+ * warm) or a cold `git worktree add` that this function then warms itself
+ * (#561, see the module doc) — either way, the worktree is warm before this
+ * returns `ok: true`. All-or-nothing: any failed step reports the step name
+ * and nothing is partially recorded on the batch.
  */
 function runBatchSetup(deps, batch, now) {
     if (batch.anchor === null)
@@ -257,6 +349,36 @@ function runBatchSetup(deps, batch, now) {
     if (runId === null || runId.trim() === '')
         return { ok: false, reason: 'runstate-mint-failed' };
     const mintedRunId = runId.trim();
+    // Pool claim first — a claimed worktree is already warm by construction, so
+    // no separate warm step runs for it (AC2). `claim()` itself never pushes
+    // the branch (mirrors setup-issue-workflow's per-issue pool-claim step),
+    // so that still happens here on success.
+    const claimed = deps.exec(teardown_1.POOL_BIN, [...teardown_1.POOL_ARGS_PREFIX, 'claim', '--issue', String(batch.anchor), '--branch', branch], deps.repoDir);
+    const claimedWorktree = claimed?.trim();
+    // Same hardening `teardown.ts`'s destructive sinks apply to a worktree path
+    // (no NUL/newline, no unresolved `..`) — this one is our own CLI's stdout,
+    // not attacker input, but garbage here would otherwise be trusted verbatim
+    // as `BatchEntry.worktree` and used as a spawn/exec cwd for every member.
+    const claimIsUsable = !!claimedWorktree &&
+        !claimedWorktree.includes('\0') &&
+        !claimedWorktree.includes('\n') &&
+        path.isAbsolute(claimedWorktree) &&
+        path.resolve(claimedWorktree) === claimedWorktree &&
+        (deps.fsExists ?? ((p) => fs.existsSync(p)))(claimedWorktree);
+    if (claimedWorktree && claimIsUsable) {
+        if (deps.exec('git', ['push', '-u', 'origin', '--', branch], claimedWorktree) === null) {
+            // Return the claim rather than leaking a permanently `assigned` pool
+            // entry nothing else will ever reference — `BatchEntry` only records
+            // `worktree`/`pool_claimed` on the `ok: true` path below.
+            deps.exec(teardown_1.POOL_BIN, [...teardown_1.POOL_ARGS_PREFIX, 'return', '--path', claimedWorktree, '--json'], deps.repoDir);
+            return { ok: false, reason: 'branch-push-failed', runId: mintedRunId };
+        }
+        return { ok: true, branch, worktree: claimedWorktree, runId: mintedRunId, poolClaimed: true };
+    }
+    // A non-null, non-empty, unusable claim response (rather than a plain "no
+    // warm spares" null/empty) is unusual enough to note on the batch that
+    // otherwise cold-builds silently.
+    const poolNote = claimedWorktree ? 'pool-claim-invalid:' : '';
     if (deps.exec('git', ['fetch', 'origin', '--', batch.base_branch], deps.repoDir) === null) {
         return { ok: false, reason: 'fetch-failed', runId: mintedRunId };
     }
@@ -269,7 +391,20 @@ function runBatchSetup(deps, batch, now) {
     if (deps.exec('git', ['worktree', 'add', '--', worktree, branch], deps.repoDir) === null) {
         return { ok: false, reason: 'worktree-add-failed', runId: mintedRunId };
     }
-    return { ok: true, branch, worktree, runId: mintedRunId };
+    const warmed = warmColdBatchWorktree(deps, batch, worktree, now, poolNote);
+    if (!warmed.ok) {
+        // Restore the "all-or-nothing" contract this function documents: a warm
+        // failure otherwise leaves the branch pushed and the worktree on disk,
+        // so the NEXT tick's retry dies at `branch-create-failed` forever
+        // instead of ever reaching warm-up again. Best-effort — a failed cleanup
+        // here just means the next retry's `worktree-add-failed`/`branch-create-failed`
+        // surfaces the leftover instead, no worse than before this cleanup existed.
+        deps.exec('git', ['worktree', 'remove', '--force', '--', worktree], deps.repoDir);
+        deps.exec('git', ['branch', '-D', branch], deps.repoDir);
+        deps.exec('git', ['push', 'origin', '--delete', branch], deps.repoDir);
+        return { ok: false, reason: warmed.reason, runId: mintedRunId };
+    }
+    return { ok: true, branch, worktree, runId: mintedRunId, poolClaimed: false };
 }
 /** Spawn one batch member's `slot-cycle` agent into the slot batch-setup (or a prior member) just released. */
 /**
@@ -422,7 +557,12 @@ function claimAndSetup(deps, config, dispatch, batchId, now, result) {
     poster(batch.anchor, setup.runId, {
         phase: 'batch-setup',
         status: 'done',
-        kv: { branch: setup.branch, worktree: setup.worktree, base_branch: batch.base_branch },
+        kv: {
+            branch: setup.branch,
+            worktree: setup.worktree,
+            base_branch: batch.base_branch,
+            pool_claimed: setup.poolClaimed ? 'true' : 'false',
+        },
     });
     deps.journal.append((0, journal_1.unitEvent)('batch-setup-done', unit(batchId), { detail: setup.worktree }), now);
     deps.store.withLock((s) => {
@@ -440,7 +580,12 @@ function claimAndSetup(deps, config, dispatch, batchId, now, result) {
             });
             return { state: releaseSlot(s, batchId, now), result: undefined };
         }
-        let next = (0, state_1.patchBatch)(s, batchId, { branch: setup.branch, worktree: setup.worktree, run_id: setup.runId }, now);
+        let next = (0, state_1.patchBatch)(s, batchId, {
+            branch: setup.branch,
+            worktree: setup.worktree,
+            run_id: setup.runId,
+            pool_claimed: setup.poolClaimed,
+        }, now);
         next = (0, state_1.transitionBatch)(next, batchId, 'executing', { executing_member: 1 }, now);
         const slot = slotFor(next, batchId);
         if (slot)
@@ -604,7 +749,7 @@ function runValidate(deps, config, dispatch, batchId, now, result) {
     if (!batch || batch.worktree === null)
         return;
     const suite = safeSuite(deps, batchId, batch.worktree);
-    const rDeps = recoveryDeps(deps, batch, now);
+    const rDeps = recoveryDeps(deps, config, batch, now);
     const poster = (0, recovery_1.createExecMilestonePoster)(deps.exec, { repoDir: deps.repoDir });
     if (suite.ok) {
         if (batch.anchor !== null && batch.run_id !== null) {
@@ -696,12 +841,12 @@ function runValidate(deps, config, dispatch, batchId, now, result) {
         return next;
     });
 }
-function evictOffender(deps, _config, batchId, offender, attribution, now, result) {
+function evictOffender(deps, config, batchId, offender, attribution, now, result) {
     const state = deps.store.load();
     const batch = (0, state_1.findBatch)(state, batchId);
     if (!batch)
         return;
-    const rDeps = recoveryDeps(deps, batch, now);
+    const rDeps = recoveryDeps(deps, config, batch, now);
     const outcome = (0, recovery_1.evictMembers)(state, batchId, { issues: [offender], reason: 'suite-red-after-fix', attribution, ranges: batch.ranges }, rDeps);
     deps.store.withLock((s) => ({
         state: applyBatchAndIssues(s, outcome.state, batchId, outcome.requeued),
@@ -757,7 +902,7 @@ function advanceMemberOrValidate(deps, config, dispatch, batchId, memberCount, c
  * (self-reported blocked, and the incremental gate below).
  */
 function evictMemberAndContinue(deps, config, dispatch, batchId, batch, memberIssue, reason, now, result) {
-    const dissolved = evictMemberDirectly(deps, batchId, memberIssue, reason, now);
+    const dissolved = evictMemberDirectly(deps, config, batchId, memberIssue, reason, now);
     if (dissolved) {
         result.failed.push(unit(batchId));
         return;
@@ -854,7 +999,8 @@ function reconcileMemberSlot(deps, config, dispatch, batchId, slot, now, result)
  * and a commit range to revert; a member evicted here has neither). Returns
  * whether the batch dissolved.
  */
-function evictMemberDirectly(deps, batchId, memberIssue, reason, now) {
+function evictMemberDirectly(deps, config, batchId, memberIssue, reason, now) {
+    const dissolvePolicy = (0, types_1.resolveDissolvePolicy)(config.dissolve_policy);
     // Pass 1 (pure — requeue + record the eviction): safe to run entirely
     // inside the lock, unlike `dissolveBatch` below, which shells out
     // (`deps.exec`/`postMilestone`) and so must NOT hold the lock while it runs.
@@ -886,7 +1032,10 @@ function evictMemberDirectly(deps, batchId, memberIssue, reason, now) {
             ],
         }, now);
         const updated = (0, state_1.findBatch)(next, batchId);
-        return { state: next, result: updated !== undefined && (0, recovery_1.checkDissolveTrigger)(updated) };
+        return {
+            state: next,
+            result: updated !== undefined && (0, recovery_1.checkDissolveTrigger)(updated, dissolvePolicy),
+        };
     });
     if (!triggered)
         return false;
@@ -897,7 +1046,7 @@ function evictMemberDirectly(deps, batchId, memberIssue, reason, now) {
     const batch = (0, state_1.findBatch)(state, batchId);
     if (!batch)
         return false;
-    const rDeps = recoveryDeps(deps, batch, now);
+    const rDeps = recoveryDeps(deps, config, batch, now);
     const outcome = (0, recovery_1.dissolveBatch)(state, batchId, { strategy: 'full', reason: 'eviction-threshold' }, rDeps);
     deps.store.withLock((s) => ({
         state: applyBatchAndIssues(s, outcome.state, batchId, outcome.requeued),
@@ -918,7 +1067,7 @@ function reconcileFixSlot(deps, config, batchId, slot, now, result) {
         return;
     deps.store.withLock((s) => ({ state: releaseSlot(s, batchId, now), result: undefined }));
     const suite = safeSuite(deps, batchId, batch.worktree);
-    const rDeps = recoveryDeps(deps, batch, now);
+    const rDeps = recoveryDeps(deps, config, batch, now);
     const { state: resolved } = (0, recovery_1.resolveFixAttempt)(deps.store.load(), batchId, offenderRecord.issue, suite.ok ? 'green' : 'red', rDeps);
     deps.store.withLock((s) => ({
         state: applyBatchAndIssues(s, resolved, batchId, []),
@@ -1064,14 +1213,18 @@ function teardownBatch(deps, batchId) {
     if (!batch || batch.worktree === null)
         return;
     const root = deps.exec('git', ['rev-parse', '--show-toplevel'], deps.repoDir) ?? deps.repoDir;
-    if (!(0, teardown_1.isSafeWorktree)(path.resolve(root), batch.worktree)) {
+    // Pool-claimed worktrees are validated by the pool's own `return` (it only
+    // accepts paths in pool state) and can legitimately live outside either
+    // `isSafeWorktree` root when `.worktree-pool.json` configures a custom
+    // `pool_dir` — mirrors `runTeardown`'s own internal skip for `poolClaimed`.
+    if (batch.pool_claimed !== true && !(0, teardown_1.isSafeWorktree)(path.resolve(root), batch.worktree)) {
         journalEvent(deps, 'teardown-failed', unit(batchId), {
             reason: 'unsafe-worktree-path',
             detail: batch.worktree,
         });
         return;
     }
-    const result = (0, teardown_1.runTeardown)(deps.exec, deps.repoDir, { worktree: batch.worktree, poolClaimed: false, branch: batch.branch }, deps.fsExists);
+    const result = (0, teardown_1.runTeardown)(deps.exec, deps.repoDir, { worktree: batch.worktree, poolClaimed: batch.pool_claimed === true, branch: batch.branch }, deps.fsExists);
     journalEvent(deps, result.cleanup === 'done' ? 'teardown-done' : 'teardown-failed', unit(batchId), {
         cleanup: result.cleanup,
         detail: result.detail,
@@ -1148,7 +1301,7 @@ function runBatchTick(deps, config, dispatch) {
                 ? [...b.fix_attempts].reverse().find((a) => a.outcome === 'dispatched')
                 : undefined;
             if (b && offenderRecord) {
-                const rDeps = recoveryDeps(deps, b, now);
+                const rDeps = recoveryDeps(deps, config, b, now);
                 const { state: resolved } = (0, recovery_1.resolveFixAttempt)(state, batch.id, offenderRecord.issue, 'red', rDeps);
                 deps.store.withLock((s) => ({
                     state: applyBatchAndIssues(s, resolved, batch.id, []),