@hecer/yoke 1.2.1 → 1.4.0

package/dist/loop/loop.js

@@ -1,10 +1,12 @@
 import { existsSync, unlinkSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
+import { isAcceptanceCriterion, loadPrd, savePrd, selectNextStory, allPass, progress, storyPathSegment } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
 import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
 import { consumeDecisionRequest } from './decision.js';
+import { writeCriterionEvidence } from './evidence.js';
+import { runQualityRepairLoop } from '../quality/loop.js';
 function blockReason(base, targetDir, git) {
     let dirty = false;
     try {
@@ -15,11 +17,93 @@ function blockReason(base, targetDir, git) {
         ? `${base} (working tree has uncommitted changes from the blocked story — review/clean before re-running)`
         : base;
 }
+function reviewOutcome(result) {
+    if (result.reviewOutcome)
+        return result.reviewOutcome;
+    if (result.success) {
+        return { kind: 'approved', verdict: { approved: true, summary: result.summary, findings: [] } };
+    }
+    return { kind: 'malformed', summary: result.summary };
+}
+function repairBlockReason(outcome, story, targetDir, git) {
+    if (outcome.kind === 'approved' || outcome.kind === 'paused' || outcome.kind === 'cancelled')
+        return null;
+    const detail = outcome.summary ? `: ${outcome.summary}` : '';
+    const stage = outcome.reason === 'gate-failed' ? ` (${outcome.stage})` : '';
+    return blockReason(`story ${story.id} repair blocked${stage}: ${outcome.reason}${detail}`, targetDir, git);
+}
+function runQualityReview(opts, executionDir, story, reporter) {
+    const qualityAssessment = opts.qualityEnabled?.(story) === false ? undefined : opts.qualityStage;
+    const reviewAssessment = opts.review;
+    if (!qualityAssessment && !reviewAssessment)
+        return null;
+    const qualityMetadata = opts.qualityMetadata?.({ targetDir: executionDir, story });
+    const rerunGates = () => {
+        const criteria = runCriterionGates(opts, executionDir, story);
+        if (!criteria.passed)
+            return { kind: 'failed', stage: 'criterion', summary: criteria.summary };
+        reporter.phase('verifying');
+        const verify = runGate(opts.verify, executionDir, story.id);
+        if (!verify.passed)
+            return { kind: 'failed', stage: 'verify', summary: verify.summary };
+        if (opts.perf) {
+            reporter.phase('perf');
+            const perf = runGate(opts.perf, executionDir, story.id);
+            if (!perf.passed)
+                return { kind: 'failed', stage: 'perf', summary: perf.summary };
+        }
+        if (opts.audit) {
+            reporter.phase('audit');
+            const audit = runGate(opts.audit, executionDir, story.id);
+            if (!audit.passed)
+                return { kind: 'failed', stage: 'audit', summary: audit.summary };
+        }
+        return { kind: 'passed' };
+    };
+    return runQualityRepairLoop({
+        quality: qualityAssessment
+            ? round => {
+                reporter.phase('comparing');
+                return qualityAssessment({ targetDir: executionDir, story }, round);
+            }
+            : undefined,
+        review: reviewAssessment
+            ? () => {
+                reporter.phase('reviewing');
+                return reviewOutcome(reviewAssessment({ targetDir: executionDir, story }));
+            }
+            : undefined,
+        repair: request => {
+            reporter.phase('repairing');
+            if (!opts.repair)
+                return { kind: 'blocked', summary: 'repair callback is not configured' };
+            const result = opts.repair({ targetDir: executionDir, story }, request);
+            return result.success ? { kind: 'repaired' } : { kind: 'blocked', summary: result.summary };
+        },
+        rerunGates,
+        limits: opts.repairLimits,
+        pause: () => consumePause(opts.targetDir),
+        onStatus: status => {
+            if (qualityMetadata)
+                reporter.quality({ ...status, ...qualityMetadata });
+        },
+    });
+}
 // Control file a supervisor drops to pause the loop at the next story boundary.
 // The loop consumes (deletes) it and stops with state 'paused' — never mid-story.
 export function pauseFilePath(targetDir) {
     return join(targetDir, '.yoke', 'loop.pause');
 }
+function consumePause(targetDir) {
+    const file = pauseFilePath(targetDir);
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+    }
+    catch { /* consumed best-effort — pausing still wins */ }
+    return true;
+}
 // Abort channel for an agent that hits genuinely undecidable acceptance criteria
 // (only instructed to use it under loop.onAmbiguity: abort). Honoured whenever
 // present: without this check, an agent that stopped without changes would sail
@@ -58,53 +142,152 @@ function consumeAmbiguity(dir) {
     const compact = content.replace(/\s+/g, ' ').trim().slice(0, 500);
     return compact || 'agent reported ambiguous acceptance criteria without details';
 }
+function runCompletionGate(opts, stories) {
+    if (!opts.completion)
+        return null;
+    const previous = process.env.YOKE_PHASE;
+    process.env.YOKE_PHASE = 'completion';
+    let verdict;
+    try {
+        verdict = opts.completion(opts.targetDir);
+    }
+    catch (error) {
+        const reason = `integrated completion gate failed: ${error.message}`;
+        (opts.reporter ?? noopReporter).blocked(reason);
+        return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.YOKE_PHASE;
+        else
+            process.env.YOKE_PHASE = previous;
+    }
+    if (verdict.passed)
+        return null;
+    const reason = `integrated system did not verify: ${verdict.summary}`;
+    (opts.reporter ?? noopReporter).blocked(reason);
+    return { status: 'blocked', iterations: 0, reason, finalProgress: progress(stories) };
+}
+function runCriterionGates(opts, executionDir, story) {
+    const criteria = story.acceptance.filter(isAcceptanceCriterion);
+    if (criteria.length === 0) {
+        return opts.requireCriterionEvidence
+            ? { passed: false, summary: `story ${story.id} lacks executable criterion evidence` }
+            : { passed: true, summary: 'legacy acceptance criteria' };
+    }
+    if (!opts.verifyCriterion)
+        return { passed: false, summary: `story ${story.id} has criteria but no criterion verifier` };
+    const evidence = criteria.map(criterion => ({
+        criterion,
+        result: opts.verifyCriterion(executionDir, story, criterion),
+    }));
+    try {
+        writeCriterionEvidence(opts.targetDir, story, evidence);
+    }
+    catch (error) {
+        return { passed: false, summary: `could not persist criterion evidence: ${error.message}` };
+    }
+    const failed = evidence.find(item => !item.result.passed);
+    return failed
+        ? { passed: false, summary: `${failed.criterion.id}: ${failed.result.summary}` }
+        : { passed: true, summary: `${evidence.length} acceptance criteria verified` };
+}
 export function runLoop(opts) {
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
-    const initial = loadPrd(opts.prdPath);
-    if (initial.length === 0) {
-        reporter.blocked('PRD has no stories');
-        return { status: 'blocked', iterations: 0, reason: 'PRD has no stories', finalProgress: { passed: 0, total: 0 } };
-    }
     for (;;) {
-        const stories = loadPrd(opts.prdPath);
-        if (allPass(stories)) {
-            reporter.complete(progress(stories));
-            return { status: 'complete', iterations, finalProgress: progress(stories) };
+        let stories = loadPrd(opts.prdPath);
+        if (stories.length === 0) {
+            reporter.blocked('PRD has no stories');
+            return { status: 'blocked', iterations, reason: 'PRD has no stories', finalProgress: { passed: 0, total: 0 } };
         }
-        if (iterations >= opts.maxIterations) {
+        const capReached = iterations >= opts.maxIterations;
+        if (capReached && !allPass(stories)) {
             reporter.capReached(progress(stories));
             return { status: 'cap-reached', iterations, finalProgress: progress(stories) };
         }
-        // Story boundary: honour a pause signal before selecting the next story.
-        // complete/cap-reached above still win — pausing an already-finished loop is meaningless.
-        const pauseFile = pauseFilePath(opts.targetDir);
-        if (existsSync(pauseFile)) {
-            try {
-                unlinkSync(pauseFile);
-            }
-            catch { /* consumed best-effort — pausing still wins */ }
+        // Intake is work at a story boundary. Cap, pause, and clean-tree safety must
+        // win before a planner is allowed to edit and commit the PRD.
+        if (consumePause(opts.targetDir)) {
             reporter.paused(progress(stories));
             return { status: 'paused', iterations, finalProgress: progress(stories) };
         }
         const pre = preDispatchGate(opts.targetDir, opts.git);
         if (!pre.ok) {
-            reporter.blocked(pre.reason ?? 'pre-dispatch gate failed');
-            return { status: 'blocked', iterations, reason: pre.reason, finalProgress: progress(stories) };
+            const reason = opts.intake ? `change intake blocked by dirty worktree: ${pre.reason ?? 'pre-dispatch gate failed'}` : pre.reason;
+            reporter.blocked(reason ?? 'pre-dispatch gate failed');
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
+        // A bounded run that finished its final story may report completion, but it
+        // must not plan additional queued work after the requested cap.
+        if (capReached) {
+            const completionFailure = runCompletionGate(opts, stories);
+            if (completionFailure)
+                return { ...completionFailure, iterations };
+            reporter.complete(progress(stories));
+            return { status: 'complete', iterations, finalProgress: progress(stories) };
+        }
+        if (opts.intake) {
+            let intake;
+            try {
+                intake = opts.intake();
+            }
+            catch (error) {
+                const stories = loadPrd(opts.prdPath);
+                const reason = `change intake failed: ${error.message}`;
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+            if (!intake.ok) {
+                const stories = loadPrd(opts.prdPath);
+                const reason = `change intake failed: ${intake.summary}`;
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+            if (intake.added > 0) {
+                const afterIntake = preDispatchGate(opts.targetDir, opts.git);
+                if (!afterIntake.ok) {
+                    const stories = loadPrd(opts.prdPath);
+                    const reason = `change intake left a dirty worktree: ${afterIntake.reason ?? 'pre-dispatch gate failed'}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
+            }
+        }
+        stories = loadPrd(opts.prdPath);
+        if (stories.length === 0) {
+            reporter.blocked('PRD has no stories');
+            return { status: 'blocked', iterations, reason: 'PRD has no stories', finalProgress: { passed: 0, total: 0 } };
+        }
+        if (allPass(stories)) {
+            const completionFailure = runCompletionGate(opts, stories);
+            if (completionFailure)
+                return { ...completionFailure, iterations };
+            reporter.complete(progress(stories));
+            return { status: 'complete', iterations, finalProgress: progress(stories) };
         }
         const story = selectNextStory(stories);
         if (!story) {
             reporter.complete(progress(stories));
             return { status: 'complete', iterations, finalProgress: progress(stories) };
         }
-        const stl = stopTheLineGate(story);
+        const stl = stopTheLineGate(story, opts.requireCriterionEvidence);
         if (!stl.ok) {
             reporter.blocked(stl.reason ?? 'stop-the-line gate failed');
             return { status: 'blocked', iterations, reason: stl.reason, finalProgress: progress(stories) };
         }
         reporter.storyStart({ id: story.id, title: story.title }, iterations + 1, progress(stories));
+        if (opts.qualityPreflight && opts.qualityEnabled?.(story) !== false) {
+            reporter.phase('quality-preflight');
+            const preflight = opts.qualityPreflight({ targetDir: opts.targetDir, story });
+            if (preflight.kind === 'blocked') {
+                const reason = blockReason(`story ${story.id} quality preflight: ${preflight.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+        }
         if (opts.isolate) {
-            const wt = join(opts.targetDir, '.yoke', 'worktrees', story.id);
+            const wt = join(opts.targetDir, '.yoke', 'worktrees', storyPathSegment(story.id));
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
             let landed = null;
             try {
@@ -133,6 +316,13 @@ export function runLoop(opts) {
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
+                const criteriaVerdict = runCriterionGates(opts, wt, story);
+                if (!criteriaVerdict.passed) {
+                    result.routing?.recordOutcome(false);
+                    const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
                 // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
                 // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
                 reporter.phase('verifying');
@@ -169,12 +359,15 @@ export function runLoop(opts) {
                 const summary = result.success
                     ? result.summary
                     : `${result.summary} (runner exited non-zero but verify is green)`;
-                if (opts.review) {
-                    reporter.phase('reviewing');
-                    const reviewResult = opts.review({ targetDir: wt, story });
-                    if (!reviewResult.success) {
+                const repairOutcome = runQualityReview(opts, wt, story, reporter);
+                if (repairOutcome) {
+                    if (repairOutcome.kind === 'paused') {
+                        reporter.paused(progress(stories));
+                        return { status: 'paused', iterations, finalProgress: progress(stories) };
+                    }
+                    const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
+                    if (reason) {
                         result.routing?.recordOutcome(false);
-                        const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
                         reporter.blocked(reason);
                         return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                     }
@@ -234,6 +427,13 @@ export function runLoop(opts) {
             reporter.blocked(reason);
             return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
         }
+        const criteriaVerdict = runCriterionGates(opts, opts.targetDir, story);
+        if (!criteriaVerdict.passed) {
+            result.routing?.recordOutcome(false);
+            const reason = blockReason(`story ${story.id} lacks acceptance evidence: ${criteriaVerdict.summary}`, opts.targetDir, opts.git);
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
         // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
         // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
         reporter.phase('verifying');
@@ -275,12 +475,15 @@ export function runLoop(opts) {
         const summary = result.success
             ? result.summary
             : `${result.summary} (runner exited non-zero but verify is green)`;
-        if (opts.review) {
-            reporter.phase('reviewing');
-            const reviewResult = opts.review({ targetDir: opts.targetDir, story });
-            if (!reviewResult.success) {
+        const repairOutcome = runQualityReview(opts, opts.targetDir, story, reporter);
+        if (repairOutcome) {
+            if (repairOutcome.kind === 'paused') {
+                reporter.paused(progress(stories));
+                return { status: 'paused', iterations, finalProgress: progress(stories) };
+            }
+            const reason = repairBlockReason(repairOutcome, story, opts.targetDir, opts.git);
+            if (reason) {
                 result.routing?.recordOutcome(false);
-                const reason = blockReason(`story ${story.id} rejected in review: ${reviewResult.summary}`, opts.targetDir, opts.git);
                 reporter.blocked(reason);
                 return {
                     status: 'blocked',

package/dist/loop/merge-queue.js

@@ -3,14 +3,20 @@ export class MergeQueue {
     enqueue(job) {
         const run = async () => {
             try {
-                await job.rebase();
-                if (!await job.verify())
-                    return { storyId: job.storyId, integrated: false, reason: 'integrated-tree verification failed' };
-                await job.integrate();
-                return { storyId: job.storyId, integrated: true };
+                const prepared = await job.rebase();
+                if (!await job.verify(prepared))
+                    return { storyId: job.storyId, status: 'reopened', integrated: false, reason: 'integrated-tree verification failed' };
+                await job.integrate(prepared);
+                try {
+                    await job.postIntegrateVerify?.(prepared);
+                    return { storyId: job.storyId, status: 'integrated', integrated: true };
+                }
+                catch (error) {
+                    return { storyId: job.storyId, status: 'integrated-but-blocked', integrated: true, reason: error instanceof Error ? error.message : String(error) };
+                }
             }
             catch (error) {
-                return { storyId: job.storyId, integrated: false, reason: error.message };
+                return { storyId: job.storyId, status: 'reopened', integrated: false, reason: error instanceof Error ? error.message : String(error) };
             }
         };
         const result = this.tail.then(run, run);

package/dist/loop/parallel-adapters.js

@@ -0,0 +1,185 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isProviderTreeAlive, reapProviderProcesses } from './cleanup.js';
+import { realGitOps } from './git.js';
+import { isPidAlive } from './lock.js';
+import { storyPathSegment } from './prd.js';
+import { killProcessTreeForCleanup } from './watchdog.js';
+export function makeParallelAdapters(targetDir, identity, injectedGit) {
+    return injectedGit
+        ? injectedAdapters(targetDir, identity, injectedGit)
+        : productionAdapters(targetDir, identity);
+}
+function injectedAdapters(targetDir, identity, git) {
+    const owned = new Set();
+    const removed = new Set();
+    return {
+        worktrees: {
+            create: input => {
+                const path = worktreePath(targetDir, input);
+                git.addWorktree(targetDir, path);
+                owned.add(path);
+                return { path, baseCommit: 'injected-base' };
+            },
+            cleanupProcess: cleanupProviderProcesses,
+            remove: input => removeOwnedWorktree(targetDir, input, owned, removed, git),
+        },
+        git: {
+            isClean: dir => git.isClean(dir),
+            rebase: input => ({ kind: 'rebased', expectedHead: input.worktree.baseCommit }),
+            commit: input => git.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity),
+            integrate: input => git.integrate(targetDir, input.worktree.path),
+        },
+        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, git),
+    };
+}
+function productionAdapters(targetDir, identity) {
+    const owned = new Set();
+    const removed = new Set();
+    return {
+        worktrees: {
+            create: input => {
+                const path = worktreePath(targetDir, input);
+                const baseCommit = gitText(targetDir, ['rev-parse', 'HEAD']);
+                mkdirSync(dirname(path), { recursive: true });
+                realGitOps.addWorktree(targetDir, path);
+                owned.add(path);
+                return { path, baseCommit };
+            },
+            cleanupProcess: cleanupProviderProcesses,
+            remove: input => removeOwnedWorktree(targetDir, input, owned, removed, realGitOps),
+        },
+        git: {
+            isClean: dir => realGitOps.isClean(dir),
+            rebase: input => rebaseCandidate(targetDir, input),
+            commit: input => realGitOps.commitAll(input.worktree.path, `yoke: complete ${input.story.id} ${input.story.title}`, identity),
+            integrate: (input, expectedHead) => integrateCandidate(targetDir, input, expectedHead),
+        },
+        candidates: primary => makeCandidateLifecycle(targetDir, primary, owned, removed, realGitOps),
+    };
+}
+function cleanupProviderProcesses(input) {
+    reapProviderProcesses(input.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
+}
+function makeCandidateLifecycle(targetDir, primary, owned, removed, git) {
+    return {
+        reserve: input => {
+            const worktree = input.candidateId === 'candidate-1'
+                ? primary.worktree
+                : { path: candidateWorktreePath(targetDir, input), baseCommit: primary.worktree.baseCommit };
+            writeCandidateStatus(targetDir, input, worktree.path, 'reserved');
+            return worktree;
+        },
+        materialize: ownership => {
+            if (ownership.worktree.path !== primary.worktree.path) {
+                mkdirSync(dirname(ownership.worktree.path), { recursive: true });
+                git.addWorktree(targetDir, ownership.worktree.path);
+                owned.add(ownership.worktree.path);
+            }
+            writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'materialized');
+        },
+        cancel: (ownership, reason) => {
+            writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'cleaning', reason);
+        },
+        reap: ownership => {
+            reapProviderProcesses(ownership.worktree.path, isPidAlive, isProviderTreeAlive, killProcessTreeForCleanup);
+        },
+        remove: ownership => {
+            removeOwnedWorktree(targetDir, ownership, owned, removed, git);
+            writeCandidateStatus(targetDir, ownership, ownership.worktree.path, 'removed');
+        },
+    };
+}
+function worktreePath(targetDir, input) {
+    return join(targetDir, '.yoke', 'worktrees', `${storyPathSegment(input.story.id)}-${input.ownerToken}`);
+}
+function removeOwnedWorktree(targetDir, input, owned, removed, git) {
+    if (removed.has(input.worktree.path))
+        return;
+    if (!owned.has(input.worktree.path)) {
+        throw new Error(`refusing to remove a worktree not created by this dispatcher: ${input.worktree.path}`);
+    }
+    git.removeWorktree(targetDir, input.worktree.path);
+    owned.delete(input.worktree.path);
+    removed.add(input.worktree.path);
+}
+function candidateWorktreePath(targetDir, input) {
+    return join(targetDir, '.yoke', 'worktrees', `${storyPathSegment(input.storyId)}-${input.ownerToken}`);
+}
+function writeCandidateStatus(targetDir, input, worktree, state, reason) {
+    const file = join(targetDir, '.yoke', 'proof', storyPathSegment(input.storyId), 'candidates', input.candidateId, 'status.json');
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ storyId: input.storyId, candidateId: input.candidateId, worktree, state, ...(reason ? { reason } : {}) }));
+}
+function rebaseCandidate(targetDir, input) {
+    const currentHead = gitText(targetDir, ['rev-parse', 'HEAD']);
+    const candidateHead = gitText(input.worktree.path, ['rev-parse', 'HEAD']);
+    try {
+        execFileSync('git', ['merge-base', '--is-ancestor', input.worktree.baseCommit, 'HEAD'], { cwd: input.worktree.path, stdio: 'pipe' });
+    }
+    catch {
+        return { kind: 'reopen', reason: `candidate history no longer descends from base ${input.worktree.baseCommit}` };
+    }
+    if (currentHead !== input.worktree.baseCommit) {
+        try {
+            execFileSync('git', ['merge-base', '--is-ancestor', input.worktree.baseCommit, currentHead], { cwd: targetDir, stdio: 'pipe' });
+        }
+        catch {
+            return { kind: 'reopen', reason: `candidate base ${input.worktree.baseCommit} is stale against target ${currentHead}` };
+        }
+        let candidateTree;
+        try {
+            execFileSync('git', ['add', '-A'], { cwd: input.worktree.path, stdio: 'pipe' });
+            const unstaged = spawnSync('git', ['diff', '--quiet', '--ignore-submodules=none'], { cwd: input.worktree.path, stdio: 'pipe' });
+            if (unstaged.error || unstaged.status !== 0)
+                return { kind: 'reopen', reason: 'candidate contains changes Git cannot snapshot' };
+            candidateTree = gitText(input.worktree.path, ['write-tree']);
+        }
+        catch (error) {
+            return { kind: 'reopen', reason: `candidate snapshot failed: ${errorMessage(error)}` };
+        }
+        const merge = spawnSync('git', ['merge-tree', '--write-tree', '--messages', '--name-only', `--merge-base=${input.worktree.baseCommit}`, currentHead, candidateTree], {
+            cwd: input.worktree.path,
+            encoding: 'utf8',
+        });
+        const mergedTree = merge.stdout.trim().split(/\r?\n/u)[0] ?? '';
+        if (merge.error || merge.status !== 0 || !/^[0-9a-f]{40,64}$/u.test(mergedTree)) {
+            const detail = [merge.stderr, merge.stdout].map(value => value.trim()).filter(Boolean).join(' · ');
+            return { kind: 'reopen', reason: `candidate tree merge failed${detail ? `: ${detail}` : ''}` };
+        }
+        try {
+            execFileSync('git', ['reset', '--soft', currentHead], { cwd: input.worktree.path, stdio: 'pipe' });
+            execFileSync('git', ['read-tree', '--reset', '-u', mergedTree], { cwd: input.worktree.path, stdio: 'pipe' });
+            const unstaged = spawnSync('git', ['diff', '--quiet', '--ignore-submodules=none'], { cwd: input.worktree.path, stdio: 'pipe' });
+            if (unstaged.error || unstaged.status !== 0 || gitText(input.worktree.path, ['ls-files', '--unmerged']) || gitText(input.worktree.path, ['write-tree']) !== mergedTree) {
+                throw new Error('materialized candidate tree did not match the computed merge');
+            }
+        }
+        catch (error) {
+            try {
+                execFileSync('git', ['reset', '--soft', candidateHead], { cwd: input.worktree.path, stdio: 'pipe' });
+                execFileSync('git', ['read-tree', '--reset', '-u', candidateTree], { cwd: input.worktree.path, stdio: 'pipe' });
+            }
+            catch { }
+            return { kind: 'reopen', reason: `candidate tree materialization failed: ${errorMessage(error)}` };
+        }
+    }
+    // Preserve the worker's candidate tree, but return commit authority to the dispatcher.
+    execFileSync('git', ['reset', '--soft', currentHead], { cwd: input.worktree.path, stdio: 'pipe' });
+    return { kind: 'rebased', expectedHead: currentHead };
+}
+function integrateCandidate(targetDir, input, expectedHead) {
+    if (!realGitOps.isClean(targetDir))
+        throw new Error('target working tree is not clean before integration');
+    const currentHead = gitText(targetDir, ['rev-parse', 'HEAD']);
+    if (currentHead !== expectedHead)
+        throw new Error(`target HEAD changed from ${expectedHead} to ${currentHead} during integrated gates`);
+    realGitOps.integrate(targetDir, input.worktree.path);
+}
+function gitText(dir, args) {
+    return execFileSync('git', args, { cwd: dir, stdio: 'pipe' }).toString().trim();
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}