@hecer/yoke 1.3.0 → 1.4.0

package/dist/agents/providers.js

@@ -1,3 +1,5 @@
+import { ModelSelectionSchema } from './contracts.js';
+export { providerSpawnOptions, startProviderProcess, } from './process.js';
 const argsFor = (agent, permissions) => {
     if (agent === 'claude') {
         const mode = permissions === 'unsafe' ? 'bypassPermissions' : permissions === 'read-only' ? 'plan' : 'auto';
@@ -19,18 +21,19 @@ const argsFor = (agent, permissions) => {
     return ['--approval-mode', approval, '--sandbox'];
 };
 export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe', selection = {}) {
+    const parsedSelection = ModelSelectionSchema.parse(selection);
     const args = argsFor(agent, permissions);
-    if (selection.model)
-        args.push('--model', selection.model);
-    if (selection.reasoningEffort) {
+    if (parsedSelection.model)
+        args.push('--model', parsedSelection.model);
+    if (parsedSelection.reasoningEffort) {
         if (agent === 'claude')
-            args.push('--effort', selection.reasoningEffort);
+            args.push('--effort', parsedSelection.reasoningEffort);
         else if (agent === 'codex')
-            args.push('--config', `model_reasoning_effort=${selection.reasoningEffort}`);
+            args.push('--config', `model_reasoning_effort=${parsedSelection.reasoningEffort}`);
     }
-    if (agent === 'codex' && selection.nativeMultiAgent === false)
+    if (agent === 'codex' && parsedSelection.nativeMultiAgent === false)
         args.push('--disable', 'multi_agent');
-    if (selection.bare) {
+    if (parsedSelection.bare) {
         if (agent === 'codex')
             args.push('--ignore-user-config');
         else if (agent === 'claude')

package/dist/agents/telemetry.js

@@ -1,4 +1,66 @@
 const finite = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+function parseJson(value) {
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return { ok: false };
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function directMachineResult(value) {
+    return isRecord(value) && value.schemaVersion === 1 ? value : undefined;
+}
+export function parseProviderResult(agent, output) {
+    const whole = parseJson(output);
+    if (whole.ok) {
+        const direct = directMachineResult(whole.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    const fragments = [];
+    for (const line of output.split(/\r?\n/u)) {
+        const parsed = parseJson(line);
+        if (!parsed.ok || !isRecord(parsed.value))
+            continue;
+        const event = parsed.value;
+        switch (agent) {
+            case 'claude':
+                if (event.type === 'result' && typeof event.result === 'string')
+                    fragments.push(event.result);
+                break;
+            case 'codex': {
+                const item = isRecord(event.item) ? event.item : undefined;
+                if (event.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string')
+                    fragments.push(item.text);
+                break;
+            }
+            case 'gemini':
+                if (event.type === 'message' && event.role === 'assistant' && typeof event.content === 'string')
+                    fragments.push(event.content);
+                break;
+        }
+    }
+    const joined = parseJson(fragments.join(''));
+    if (joined.ok) {
+        const direct = directMachineResult(joined.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    for (const fragment of fragments.reverse()) {
+        const parsed = parseJson(fragment);
+        if (!parsed.ok)
+            continue;
+        const direct = directMachineResult(parsed.value);
+        if (direct !== undefined)
+            return direct;
+    }
+    return null;
+}
 export function parseProviderTelemetry(agent, lines) {
     let inputTokens;
     let cachedInputTokens;

package/dist/cli.js

@@ -52,6 +52,48 @@ export function runDesignScan(targetDir, opts) {
     console.log(`${label} — ✓`);
     return 0;
 }
+export function parseQualityFlags(args) {
+    const quality = args.includes('--quality') ? true : args.includes('--no-quality') ? false : undefined;
+    const qualityUnbounded = args.includes('--quality-unbounded') || undefined;
+    const parsePositive = (flag) => {
+        const raw = args.find(arg => arg.startsWith(flag));
+        if (!raw)
+            return undefined;
+        const value = Number(raw.slice(flag.length));
+        return Number.isInteger(value) && value > 0 ? value : `Invalid ${flag.slice(0, -1)} value: ${raw}`;
+    };
+    const qualityRounds = parsePositive('--quality-rounds=');
+    if (typeof qualityRounds === 'string')
+        return { ok: false, error: qualityRounds };
+    const qualityMinutes = parsePositive('--quality-minutes=');
+    if (typeof qualityMinutes === 'string')
+        return { ok: false, error: qualityMinutes };
+    const candidates = parsePositive('--candidates=');
+    if (typeof candidates === 'string')
+        return { ok: false, error: candidates };
+    const policyArg = args.find(arg => arg.startsWith('--quality-policy='))?.slice('--quality-policy='.length);
+    if (policyArg && policyArg !== 'blocking' && policyArg !== 'advisory') {
+        return { ok: false, error: `Invalid --quality-policy value: ${policyArg} (expected blocking|advisory)` };
+    }
+    const qualityPolicy = policyArg === 'blocking' || policyArg === 'advisory' ? policyArg : undefined;
+    if (quality === true && args.includes('--no-quality'))
+        return { ok: false, error: 'Cannot use --quality with --no-quality.' };
+    if (qualityUnbounded && quality === false)
+        return { ok: false, error: 'Cannot use --quality-unbounded with --no-quality.' };
+    if (qualityUnbounded && (qualityRounds !== undefined || qualityMinutes !== undefined)) {
+        return { ok: false, error: 'Cannot use --quality-unbounded with --quality-rounds or --quality-minutes.' };
+    }
+    return {
+        ok: true,
+        options: {
+            ...(qualityUnbounded ? { quality: true, qualityUnbounded: true } : quality !== undefined ? { quality } : {}),
+            ...(qualityRounds !== undefined ? { qualityRounds } : {}),
+            ...(qualityMinutes !== undefined ? { qualityMinutes } : {}),
+            ...(qualityPolicy ? { qualityPolicy } : {}),
+            ...(candidates !== undefined ? { candidates } : {}),
+        },
+    };
+}
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -217,7 +259,12 @@ export function main(argv) {
                     return 1;
                 }
                 const { version: _version, storyId: _storyId, requestId: _requestId, answered: _answered, ...resumeOptions } = resume;
-                return runLoopCommand(targetDir, resumeOptions);
+                const qualityFlags = parseQualityFlags(rest);
+                if (!qualityFlags.ok) {
+                    console.error(qualityFlags.error);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options });
             }
             if (sub === 'answer') {
                 const choice = rest.find(a => a.startsWith('--choice='))?.slice('--choice='.length);
@@ -342,9 +389,14 @@ export function main(argv) {
                     console.error(`Invalid --decision-policy value: ${dpArg} (expected auto|critical)`);
                     return 1;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, parallel, reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions });
+                const qualityFlags = parseQualityFlags(rest);
+                if (!qualityFlags.ok) {
+                    console.error(qualityFlags.error);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, parallel, reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions, ...qualityFlags.options });
             }
-            console.log('usage: yoke loop <on|off|status|decision|answer|resume [--discard]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--parallel=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--json]> [targetDir]');
+            console.log('usage: yoke loop <on|off|status|decision|answer|resume [--discard] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--parallel=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]');
             return 1;
         }
         case 'new': {

package/dist/loop/candidate-boundaries.js

@@ -0,0 +1,43 @@
+import { posix, win32 } from 'node:path';
+import { z } from 'zod';
+const CandidateEvidenceSchema = z.object({
+    digest: z.string().min(1),
+    artifacts: z.array(z.string()),
+});
+const CandidateIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export function candidateConfigProblem(input) {
+    if (!Number.isInteger(input.maxCandidates) || input.maxCandidates < 1 || input.maxCandidates > 5) {
+        return 'maxCandidates must be an integer from 1 to 5';
+    }
+    if (input.candidates.length === 0)
+        return 'at least one candidate is required';
+    if (input.candidates.some(candidate => !CandidateIdSchema.safeParse(candidate.id).success)) {
+        return 'candidate ids must be non-empty safe identifiers';
+    }
+    if (new Set(input.candidates.map(candidate => candidate.id)).size !== input.candidates.length) {
+        return 'candidate ids must be unique';
+    }
+    return null;
+}
+export function parseCandidateEvidence(value) {
+    const parsed = CandidateEvidenceSchema.parse(value);
+    return { digest: parsed.digest, artifacts: [...parsed.artifacts] };
+}
+export function canonicalWorktreePath(path, platform) {
+    if (platform === 'win32') {
+        if (!/^(?:[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/][^\\/]+)/.test(path))
+            return null;
+        const normalized = win32.normalize(path).replaceAll('/', '\\').toLowerCase();
+        return trimSeparators(normalized, win32.parse(normalized).root, '\\');
+    }
+    if (!posix.isAbsolute(path))
+        return null;
+    const normalized = posix.normalize(path);
+    return trimSeparators(normalized, posix.parse(normalized).root, '/');
+}
+function trimSeparators(path, root, separator) {
+    let key = path;
+    while (key.length > root.length && key.endsWith(separator))
+        key = key.slice(0, -1);
+    return key;
+}

package/dist/loop/candidate-cleanup.js

@@ -0,0 +1,98 @@
+const stageOrder = ['cancel', 'reap', 'remove'];
+export class CandidateCleanup {
+    lifecycle;
+    onLifecycle;
+    #states = new Map();
+    constructor(lifecycle, onLifecycle) {
+        this.lifecycle = lifecycle;
+        this.onLifecycle = onLifecycle;
+    }
+    register(ownership) {
+        this.#states.set(ownership.candidateId, { ownership, materialized: false, completed: new Set(), failed: new Map(), pending: new Map() });
+    }
+    markMaterialized(candidateId) {
+        const state = this.#states.get(candidateId);
+        if (state)
+            state.materialized = true;
+    }
+    cancelNow(reason) {
+        for (const state of this.#states.values()) {
+            state.ownership.controller.abort(reason);
+            this.onLifecycle?.(state.ownership, 'cleaning', reason);
+            void this.#runStage(state, 'cancel', () => this.lifecycle.cancel(state.ownership, reason));
+        }
+    }
+    async cleanup(ownership, reason) {
+        const state = this.#states.get(ownership.candidateId);
+        if (!state)
+            return;
+        ownership.controller.abort(reason);
+        this.onLifecycle?.(ownership, 'cleaning', reason);
+        if (!await this.#runStage(state, 'cancel', () => this.lifecycle.cancel(ownership, reason)))
+            return;
+        if (!await this.#runStage(state, 'reap', () => this.lifecycle.reap(ownership)))
+            return;
+        if (await this.#runStage(state, 'remove', () => this.lifecycle.remove(ownership)))
+            this.onLifecycle?.(ownership, 'removed', reason);
+    }
+    async cleanupAll(reason, keepCandidateId) {
+        for (const state of this.#states.values()) {
+            if (state.ownership.candidateId !== keepCandidateId)
+                await this.cleanup(state.ownership, reason);
+        }
+    }
+    hasFailures() {
+        return [...this.#states.values()].some(state => state.failed.size > 0);
+    }
+    failureSummary() {
+        return this.recovery().flatMap(item => item.failedStages.map(failure => `${item.ownership.candidateId}:${failure.stage}: ${failure.summary}`)).join('; ');
+    }
+    recovery() {
+        return [...this.#states.values()].filter(state => state.failed.size > 0).map(state => ({
+            ownership: {
+                candidateId: state.ownership.candidateId,
+                coordinatorId: state.ownership.coordinatorId,
+                ownerToken: state.ownership.ownerToken,
+                storyId: state.ownership.storyId,
+                provider: { ...state.ownership.provider },
+                worktree: { ...state.ownership.worktree },
+            },
+            materialized: state.materialized,
+            completedStages: stageOrder.filter(stage => state.completed.has(stage)),
+            failedStages: stageOrder.flatMap(stage => {
+                const summary = state.failed.get(stage);
+                return summary ? [{ stage, summary }] : [];
+            }),
+            pendingStages: stageOrder.filter(stage => !state.completed.has(stage) && !state.failed.has(stage)),
+        }));
+    }
+    #runStage(state, stage, operation) {
+        if (state.completed.has(stage))
+            return Promise.resolve(true);
+        const pending = state.pending.get(stage);
+        if (pending)
+            return pending.then(() => state.completed.has(stage));
+        try {
+            const result = operation();
+            if (!(result instanceof Promise)) {
+                state.completed.add(stage);
+                state.failed.delete(stage);
+                return Promise.resolve(true);
+            }
+            const task = result.then(() => {
+                state.completed.add(stage);
+                state.failed.delete(stage);
+            }).catch(error => {
+                state.failed.set(stage, error instanceof Error ? error.message : String(error));
+            }).finally(() => {
+                state.pending.delete(stage);
+            });
+            state.pending.set(stage, task);
+            return task.then(() => state.completed.has(stage));
+        }
+        catch (error) {
+            state.failed.set(stage, error instanceof Error ? error.message : String(error));
+            return Promise.resolve(false);
+        }
+    }
+}

package/dist/loop/candidate-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/loop/candidate-selection.js

@@ -0,0 +1,84 @@
+import { randomUUID } from 'node:crypto';
+import { reduceCandidatePairComparisons } from '../quality/verdict.js';
+import { parseCandidateEvidence } from './candidate-boundaries.js';
+export async function selectCandidate(input) {
+    const first = input.candidates[0];
+    if (!first)
+        return { kind: 'inconsistent', reason: 'selection requires one candidate' };
+    let selected = first;
+    let selectedEvidence = await prepareEvidence(input, first);
+    input.ensureActive();
+    if (input.pause?.())
+        return { kind: 'paused' };
+    const comparisons = [];
+    for (let index = 1; index < input.candidates.length; index += 1) {
+        const challenger = input.candidates[index];
+        if (!challenger)
+            continue;
+        const challengerEvidence = await prepareEvidence(input, challenger);
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const normal = issueComparison({ left: { candidate: selected, evidence: selectedEvidence }, right: { candidate: challenger, evidence: challengerEvidence }, provenance: input.judgeProvenance });
+        const swapped = issueComparison({ left: { candidate: challenger, evidence: challengerEvidence }, right: { candidate: selected, evidence: selectedEvidence }, provenance: input.judgeProvenance });
+        const normalVerdict = await input.judge(structuredClone(normal.expected.request));
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const swappedVerdict = await input.judge(structuredClone(swapped.expected.request));
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        const reduction = reduceCandidatePairComparisons({ expected: { normal: normal.expected, swapped: swapped.expected }, normal: normalVerdict, swapped: swappedVerdict });
+        if (reduction.kind === 'inconsistent')
+            return reduction;
+        const winner = reduction.winnerCandidateId === selected.candidateId ? selected : challenger;
+        const loser = winner.candidateId === selected.candidateId ? challenger : selected;
+        comparisons.push({
+            normal: { request: structuredClone(normal.expected.request), verdict: structuredClone(reduction.normal) },
+            swapped: { request: structuredClone(swapped.expected.request), verdict: structuredClone(reduction.swapped) },
+            selectedCandidateId: reduction.winnerCandidateId,
+            selectedDigest: reduction.winnerDigest,
+        });
+        await input.discard(loser);
+        input.ensureActive();
+        if (input.pause?.())
+            return { kind: 'paused' };
+        if (winner.candidateId === challenger.candidateId) {
+            selected = challenger;
+            selectedEvidence = challengerEvidence;
+        }
+    }
+    input.ensureActive();
+    return input.pause?.() ? { kind: 'paused' } : { kind: 'selected', candidate: selected, evidence: selectedEvidence.trusted, comparisons };
+}
+async function prepareEvidence(input, candidate) {
+    const trusted = parseCandidateEvidence(input.evidence(candidate));
+    const handle = { digest: `evidence-${randomUUID()}`, artifacts: trusted.artifacts.map(() => `artifact-${randomUUID()}`) };
+    await input.stageEvidence({
+        handle: { digest: handle.digest, artifacts: [...handle.artifacts] },
+        trusted: { digest: trusted.digest, artifacts: [...trusted.artifacts] },
+    });
+    return { trusted, handle };
+}
+function issueComparison(input) {
+    const request = {
+        permissions: 'read-only',
+        attemptId: randomUUID(),
+        left: { digest: input.left.evidence.handle.digest, artifacts: [...input.left.evidence.handle.artifacts], label: 'A' },
+        right: { digest: input.right.evidence.handle.digest, artifacts: [...input.right.evidence.handle.artifacts], label: 'B' },
+    };
+    return {
+        request,
+        expected: {
+            request: {
+                permissions: request.permissions,
+                attemptId: request.attemptId,
+                left: { ...request.left, artifacts: [...request.left.artifacts] },
+                right: { ...request.right, artifacts: [...request.right.artifacts] },
+            },
+            candidateIds: { left: input.left.candidate.candidateId, right: input.right.candidate.candidateId },
+            provenance: { ...input.provenance },
+        },
+    };
+}

package/dist/loop/candidates.js

@@ -0,0 +1,228 @@
+import { candidateConfigProblem, canonicalWorktreePath } from './candidate-boundaries.js';
+import { CandidateCleanup } from './candidate-cleanup.js';
+import { selectCandidate } from './candidate-selection.js';
+import { runStoryWorker } from './worker.js';
+class CandidateCancellationError extends Error {
+    name = 'CandidateCancellationError';
+}
+export async function coordinateCandidates(input) {
+    const configProblem = candidateConfigProblem(input);
+    if (configProblem)
+        return { kind: 'blocked', reason: 'invalid-config', summary: configProblem };
+    if (input.signal?.aborted)
+        return { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+    const definitions = input.candidates.slice(0, input.maxCandidates);
+    const pathPlatform = input.pathPlatform ?? (process.platform === 'win32' ? 'win32' : 'posix');
+    const owned = [];
+    const outcomes = new Map();
+    const cleanup = new CandidateCleanup(input.lifecycle, input.onLifecycle);
+    const terminalize = async (candidate, reason) => {
+        const result = outcomes.get(candidate.candidateId) ?? {
+            kind: 'cancelled', storyId: candidate.storyId, worktree: candidate.worktree.path,
+            baseCommit: candidate.worktree.baseCommit, provider: candidate.provider, summary: reason,
+            evidence: { criteria: [] },
+        };
+        await input.recordResult?.({ ...candidate, result });
+        await input.recordElimination?.({ ...candidate, result });
+    };
+    const terminalizeAll = async (reason) => {
+        for (const candidate of owned)
+            await terminalize(candidate, reason);
+    };
+    const ensureActive = () => {
+        if (input.signal?.aborted)
+            throw new CandidateCancellationError(cancellationSummary(input.signal));
+    };
+    const cancelActive = () => cleanup.cancelNow(input.signal ? cancellationSummary(input.signal) : 'candidate coordinator cancelled');
+    input.signal?.addEventListener('abort', cancelActive, { once: true });
+    const finishPaused = async () => {
+        await terminalizeAll('candidate coordination paused');
+        await cleanup.cleanupAll('candidate coordination paused');
+        ensureActive();
+        return cleanup.hasFailures()
+            ? blocked(cleanup, 'cleanup-error', 'candidate pause cleanup failed')
+            : { kind: 'paused', summary: 'candidate coordination paused' };
+    };
+    try {
+        const paths = new Set();
+        for (const definition of definitions) {
+            const controller = new AbortController();
+            const provenance = provenanceFor(input, definition);
+            const worktree = input.lifecycle.reserve({ ...provenance, baseCommit: input.baseCommit });
+            const candidate = { ...provenance, worktree, signal: controller.signal, controller, definition };
+            owned.push(candidate);
+            cleanup.register(candidate);
+            input.onLifecycle?.(candidate, 'reserved');
+            const canonicalPath = canonicalWorktreePath(worktree.path, pathPlatform);
+            if (worktree.baseCommit !== input.baseCommit || canonicalPath === null || paths.has(canonicalPath)) {
+                await cleanup.cleanupAll('candidate worktree invariant failed');
+                ensureActive();
+                return blocked(cleanup, 'worktree-invariant', 'candidate worktrees must be unique absolute paths and share the configured base');
+            }
+            paths.add(canonicalPath);
+        }
+        for (const candidate of owned) {
+            await input.lifecycle.materialize(candidate);
+            cleanup.markMaterialized(candidate.candidateId);
+            input.onLifecycle?.(candidate, 'materialized');
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+        }
+        for (const candidate of owned)
+            input.onLifecycle?.(candidate, 'running');
+        const runs = await runCandidates(input, owned);
+        for (const run of runs)
+            outcomes.set(run.owned.candidateId, run.result);
+        ensureActive();
+        if (input.pause?.() || runs.some(run => run.result.kind === 'paused')) {
+            return await finishPaused();
+        }
+        const green = [];
+        for (const run of runs) {
+            await input.recordResult?.({ ...run.owned, result: run.result });
+            switch (run.result.kind) {
+                case 'candidate':
+                    green.push({ ...run.owned, result: run.result });
+                    break;
+                case 'cancelled':
+                case 'mechanical-failure':
+                case 'quality-failure':
+                case 'review-failure':
+                    input.onLifecycle?.(run.owned, 'cleaning', run.result.summary);
+                    await input.recordElimination?.({ ...run.owned, result: run.result });
+                    await cleanup.cleanup(run.owned, run.result.summary);
+                    ensureActive();
+                    break;
+                case 'paused':
+                    throw new Error('paused candidates must be handled before mechanical filtering');
+            }
+        }
+        ensureActive();
+        if (input.pause?.())
+            return await finishPaused();
+        if (green.length === 0)
+            return blocked(cleanup, 'zero-green', 'no candidate passed every mechanical gate');
+        for (const candidate of green)
+            input.onLifecycle?.(candidate, 'selecting');
+        input.onSelecting?.();
+        const selection = await selectCandidate({
+            candidates: green,
+            evidence: input.evidence,
+            stageEvidence: input.stageEvidence,
+            judgeProvenance: input.judgeProvenance,
+            judge: input.judge,
+            ...(input.pause ? { pause: input.pause } : {}),
+            ensureActive,
+            discard: async (candidate) => {
+                await input.recordElimination?.(candidate);
+                await cleanup.cleanup(candidate, 'candidate was not selected');
+            },
+        });
+        ensureActive();
+        if (selection.kind === 'paused')
+            return await finishPaused();
+        if (selection.kind === 'inconsistent') {
+            for (const candidate of green)
+                await input.recordElimination?.({ ...candidate, result: candidate.result }, `selection-inconsistent: ${selection.reason}`);
+            await cleanup.cleanupAll(`candidate selection was inconsistent: ${selection.reason}`);
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+            return blocked(cleanup, 'selection-inconsistent', selection.reason);
+        }
+        const { controller: _controller, definition: _definition, ...winner } = selection.candidate;
+        const selectedWinner = {
+            ...winner,
+            digest: selection.evidence.digest,
+            artifacts: [...selection.evidence.artifacts],
+            comparisons: [...selection.comparisons],
+        };
+        await input.recordSelection?.(selectedWinner);
+        await cleanup.cleanupAll('candidate was not selected', selection.candidate.candidateId);
+        ensureActive();
+        if (input.pause?.())
+            return await finishPaused();
+        if (cleanup.hasFailures()) {
+            await cleanup.cleanup(selection.candidate, 'candidate cleanup failed');
+            ensureActive();
+            if (input.pause?.())
+                return await finishPaused();
+            return blocked(cleanup, 'cleanup-error', 'candidate loser cleanup failed');
+        }
+        return {
+            kind: 'winner',
+            winner: selectedWinner,
+        };
+    }
+    catch (error) {
+        let proofFailure;
+        try {
+            await terminalizeAll(`candidate coordinator failed: ${message(error)}`);
+        }
+        catch (proofError) {
+            proofFailure = message(proofError);
+        }
+        await cleanup.cleanupAll('candidate coordinator failed');
+        if (proofFailure)
+            return blocked(cleanup, 'cleanup-error', `candidate terminal proof failed: ${proofFailure}`);
+        if (input.signal?.aborted) {
+            return cleanup.hasFailures()
+                ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
+                : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+        }
+        if (input.pause?.()) {
+            try {
+                return await finishPaused();
+            }
+            catch (pauseError) {
+                if (input.signal?.aborted) {
+                    return cleanup.hasFailures()
+                        ? blocked(cleanup, 'cleanup-error', 'candidate cancellation cleanup failed')
+                        : { kind: 'cancelled', summary: cancellationSummary(input.signal) };
+                }
+                return blocked(cleanup, 'coordinator-error', message(pauseError));
+            }
+        }
+        return blocked(cleanup, 'coordinator-error', message(error));
+    }
+    finally {
+        input.signal?.removeEventListener('abort', cancelActive);
+    }
+}
+async function runCandidates(input, owned) {
+    const settled = await Promise.allSettled(owned.map(async (candidate) => ({
+        owned: candidate,
+        result: await runStoryWorker({
+            ...candidate.definition.worker,
+            ...(candidate.definition.runnerFor ? { runner: candidate.definition.runnerFor({ signal: candidate.signal }) } : {}),
+            ...(candidate.definition.reporterFor ? { reporter: candidate.definition.reporterFor(candidate) } : {}),
+            story: structuredClone(input.story),
+            worktree: candidate.worktree.path,
+            baseCommit: candidate.worktree.baseCommit,
+            cancellation: { signal: candidate.signal },
+        }),
+    })));
+    const runs = [];
+    for (const outcome of settled) {
+        if (outcome.status === 'rejected')
+            throw new Error(`candidate worker failed: ${message(outcome.reason)}`);
+        runs.push(outcome.value);
+    }
+    return runs;
+}
+function provenanceFor(input, definition) {
+    return { candidateId: definition.id, coordinatorId: input.coordinatorId, ownerToken: input.ownerToken(definition.id), storyId: input.story.id, provider: definition.worker.provider };
+}
+function cancellationSummary(signal) {
+    return typeof signal.reason === 'string' && signal.reason.length > 0 ? signal.reason : 'candidate coordinator cancelled';
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function blocked(cleanup, reason, summary) {
+    const recovery = cleanup.recovery();
+    return cleanup.hasFailures()
+        ? { kind: 'blocked', reason: 'cleanup-error', summary: cleanup.failureSummary(), recovery }
+        : { kind: 'blocked', reason, summary };
+}