@hecer/yoke 1.2.1 → 1.4.0

package/dist/loop/watchdog.js

@@ -1,9 +1,11 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { constants } from 'node:os';
 import { writeFileSync, rmSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { processIncarnation } from '../agents/process-incarnation.js';
 // Kill one recorded process tree, platform-appropriately. Exported for
 // `yoke loop cleanup` (scoped reaping of recorded runner pids).
-export function killProcessTree(pid) {
+export function killProcessTree(pid, force = true) {
     if (process.platform === 'win32') {
         try {
             spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
@@ -12,11 +14,51 @@ export function killProcessTree(pid) {
     }
     else {
         try {
-            process.kill(pid, 'SIGKILL');
+            process.kill(pid, force ? 'SIGKILL' : 'SIGTERM');
         }
         catch { /* already gone */ }
     }
 }
+function waitForCleanupRetry() {
+    spawnSync(process.execPath, ['-e', 'Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)'], { stdio: 'ignore' });
+}
+export function killProcessForCleanup(pid, platform = process.platform, runTaskkill = (command, args) => spawnSync(command, args, { stdio: 'ignore' }).status, sendSignal = (target, signal) => { process.kill(target, signal); }, isProcessAlive = (target) => {
+    try {
+        process.kill(target, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (platform === 'win32')
+        return runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) === 0;
+    try {
+        sendSignal(pid, 'SIGKILL');
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (!isProcessAlive(pid))
+            return true;
+        waitForCleanupRetry();
+    }
+    return false;
+}
+export function killProcessTreeForCleanup(pid, platform = process.platform, runTaskkill = (command, args) => spawnSync(command, args, { stdio: 'ignore' }).status, sendSignal = (target, signal) => { process.kill(target, signal); }) {
+    if (platform === 'win32')
+        return runTaskkill('taskkill', ['/PID', String(pid), '/T', '/F']) === 0;
+    try {
+        // Provider processes run detached on POSIX, so their PID is also the
+        // process-group leader. Signal the group to reap descendants as well.
+        sendSignal(-pid, 'SIGKILL');
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+    return true;
+}
 // win32 default: kill the whole tree. Console apps have no reliable soft-close
 // on Windows, so both phases force (/F) — the grace pass is a retry, not an
 // escalation. Best-effort by design: taskkill is a standard Windows component.
@@ -30,7 +72,7 @@ export function runWatchdog(opts) {
     const spawnFn = opts.spawnFn ?? spawn;
     const out = opts.out ?? ((d) => process.stdout.write(d));
     const err = opts.err ?? ((d) => process.stderr.write(d));
-    const child = spawnFn(opts.command, opts.args, { shell: process.platform === 'win32' });
+    const child = spawnFn(opts.command, opts.args, { shell: process.platform === 'win32', detached: process.platform !== 'win32' });
     if (opts.stdin && child.stdin) {
         try {
             opts.stdin.pipe(child.stdin);
@@ -39,7 +81,7 @@ export function runWatchdog(opts) {
     }
     if (opts.pidFile && child.pid !== undefined) {
         try {
-            writeFileSync(opts.pidFile, JSON.stringify({ watchdogPid: process.pid, childPid: child.pid, startedAt: new Date().toISOString() }));
+            writeFileSync(opts.pidFile, JSON.stringify({ watchdogPid: process.pid, watchdogIncarnation: processIncarnation(process.pid), childPid: child.pid, childIncarnation: processIncarnation(child.pid), startedAt: new Date().toISOString() }));
         }
         catch { /* best-effort — cleanup falls back to worktree/lock handling */ }
     }
@@ -54,12 +96,15 @@ export function runWatchdog(opts) {
     const graceMs = opts.graceMs ?? 5000;
     // Explicitly-passed killTree wins (including an explicit undefined, which pins
     // the per-process signal path — tests use this to be platform-independent).
-    const killTree = 'killTree' in opts ? opts.killTree : (process.platform === 'win32' ? taskkillTree : undefined);
+    const killTree = 'killTree' in opts ? opts.killTree : (pid, _force) => killProcessTreeForCleanup(pid);
     // Terminate the child — via the tree-killer when we have one and a pid,
     // otherwise per-process signals (POSIX default; SIGKILL is uncatchable).
+    let terminationRequested = false;
+    let terminationConfirmed = false;
     const terminate = (child, force) => {
+        terminationRequested = true;
         if (killTree && child.pid !== undefined) {
-            killTree(child.pid, force);
+            terminationConfirmed = killTree(child.pid, force) === true || terminationConfirmed;
             return;
         }
         try {
@@ -111,7 +156,21 @@ export function runWatchdog(opts) {
         child.stdout.on('data', (d) => { out(d); arm(); });
         child.stderr.on('data', (d) => { err(d); arm(); });
         child.on('error', () => { clear(); removePidFile(); resolve(127); });
-        child.on('close', (code) => { clear(); removePidFile(); resolve(killedForIdle ? 124 : (code ?? 0)); });
+        child.on('close', (code, signal) => {
+            clear();
+            if (!terminationRequested || terminationConfirmed)
+                removePidFile();
+            if (killedForIdle) {
+                resolve(124);
+                return;
+            }
+            if (code !== null) {
+                resolve(code);
+                return;
+            }
+            const signalNumber = signal ? constants.signals[signal] : undefined;
+            resolve(signalNumber === undefined ? 1 : 128 + signalNumber);
+        });
         arm();
     });
 }

package/dist/loop/worker-cancellation.js

@@ -0,0 +1,17 @@
+export function bindStoryWorkerCancellation(cancellation, handle) {
+    const signal = cancellation?.signal;
+    if (!signal)
+        return () => { };
+    const cancel = () => {
+        const reason = typeof signal.reason === 'string' && signal.reason.length > 0
+            ? signal.reason
+            : 'worker cancellation requested';
+        handle.cancel(reason);
+    };
+    if (signal.aborted) {
+        cancel();
+        return () => { };
+    }
+    signal.addEventListener('abort', cancel, { once: true });
+    return () => signal.removeEventListener('abort', cancel);
+}

package/dist/loop/worker-cleanup.js

@@ -0,0 +1,23 @@
+export function createWorkerCleanup(steps) {
+    const completedByWorker = new WeakMap();
+    const orderedSteps = [steps.cleanupProcess ?? (() => undefined), steps.removeWorktree, steps.releaseClaim];
+    return input => {
+        const completed = completedByWorker.get(input) ?? new Set();
+        completedByWorker.set(input, completed);
+        for (const [index, step] of orderedSteps.entries()) {
+            if (completed.has(index))
+                continue;
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                try {
+                    step(input);
+                    completed.add(index);
+                    break;
+                }
+                catch (error) {
+                    if (attempt === 1)
+                        throw error instanceof Error ? error : new Error(String(error));
+                }
+            }
+        }
+    };
+}

package/dist/loop/worker-contracts.js

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

package/dist/loop/worker.js

@@ -0,0 +1,254 @@
+import { isAcceptanceCriterion } from './prd.js';
+import { runQualityRepairLoop } from '../quality/loop.js';
+function emptyEvidence() { return { criteria: [] }; }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertNever(value) {
+    throw new Error(`Unexpected worker result: ${String(value)}`);
+}
+function cancellationReason(cancellation) {
+    if (cancellation?.signal?.aborted) {
+        return typeof cancellation.signal.reason === 'string' && cancellation.signal.reason.length > 0
+            ? cancellation.signal.reason
+            : 'worker cancellation requested';
+    }
+    return cancellation?.handle?.isCancelled() ? 'worker cancellation requested' : null;
+}
+function runGate(gate, worktree, storyId) {
+    const previous = process.env.YOKE_STORY;
+    process.env.YOKE_STORY = storyId;
+    try {
+        return gate(worktree);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.YOKE_STORY;
+        else
+            process.env.YOKE_STORY = previous;
+    }
+}
+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 runMechanicalGates(input, context, evidence) {
+    const criteria = context.story.acceptance.filter(isAcceptanceCriterion);
+    if (criteria.length === 0) {
+        if (input.requireCriterionEvidence)
+            return { kind: 'failed', stage: 'criterion', summary: `story ${context.story.id} lacks executable criterion evidence` };
+    }
+    else {
+        if (!input.verifyCriterion)
+            return { kind: 'failed', stage: 'criterion', summary: `story ${context.story.id} has criteria but no criterion verifier` };
+        for (const criterion of criteria) {
+            const cancelled = cancellationReason(input.cancellation);
+            if (cancelled)
+                return { kind: 'cancelled', summary: cancelled };
+            const result = input.verifyCriterion(context.targetDir, context.story, criterion);
+            const criteriaEvidence = [...evidence.criteria, { id: criterion.id, passed: result.passed, summary: result.summary }];
+            evidence.criteria = criteriaEvidence;
+            input.callbacks?.onGate?.('criterion', result);
+            if (!result.passed)
+                return { kind: 'failed', stage: 'criterion', summary: result.summary };
+        }
+    }
+    const cancelled = cancellationReason(input.cancellation);
+    if (cancelled)
+        return { kind: 'cancelled', summary: cancelled };
+    input.reporter?.phase('verifying');
+    const verify = runGate(input.verify, context.targetDir, context.story.id);
+    evidence.verify = verify;
+    input.callbacks?.onGate?.('verify', verify);
+    if (!verify.passed)
+        return { kind: 'failed', stage: 'verify', summary: verify.summary };
+    const afterVerifyCancellation = cancellationReason(input.cancellation);
+    if (afterVerifyCancellation)
+        return { kind: 'cancelled', summary: afterVerifyCancellation };
+    if (input.perf) {
+        input.reporter?.phase('perf');
+        const perf = runGate(input.perf, context.targetDir, context.story.id);
+        evidence.perf = perf;
+        input.callbacks?.onGate?.('perf', perf);
+        if (!perf.passed)
+            return { kind: 'failed', stage: 'perf', summary: perf.summary };
+        const afterPerfCancellation = cancellationReason(input.cancellation);
+        if (afterPerfCancellation)
+            return { kind: 'cancelled', summary: afterPerfCancellation };
+    }
+    if (input.audit) {
+        input.reporter?.phase('audit');
+        const audit = runGate(input.audit, context.targetDir, context.story.id);
+        evidence.audit = audit;
+        input.callbacks?.onGate?.('audit', audit);
+        if (!audit.passed)
+            return { kind: 'failed', stage: 'audit', summary: audit.summary };
+        const afterAuditCancellation = cancellationReason(input.cancellation);
+        if (afterAuditCancellation)
+            return { kind: 'cancelled', summary: afterAuditCancellation };
+    }
+    return { kind: 'passed' };
+}
+function finalResult(input, result) {
+    input.callbacks?.onResult?.(result);
+    return result;
+}
+function baseResult(input, evidence, summary) {
+    return {
+        storyId: input.story.id,
+        worktree: input.worktree,
+        baseCommit: input.baseCommit,
+        provider: input.provider,
+        summary,
+        evidence,
+    };
+}
+function resultFromQuality(input, evidence, summary, outcome) {
+    switch (outcome.kind) {
+        case 'approved':
+            return {
+                ...baseResult(input, evidence, summary),
+                kind: 'candidate',
+                routing: { outcome: 'pending-integration' },
+            };
+        case 'paused':
+            return { ...baseResult(input, evidence, summary), kind: 'paused' };
+        case 'cancelled':
+            return { ...baseResult(input, evidence, outcome.summary), kind: 'cancelled' };
+        case 'blocked':
+            switch (outcome.reason) {
+                case 'quality-inconsistent':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'quality-failure', reason: 'inconsistent' };
+                case 'quality-infrastructure':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'quality-failure', reason: 'infrastructure' };
+                case 'review-malformed':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'review-failure', reason: 'malformed' };
+                case 'review-infrastructure':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'review-failure', reason: 'infrastructure' };
+                case 'gate-failed':
+                    return { ...baseResult(input, evidence, outcome.summary), kind: 'mechanical-failure', stage: outcome.stage };
+                case 'no-actionable-finding':
+                case 'round-budget-exhausted':
+                case 'time-budget-exhausted':
+                case 'repair-failed':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'mechanical-failure', stage: 'quality' };
+                default:
+                    return assertNever(outcome);
+            }
+        default:
+            return assertNever(outcome);
+    }
+}
+export async function runStoryWorker(input) {
+    const evidence = emptyEvidence();
+    const cancelled = cancellationReason(input.cancellation);
+    if (cancelled)
+        return finalResult(input, { ...baseResult(input, evidence, cancelled), kind: 'cancelled' });
+    const workerStory = structuredClone(input.story);
+    const context = { targetDir: input.worktree, story: workerStory };
+    const qualityEnabled = input.qualityEnabled?.(workerStory) ?? input.qualityStage !== undefined;
+    const preflight = qualityEnabled ? input.qualityPreflight?.(context) : undefined;
+    if (preflight?.kind === 'blocked') {
+        return finalResult(input, { ...baseResult(input, evidence, preflight.summary), kind: 'mechanical-failure', stage: 'quality' });
+    }
+    let implementation;
+    try {
+        implementation = await input.runner(context);
+    }
+    catch (error) {
+        return finalResult(input, {
+            ...baseResult(input, evidence, `worker implementation failed: ${errorMessage(error)}`),
+            kind: 'mechanical-failure',
+            stage: 'implementation',
+        });
+    }
+    if (implementation.tokens)
+        input.reporter?.addTokens(implementation.tokens);
+    const afterImplementationCancellation = cancellationReason(input.cancellation);
+    if (afterImplementationCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, afterImplementationCancellation), kind: 'cancelled' });
+    }
+    const decision = input.beforeGates?.(context);
+    if (decision) {
+        return finalResult(input, { ...baseResult(input, evidence, decision), kind: 'paused', reason: 'decision' });
+    }
+    const gates = runMechanicalGates(input, context, evidence);
+    if (gates.kind === 'cancelled') {
+        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'cancelled' });
+    }
+    if (gates.kind === 'failed') {
+        implementation.routing?.recordOutcome(false);
+        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'mechanical-failure', stage: gates.stage });
+    }
+    const summary = implementation.success
+        ? implementation.summary
+        : `${implementation.summary} (runner exited non-zero but verify is green)`;
+    if (!qualityEnabled && !input.review) {
+        return finalResult(input, {
+            ...baseResult(input, evidence, summary),
+            kind: 'candidate',
+            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+        });
+    }
+    const beforeQualityCancellation = cancellationReason(input.cancellation);
+    if (beforeQualityCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, beforeQualityCancellation), kind: 'cancelled' });
+    }
+    const qualityStage = qualityEnabled ? input.qualityStage : undefined;
+    const review = input.review;
+    const quality = runQualityRepairLoop({
+        ...(qualityStage
+            ? { quality: (round) => {
+                    input.reporter?.phase('comparing');
+                    return qualityStage(context, round);
+                } }
+            : {}),
+        ...(review
+            ? { review: () => {
+                    input.reporter?.phase('reviewing');
+                    return reviewOutcome(review(context));
+                } }
+            : {}),
+        repair: request => {
+            if (!input.repair)
+                return { kind: 'blocked', summary: 'repair callback is not configured' };
+            input.reporter?.phase('repairing');
+            const repair = input.repair(context, request);
+            return repair.success ? { kind: 'repaired' } : { kind: 'blocked', summary: repair.summary };
+        },
+        rerunGates: () => {
+            const rerun = runMechanicalGates(input, context, evidence);
+            if (rerun.kind === 'passed')
+                return { kind: 'passed' };
+            if (rerun.kind === 'cancelled')
+                return rerun;
+            return { kind: 'failed', stage: rerun.stage, summary: rerun.summary };
+        },
+        ...(input.repairLimits ? { limits: input.repairLimits } : {}),
+        pause: input.pause,
+        onStatus: status => {
+            const metadata = input.qualityMetadata?.(context);
+            input.reporter?.quality({ ...status, ...(metadata ?? { policy: 'blocking' }) });
+        },
+    });
+    evidence.quality = quality;
+    const afterQualityCancellation = cancellationReason(input.cancellation);
+    if (afterQualityCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, afterQualityCancellation), kind: 'cancelled' });
+    }
+    const result = resultFromQuality(input, evidence, summary, quality);
+    if (result.kind !== 'candidate' && result.kind !== 'paused')
+        implementation.routing?.recordOutcome(false);
+    if (result.kind === 'candidate') {
+        return finalResult(input, {
+            ...result,
+            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+        });
+    }
+    return finalResult(input, result);
+}

