@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/prompts.js

@@ -22,6 +22,19 @@ import { appendEvent } from './events.js';
  */
 export class PromptError extends SmithError {
 }
+/**
+ * True when `text` is harness-injected rather than something the operator
+ * typed: blank, or a record opening with one of the CLI's own tags (reminders,
+ * local and shell command echoes, task notifications, memory input, and a
+ * subagent's hand-back, which is model output delivered as a user turn). The
+ * one list, shared by the dashboard's reader and any writer of operator
+ * prompts.
+ */
+export function isHarnessText(text) {
+    const trimmed = text.trim();
+    return (trimmed === '' ||
+        /^<(system-reminder|local-command|command-message|bash-input|bash-stdout|bash-stderr|task-notification|user-memory-input|agent-message)/.test(trimmed));
+}
 /**
  * Append one `user_prompt`, returning the stored event.
  *

package/factory/orchestrator/dist/providers/schema-validate.js

@@ -93,7 +93,7 @@ export function extractBalancedJson(text) {
 /**
  * Schemas that describe ONE item a `kind: review` judge returns MANY of. Both
  * of them: `finding` is the stored record (the native reviewer's contract,
- * .claude/agents/reviewer.md), `finding-evidence` is the judge's half of it —
+ * .claude/agents/bs-reviewer.md), `finding-evidence` is the judge's half of it —
  * the same evidence without the six identity fields the orchestrator owns.
  * A set, not a comparison, because the second entry was added a year after the
  * first and the `=== 'finding'` it replaced would have silently validated an
@@ -136,7 +136,7 @@ function describeShape(parsed) {
 /**
  * Extract + schema-validate a judge's raw text response. `finding.schema.json`
  * describes ONE finding, but a `kind: review` judge's contract
- * (.claude/agents/reviewer.md) returns an ARRAY of findings — so against an
+ * (.claude/agents/bs-reviewer.md) returns an ARRAY of findings — so against an
  * ARRAY_VALUED_SCHEMAS name the top-level value must be that array, bare or
  * wrapped in one single-key object (see `unwrapArray`), and validates
  * element-wise; the value returned is the array itself, unwrapped. A bare

package/factory/orchestrator/dist/providers/types.js

@@ -1,7 +1,7 @@
 // Provider-agnostic judge contract (architecture §6): "any model that can
 // honor the I/O contract can serve" — a JudgeRequest is a plain diff+spec+
 // prior-findings prompt already assembled by the caller from
-// .claude/agents/{reviewer,verifier}.md's own contract, plus a schema
+// .claude/agents/bs-{reviewer,verifier}.md's own contract, plus a schema
 // name the extracted response is validated against. Transports never see
 // more than `prompt` — the trust boundary (architecture §6 "External
 // providers judge; they never gain write access... their findings are

package/factory/orchestrator/dist/queue.js

@@ -1,14 +1,17 @@
 import { execFileSync } from 'node:child_process';
-import { collectCommittedChanges } from './claims.js';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { claimsOverlap, collectCommittedChanges, touchesSerializeAlways } from './claims.js';
 import { certifyCommit, UNCOMMITTED_WORK_CODE } from './commit.js';
 import { SmithError } from './errors.js';
-import { runGit } from './git.js';
+import { validateEventEnvelope } from './events.js';
+import { runGit, runGitRaw, writeMergeTree } from './git.js';
 import { topoSort } from './graph.js';
 import { buildSymbolGraph, collectSources } from './symbols.js';
 import { emitTaskBlocked, emitWaveMerged } from './taskEvents.js';
 import { projectCommandEnv } from './testgate.js';
 import { renderSelectedTestCmd, selectTests } from './testSelect.js';
-import { integrationBranchName } from './worktree.js';
+import { epicBranchPrefix, integrationBranchName } from './worktree.js';
 export class QueueError extends SmithError {
 }
 /**
@@ -23,6 +26,67 @@ export function admit(tasks, edges = []) {
     }
     return result.order;
 }
+/**
+ * Split an admitted order into maximal runs of consecutive tasks a batch
+ * step can stack into one candidate and test once (roadmap `merge-lanes`;
+ * the batching idea is Zuul's shared-queue gating and Mergify's batch/bisect,
+ * https://zuul-ci.org/docs/zuul/latest/gating.html,
+ * https://docs.mergify.com/merge-queue/batches/).
+ *
+ * Greedy, left to right, one open group at a time: a task joins the open
+ * group when its claims are disjoint from every member already in it and it
+ * does not depend_on one of them; otherwise the open group closes and the
+ * task starts the next one. Three conditions never even get a chance to
+ * join a group — they close whatever is open and are appended as a group of
+ * one, closed immediately, so a task after them starts fresh rather than
+ * silently inheriting their neighbours:
+ *   - no claims at all (nothing to prove disjoint, so nothing to batch with);
+ *   - a claim a serialize-always glob covers (worktree.yml already refuses to
+ *     run these concurrently; batching would silently defeat that refusal);
+ *   - depends_on a task that is anywhere in the walk before it — conservative
+ *     on purpose: batching a dependency chain has not been proven safe here,
+ *     even though the chain would still test together inside one group.
+ */
+export function groupForBatch(tasks, edges = [], serializeAlwaysGlobs = []) {
+    const dependsOn = new Map();
+    for (const edge of edges) {
+        if (!dependsOn.has(edge.task))
+            dependsOn.set(edge.task, new Set());
+        dependsOn.get(edge.task).add(edge.dependsOn);
+    }
+    const byId = new Map(tasks.map((t) => [t.taskId, t]));
+    const groups = [];
+    let current = [];
+    for (const task of tasks) {
+        const claims = task.claims ?? [];
+        const hasClaims = claims.length > 0;
+        const isSerializeAlways = hasClaims && touchesSerializeAlways({ claims }, serializeAlwaysGlobs).length > 0;
+        if (!hasClaims || isSerializeAlways) {
+            if (current.length > 0)
+                groups.push(current);
+            groups.push([task.taskId]);
+            current = [];
+            continue;
+        }
+        const deps = dependsOn.get(task.taskId);
+        const dependsOnGroupMember = deps !== undefined && current.some((id) => deps.has(id));
+        const overlapsGroupMember = current.some((id) => {
+            const member = byId.get(id);
+            const memberClaims = member?.claims ?? [];
+            return (memberClaims.length > 0 && claimsOverlap({ claims }, { claims: memberClaims }).overlaps);
+        });
+        if (dependsOnGroupMember || overlapsGroupMember) {
+            groups.push(current);
+            current = [task.taskId];
+        }
+        else {
+            current.push(task.taskId);
+        }
+    }
+    if (current.length > 0)
+        groups.push(current);
+    return groups;
+}
 const OUTPUT_TAIL_LINES = 50;
 function tailLines(text, n) {
     const lines = text.split('\n');
@@ -36,34 +100,21 @@ function conflictingFiles(worktreeDir) {
         .filter((f) => f.length > 0);
 }
 /**
- * Serial merge-queue admission step for one task: rebase its branch onto the
- * current epic integration head, run the epic's test command, then
- * merge --no-ff into the integration branch. Never auto-resolves a conflict
- * and never touches main — the caller decides what happens next on a
- * non-merged outcome.
+ * Certify there is a commit to merge (D-30/P9-8) and rebase the task's
+ * branch onto the current integration head. Returns the blocked outcome when
+ * either refuses, or null when the branch is ready to test — shared by
+ * `step` and the batch path (`runGroup`) so a task that cannot even be
+ * rebased fails exactly the same way whether it is running alone or as part
+ * of a group.
  */
-export async function step(task, opts) {
-    const integrationBranch = integrationBranchName(opts.epic);
-    const events = opts.events;
-    /**
-     * Log the outcome the queue just observed — a refusal it has already decided
-     * on, or a failure it has already seen. Never a prediction about work still
-     * ahead of it: an event written before the merge that the merge then
-     * falsifies is exactly the phantom row D-46 is about.
-     */
-    const logBlocked = async (error, detail) => {
-        if (!events)
-            return;
-        const { ctx, ...opt } = events;
-        await emitTaskBlocked(task.taskId, { error, severity: 'S2-major', detail }, ctx, opt);
-    };
+async function certifyAndRebase(task, integrationBranch, logBlocked) {
     // Before the rebase, because a rebase, a test run and a merge all "succeed"
     // against a branch that carries nothing: certify that there is a commit to
     // merge at all (D-30/P9-8). A task that merges nothing is a bug, not a pass.
     const commit = certifyCommit(task.worktreeDir, { baseRef: integrationBranch });
     if (!commit.certified) {
         const reason = commit.reason;
-        await logBlocked(reason === 'not-a-git-worktree' ? 'execution.env-failure' : UNCOMMITTED_WORK_CODE, commit.dirty.length > 0
+        await logBlocked(task.taskId, reason === 'not-a-git-worktree' ? 'execution.env-failure' : UNCOMMITTED_WORK_CODE, commit.dirty.length > 0
             ? `${task.branch} has uncommitted work: ${commit.dirty.join(', ')}`
             : `${task.branch} has nothing to merge into ${integrationBranch} (${reason}).`);
         return { outcome: 'nothing-to-merge', taskId: task.taskId, reason, dirty: commit.dirty };
@@ -77,14 +128,50 @@ export async function step(task, opts) {
     catch {
         const files = conflictingFiles(task.worktreeDir);
         execFileSync('git', ['rebase', '--abort'], { cwd: task.worktreeDir, stdio: 'pipe' });
-        await logBlocked('integration.merge-conflict-textual', `Rebase onto ${integrationBranch} conflicted in: ${files.join(', ')}`);
+        await logBlocked(task.taskId, 'integration.merge-conflict-textual', `Rebase onto ${integrationBranch} conflicted in: ${files.join(', ')}`);
         return { outcome: 'rebase-conflict', taskId: task.taskId, conflictingFiles: files };
     }
+    return null;
+}
+/**
+ * Serial merge-queue admission step for one task: rebase its branch onto the
+ * current epic integration head, run the epic's test command, then
+ * merge --no-ff into the integration branch. Never auto-resolves a conflict
+ * and never touches main — the caller decides what happens next on a
+ * non-merged outcome.
+ */
+export async function step(task, opts) {
+    const integrationBranch = integrationBranchName(opts.epic, epicBranchPrefix(opts.projectDir, opts.epic));
+    const events = opts.events;
+    // Refused before certifyAndRebase's real `git rebase` or the merge below
+    // ever runs: both mutate git for real, and used to be discovered only by
+    // the append at the far end (emitWaveMerged/emitTaskBlocked). A merge that
+    // already landed by the time that append throws is a merge the log cannot
+    // see — a real incident, not a hypothetical one.
+    if (events) {
+        const { ctx, ...opt } = events;
+        await validateEventEnvelope({ session_id: ctx.sessionId, event_type: 'wave-merged', causal_parent: ctx.causalParent }, opt);
+    }
+    /**
+     * Log the outcome the queue just observed — a refusal it has already decided
+     * on, or a failure it has already seen. Never a prediction about work still
+     * ahead of it: an event written before the merge that the merge then
+     * falsifies is exactly the phantom row D-46 is about.
+     */
+    const logBlocked = async (taskId, error, detail) => {
+        if (!events)
+            return;
+        const { ctx, ...opt } = events;
+        await emitTaskBlocked(taskId, { error, severity: 'S2-major', detail }, ctx, opt);
+    };
+    const early = await certifyAndRebase(task, integrationBranch, logBlocked);
+    if (early)
+        return early;
     const plan = planTestRun(task.worktreeDir, opts);
     const testOutcome = runTestCmd(plan.cmd, task.worktreeDir);
     if (!testOutcome.passed) {
         const outputTail = tailLines(testOutcome.output, OUTPUT_TAIL_LINES);
-        await logBlocked('execution.test-failure', outputTail);
+        await logBlocked(task.taskId, 'execution.test-failure', outputTail);
         return {
             outcome: 'tests-failed',
             taskId: task.taskId,
@@ -92,14 +179,368 @@ export async function step(task, opts) {
             ...(plan.report ? { tests: plan.report } : {}),
         };
     }
-    execFileSync('git', ['checkout', integrationBranch], { cwd: opts.projectDir, stdio: 'pipe' });
-    execFileSync('git', ['merge', '--no-ff', task.branch, '-m', `Merge ${task.taskId} into ${integrationBranch}`], { cwd: opts.projectDir, stdio: 'pipe' });
+    // Merge where the integration branch already lives, or with no working tree
+    // at all — never by `git checkout` in the project directory, which moved
+    // the operator's own clone off the branch they were using.
+    const message = `Merge ${task.taskId} into ${integrationBranch}`;
+    const holder = worktreeHolding(opts.projectDir, integrationBranch);
+    if (holder === null) {
+        mergeWithoutWorktree(opts.projectDir, integrationBranch, task.branch, message);
+    }
+    else {
+        // A merge into a worktree with edits in it either stops half-way or folds
+        // someone's unfinished work into the merge's checkout; neither is ours.
+        const dirty = trackedChanges(holder);
+        if (dirty.length > 0) {
+            await logBlocked(task.taskId, 'execution.env-failure', `${integrationBranch} is checked out in ${holder}, which has uncommitted changes: ${dirty.join(', ')}`);
+            return {
+                outcome: 'integration-dirty',
+                taskId: task.taskId,
+                worktree: holder,
+                dirty,
+                ...(plan.report ? { tests: plan.report } : {}),
+            };
+        }
+        execFileSync('git', ['merge', '--no-ff', task.branch, '-m', message], {
+            cwd: holder,
+            stdio: 'pipe',
+        });
+    }
     if (events) {
         const { ctx, ...opt } = events;
-        await emitWaveMerged(task.taskId, ctx, opt, mergedFiles(opts.projectDir));
+        await emitWaveMerged(task.taskId, ctx, opt, mergedFiles(opts.projectDir, integrationBranch));
     }
     return { outcome: 'merged', taskId: task.taskId, ...(plan.report ? { tests: plan.report } : {}) };
 }
+/**
+ * The worktree (the main one or any linked one) that has `branch` checked
+ * out, or null when none does. git refuses to check a branch out in two
+ * worktrees at once, so there is at most one. An entry git marks `prunable`
+ * — its directory is gone — holds nothing: there is no checkout to merge in,
+ * and moving the branch under it harms nothing. It is not pruned here either;
+ * the operator's worktree registrations are theirs (architecture §18 rule 10).
+ */
+function worktreeHolding(projectDir, branch) {
+    const ref = `branch refs/heads/${branch}`;
+    const records = runGitRaw(projectDir, ['worktree', 'list', '--porcelain', '-z']).split('\0\0');
+    for (const record of records) {
+        const lines = record.split('\0');
+        const dir = lines.find((l) => l.startsWith('worktree '));
+        if (dir === undefined || !lines.includes(ref))
+            continue;
+        if (lines.some((l) => l === 'prunable' || l.startsWith('prunable ')))
+            continue;
+        return dir.slice('worktree '.length);
+    }
+    return null;
+}
+/** Tracked paths with staged or unstaged changes. Untracked files never block a merge. */
+function trackedChanges(worktreeDir) {
+    const fields = runGitRaw(worktreeDir, [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--untracked-files=no',
+    ]).split('\0');
+    const paths = [];
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i];
+        if (field.length < 4)
+            continue;
+        paths.push(field.slice(3));
+        // A rename or copy carries its source path as the next NUL field.
+        if (field[0] === 'R' || field[0] === 'C')
+            i++;
+    }
+    return paths;
+}
+/**
+ * Merge `source` into `branch` with plumbing alone, for when no worktree has
+ * `branch` checked out: `merge-tree --write-tree` builds the merged tree,
+ * `commit-tree` makes the two-parent merge commit (author and committer from
+ * git config, as `git merge` would), and `update-ref` moves `branch` only if
+ * it still points where the merge started.
+ *
+ * No working tree means no commit hook runs — deliberately: the queue is
+ * plumbing, and the gate runs the suite. It also means nothing is added to,
+ * removed from or pruned out of the repository's worktree list.
+ *
+ * A conflict throws, and so does a `branch` that moved during the merge;
+ * either way `branch` is left where it was.
+ */
+/** `merge-tree --write-tree` + `commit-tree`, the two-parent merge commit
+ * alone — no ref touched. Shared by `mergeWithoutWorktree` (one task, lands
+ * immediately) and `attemptCandidate` (N tasks, chained, lands only once at
+ * the end). */
+function buildMergeCommit(projectDir, base, head, message) {
+    const tree = writeMergeTree(projectDir, base, head);
+    return runGit(projectDir, ['commit-tree', tree, '-p', base, '-p', head, '-m', message]);
+}
+function mergeWithoutWorktree(projectDir, branch, source, message) {
+    const base = runGit(projectDir, ['rev-parse', '--verify', `refs/heads/${branch}^{commit}`]);
+    const head = runGit(projectDir, ['rev-parse', '--verify', `${source}^{commit}`]);
+    const commit = buildMergeCommit(projectDir, base, head, message);
+    runGit(projectDir, ['update-ref', '-m', message, `refs/heads/${branch}`, commit, base]);
+}
+function landCandidate(projectDir, integrationBranch, base, candidate, message) {
+    const holder = worktreeHolding(projectDir, integrationBranch);
+    if (holder === null) {
+        try {
+            runGit(projectDir, [
+                'update-ref',
+                '-m',
+                message,
+                `refs/heads/${integrationBranch}`,
+                candidate,
+                base,
+            ]);
+        }
+        catch {
+            return { outcome: 'integration-moved' };
+        }
+        return { outcome: 'landed' };
+    }
+    const dirty = trackedChanges(holder);
+    if (dirty.length > 0) {
+        return { outcome: 'integration-dirty', worktree: holder, dirty };
+    }
+    try {
+        execFileSync('git', ['merge', '--ff-only', candidate], { cwd: holder, stdio: 'pipe' });
+    }
+    catch {
+        return { outcome: 'integration-moved' };
+    }
+    return { outcome: 'landed' };
+}
+/**
+ * Report `tasks` as blocked by an `integration-dirty` refusal already
+ * observed elsewhere — the dirty holder's own outcome (`attemptCandidate`'s
+ * landing) or a sibling half's (`bisectGroup`, once one half has found
+ * nothing can land). Shared so every task the batch touches gets the same
+ * outcome shape and log line regardless of which call site saw the dirty
+ * worktree first.
+ */
+async function dirtyOutcomes(tasks, landing, integrationBranch, logBlocked) {
+    const outcomes = [];
+    for (const task of tasks) {
+        await logBlocked(task.taskId, 'execution.env-failure', `${integrationBranch} is checked out in ${landing.worktree}, which has uncommitted changes: ${landing.dirty.join(', ')}`);
+        outcomes.push({
+            outcome: 'integration-dirty',
+            taskId: task.taskId,
+            worktree: landing.worktree,
+            dirty: landing.dirty,
+        });
+    }
+    return outcomes;
+}
+/**
+ * A scratch worktree for testing a batch candidate before anything lands —
+ * a sibling of the project, the same convention `taskWorktreeDir` uses, but
+ * named so it can never collide with a real task id or the reserved
+ * `integration` one: nothing outside this function should ever address it.
+ */
+function batchCandidateWorktreeDir(projectDir) {
+    const project = path.resolve(projectDir);
+    return path.join(path.dirname(project), '.wt', path.basename(project), `batch-${randomUUID()}`);
+}
+/**
+ * Fold `readyTasks` onto the current integration head with git plumbing
+ * alone (no worktree, no branch touched until the very end), test the result
+ * once in a throwaway detached worktree, and either land it with one
+ * compare-and-swap or bisect it. `readyTasks` have already been certified and
+ * rebased by the caller (`runGroup`) — this only builds, tests and lands.
+ */
+async function attemptCandidate(readyTasks, opts, integrationBranch, logBlocked, 
+/**
+ * Set by the caller when it already knows this exact set is guilty of a
+ * red parent — the sibling half of a bisection whose other half landed
+ * clean. Skips the group's own suite run for 2+ tasks (there is nothing
+ * left to learn from testing a candidate already known red) and goes
+ * straight to splitting it further. A single task still runs, because its
+ * own failure output tail is the thing the caller reports.
+ */
+knownRed = false) {
+    if (knownRed && readyTasks.length >= 2) {
+        return bisectGroup(readyTasks, opts, integrationBranch, logBlocked);
+    }
+    const projectDir = opts.projectDir;
+    const base = runGit(projectDir, [
+        'rev-parse',
+        '--verify',
+        `refs/heads/${integrationBranch}^{commit}`,
+    ]);
+    // Chain each task's merge onto the last, exactly like `mergeWithoutWorktree`
+    // does for one task — `merge-tree` computes its own merge-base from the two
+    // commits it is given, and since every task was rebased onto `base` (not
+    // onto each other), that merge-base is `base` at every step. Claim-disjoint
+    // tasks (groupForBatch's contract) fold without conflict; a fold that does
+    // conflict anyway throws, same as a single-task merge conflict would.
+    let head = base;
+    const foldCommits = new Map();
+    for (const task of readyTasks) {
+        const source = runGit(projectDir, ['rev-parse', '--verify', `${task.branch}^{commit}`]);
+        const message = `Merge ${task.taskId} into ${integrationBranch}`;
+        head = buildMergeCommit(projectDir, head, source, message);
+        foldCommits.set(task.taskId, head);
+    }
+    const candidate = head;
+    const worktreeDir = batchCandidateWorktreeDir(projectDir);
+    runGit(projectDir, ['worktree', 'add', '--detach', worktreeDir, candidate]);
+    let testOutcome;
+    try {
+        testOutcome = runTestCmd(opts.testCmd, worktreeDir);
+    }
+    finally {
+        // Always removed, including on error — this worktree exists only to run
+        // one suite once and has no meaning once that suite has an answer.
+        runGit(projectDir, ['worktree', 'remove', '--force', worktreeDir]);
+    }
+    if (testOutcome.passed) {
+        const message = `Batch-merge ${readyTasks.map((t) => t.taskId).join(', ')} into ${integrationBranch}`;
+        const landing = landCandidate(projectDir, integrationBranch, base, candidate, message);
+        if (landing.outcome === 'integration-dirty') {
+            // Mirrors `step`'s own refusal: a worktree holds the integration
+            // branch and carries uncommitted tracked changes, so merging into it
+            // either stops half-way or folds someone's unfinished work in. The
+            // tests already ran and passed; nothing landed.
+            const outcomes = await dirtyOutcomes(readyTasks, landing, integrationBranch, logBlocked);
+            return { outcomes, suiteRuns: 1 };
+        }
+        if (landing.outcome === 'integration-moved') {
+            // The ref moved under the batch between the candidate's build and its
+            // land — D-46's compare-and-swap race, the same one a single task's
+            // `mergeWithoutWorktree` throws on, just reachable here with a whole
+            // group under test at once. Nothing landed, so every ready task
+            // reports it rather than one throw swallowing the rest of the group.
+            const outcomes = [];
+            for (const task of readyTasks) {
+                await logBlocked(task.taskId, 'execution.env-failure', `${integrationBranch} moved to a different commit while this batch was testing; nothing landed.`);
+                outcomes.push({ outcome: 'integration-moved', taskId: task.taskId });
+            }
+            return { outcomes, suiteRuns: 1 };
+        }
+        const outcomes = [];
+        for (const task of readyTasks) {
+            const commit = foldCommits.get(task.taskId);
+            if (opts.events) {
+                const { ctx, ...opt } = opts.events;
+                // This task's own merge commit against its own first parent — not
+                // the integration tip, which by now carries every task in the batch.
+                await emitWaveMerged(task.taskId, ctx, opt, mergedFiles(projectDir, commit));
+            }
+            outcomes.push({ outcome: 'merged', taskId: task.taskId });
+        }
+        return { outcomes, suiteRuns: 1 };
+    }
+    // Red. A lone task's failure is a genuine test failure, reported exactly as
+    // `step` reports one. Two or more: bisect — Zuul's shared-queue gating and
+    // Mergify's batch/bisect (cited at groupForBatch) — rather than fail every
+    // task in the group for one task's sake: split, recurse on the left half,
+    // then recurse on the right half. `runGroup` re-certifies and re-rebases
+    // each half against whatever the integration head is when its turn comes,
+    // which is what makes "land the innocent half, then retest the guilty one
+    // rebuilt on the new head" and "the left half was itself red, so it
+    // recursed, and only then did the right half get its own turn" the same
+    // code path: the right half's `runGroup` call sees the left half's result
+    // simply because it starts after the left half's `await` returns.
+    if (readyTasks.length === 1) {
+        const task = readyTasks[0];
+        const outputTail = tailLines(testOutcome.output, OUTPUT_TAIL_LINES);
+        await logBlocked(task.taskId, 'execution.test-failure', outputTail);
+        return {
+            outcomes: [{ outcome: 'tests-failed', taskId: task.taskId, outputTail }],
+            suiteRuns: 1,
+        };
+    }
+    const bisected = await bisectGroup(readyTasks, opts, integrationBranch, logBlocked);
+    return { outcomes: bisected.outcomes, suiteRuns: 1 + bisected.suiteRuns };
+}
+/**
+ * Split a red (or known-red) group in half and recurse on each — the shared
+ * tail of `attemptCandidate`'s red path, factored out so a known-red group
+ * can jump straight here without spending a suite run to relearn what the
+ * caller already knows. `left` runs with no assumption of its own; when it
+ * comes back fully merged, the failure cannot be in it, so `right` is
+ * dispatched already known red (`runGroup`, ready.length >= 2 skips its own
+ * test the same way).
+ */
+async function bisectGroup(readyTasks, opts, integrationBranch, logBlocked) {
+    const mid = Math.ceil(readyTasks.length / 2);
+    const left = await runGroup(readyTasks.slice(0, mid), opts, integrationBranch, logBlocked);
+    // Once anything has hit integration-dirty, nothing can land regardless of
+    // what the right half's suite says — the checkout stays dirty until an
+    // operator clears it — so report the right half the same way instead of
+    // spending a suite run (or more bisection) to learn that.
+    const dirty = left.outcomes.find((o) => o.outcome === 'integration-dirty');
+    if (dirty) {
+        const rightOutcomes = await dirtyOutcomes(readyTasks.slice(mid), dirty, integrationBranch, logBlocked);
+        return { outcomes: [...left.outcomes, ...rightOutcomes], suiteRuns: left.suiteRuns };
+    }
+    const rightKnownRed = left.outcomes.every((o) => o.outcome === 'merged');
+    const right = await runGroup(readyTasks.slice(mid), opts, integrationBranch, logBlocked, rightKnownRed);
+    return {
+        outcomes: [...left.outcomes, ...right.outcomes],
+        suiteRuns: left.suiteRuns + right.suiteRuns,
+    };
+}
+/**
+ * Certify and rebase every task in the group, then fold whatever survives
+ * into one candidate via `attemptCandidate` — recursing through
+ * `attemptCandidate` on a red candidate. Order-preserving: a task's outcome
+ * lands at its own position in the returned array no matter which half of a
+ * bisection (or neither — a certify/rebase refusal) produced it, so the
+ * caller can print outcomes in admitted order the same way `step` does.
+ */
+async function runGroup(tasks, opts, integrationBranch, logBlocked, knownRed = false) {
+    if (tasks.length === 0)
+        return { outcomes: [], suiteRuns: 0 };
+    const byTaskId = new Map();
+    const ready = [];
+    for (const task of tasks) {
+        const early = await certifyAndRebase(task, integrationBranch, logBlocked);
+        if (early)
+            byTaskId.set(task.taskId, early);
+        else
+            ready.push(task);
+    }
+    let suiteRuns = 0;
+    if (ready.length > 0) {
+        const result = await attemptCandidate(ready, opts, integrationBranch, logBlocked, knownRed);
+        suiteRuns = result.suiteRuns;
+        for (const outcome of result.outcomes)
+            byTaskId.set(outcome.taskId, outcome);
+    }
+    return { outcomes: tasks.map((t) => byTaskId.get(t.taskId)), suiteRuns };
+}
+/**
+ * The batch equivalent of `step`, for a group of two or more claim-disjoint
+ * tasks (`groupForBatch` decides the grouping; a group of one should just
+ * call `step`). Rebases each task in its own worktree exactly as `step`
+ * does, stacks the survivors into one candidate with git plumbing alone (no
+ * worktree touches the project checkout, no branch moves until the end), and
+ * runs the test command once against it. Green lands the whole candidate
+ * with one compare-and-swap; red bisects (see `attemptCandidate`) instead of
+ * failing every task in the group for one task's sake.
+ */
+export async function batchStep(tasks, opts) {
+    const integrationBranch = integrationBranchName(opts.epic, epicBranchPrefix(opts.projectDir, opts.epic));
+    const events = opts.events;
+    // Same envelope check as step(), and for the same reason: runGroup below
+    // rebases and merges real git state for every task in the group before its
+    // first append. The causal_parent is one value for the whole batch call, so
+    // one check here, before runGroup starts, covers it.
+    if (events) {
+        const { ctx, ...opt } = events;
+        await validateEventEnvelope({ session_id: ctx.sessionId, event_type: 'wave-merged', causal_parent: ctx.causalParent }, opt);
+    }
+    const logBlocked = async (taskId, error, detail) => {
+        if (!events)
+            return;
+        const { ctx, ...opt } = events;
+        await emitTaskBlocked(taskId, { error, severity: 'S2-major', detail }, ctx, opt);
+    };
+    return runGroup(tasks, opts, integrationBranch, logBlocked);
+}
 /** The commit `ref` names, or null when it names nothing (or nothing committish). */
 function resolveCommit(projectDir, ref) {
     try {
@@ -141,7 +582,7 @@ function isAncestor(projectDir, ancestor, descendant) {
  */
 export async function adopt(task, opts) {
     const { projectDir } = opts;
-    const integrationBranch = integrationBranchName(opts.epic);
+    const integrationBranch = integrationBranchName(opts.epic, epicBranchPrefix(projectDir, opts.epic));
     for (const ref of [integrationBranch, task.branch]) {
         if (!resolveCommit(projectDir, ref)) {
             throw new QueueError('queue.adopt-unknown-branch', `Branch "${ref}" does not exist in ${projectDir} — there is nothing to adopt against.`, { branch: ref, taskId: task.taskId });