@hecer/yoke 1.3.0 → 1.5.0

package/dist/loop/loop.js

@@ -6,6 +6,7 @@ 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 {
@@ -16,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
@@ -125,12 +208,7 @@ export function runLoop(opts) {
         }
         // 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.
-        const pauseFile = pauseFilePath(opts.targetDir);
-        if (existsSync(pauseFile)) {
-            try {
-                unlinkSync(pauseFile);
-            }
-            catch { /* consumed best-effort — pausing still wins */ }
+        if (consumePause(opts.targetDir)) {
             reporter.paused(progress(stories));
             return { status: 'paused', iterations, finalProgress: progress(stories) };
         }
@@ -199,6 +277,15 @@ export function runLoop(opts) {
             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', storyPathSegment(story.id));
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
@@ -272,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) };
                     }
@@ -385,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);
+}

package/dist/loop/parallel-command.js

@@ -0,0 +1,287 @@
+import { existsSync, rmSync } from 'node:fs';
+import { createDispatcher } from './dispatcher.js';
+import { consumeDecisionRequest } from './decision.js';
+import { pauseFilePath } from './loop.js';
+import { makeParallelAdapters } from './parallel-adapters.js';
+import { loadPrd, progress } from './prd.js';
+import { makeAsyncRunner } from './runner.js';
+import { runStoryWorker } from './worker.js';
+export async function runParallelLoopCommand(input) {
+    const adapters = makeParallelAdapters(input.targetDir, input.identity, input.git);
+    if (!adapters.git.isClean(input.targetDir)) {
+        input.reporter.blocked('target working tree is not clean');
+        return 1;
+    }
+    let pauseConsumed = false;
+    const pause = () => {
+        if (pauseConsumed)
+            return true;
+        const path = pauseFilePath(input.targetDir);
+        if (!existsSync(path))
+            return false;
+        rmSync(path, { force: true });
+        pauseConsumed = true;
+        return true;
+    };
+    const dispatcher = createDispatcher({
+        targetDir: input.targetDir,
+        prdPath: input.prdPath,
+        stories: loadPrd(input.prdPath),
+        maxConcurrency: input.maxConcurrency,
+        maxIterations: input.maxIterations,
+        providers: input.providers,
+        affinityProviders: input.affinityProviders,
+        worktrees: adapters.worktrees,
+        git: adapters.git,
+        ...(input.candidateCount && input.candidateCount > 1 ? {
+            candidateCount: input.candidateCount,
+            candidateCoordinator: workerInput => candidateCoordinatorInput(input, adapters, workerInput, pause),
+        } : {}),
+        pause,
+        onProgress: status => input.reporter.parallel?.(status),
+        gates: {
+            verify: input.verify,
+            verifyCriterion: input.verifyCriterion,
+            requireCriterionEvidence: input.requireCriterionEvidence,
+            perf: input.perf,
+            audit: input.audit,
+            qualityReview: (path, story, worker) => integrationGate(input, path, story, integratorReporter(input.reporter, worker)),
+            integrationPhase: (worker, phase) => reportIntegrator(input.reporter, worker, phase),
+        },
+        worker: workerInput => {
+            const runner = input.runner ?? asyncRunner(input, workerInput.provider, workerInput.cancellation.signal, workerInput.ownerToken);
+            const result = runStoryWorker({
+                story: workerInput.story,
+                worktree: workerInput.worktree.path,
+                baseCommit: workerInput.worktree.baseCommit,
+                provider: workerInput.provider,
+                runner,
+                verify: input.verify,
+                verifyCriterion: input.verifyCriterion,
+                requireCriterionEvidence: input.requireCriterionEvidence,
+                perf: input.perf,
+                audit: input.audit,
+                qualityPreflight: input.quality?.qualityPreflight,
+                qualityStage: input.quality?.qualityStage,
+                repair: input.quality?.repair,
+                repairLimits: input.quality?.repairLimits,
+                qualityMetadata: input.quality?.qualityMetadata,
+                qualityEnabled: input.quality?.qualityEnabled,
+                review: input.review,
+                cancellation: workerInput.cancellation,
+                beforeGates: context => {
+                    const decision = consumeDecisionRequest(context.targetDir, input.targetDir, context.story.id);
+                    if (!decision)
+                        return null;
+                    input.onCriticalDecision?.(decision);
+                    return decision.question;
+                },
+                pause,
+                reporter: workerReporter(input.reporter, workerInput),
+            });
+            return Promise.resolve(result);
+        },
+    });
+    const result = await dispatcher.run();
+    const finalProgress = progress(loadPrd(input.prdPath));
+    if (result.status === 'complete' && input.completion) {
+        const gate = input.completion(input.targetDir);
+        if (!gate.passed) {
+            input.reporter.blocked(gate.summary);
+            return 1;
+        }
+    }
+    if (result.status === 'complete')
+        input.reporter.complete(finalProgress);
+    else if (result.status === 'paused')
+        input.reporter.paused(finalProgress);
+    else if (result.status === 'cap-reached')
+        input.reporter.capReached(finalProgress);
+    else
+        input.reporter.blocked(result.reason ?? `parallel dispatcher ${result.status}`);
+    return result.status === 'complete' ? 0 : result.status === 'paused' ? 3 : 1;
+}
+function candidateCoordinatorInput(input, adapters, worker, pause) {
+    const quality = input.quality;
+    const candidateCount = input.candidateCount;
+    if (!quality || !candidateCount)
+        throw new Error('candidate dispatch requires quality hooks and a candidate count');
+    const candidateIds = Array.from({ length: candidateCount }, (_, index) => `candidate-${index + 1}`);
+    const comparison = quality.candidateComparison(worker.story, candidateIds);
+    const reporter = workerReporter(input.reporter, worker);
+    return {
+        story: worker.story,
+        baseCommit: worker.worktree.baseCommit,
+        maxCandidates: candidateCount,
+        candidates: candidateDefinitions(input, worker, candidateCount, pause),
+        coordinatorId: `${worker.dispatcherId}:${worker.story.id}:${worker.ownerToken}`,
+        ownerToken: candidateId => `${worker.ownerToken}-${candidateId}`,
+        lifecycle: adapters.candidates(worker),
+        evidence: comparison.evidence,
+        stageEvidence: comparison.stageEvidence,
+        judgeProvenance: comparison.judgeProvenance,
+        onSelecting: () => reporter.phase('selecting-candidate'),
+        onLifecycle: (candidate, state, reason) => candidateReporter(input.reporter, worker, candidate, state, reason),
+        judge: request => comparison.judge(request),
+        recordResult: comparison.recordResult,
+        recordElimination: comparison.recordElimination,
+        recordSelection: comparison.recordSelection,
+        signal: worker.cancellation.signal,
+        pause,
+    };
+}
+function candidateDefinitions(input, worker, candidateCount, pause) {
+    const quality = input.quality;
+    return Array.from({ length: candidateCount }, (_, index) => {
+        const candidateId = `candidate-${index + 1}`;
+        const qualityRoundBase = (index + 1) * 10_000;
+        const runner = input.runner ?? asyncRunner(input, worker.provider, undefined, `${worker.ownerToken}-${candidateId}`);
+        return {
+            id: candidateId,
+            worker: {
+                provider: worker.provider,
+                runner,
+                verify: input.verify,
+                verifyCriterion: input.verifyCriterion,
+                requireCriterionEvidence: input.requireCriterionEvidence,
+                perf: input.perf,
+                audit: input.audit,
+                ...(quality ? {
+                    qualityPreflight: quality.qualityPreflight,
+                    qualityStage: (context, round, attempt) => quality.qualityStage(context, qualityRoundBase + round, attempt),
+                    repair: quality.repair,
+                    repairLimits: quality.repairLimits,
+                    qualityMetadata: quality.qualityMetadata,
+                    qualityEnabled: quality.qualityEnabled,
+                } : {}),
+                review: input.review,
+                beforeGates: context => {
+                    if (pause())
+                        return 'candidate coordination paused';
+                    const decision = consumeDecisionRequest(context.targetDir, input.targetDir, context.story.id);
+                    if (!decision)
+                        return null;
+                    input.onCriticalDecision?.(decision);
+                    return decision.question;
+                },
+                pause,
+                reporter: workerReporter(input.reporter, worker),
+                reporterFor: (candidate) => workerReporter(input.reporter, worker, candidate),
+            },
+            runnerFor: cancellation => input.runner ?? asyncRunner(input, worker.provider, cancellation.signal, `${worker.ownerToken}-${candidateId}`),
+        };
+    });
+}
+function workerReporter(reporter, worker, candidate) {
+    const attribution = {
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: worker.provider.provider,
+        ...(worker.provider.model ? { model: worker.provider.model } : {}),
+        ...(candidate ? { candidateId: candidate.candidateId, worktree: candidate.worktree.path } : {}),
+    };
+    return {
+        phase: phase => {
+            if (reporter.parallelWorker)
+                reporter.parallelWorker({ ...attribution, phase });
+            else
+                reporter.phase(phase);
+        },
+        quality: quality => {
+            if (reporter.parallelWorker)
+                reporter.parallelWorker({ ...attribution, quality });
+            else
+                reporter.quality(quality);
+        },
+        addTokens: usage => reporter.addTokens(usage),
+    };
+}
+function candidateReporter(reporter, worker, candidate, state, reason) {
+    if (!reporter.parallelWorker)
+        return;
+    reporter.parallelWorker({
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: candidate.provider.provider,
+        ...(candidate.provider.model ? { model: candidate.provider.model } : {}),
+        candidateId: candidate.candidateId,
+        worktree: candidate.worktree.path,
+        lifecycle: state,
+        ...(reason ? { reason } : {}),
+    });
+}
+function integratorReporter(reporter, worker) {
+    const attribution = {
+        story: worker.story.id,
+        storyTitle: worker.story.title,
+        provider: worker.provider.provider,
+        ...(worker.provider.model ? { model: worker.provider.model } : {}),
+    };
+    return {
+        phase: phase => reportIntegrator(reporter, worker, phase),
+        quality: quality => {
+            if (reporter.parallelIntegrator)
+                reporter.parallelIntegrator({ ...attribution, quality });
+            else
+                reporter.quality(quality);
+        },
+    };
+}
+function reportIntegrator(reporter, worker, phase) {
+    if (reporter.parallelIntegrator) {
+        reporter.parallelIntegrator(phase
+            ? { story: worker.story.id, storyTitle: worker.story.title, provider: worker.provider.provider, ...(worker.provider.model ? { model: worker.provider.model } : {}), phase }
+            : null);
+        return;
+    }
+    if (phase)
+        reporter.phase(phase);
+}
+function asyncRunner(input, provider, signal, workerId) {
+    const { model: _globalModel, reasoningEffort: _globalReasoningEffort, ...selection } = input.selection;
+    const runner = makeAsyncRunner(provider.provider, {
+        onAmbiguity: input.onAmbiguity,
+        permissions: input.permissions,
+        selection: {
+            ...selection,
+            ...(provider.model ? { model: provider.model } : {}),
+            ...(provider.reasoningEffort ? { reasoningEffort: provider.reasoningEffort } : {}),
+        },
+        process: { idleTimeoutMs: input.idleMs, signal, workerId },
+    });
+    return async (context) => providerProcessResultToAgentResult(provider.provider, context.story.id, await runner(context).completion);
+}
+export function providerProcessResultToAgentResult(agent, storyId, result) {
+    const tokens = result.telemetry.tokens;
+    const telemetry = tokens ? { tokens } : {};
+    switch (result.kind) {
+        case 'succeeded': return { success: true, summary: `${agent} implemented ${storyId}`, ...telemetry };
+        case 'cancelled': return { success: false, summary: result.reason, ...telemetry };
+        case 'timed-out': return { success: false, summary: result.reason, ...telemetry };
+        case 'spawn-failed': return { success: false, summary: result.error, ...telemetry };
+        case 'failed': return { success: false, summary: `${agent} exited ${result.exitCode ?? 'without a code'}`, ...telemetry };
+        default: return assertNever(result);
+    }
+}
+function reviewGate(review, path, story) {
+    if (!review)
+        return { passed: true, summary: 'integrated gates passed' };
+    const result = review({ targetDir: path, story });
+    return { passed: result.success && result.reviewOutcome?.kind !== 'rejected', summary: result.summary };
+}
+function assertNever(value) { throw new Error(`unexpected provider result: ${String(value)}`); }
+function integrationGate(input, path, story, reporter) {
+    const context = { targetDir: path, story };
+    const qualityEnabled = input.quality?.qualityEnabled(story) ?? false;
+    if (qualityEnabled)
+        reporter.phase('comparing');
+    const preflight = qualityEnabled ? input.quality?.qualityPreflight(context) : undefined;
+    if (preflight?.kind === 'blocked')
+        return { passed: false, summary: preflight.summary };
+    const quality = qualityEnabled ? input.quality?.qualityStage(context, 10_000, 'integration') : undefined;
+    if (quality && quality.kind !== 'pass' && quality.kind !== 'skipped')
+        return { passed: false, summary: quality.summary };
+    if (input.review)
+        reporter.phase('reviewing');
+    return reviewGate(input.review, path, story);
+}