package/dist/prd/command.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from '../retrofit/config.js';
-import { loadPrd, progress } from '../loop/prd.js';
+import { acceptanceText, criterionCommandProblem, isAcceptanceCriterion, loadPrd, progress } from '../loop/prd.js';
 import { agentInvocation, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
 import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
@@ -14,8 +14,12 @@ export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority o
 #   area: foundation      # optional collision domain for parallel runs
 #   agent: codex          # optional claude|codex|gemini affinity
 #   acceptance:
-#     - "the verify command exits 0"
-#     - "a placeholder test exists and passes"
+#     - id: suite-runs
+#       text: "the project test suite can run"
+#       verify: ["npm run test:suite-runs"]
+#     - id: scaffold-starts
+#       text: "the scaffolded application starts"
+#       verify: ["npm run test:scaffold-starts"]
 #   passes: false
 []
 `;
@@ -30,7 +34,7 @@ export function buildPrdDraftPrompt(idea, planningBrief) {
     if (planningBrief?.trim()) {
         lines.push('', '## Approved planning brief (treat these decisions as settled)', planningBrief.trim(), '', 'Do not reopen settled choices or invent alternatives that contradict this brief.');
     }
-    lines.push('', 'Break the idea into 5-12 small, independently shippable stories; each must fit one loop iteration.', 'Each story needs:', '- id: STORY-1, STORY-2, ... (unique)', '- title: one imperative sentence', '- priority: dense integers from 1 (lower = built first)', '- needs: optional list of story IDs that must pass first; the graph must be acyclic', '- area: optional collision domain for safe parallel scheduling', '- agent: optional claude|codex|gemini affinity', '- acceptance: 2-5 testable, behavioral criteria (observable outcomes, never implementation steps)', '- passes: false', '', 'If the project has no source code yet, STORY-1 must scaffold the project skeleton with a runnable', 'test suite, and its acceptance must include that the verify command (verify.command in', '.yoke/config.yaml) exits 0.', '', 'Write ONLY the file .yoke/prd.yaml as a YAML array of stories in exactly that shape.', 'Do not modify any other file. Do not commit.');
+    lines.push('', 'Break the idea into 5-12 small, independently shippable stories; each must fit one loop iteration.', 'Each story needs:', '- id: STORY-1, STORY-2, ... (unique)', '- title: one imperative sentence', '- priority: dense integers from 1 (lower = built first)', '- needs: optional list of story IDs that must pass first; the graph must be acyclic', '- area: optional collision domain for safe parallel scheduling', '- agent: optional claude|codex|gemini affinity', '- acceptance: 2-5 testable, behavioral criteria (observable outcomes, never implementation steps)', '  Each criterion is an object with a stable id, behavioral text, and verify: [one or more approved test commands].', '  Every criterion id must appear in every verify command; use one test command without shell control operators.', '- passes: false', '', 'If the project has no source code yet, STORY-1 must scaffold the project skeleton with a runnable', 'test suite, and its acceptance must include that the verify command (verify.command in', '.yoke/config.yaml) exits 0.', '', 'Write ONLY the file .yoke/prd.yaml as a YAML array of stories in exactly that shape.', 'Do not modify any other file. Do not commit.');
     return lines.join('\n');
 }
 export function prdFile(targetDir) {
@@ -113,6 +117,7 @@ export function runPrdCheck(targetDir) {
         return 1;
     }
     const errors = [];
+    const requireCriteria = loadConfig(targetDir)?.verify?.requireCriteria ?? false;
     if (stories.length === 0)
         errors.push('PRD has no stories');
     const seen = new Set();
@@ -123,7 +128,15 @@ export function runPrdCheck(targetDir) {
         // the schema allows [], but the loop's stop-the-line gate blocks it — fail fast here
         if (s.acceptance.length === 0)
             errors.push(`story ${s.id} has no acceptance criteria`);
-        if (s.acceptance.some(criterion => /\b(?:TBD|TODO|TO BE DECIDED|DECIDE LATER)\b|\?\?\?/i.test(criterion))) {
+        if (requireCriteria && s.acceptance.some(criterion => !isAcceptanceCriterion(criterion))) {
+            errors.push(`story ${s.id} lacks executable criterion evidence`);
+        }
+        for (const criterion of s.acceptance.filter(isAcceptanceCriterion)) {
+            const problem = criterionCommandProblem(criterion);
+            if (problem)
+                errors.push(problem);
+        }
+        if (s.acceptance.some(criterion => /\b(?:TBD|TODO|TO BE DECIDED|DECIDE LATER)\b|\?\?\?/i.test(acceptanceText(criterion)))) {
             errors.push(`story ${s.id} has unresolved planning decisions in acceptance criteria`);
         }
     }

package/dist/quality/artifacts.js

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { hasShellControlOperator, parseQualityCommand } from './process-command.js';
+export function collectCandidateArtifacts(input, adapters) {
+    const captured = captureCandidateArtifacts(input, adapters);
+    if (captured.kind === 'rejected')
+        return captured;
+    return { kind: 'collected', artifacts: captured.artifacts.map(value => value.artifact), digests: captured.digests };
+}
+export function captureCandidateArtifacts(input, adapters) {
+    if ('command' in input.candidate) {
+        if (hasShellControlOperator(input.candidate.command))
+            return { kind: 'rejected', reason: 'shell-control' };
+        if (!parseQualityCommand(input.candidate.command))
+            return { kind: 'rejected', reason: 'invalid-command' };
+        const bytes = input.candidate.kind === 'command-output'
+            ? adapters.commandOutput(input.candidate.command)
+            : adapters.benchmark(input.candidate.command);
+        const artifact = { kind: input.candidate.kind, source: input.candidate.command, bytes: bytes.byteLength, digest: digest(bytes) };
+        return { kind: 'captured', artifacts: [{ artifact, bytes }], digests: [artifact.digest] };
+    }
+    const projectRoot = resolve(input.projectDir);
+    const proofRoot = join(projectRoot, '.yoke', 'proof');
+    const kind = input.candidate.kind === 'screenshots' ? 'screenshot' : 'file';
+    const artifacts = [];
+    for (const source of input.candidate.paths) {
+        if (containsTraversal(source))
+            return { kind: 'rejected', reason: 'path-traversal' };
+        if (isAbsolute(source))
+            return { kind: 'rejected', reason: 'outside-project' };
+        const path = resolve(projectRoot, source);
+        if (!isInside(projectRoot, path))
+            return { kind: 'rejected', reason: 'outside-project' };
+        if (kind === 'screenshot' && !isInside(proofRoot, path))
+            return { kind: 'rejected', reason: 'outside-proof' };
+        const canonicalRoot = adapters.realpath?.(projectRoot) ?? projectRoot;
+        const canonicalPath = adapters.realpath?.(path) ?? path;
+        if (!isInside(canonicalRoot, canonicalPath))
+            return { kind: 'rejected', reason: 'outside-project' };
+        if (kind === 'screenshot' && !isInside(adapters.realpath?.(proofRoot) ?? proofRoot, canonicalPath))
+            return { kind: 'rejected', reason: 'outside-proof' };
+        const bytes = adapters.readFile(canonicalPath);
+        if (bytes === null)
+            return { kind: 'rejected', reason: 'missing' };
+        artifacts.push({ artifact: { kind, path: canonicalPath, bytes: bytes.byteLength, digest: digest(bytes) }, bytes });
+    }
+    artifacts.sort((left, right) => left.artifact.digest.localeCompare(right.artifact.digest) || (left.artifact.path ?? '').localeCompare(right.artifact.path ?? ''));
+    return { kind: 'captured', artifacts, digests: artifacts.map(artifact => artifact.artifact.digest) };
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function containsTraversal(path) {
+    return path.split(/[\\/]+/).includes('..');
+}
+function isInside(root, path) {
+    const relativePath = relative(root, path);
+    return relativePath === '' || (!relativePath.startsWith(`..${sep}`) && relativePath !== '..' && !isAbsolute(relativePath));
+}