@hecer/yoke 1.3.0 → 1.5.0

package/dist/agents/process-record.js

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function createProviderProcessRecord(targetDir, childPid, workerId, startedAt = new Date().toISOString()) {
+    const worker = workerId?.replace(/[^A-Za-z0-9_-]/gu, '_') || 'call';
+    return {
+        path: join(targetDir, '.yoke', 'provider-processes', `${worker}-${randomUUID()}.json`),
+        version: 1,
+        owner: 'provider-process',
+        targetDir,
+        childPid,
+        startedAt,
+        ...(workerId ? { workerId } : {}),
+    };
+}
+export const filesystemProviderProcessRecordAdapter = {
+    publish(record) {
+        const directory = join(record.targetDir, '.yoke', 'provider-processes');
+        mkdirSync(directory, { recursive: true });
+        const temporary = `${record.path}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({
+            version: record.version,
+            owner: record.owner,
+            targetDir: record.targetDir,
+            childPid: record.childPid,
+            startedAt: record.startedAt,
+            ...(record.workerId ? { workerId: record.workerId } : {}),
+        }), { flag: 'wx' });
+        try {
+            linkSync(temporary, record.path);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseProviderProcessRecord(value) {
+    if (!isRecord(value))
+        return null;
+    const workerId = value.workerId;
+    if (value.version !== 1 ||
+        value.owner !== 'provider-process' ||
+        typeof value.targetDir !== 'string' ||
+        typeof value.childPid !== 'number' ||
+        !Number.isInteger(value.childPid) ||
+        value.childPid <= 0 ||
+        typeof value.startedAt !== 'string' ||
+        value.startedAt.length === 0 ||
+        (workerId !== undefined && typeof workerId !== 'string'))
+        return null;
+    return {
+        version: 1,
+        owner: 'provider-process',
+        targetDir: value.targetDir,
+        childPid: value.childPid,
+        startedAt: value.startedAt,
+        ...(typeof workerId === 'string' ? { workerId } : {}),
+    };
+}

package/dist/agents/process-streams.js

@@ -0,0 +1,40 @@
+import { parseProviderTelemetry } from './telemetry.js';
+export function createBoundedOutput(limitBytes) {
+    let text = '';
+    let truncated = false;
+    return {
+        append(next) {
+            const combined = `${text}${next}`;
+            if (Buffer.byteLength(combined) <= limitBytes) {
+                text = combined;
+                return;
+            }
+            text = Buffer.from(combined).subarray(-limitBytes).toString('utf8');
+            truncated = true;
+        },
+        get text() { return text; },
+        get truncated() { return truncated; },
+    };
+}
+export function createTelemetryAccumulator(agent) {
+    let trailing = '';
+    let telemetry = { usageAvailable: false };
+    const update = (lines) => {
+        const next = parseProviderTelemetry(agent, [...lines]);
+        if (next.usageAvailable)
+            telemetry = next;
+    };
+    return {
+        append(text) {
+            const parts = `${trailing}${text}`.split(/\r?\n/u);
+            trailing = parts.pop() ?? '';
+            update(parts);
+        },
+        finish() {
+            if (trailing)
+                update([trailing]);
+            trailing = '';
+            return telemetry;
+        },
+    };
+}

package/dist/agents/process.js

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { killProcessTreeForCleanup } from '../loop/watchdog.js';
+import { createProviderProcessRecord, filesystemProviderProcessRecordAdapter, } from './process-record.js';
+import { createBoundedOutput, createTelemetryAccumulator } from './process-streams.js';
+import { processIncarnation } from './process-incarnation.js';
+function cancellationReason(signal) {
+    return typeof signal.reason === 'string' && signal.reason.length > 0
+        ? signal.reason
+        : 'provider process cancellation requested';
+}
+export function providerSpawnOptions(invocation, platform = process.platform) {
+    const windowsCommandShim = !/[\\/]/u.test(invocation.command) || /\.(?:bat|cmd)$/iu.test(invocation.command);
+    return {
+        command: invocation.command,
+        args: invocation.args,
+        cwd: invocation.cwd,
+        shell: platform === 'win32' && windowsCommandShim,
+        detached: platform !== 'win32',
+    };
+}
+export function startProviderProcess(agent, invocation, options = {}) {
+    const spawnOptions = providerSpawnOptions(invocation);
+    const child = spawn(spawnOptions.command, [...spawnOptions.args], {
+        cwd: spawnOptions.cwd,
+        shell: spawnOptions.shell,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: spawnOptions.detached,
+    });
+    const targetDir = resolve(invocation.cwd);
+    const pid = child.pid;
+    const startedAt = pid === undefined ? `unverified:${new Date().toISOString()}` : processIncarnation(pid) ?? `unverified:${new Date().toISOString()}`;
+    const record = createProviderProcessRecord(targetDir, pid ?? 0, options.workerId, startedAt);
+    const recordAdapter = options.recordAdapter ?? filesystemProviderProcessRecordAdapter;
+    const terminateProcessTree = options.terminateProcessTree ?? ((processPid) => killProcessTreeForCleanup(processPid));
+    let recordPublished = false;
+    const stdout = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
+    const stderr = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
+    const telemetry = createTelemetryAccumulator(agent);
+    const idleTimeoutMs = options.idleTimeoutMs ?? 0;
+    const terminationGraceMs = options.terminationGraceMs ?? 5_000;
+    let termination;
+    let idleTimer;
+    let forceTimer;
+    let recordFailure;
+    let terminationConfirmed = false;
+    let settled = false;
+    let resolveCompletion = () => { };
+    const completion = new Promise(resolveCompletionValue => {
+        resolveCompletion = resolveCompletionValue;
+    });
+    const removeRecord = () => {
+        if (recordPublished)
+            recordAdapter.remove(record.path);
+    };
+    const clearTimers = () => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        if (forceTimer)
+            clearTimeout(forceTimer);
+        idleTimer = undefined;
+        forceTimer = undefined;
+    };
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimers();
+        options.signal?.removeEventListener('abort', onAbort);
+        if (!termination || terminationConfirmed)
+            removeRecord();
+        resolveCompletion(result);
+    };
+    const evidence = () => ({
+        invocation,
+        pid,
+        stdout: stdout.text,
+        stderr: stderr.text,
+        stdoutTruncated: stdout.truncated,
+        stderrTruncated: stderr.truncated,
+        telemetry: telemetry.finish(),
+    });
+    const finalize = (exitCode) => {
+        const details = evidence();
+        if (recordFailure) {
+            finish({ ...details, kind: 'spawn-failed', error: recordFailure });
+            return;
+        }
+        if (termination?.kind === 'timed-out') {
+            finish({ ...details, kind: 'timed-out', reason: termination.reason });
+            return;
+        }
+        if (termination?.kind === 'cancelled') {
+            finish({ ...details, kind: 'cancelled', reason: termination.reason });
+            return;
+        }
+        if (exitCode === 0) {
+            finish({ ...details, kind: 'succeeded', exitCode });
+            return;
+        }
+        finish({ ...details, kind: 'failed', exitCode });
+    };
+    const terminate = (next) => {
+        if (termination || settled)
+            return false;
+        termination = next;
+        if (pid !== undefined)
+            terminationConfirmed = terminateProcessTree(pid, false);
+        forceTimer = setTimeout(() => {
+            if (pid !== undefined && !settled)
+                terminationConfirmed = terminateProcessTree(pid, true);
+        }, terminationGraceMs);
+        return true;
+    };
+    const armIdleTimer = () => {
+        if (idleTimeoutMs <= 0 || termination || settled)
+            return;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            terminate({ kind: 'timed-out', reason: 'provider process produced no output before its idle timeout' });
+        }, idleTimeoutMs);
+    };
+    const onAbort = () => {
+        if (options.signal)
+            terminate({ kind: 'cancelled', reason: cancellationReason(options.signal) });
+    };
+    const onOutput = (stream, chunk) => {
+        const text = String(chunk);
+        if (stream === 'stdout') {
+            stdout.append(text);
+            telemetry.append(text);
+        }
+        else {
+            stderr.append(text);
+        }
+        options.onOutput?.({ stream, text });
+        armIdleTimer();
+    };
+    child.stdout?.on('data', chunk => { onOutput('stdout', chunk); });
+    child.stderr?.on('data', chunk => { onOutput('stderr', chunk); });
+    child.stdin?.on('error', () => { });
+    child.on('close', code => { finalize(code); });
+    child.on('error', error => {
+        finish({ ...evidence(), kind: 'spawn-failed', error: recordFailure ?? error.message });
+    });
+    if (pid !== undefined) {
+        try {
+            recordAdapter.publish(record);
+            recordPublished = true;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            recordFailure = `process ownership record failure: ${reason}`;
+            child.stdin?.end();
+            terminate({ kind: 'cancelled', reason: recordFailure });
+        }
+    }
+    const handle = {
+        pid,
+        invocation,
+        recordPath: record.path,
+        completion,
+        cancel(reason) {
+            return terminate({ kind: 'cancelled', reason });
+        },
+    };
+    if (recordFailure)
+        return handle;
+    child.stdin?.end(invocation.input);
+    if (options.signal?.aborted)
+        onAbort();
+    else
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+    armIdleTimer();
+    return handle;
+}

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/audit/command.js

@@ -22,12 +22,20 @@ export function runAudit(targetDir, opts = {}) {
         }
         findings.push(...scanSensitiveChanges(changed));
         if (opts.command) {
-            try {
-                execSync(opts.command, { cwd: targetDir, stdio: 'pipe' });
-            }
-            catch {
-                findings.push({ ruleId: 'audit.custom-command', severity: 'high', message: `Audit command failed: ${opts.command}`, file: '.yoke/config.yaml' });
+            let commandResult;
+            if (opts.commandRunner)
+                commandResult = opts.commandRunner(opts.command, targetDir);
+            else {
+                try {
+                    execSync(opts.command, { cwd: targetDir, stdio: 'pipe' });
+                    commandResult = { passed: true, summary: `audit passed: ${opts.command}` };
+                }
+                catch {
+                    commandResult = { passed: false, summary: `Audit command failed: ${opts.command}` };
+                }
             }
+            if (!commandResult.passed)
+                findings.push({ ruleId: 'audit.custom-command', severity: 'high', message: commandResult.summary, file: '.yoke/config.yaml' });
         }
         else {
             const dependency = opts.dependency ?? ((repoFiles) => {

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 {};